socialize.notifyLogin REST

Skip to end of metadata
Go to start of metadata

 

Description

The socialize.notifyLogin 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 in to your site using your own login system (the site's username and password) not when a user authenticates using a social network. Any registration process that begins with social authentication should not end with notifyLogin.

This API method registers a new user in the Gigya service if the siteUID parameter provided is new. For reporting purposes, the newUser parameter should also be set to ' true '. The method reconnects a returning user if the siteUID already exists in the Gigya records. 

When receiving the notifyLogin response , please make sure to create a session cookie , so as to maintain the client application synchronized with the user state. The notifyLogin response includes data fields specifying the name, content and location of the session cookie. Please make sure that the page following the login includes Gigya's library i.e., gigya.js, in order for Gigya to read the cookie before it expires. If you are using an ajax-based site login (no page refresh after logging in), make a call to socialize.refreshUI after setting the session cookie so that Gigya is able to process the authorization before it expires.

Adding Connections

It is essential to call notifyLogin if you are enabling 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 be automatically made 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.

Read more about integrating Gigya's Social Login and the implementation flow in our Social Login guide.

 

Request URL

Where <Data_Center> is:
  • us1.gigya.com - For the US data center.
  • eu1.gigya.com - For the European data center.
  • au1.gigya.com - For the Australian data center.
  • ru1.gigya.com - For the Russian data center.
  • cn1.gigya-api.cn - For the Chinese data center.

If you are not sure of your site's data center, see Finding Your Data Center.

Parameters

RequiredNameTypeDescription
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

providerNameauthTokenproviderUIDtokenSecret
facebook
googleplus
linkedin
microsoft
renren
sina
twitter
vkontakte
wechat
yahoo
(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.

Notes:

  • 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)

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>" }

cidstring
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.
newUserBooleanThis parameter determines whether this user is new to the site. The default value is false.
regSourcestringA string representing the source of the registration. This would typically be the URL where it took place.
sessionExpirationinteger
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 after a 60 second period; 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 length within this 60 second window, after which the session is terminated if no cookie is found. 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). 

skipValidationBooleanDefault is false. If set to true, the server will not perform any validation on the user and will not return any pending state errors and will not check for any registration requirements for the end user. This parameter can only be used over HTTPS.
targetEnvstring

This parameter defines your client side environment, which in return determines the server response data fields. The default value of this parameter is "browser", which means that by default you receive cookie-related data in the response.

If your client runs on a mobile you will call this method using a Mobile SDK. Since version 2.15.6, this parameter is automatically set to "mobile" (there is no need to set it manually). In any other case, you should set this parameter to be "mobile".

As a result of setting the parameter to "mobile" the server response data fields will include: sessionToken and sessionSecret (instead of cookie related data). In such case, you should send the sessionToken and sessionSecret to your mobile client. On your client side, call GSAPI.setSession (using the Mobile SDK) to save them in the app's storage.

userInfoJSON object

This parameter allows you to provide Gigya with site's user profile data. This will ensure consistent user experience. Gigya will use this information, for example, in plugins that show user info, such as the Chat and the Comments plugins.

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.

For example:

userInfo={firstName:"David", gender:"m", age:30}

You must always pass a photoURL when passing a thumbnailURL .

format string Determines the format of the response. The options are:
  • json (default)
  • jsonp - if the format is jsonp then you are required to define a callback method (see parameter below).
callback string This parameter is required only when the format parameter is set to jsonp (see above). In such cases this parameter should define the name of the callback method to be called in the response, along with the jsonp response data.
httpStatusCodes Boolean The default value of this parameter is false, which means that the HTTP status code in Gigya's response is always 200 (OK), even if an error occurs. The error code and message is given within the response data (see below). If this parameter is set to true, the HTTP status code in Gigya's response would reflect an error, if one occurred.
The following parameters are Required only when calling the method from client side (e.g., using a Mobile SDK):
UIDSigstringThe UIDSig is an HMAC-SHA1 signature proving the authenticity of the data. The signature construction should be implemented on your server side. You can read more in Constructing a Signature.
UIDTimestampstringThe UIDTimestamp is the current GMT time when request is made. The expected format is the Unix time format (i.e., the number of seconds since Jan. 1st 1970). Gigya will check the time difference between the timestamp and the time on Gigya's server when this request is received. If the time difference is more than 5 minutes, the request is considered forged. Please make sure that the UIDTimestamp holds the same timestamp used in the construction of the UIDSig parameter. You can read more in Constructing a Signature.

