Was this article helpful?

socialize.showLoginUI

Last modified 13:12, 30 Jul 2014

Description

Displays a "Login" plugin, which is Gigya's Social Login plugin. The plugin displays all the available providers' logos as login options, enabling the user to login to your site via his social network / webmail account.

The plugin displays, by default, the logos of the following providers:

Facebook, Twitter, Yahoo, Microsoft Messenger, Google+, LinkedIn, AOL, FourSquare, Instagram, Renren, Tencent QQ, Sina Weibo, Kaixin, Vkontakte, WordPress, Blogger, Typepad, liveJournal, VeriSign, OpenID, Skyrock, VZnet.

In addition, the following providers are supported and may be added explicitly: Paypal, Amazon, Netlog, Signon, Orange France, mixi, Yahoo JAPAN, Odnoklassniki, Spiceworks, Livedoor.

Some providers require that the user provide permission to access their data on the first sign-in. Yahoo will require the user to provide explicit permission every time they sign-in.

You may customize the list of providers' logos that appear on the plugin using the enabledProviders and disabledProviders parameters or by using the requiredCapabilities parameter.

The plugin may be embedded in the page or displayed as a popup at the center of the page. If the plugin is opened as a popup, then it automatically disappears at the end of the login process.

In the Social Login demo page you will find a complete working example which uses the socialize.showLoginUI method. You may view the code, run it and view the outcome.

Plugin's Default Design:

LoginUI1.gif

The plugin's design is customizable through the use of the parameters listed below.

Note: If you plan on integrating the Login plugin, we highly recommend reading the Social Login guide, which is a step-by-step guide for implementing the Social Login process in your site.

 

Syntax

gigya.socialize.showLoginUI(params)

 

Method Parameters

The following table lists the params object members:

Required Name Type Description
Optional width integer Determines the width you desire for the plugin. You may also use percentages to determine the width.
Template:~gs api common UI parameters(new)
  actionAttributes JSON object In Gamification your users receive points for actions they perform on your site, in this case logging in 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 logs in, 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>" }
  authCodeOnly Boolean This parameter is intended only for developers who wish to implement the "Web Server Flow" of the OAuth 2.0 standard. The default value of this parameter is 'false'. If set to 'true', you will not receive the user data in the onLogin event data. Instead you will receive an authCode.
The authCode contains a code that is intended to be used for invoking the OAuth 2.0 getToken end-point along with the grant_type parameter set to authorization_code.
  authFlow string Using this parameter you may specify that the login flow will use page redirects instead of using a popup. This gives a solution for environments where popups are unavailable (e.g. mobile web view controls). This parameter accepts two values:
  • "popup" (default)
  • "redirect" - the login flow uses page redirects. When the login process completes successfully, the user is redirected to the URL specified by the redirectURL parameter (see above). If the redirectURL parameter is not specified, the user will be redirected to the original page from which the login process started.
    Notes: This option will only work if CNAME is configured.
    When using this mode, the onLogin event is not fired.
  autoDetectUserProviders string This parameter, when specified and loading Facebook Connect is possible, and the user is detected as a Facebook user, the login plugin displays a large provider button at the top and the rest of the login buttons at the bottom. Currently the supported values are:
  buttonSize integer A number denoting the height of the buttons in pixels. Width will be set in proportion to the height.
  buttonsStyle string This parameter enables selecting one of the pre-defined design styles for the network buttons on the Login UI. Currently Gigya offers three design styles:
  • 'standard' (default):
    showLogin-standard.jpg
  • 'fullLogo':
    showLogin-fullLogo.jpg
  • 'fullLogoColored'
    showLogin-fullLogoColored.jpg
  • 'signInWith':
    showLogin-signinWith.jpg
  cid string 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: the value of this parameter overrides the value of the identical parameter in the global configuration object
  customButton customButton object This parameter is used to add a single customButton object to the login bar.
You may define any OpenID provider as an authentication destination - read more about Adding a Custom OpenID Provider
You may also define a SAML login provider - read more about Adding a SAML Login Provider.
  disabledProviders string A comma-delimited list of provider names to exclude in the method execution. This parameter gives the possibility to specify providers to which that you don't want this method to apply. If you do not set this parameter, by default no provider is disabled (i.e. the method applies to all connected providers).
