socialize.notifyLogin JS

Skip to end of metadata
Go to start of metadata





This API method notifies the Gigya service that the user has been logged in by the site. We recommend calling this method when a user logs into your site using your own login system (the site's username and password).


Note: This method is also supported in our REST API. It is highly recommended when possible, for security reasons, to execute this method from your server, so please refer to REST API > socialize.notifyLogin


The notifyLogin call registers a new user in the Gigya service when the siteUID parameter provided is new, or reconnects a returning user when the siteUID already exists in our records.

It is essential to call notifyLogin if you enable users in your site to add connections to social networks via Gigya (using socialize.showAddConnectionsUI or socialize.addConnection). The notifyLogin call allows Gigya to associate the current user's social connections with the User ID you have designated to this user. This association has several benefits:

  • Any connections the user makes to social networks will be associated with the site account. The social graph will automatically be available the next time the user logs in to the site.
  • In calls to socialize.getUserInfo and socialize.getFriendsInfo Gigya will return your own User ID as the UID for this user.
  • Gigya will set the isSiteUser flag for this user to 'true', thus even if this user is referred to as a friend of another user you can easily tell he is a user of your site and not just a friend of the visiting user.

 For more information, see Social Login.

Security Requirements

The Gigya service supports a mechanism to verify the authenticity of the notifyLogin call. This mechanism is used to prove that the call is in fact coming from your site in order to prevent fraud.

We require every notifyLogin call to be signed using a HMAC-SHA1 signature. The " UIDSig " parameter (see the table of parameters below) is defined for this objective, and is a required parameter. Gigya verifies the authenticity of the signature to prove that it has in fact originated from your site and not from somewhere else.

Follow the instructions in Constructing a Signature to set the UIDSig parameter of the notifyLogin call, and make the API call as soon as possible after that to prevent the signature from expiring.





The following table lists the available parameters:

siteUID^ stringA unique identifier used by your site to identify the user. You may use the account ID that you have designated for this user in your database. This parameter accepts up to 252 ASCII characters (it does not accept Unicode).
providerSessions^ JSON object

This parameter gives the option to pass to Gigya session information obtained directly from a social network, so it can be used for making API calls to the social network. The value of this parameter is a JSON object with references to other objects, for example:

	"facebook": { 
		"authToken": "9187391837918237" 
    "yahoo": { 
		"authToken": "kjhd0ukjhuwd", 
		"providerUID": "BAK85htUqnLxSm" 

The provider field names may be: 'facebook', 'twitter', 'yahoo', 'microsoft', 'linkedin', 'qq', 'renren', 'sina' (Note: messenger has been replaced by microsoft, however, for backward compatibility, either can be used).

The fields for each sub-object are:

authToken *

The session authentication token.

For Facebook, this member should hold the Facebook Session Key.

code * A preliminary verification code received from the provider while establishing a session. The code is used in the process of receiving a session authentication token.
   * You must pass either authToken or code.
providerUID * * The user's account ID in the provider's system. ** Only required for certain providers, see chart.
tokenSecret * *

The session token secret.  ** Only required for certain providers, see chart.

For Facebook, this member should hold the Facebook sessionSecret.


Requirements by Provider

(Note: messenger has been replaced by microsoft, however, for backward compatibility, either can be used). 

tokenExpirationThe absolute time when the session token expires in UNIX time format.
tokenExpiresInThe number of seconds until the session token expires. This will be used only if tokenExpiration is not provided.
sessionHandleThe session handle encoded in BASE64.
sessionHandleExpirationThe absolute time when the session expires in UNIX time format.


  • If this parameter (providerSessions) is specified the call must be done over HTTPS. The siteUID parameter becomes optional.
  • Each provider requires a different set of fields for making API calls. See the chart above.

You are required to pass at least one of these parameters (siteUID and/or providerSessions)


An HMAC-SHA1 signature proving the authenticity of the data.

* This parameter is required if you pass the siteUID parameter (above) with this method. See the "Security Requirements" above for more details.


The GMT time in which the request is made. The expected format is the Unix time format (e.g., the number of seconds since Jan. 1st 1970).

* This parameter is required if you pass the siteUID parameter (above) with this method. Gigya checks the time difference between the timestamp and the time on Gigya's server when the setUID request is received. If the time difference is more than 5 minutes, the request is considered forged.

actionAttributesJSON objectIn Gamification  your users receive points for actions they perform on your site, in this case performing a notify login action grants the user points. Action Attributes may be used to annotate actions with additional information, such as the section of the web site that generated the action. If you set here the actionAttributes, each time a user  performs a notify login action , the action also receives an attribute, for example "tv-show":"glee", which can mean that the action was performed on the "Glee" page of the site. 
actionAttributes contain a JSON object comprised of a series of attribute keys (categories) with associated values. You can also use a generic "tags" key.

No more than three values can be given, they can be with a single key or each have their own key.

For more information see Variants and Action Attributes. Action attributes are later used to filter GM Plugins by a certain attribute.
Example:  {"<attribute key1>": ["<attribute value1>", "<attribute value2>"],  "<attribute key2>": "<attribute value3>" }

A reference to a callback function. Gigya calls the specified function along with the results of the API method when the API method completes.
The callback function should be defined with the following signature: functionName(Response).
The "Response Object Data Members" table below provides specification of the data that is passed to the callback function.
A string of maximum 100 characters length. The CID sets categories for transactions that can be used later for filtering reports generated by Gigya in the "Context ID" combo box. The CID allows you to associate the report information with your own internal data. For example, to identify a specific widget or page on your site/application. You should not define more than 100 different context IDs.

Note: This parameter overrides the value of the identical parameter in Global Conf (the global configuration object). If the parameter is not set for the method, the value from Global Conf is used.

A developer-created object that is passed back unchanged to the application as one of the fields in the response object.
newUserBooleanThis parameter determines whether this user is new to the site. The default value is false.
If 'newUser == TRUE', a 'SocializeNotifyLoginNewUser' event is called and a new user is created. 
regSourcestringA string representing the source of the registration. This would typically be the URL where it took place.
This parameter defines the length of time that Gigya should keep the user's login session valid. It can be configured via Global Configuration, via an individual API call, or left empty. If no value is specified, the default values are 0 or -2, depending on whether your site uses RaaS or not (see below); Global configuration overrides the default, and setting the value via individual API calls override the global configuration. 

The expected values are:

  •  0 - Session expires when the browser closes. This is the default behavior when RaaS is enabled in your site.

  • -1 - Session ends immediately, and Gigya gives you the option of creating a cookie that is stored on the site visitor's client (browser), allowing the site to control the session. A typical use case is when the session could include sensitive data (such as credit card details), and the session should be short, with the option of restarting the duration when users perform actions. Useful if you always set the session expiration via individual API methods or with each request, such as when the site session is controlled by a CMS (e.g., Drupal). For additional information, see how to define a session expiration cookie.

  • -2 - Session is valid forever. This is the default behavior when RaaS is not enabled in your site. 

  • Any custom integer - defines the number of seconds the session is active, e.g., 3600  (one hour). 

userInfoJSON object/stringThis parameter allows you to provide Gigya with a site's user profile data. This ensures consistent user experience. Gigya uses this information, for example, in plugins that show user info, such as the Chat and the Comments plugins. 
Note: When using Gigya's plugins, notifyLogin must be called with userInfo for site users who don't have a social identity in order for them to interact with the plugins.

The object may include the following fields: nickname, photoURL, thumbnailURL, firstName, lastName, gender, age, email. The comments and activity feeds require both a firstName and a lastName .
For example:

userInfo: { firstName: "David", lastName: "Blair", gender: "m", age:30 }
timestampstring Deprecated . Please use the UIDTimestamp parameter instead.
signaturestring Deprecated . Please use the UIDSig parameter instead.
providerstring Deprecated . Please use the providerSessions parameter instead.
authTokenstring Deprecated . Please use the providerSessions parameter instead.
tokenSecretstring Deprecated . Please use the providerSessions parameter instead.
tokenExpirationstring Deprecated . Please use the providerSessions parameter instead.
sessionHandlestring Deprecated . Please use the providerSessions parameter instead.
sessionHandleExpirationstring Deprecated . Please use the providerSessions parameter instead.

Response Object Data Members

errorCode integer The result code of the operation. Code '0' indicates success, any other number indicates failure. For a complete list of error codes, see the table.
errorMessage string A short textual description of an error associated with the errorCode for logging purposes.
callId string Unique identifier of the transaction, for debugging purposes.
context object The context object passed by the application as a parameter to the API method, or null if no context object has been passed.
userUser objectUser object with updated information for the current user. The information also includes a list of the providers to which the user is currently connected.

Triggered Global Event

By using this method the onLogin global event is triggered (the onLogin global event is fired when a user successfully logs in to Gigya). For more information, see onLogin event data. Note that if the onLogin global event is fired as a result of a notifyLogin() call, the provider field of the event data is set to "site". The event is guaranteed to be fired before the notifyLogin's callback is called. To register an event handler use the socialize.addEventHandlers API method. For more information about handling Gigya events, see Events.

Code Sample

The following code example uses authorization tokens and should be run server-side only.

var secret = 'Put your secret key here'; // Obtain your secret key from the 'Site Setup' page on Gigya's website
var yourSiteUid= '<siteUID>'; // siteUID should be retrieved from your user management system

function your_b64_hmac_sha1(secret, datePlusSite) { 
    var b64Sig = ''; // Place your implementation here ... 
    return b64Sig; 

function printResponse(response) {
    if ( response.errorCode == 0 ) {
        alert('After notifyLogin');    

var dateStr = getCurrentTime();  // Current time in Unix format (i.e. the number of seconds since Jan. 1st 1970)
var datePlusSite = dateStr + "_" + yourSiteUid;
var yourSig = your_b64_hmac_sha1(secret, datePlusSite);

var params={
    providerSessions: { 
      "facebook" : { "authToken" : "Put Facebook accessToken here", tokenSecret: 'Put Facebook sessionSecret here', tokenExpiration: '657658465'},
      "yahoo" : { "authToken" : "Put your Yahoo Auth Token key here" }



  • This sample is not meant to be fully functional code. For brevity's sake, only the code required for demonstrating the API call itself is presented.
  • To run the code on your own domain, add your Gigya API key to the gigya.js URL. A Gigya API key can be obtained on the Site Dashboard page on Gigya's website. Please make sure that the domain from which you are loading the page is the same domain name that you used for generating the API key.


Additional Information

notifyLogin Troubleshooting Tips