Authorization Parameters

Each REST API request must contain identification and authorization parameters.

Note: The authorization parameters are required only if you are using the REST API directly. If you are using one of Gigya's SDKs then these parameters are not required, since the SDK implements the authorization method internally.

There are two methods of authorization:

  1. If you are using Gigya's proprietary authorization method, you will need to pass the parameters specified here. Or, if you are making a call over HTTPS then you may pass the secret parameter instead of the timestamp , nonce and sig parameters. For more information, please read the Using Gigya's REST API with our proprietary authorization method guide.
  2. If you are conforming with the OAuth 2.0 standard, use the method socialize.getToken instead of this method, with parameters grant_type set to none and x_siteUID set to the user's site identifier. For more information, please read the Using Gigya's REST API in compliance with OAuth 2.0 guide.

 

Response Data

FieldTypeDescription
 
statusCode integer The HTTP response code of the operation. Code '200' indicates success.
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 Error Codes table.
statusReason string A brief explanation of the status code.
errorMessage string A short textual description of an error, associated with the errorCode, for logging purposes. This field will appear in the response only in case of an error.
errorDetails string This field will appear in the response only in case of an error and will contain the exception info, if available.
fullEventName string The full name of the event that triggered the response. This is an internally used parameter that is not always returned and should not be relied upon by your implementation.
callId string Unique identifier of the transaction, for debugging purposes.
time string The time of the response represented in ISO 8601 format, i.e., yyyy-mm-dd-Thh:MM:ss.SSSZ or

 

 

cookieNamestringPlease create a session cookie with the name specified by this field.
cookieValuestringPlease create a session cookie with the value specified by this field.
cookieDomainstringPlease create a session cookie with the domain specified by this field.
cookiePathstringPlease create a session cookie with the path specified by this field.
UIDstringThe User ID that should be used for login verification as described under Validate the UID Signature in the Social Login Process.
UIDSignaturestringThe signature that should be used for login verification as described under Validate the UID Signature in the Social Login Process.
signatureTimestampnumberThe GMT time of the response in UNIX time format (i.e., the number of seconds since Jan. 1st 1970). The timestamp should be used for login verification as described under Validate the UID Signature in the Social Login Process.
The following fields are returned only if you have set the parameter targetEnv="mobile" when calling the method (in such case the cookie related fields defined above are not returned):
sessionTokenstringPlease send this data field  to your mobile client. On your client side, call GSAPI.setSession ( using the  Mobile SDK ) to save it on the app's storage.
sessionSecretstringPlease send  this data field to your mobile client. On your client side, call GSAPI.setSession ( using the  Mobile SDK) to save it on the app's storage.

A field that does not contain data will not appear in the response.

 

Response Example

{
  "UID": "134314",
  "UIDSignature": "mGRzMkza71I1YPhYWcOJKd23NMs=",
  "signatureTimestamp": "1333440164",
  "cookieName": "gac_2_5TRBahRnBLBRwbF-syLyCfVGrBow7WpTferAz_J2zaPr1VUayUFn2BRvu78Vr5pd",
  "cookieValue": "VC1_1236F819FF645F423347D1204AF06E70_5j-T4sDYeyU8YF51FqjV861l_7adCvkuBlyjRboBJjh15B5Wr2MdqL0qOVsrCi7fFmOl5c70KSwbSBpTQ2aL8vpjVmaKLnW_CyeBYj4IUY1EKO2kgC7AWjPReuHbd_IydP_WfJJKI3JTLGt1TkEoBg==",
  "cookieDomain": "tanyatest.com",
  "cookiePath": "/",
  "statusCode": 200,
  "errorCode": 0,
  "statusReason": "OK",
  "callId": "8e6dea6eb5e34f2a98860b0ddff51408",
  "time": "2015-03-22T11:42:25.943Z"
}

 

Additional Information

notifyLogin Troubleshooting Tips