For example, if you would like the method to apply to all providers except Google+ and Twitter, define: disabledProviders: "googleplus, twitter".
Valid provider names include: facebook, twitter, yahoo, messenger, googleplus, linkedin, aol, foursquare, orkut, instagramrenren, qq, sina, kaixin, vkontakte, blogger, wordpress, typepad, paypal, amazon, livejournal, verisign, openid, netlog, signon, orangefrance, mixi, yahoojapan, odnoklassnikispiceworks, livedoor, skyrock, vznet, xing.
Note: the value of this parameter overrides the value of the identical parameter in the global configuration object.
  enabledProviders string A comma-delimited list of provider names to include in the method execution. This parameter gives the possibility to apply this method only to a subset of providers of your choice. If you do not set this parameter, by default all the providers are enabled (i.e. the method applies to all connected providers).
For example, if you would like the method to apply only to Facebook and Twitter, define: enabledProviders: "facebook, twitter".
Valid provider names include: facebook, twitter, yahoo, messenger, googleplus, linkedin, aol, foursquare, orkut, instagramrenren, qq, sina, kaixin, vkontakte, blogger, wordpress, typepad, paypal, amazon, livejournal, verisign, openid, netlog, signon, orangefrance, mixi, yahoojapan, odnoklassnikispiceworks, livedoor, skyrock, vznet, xing. 
Note: the value of this parameter overrides the value of the identical parameter in the global configuration object.
  extraFields string

This parameter accepts a comma-separated list of additional data fields to retrieve. The current valid values are: languages, address, phones, education, honors, publications, patents, certifications, professionalHeadline, bio, industry, specialties, work, skills, religion, politicalView, interestedIn, relationshipStatus, hometown, favorites, likes, followersCount, followingCount, username, locale, verified, irank and timezone.

Note: Before your application can retrieve Facebook data, the user must grant your application with access. Please make sure you have checked the check boxes that enable retrieving the relevant fields from Facebook in the Permissions page on Gigya's website. You may find more information in the Facebook Permissions section of our guide.

  facebookExtraPermissions string A comma-delimited list of Facebook extended permissions to request from the user. This parameter gives the possibility to request extended permissions in addition to the permissions that Gigya is already requesting.
Please refer to Facebook's extended permissions page for the complete list of permissions.
For example, if you wish to RSVP to events on the user's behalf and to to send text messages to the user define: 
facebookExtraPermissions : "rsvp_event,sms"
Note: the value of this parameter overrides the value of the identical parameter in the global configuration object.
  facepilePosition string This parameter specifies where to display the Facebook facepile plugin if loading Facebook Connect is possible and the user is currently logged into Facebook (requires Native SDK Capabilities). The optional values for this parameter are:
  • 'none' (default)
  • 'top'
  • 'bottom'
  forceAuthentication Boolean The default value of this parameter is 'false'. If set to 'true', the user will be forced to provide her social network credentials during the login, even if she is already connected to the social network. This parameter is currently supported by Facebook, Twitter, Renren, and LinkedIn. Please note that the behavior of the various social networks may be slightly different: Facebook expects the current user to enter their password, and will not accept a different user name. Other networks prompt the user to re-authorize the application or allow a different user to log in. 
  googleExtraPermissions string This parameter gives the possibility to request extended permissions in addition to the permissions that Gigya is already requesting. The supported values are: "wallet" - for Google wallet permissions.
Note: the value of this parameter overrides the value of the identical parameter in the global configuration object.
  googlePlayAppID string The objective of this parameter is to support Over The Air app installs for Android devices during Google+ login. Set this parameter with the package name of your Android app (for example: "com.yourdomain.app"). As a result, after signing in with Google+, users have the option to send your Android app to their device instantly, without leaving your website. As a preliminary step you'll need to Utilize Google+ Native Android Sign-on on your Android app. The package name passed to this parameter is the same one you enter when enabling the Google+ API.
  headerText string Sets the plugin's header text.
  includeAllIdentities Boolean The default value of this parameter is 'false'. If set to 'true', you will receive all the user's identities, including those with expired sessions. Each <identity> entry will have an attribute <isExpiredSession> that will be 'true' when the session has expired for that provider (or is otherwise inactive) and 'false' if it is active.
  includeiRank Boolean Deprecated. This parameter's default value is 'false'. If set to 'true' you will receive the user's iRank (influencer rank) in the response User object.
  lastLoginButtonSize integer This parameter is relevant only if the lastLoginIndication parameter is set to 'welcome'. This parameter defines the size of the login network button on the 'welcome back' screen. The parameter defines the button height in pixels.
  lastLoginIndication string The Login plugin gives an indication of the last provider to which the user was logged in.
