1. Gigya's Documentation
  2. REST API
  3. Socialize
  4. socialize.notifyLogin
Was this article helpful?

socialize.notifyLogin

Modified 15:33, 17 Mar 2013 by Tanya

Description

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 in to your site using your own login system (the site's username and password).
The notifyLogin call registers a new user in the Gigya service, in case the siteUID parameter provided is new, or reconnects a returning user in case the siteUID already exists in our records.
If it is a new user, call the notifyLogin API method with the newUser parameter set to 'true'. This will enable Gigya to distinguish between a new site user and a returning site user, allowing Gigya to analyze users' login/registration behavior with or without Social Login and compare the ratio.
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. socialize.js, in order for Gigya to read the cookie before it expires.

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.

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

 

Request URL

http[s]://socialize.gigya.com/socialize.notifyLogin

 

Parameters

Required Name Type Description
Required siteUID string A unique identifier used by your site to identify the user. You may use the user's account ID that you have designated for this user in you database.
Note: the parameter accepts only ASCII characters (not Unicode) and up to 252 characters.
Optional cid string A string of maximum 100 characters length. This string is associated with each transaction and will later appear on 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. The "Context ID" combo box lets you filter the report data by site/application context.
  sessionExpiration integer This parameter defines the time in seconds that Gigya should keep the login session valid for the user. To end the session when the browser closes, please assign the value '0'. If this parameter is not specified, the session will be valid forever.
  newUser Boolean This parameter determines whether this user is new to the site. The default value is false.
  userInfo JSON 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.
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.
For example: 
userInfo={ firstName: "David", gender: "m", age:30 }
  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 reference to other objects. The field names of the main object are the names of the provider to set the session information for. The sub-objects contain the session information. For example:
{ 
      "facebook" : { "authToken" : "9187391837918237" },
      "yahoo" : { "authToken" : "kjhd0ukjhuwd", tokenSecret : "aALJSIjlSyug", 
           tokenExpiration: "123890983" }
 }
Note, each provider requires a different set of fields for making API calls.
The provider field names may be: 'facebook', 'twitter', 'yahoo', 'messenger', 'linkedin', 'myspace', 'orkut', 'sina', 'qq', 'renren'.
The sub-objects' fields are:
authToken The session authentication token.
Note: For Facebook this member should hold the Facebook Session Key.
tokenSecret The session token secret.
Note: For Facebook this member should hold the Facebook sessionSecret.
tokenExpiration The absolute time when the session token expires in UNIX time format.
sessionHandle The session handle encoded in BASE64.
sessionHandleExpiration The absolute time when the session expires in UNIX time format.
Note: If this parameter is specified the call must be done over HTTPS. The siteUID parameter becomes optional.
  targetEnv string 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:
If you are calling 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.
  actionAttributes JSON object In 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. 

These action attributes are later used to display the GM Plugins filtered according to a certain attribute. For example, you can show the Leaderboard plugin only for top users on the "Glee" page.

This parameter receives a JSON object, comprised of a set or sets of a key (category) and a value or values, i.e.:
    {
        "<attribute1 name>": ["<attribute1 value1>", "<attribute1 value2>", ...],
        "<attribute2 name>": "<attribute2 value>",
        ...
    }
For example:
    {

        "tv-show": ["glee", "30rock"],
        "music": "pop"
    }
In this example the action receives three attributes: {"tv-show":"glee"}, {"tv-show":"30rock"}, and {"music":"pop"}. This parameter may receive a list of up to three sets of key and value entries per call. If more values are entered, only the first three will count and the rest will be ignored. The three sets of key and value can be one key with three values, or three keys with one value each, or two keys, one with two values and the other with one value. 
You can also choose to input attributes using a generic "Tags" key, with no category name, for example: {"tags": ["glee", "house", "pop"]}. In this case the action receives these three attributes: {"tags":"glee"}, {"tags":"house"}, and {"tags":"pop"}.
The following parameters are Required only when calling the method from client side (e.g. using a Mobile SDK): 
  UIDSig string The 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.
  UIDTimestamp string The 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 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

Field Type Description
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.
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.
callId string Unique identifier of the transaction, for debugging purposes.
cookieName string Please create a session cookie with the name specified by this field.
cookieValue string Please create a session cookie with the value specified by this field.
cookieDomain string Please create a session cookie with the domain specified by this field.
cookiePath string Please create a session cookie with the path specified by this field.
UID string The User ID that should be used for login verification as described under  Validate the UID Signature in the Social Login Process.
UIDSignature string The signature that should be used for login verification as described under Validate the UID Signature in the Social Login Process.
signatureTimestamp number The 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):
sessionToken string Please 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.
sessionSecret string Please 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.

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

.

Was this article helpful?
Pages that link here
Page statistics
4166 view(s) and 6 edit(s)
Social share
Share this page?

Tags

This page has no custom tags set.

Comments

You must to post a comment.

Attachments