Description
This method instructs Gigya Socialize to authenticate the user using an external provider, such as Facebook or Yahoo.
Gigya Socialize will open a popup window with the login screen of the requested provider. In some cases, such as Facebook and Myspace, users will also be asked to give the site permission to access their personal data. When the login process completes, the popup window will close automatically, the method callback function will be called and the global onLogin event will be fired.
Supporting Providers
This operation currently supported by the following providers: Facebook, Myspace, Twitter, Yahoo, LinkedIn, AOL, Windows Live ID, Google, WordPress, BloggerID, Typepad, liveJournal, Hyves, VeriSignID.
Securing the Login Process
Gigya Socialize supports a mechanism to verify the authenticity of the login process. To prevent fraud, Gigya "signs" the authentication process with a cryptographic signature.
Your site will receive the cryptographic signature provided by Gigya in the login method's callback function as part of the response object (please refer to the Response object Data Members table below).
We highly recommend verifying the authenticity of the signature to prove that it is indeed originating from Gigya, rather than somewhere else.
To learn more about this subject, please refer to the Cryptographic Signatures section in the Security page of the Developer's Guide.
Syntax
gigya.services.socialize.login(conf,params)
Method parameters
conf object
Please refer to the Conf object page for full specifications.
params object members
| Required | Name | Type | Description |
| Required | provider | string | The provider which will be used for authenticating the user. The following values are currently supported for use with this parameter: facebook, myspace, twitter, yahoo, linkedin, google, aol, liveid, wordpress, bloggerid, typepad, livejournal, hyves, verisignid. |
| Optional | redirectURL | string | A URL to redirect the user to, when the login process is successfully completed. The following additional parameters will be appended to the URL string: UID, UIDSig, timestamp, loginProvider, nickname, photoURL, thumbnailURL, firstName, lastName, gender, birthDay, birthMonth, birthYear, email, country, state, city, zip, profileURL, proxiedEmail, provider. These parameters are equivalent to the User object fields. Please find the parameters' description in the User object reference page. If the redirectURL parameter is provided, the callback function will not be called and the onLogin event will not be generated. Note: the redirectURL parameter is not supported in ActionScript environment. |
| | useFacebookConnect | boolean | Assigning "true" to this parameter, will cause Gigya Socialize to pop-up Facebook Connect UI when connecting to the user's Facebook account (i.e. when the user presses the Facebook button of the Connect UI). You may find more information about the subject in Using Facebook Connect section in the Developer's Guide. Note: this parameter is not supported in ActionScript environment. |
| | invite | Invite object | If this parameter is specified then the "Invite" dialog will be displayed when a user logs-in to Facebook. You may find more information about the subject in Inviting Friends section in the Developer's Guide. |
| | shortURLs | string | This parameter is relevant only if you use the 'invite' parameter defined above. Using this parameter you may determine whether to use Gigya's URL shortening service for URLs, which are published through this method. The optional values for this parameter are: - 'always' (default): always shorten URLs.
- 'whenRequired': shorten URLs when needed - when posting to Twitter, LinkedIn, MySpace and Yahoo where the status update is limited to 140 char.
- 'never' - never shorten URLs.
When Gigya's URL shortening service is active, Gigya tracks all the traffic coming from the distributed URLs. In such case, 'Referred Traffic' reports will be available to you. Note: the value of this parameter overrides the value of the identical parameter in the Conf object. |
| | 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. |
| callback | function | A reference to a callback function. Gigya will call 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 which is passed to the callback function. |
| | cid | string | A string of maximum 100 characters length. This string will be 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.
Note: the value of this parameter overrides the value of the identical parameter in the Conf object. |
| | context | object | A developer-created object that will be passed back unchanged to the application as one of the fields in the response object. |
Response object Data Members
Code Sample
var conf = {
APIKey:'2_fA4cZD0cEmxKUjDdNai8hyK4fZ-Jq7w4qm1x-pkS-7E6NDm90gAmrdcugVoaewUS'
};
var params = {
provider:'facebook',
callback: 'onLogin',
redirectURL:'http://www.MySite.com'
};
gigya.services.socialize.login(conf, params);
function onLogin(response)
{
// verify the signature ...
}
function onLogin(response:Object):void
{
// verify the signature ...
}
function login():void {
var conf:Object = {
mcRoot:this.root,
APIKey:'2_fA4cZD0cEmxKUjDdNai8hyK4fZ-Jq7w4qm1x-pkS-7E6NDm90gAmrdcugVoaewUS'
};
var params:Object = {
provider:'facebook',
callback: 'onLogin',
redirectURL:'http://www.MySite.com'
};
gigya.services.socialize.login(conf, params);
}
Notes:
- 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.
- The API key in the sample will only work on http://localhost/...
- To run the code on your own domain, modify the API key in the example to your own API key. A Gigya API Key can be obtained on the Site Setup page on Gigya's website. Please make sure that the domain you are loading the page from is the same domain name that you used for generating the API Key.
- In some cases it is necessary to connect the user to a provider? prior to calling the API method. For connecting the user to a provider, you may use the Connect API method call or the pre-built Connect Widget.
- Best practice is, to define one global conf object and use it throughout the application.