You may change the way the last login provider is presented using this parameter. Currently supported values for this parameter are:
  • "border" (default) - Last login provider's logo will be displayed first and will be surrounded with a green border.
  • "welcome" - This option changes the view of the plugin. The plugin will show a "Welcome back" view, with the user name and with only the last login provider's logo as a login option. The view includes a "Not you?" link next to the user name and a "Connect using a different service" link. Both links take the Login plugin to the regular view. When "Not you?" is clicked, the plugin sets forceAuthentication to true for the following login attempts on the same page.
  • "none" - There will be no indication for last login provider.

You may find more information about this feature and screenshots in the Last Logged In section of the Developer's Guide.
  onButtonClicked function
ref
A reference to an event handler function that will be called when one of the plugin's buttons is clicked.
  onClose function ref A reference to an event handler function that will be called in one of the following scenarios:
  • If the plugin is displayed as a popup the event will be fired when the plugin closes.
  • If the plugin is embedded in page the event will be fired when the user clicks a button that indicates the dialog should be closed. In this case the dialog will not hide itself automatically.
  onError function ref A reference to an event handler function that will be called when an error occurs.
  onLoad function ref A reference to an event handler function that will be called when the plugin has finished drawing itself.
  onLogin function
ref
A reference to a function that is called when the user is successfully authenticated by Gigya.
  pendingRegistration Boolean The default value of this parameter is 'true'. The default behavior - when a new user logs-in (registers) his new Gigya account is not considered final until socialize.notifyRegistration is called. While being not-final the identities associated with this account can be connected to another account without causing an error.
If this parameter is set to 'false' - when a new user logs-in (registers), his new Gigya account is final immediately.
Note: the value of this parameter overrides the value of the newUsersPendingRegistration parameter in the global configuration object.
  redirectURL URL A URL to which to redirect the user when the login completes successfully.
The following additional parameters will be appended to the URL string:
UID, UIDSig, timestamp, loginProvider, loginProviderUID, 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 supplied, the onLogin global event will not be called.
Note: we strongly advise providing a secure Https URL.
  requiredCapabilities string A comma separated list of any of the following capabilities: Login, Notifications, Actions, Friends, Status, Photos, Contacts. Only providers that are available and support all the required capabilities will be visible.
  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.
Note: the value of this parameter overrides the value of the identical parameter in the global configuration object.
  showTermsLink Boolean Show or hide the "Terms" link. Clicking the "Terms" link opens Gigya's Legal Notices page.
  showTooltips Boolean The default value of this parameter is 'true'.  Determines whether a tooltip will be displayed when the mouse hovers over a social network icon. The tooltip presents the social network's full name.
  showWhatsThis Boolean Indicates whether to show or hide a "What's this" link. When the user rolls over the link, a hint will pop up describing the Login plugin. By default the value of this parameter is 'false'. In order for the "What's this" link to appear, you must specify a width of at least 150px and a height of at least 100px on the UI component.
login_whats_this.gif
  whatsThisText string This parameter is relevant only if the showWhatsThis parameter is set to 'true'. Using this parameter you may define the text that will appear in the pop-up hint (see screenshot above). The default text is: "You can use your account from one of these services to sign into the site".
  useHTML Boolean Deprecated. The Login plugin is available in both Flash and HTML versions. By default, the HTML version is used. You may override the default behavior. Setting this parameter with the value 'false', will force Gigya to use the Flash version.

 

customButton Object

A JSON-encoded object representing a single custom button:

Required Field Name Type Description
Required providerName string The provider name to display in the login popup window and to remember as the last login. 
  iconURL string The URL of the provider icon to display on the button (the icon will be resized to fit the selected size).
  lastLoginIconURL string The URL of the provider icon to display on the button when this provider was the last one used for login.
Optional type string Can be "OpenID", "saml", or "eventOnly". The default value is "eventOnly", which means that only an onButtonClicked event will be fired.
  idpName string The name of the SAML provider when type is "saml". Login will be attempted with the name provided here with a "saml-" prefix, e.g. "saml-idp1".
  position integer The index of the button within the plugin. The regular provider buttons should be organized to fill the gaps between custom buttons. The default is 1.
  logoURL string
 The URL of the provider to display in the login dialog.
  openIDURL string
A URL template representing an OpenID user where $USERNAME$ represents the placeholder for the username. For example: http://aol.com$USERNAME$. When this parameter is provided it should be passed on to the server login call. Required if type='openID'. When using a "saml" button, this field is not valid.

 

Plugin Events

An Event Handler is a JavaScript function with the following signature:

functionName(eventObj)

The single argument, eventObj, contains information about the event and has different fields for different events.

The following tables specify the list of fields available in the eventObj for each event:

 

onLoad Event Data

Field Type Description
eventName string The name of the event.
sourcestringThe source plugin that generated this event. The value of this field is the name of the plugin's API method, e.g. 'showLoginUI', 'showCommentsUI', etc.
context object The context object passed by the application as parameter to the API method, or null if no context object has been passed.

 

onError Event Data

Field Type Description
eventName string The name of the event.
sourcestringThe source plugin that generated this event. The value of this field is the name of the plugin's API method, e.g. 'showLoginUI', 'showCommentsUI', etc.
context object The context object passed by the application as parameter to the API method, or null if no context object has been passed.
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.
errorDetails string This field will contain the exception info, if available.

onClose Event Data

Field Type Description
eventName string The name of the event.
sourcestringThe source plugin that generated this event. The value of this field is the name of the plugin's API method, e.g. 'showLoginUI', 'showCommentsUI', etc.
context object The context object passed by the application as parameter to the API method, or null if no context object has been passed.

 

onLogin Event Data

Field Type Description
eventName string The name of the event: 'login'.
source string The source plugin that generated this event. The value of this field is the name of the plugin's API method, in this case 'showLoginUI'.
Note: this field will not be available if the source of this event is not a plugin (e.g. if the source is a socialize.login API call).
context object The context object passed as a parameter to the plugin/method that triggered this event, or null if no object was passed.
user User object User object with updated information for the current user.
UIDSignature  string The signature that should be used for login verification, as described under the Validate the UID Signature in the Social Sign-On Process section.
signatureTimestamp  string The GMT time of the response in UNIX time format (i.e. the number of seconds since Jan. 1st 1970). The time stamp should be used for login verification, as described under the Validate the UID Signature in the Social Sign-On Process section.
UID string The User ID that should be used for login verification*.
Note: The UID string must be encoded using the encodeURIComponent() function before sending it from your client to your server.
provider string The name of the provider that the user used in order to login (e.g. "Facebook"). Note: If this event is fired as a result of a socialize.notifyLogin call, i.e. the user was authenticated by your site, the provider field will be set to "site".
* To learn more about login verification, please refer to the Validate the UID Signature in the Social Sign-On Process section in the Security page of the Developer's Guide.

 

onButtonClicked Event Data

Field Type Description
eventName string The name of the event.
sourcestringThe source plugin that generated this event. The value of this field is the name of the plugin's API method, e.g. 'showLoginUI', 'showCommentsUI', etc.
context object The context object passed by the application as parameter to the API method, or null if no context object has been passed.
button customButton object The object representing the custom button that has been clicked. If the clicked button is not a custom button, no CustomButton object will be returned.

 

Global Event Triggered

By using this plugin, the onLogin global event may be triggered (the onLogin global event is fired, when a user successfully logs in to Gigya). To register an event handler use the socialize.addEventHandlers API method. Refer to the onLogin event data. Refer to the Events page in the Developer's Guide - to learn more about how to handle events generated by the Gigya service.

 

Code Sample

var context = {
    msg:'This is my params.context.msg'
};	

var params = { 
    captionText: 'This is my caption text',
    headerText: 'This is my header content',
    showTermsLink: false,
    redirectURL: 'http://www.yourNewSite.com',
    context: context,
};

params['onLoad'] = function(evt) {              
    evt['msg'] = 'After onLoad';
    var msg = 'Event name is : ' + evt.eventName +'\n';
    msg+= 'evt[\'msg\'] is : ' + evt['msg']+'\n';
    msg+= 'context.msg is : ' + evt['context']['msg'];            
    alert(msg);
};

gigya.socialize.showLoginUI(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.
  • To run the code on your own domain, add your Gigya API key to the socialize.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.

Tags

This page has no custom tags set.

Comments

You must to post a comment.

Attachments