socialize.showLoginUI JS

Skip to end of metadata
Go to start of metadata

Description

Displays Gigya's Social Login plugin, which lists all the available providers' logos as login options, enabling the user to log into your site via their social network or webmail account.

Notes: 

  • All new implementations of the login plugin must use version 2. Apply this by setting the version parameter in this API to 2. 
  • Make sure that all pages using socialize.showLoginUI have a <!DOCTYPE html> tag preceding the <html> tag of your pages for backward browser compatibility.

Supporting Providers

  • By default, the plugin displays the logos of the following providers: Facebook, Twitter, Google+, LinkedIn, Yahoo!, Microsoft, Instagram, Odnoklassniki, Foursquare, renren, Tencent QQ, Sina Weibo, Vkontakte, AOL, WordPress, Blogger, Line, and WeChat.
  • The following providers are also supported and may be added explicitly: Amazon, Livedoor, mixi, Netlog, Orange France, PayPal, PayPalOAuth,  Spiceworks, Xing, Yahoo! Japan .
  • 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.

Plugin Design and Options

This is the default design of the plugin:

 

To view the popup version, click here.

 

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.

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

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.

 

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

 

 

Parameters

The following table lists the available parameters:

RequiredNameTypeDescription
versioninteger

Gigya offers a new improved version of the Login plugi n. To use the new plugin set this parameter to "2". All new implementations are required to use the new version, although existing implementations without this parameter will continue to function.

widthstringSets the width you desire for the plugin. You may also use percentages to set the width, e.g., width: 80%, in which case the plugin will be responsive. The login plugin supports the percentage option from version 2, so using the version parameter, set the version to "2" if you haven't yet.
height integer Determines the height you desire for the plugin.
containerID string An ID of a <DIV> element on the page in which you want to display the plugin. If this parameter is not provided then the plugin will be displayed as a popup at the center of the page. Please refer to Dialog or Embedded section for extended explanation.
captionText string Sets the caption text. This parameter is relevant only when the plugin is in a popup mode (i.e. if the containerID/container parameter is not provided). If the plugin is embedded in the page then the caption is not presented.
context object A reference to a developer created object that will be passed back unchanged to the event handlers of any event triggered as a consequence of using this plugin. The context object will be passed as one of the fields of the eventObj received by the event handler (see extended explanation in the "Plugin Events" and in the "Global Event Triggered" sections below).

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

authCodeOnlyBooleanThis 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.
authFlowstringUsing 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. Note that this option will only work if CNAME is configured. When using this mode, the onLogin event is not fired.
autoDetectUserProvidersstringThis 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:
buttonSizeinteger

A number denoting the height of the buttons in pixels. Width will be set in proportion to the height.

buttonsStylestringThis parameter enables selecting one of the pre-defined design styles for the network buttons on the Login UI. Currently Gigya offers the following design styles:
  • "standard" (default):

  • "fullLogo":

  • "fullLogoColored":

  • "signInWith":

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.

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.

 
customButtonsan array of JSON objects

This parameter is used to add multiple customButton objects to the Gigya Social Login widget either directly or when using Screen-Sets. You can use customButton objects to add custom login options for any combination of OpenID Connect and/or SAML providers. See Adding a Custom OpenID Provider and Adding a SAML Login Provider, respectively.

 Expand a code example
customButtons= [
    {   // customButton object #1
        "type": "saml",
        "providerName":"Gateway One",
        "idpName":"testIdp-gig01",
        "iconURL": "http://developers.gigya.com/download/attachments/15795144/IDP.png",
        "logoURL": "",
        "lastLoginIconURL":"http://developers.gigya.com/download/attachments/15795144/IDP.png",
        "position":"4"
    },
    {   // customButton object #2
        "type": "saml",
        "providerName":"Gateway Two",
        "idpName":"testIdp-gig02",
        "iconURL": "http://developers.gigya.com/download/attachments/15795144/IDP.png",
        "logoURL": "",
        "lastLoginIconURL":"http://developers.gigya.com/download/attachments/15795144/IDP.png",
        "position":"5"
    },
    {   // customButton object #3
        "type": "OpenID",
        "providerName":"Gateway Three",
        "idpName":"testOIDC-gig03",
        "iconURL": "http://developers.gigya.com/download/attachments/15795144/IDP.png",
        "logoURL": "",
        "lastLoginIconURL":"http://developers.gigya.com/download/attachments/15795144/IDP.png",
        "position":"6"
    }
];
gigya.accounts.showScreenSet({screenSet:'Default-RegistrationLogin',customButtons})

It is important to note that any unique user can only be connected to a single SAML provider.

When using a customButtons array with showAddConnectionsUI, you should only include a single button object in the array. If you include multiple custom button objects, only the first button defined will be displayed in the UI.

customButtoncustomButton object

This parameter is deprecated. Use customButtons, above.

 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.

deviceType

string

Specifies the type of the device the UI is to be displayed on (see the "pagingButtonStyle" parameter). The possible values are:

  • desktop (default)
  • mobile
  • auto - When this value is used, you must also include the following meta tag in the <head> section of your site for mobile devices to be automatically recognized:
// This must be the first item beneath the 
// <title></title> section of your page!
<meta name="viewport" content="width=device-width">

Otherwise, the device will be recognized as a desktop device.

disabledProvidersstring
A comma-delimited list of provider names to exclude in the method execution. This parameter gives the possibility to specify providers to which you do not 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 Twitter, define: disabledProviders: "twitter".
Valid provider names include:
facebook, twitter, googleplus, linkedin, yahoo, microsoft, aol, foursquare, instagram, vkontakte, renren, qq, sina, mixi, yahoojapan, odnoklassniki, spiceworks, wordpress, blogger, paypal, paypaloauth, netlog, orangefrance, livedoor, line, amazon, xing, wechat (Note: messenger has been replaced by microsoft, however, for backward compatibility, either can be used).

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.

enabledProvidersstring
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 Twitter, define: enabledProviders: "twitter".
Valid provider names include:
facebook, twitter, googleplus, linkedin, yahoo, microsoft, aol, foursquare, instagram, vkontakte, renren, qq, sina, mixi, yahoojapan, odnoklassniki, spiceworks, wordpress, blogger, paypal, paypaloauth, netlog, orangefrance, livedoor, line, amazon, xing, wechat (Note: messenger has been replaced by microsoft, however, for backward compatibility, either can be used). 

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.

extraFieldsstring
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, timezone, and samlData.

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.

facebookExtraPermissionsstringA 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: 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.

forceAuthenticationBooleanThe default value of this parameter is 'false'. If it is set to 'true', the user is forced to provide their social network credentials during login - even if the user is already connected to the social network. This parameter is currently supported by Facebook, Twitter, Renren, and LinkedIn. 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.
googleExtraPermissionsstringThis 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: 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.

googlePlayAppIDstringThe 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.
headerTextstringSets the plugin's header text.
includeAllIdentitiesBooleanThe 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  entry will have an attribute that will be 'true' when the session has expired for that provider (or is otherwise inactive) and 'false' if it is active.
lastLoginButtonSizeintegerThis 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.
lastLoginIndicationstringThe 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.
onButtonClickedfunction refA reference to an event handler function that will be called when one of the plugin's buttons is clicked.
onClosefunction refA 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.
onErrorfunction refA reference to an event handler function that will be called when an error occurs.
onLoadfunction refA reference to an event handler function that will be called when the plugin has finished drawing itself.
onLoginfunction refA reference to a function that is called when the user is successfully authenticated by Gigya.

pagingButtonStyle

string

Controls the looks of the "next/previous" buttons. The possible values are:

  • arrows - The familiar arrow buttons:

  • newArrows (default) - Arrows that are slightly further away from the login buttons, for better usability in a touch input:

  • floating - Floating buttons optimized for touch input in small screen sizes:

  • auto - This value sets the buttons to floating if the deviceType parameter has been set to "mobile" or the device has been recognized as mobile (see deviceType for details), and the width of the Login Plugin UI has been set to under 500px. Otherwise, the buttons are set to newArrows.

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.

requiredCapabilitiesstringA 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.
sessionExpirationinteger

This parameter defines the length of time that Gigya should keep the user's login session valid.

The expected values are:

  •  0 - Session expires when the browser closes.

  • -1 - Session ends immediately and a cookie is stored on the site visitor's client (browser) which allows the site to change the expiration while the user is logged in. Useful if you always and only set the session expiration via individual API methods. For additional information see how to Control Session Expiration.

  • -2 - Session is valid forever.

  • Any custom integer, defined as the number of seconds to keep the session active, e.g., 3600  (which is equivalent to 1 hour).  In this case, the session will remain valid until it expires or until it is explicitly ended (e.g., by calling accounts.logout).

You can override global policy settings and the Global conf setting via setting the expiration as a parameter in any of the supported API methods (i.e., notifyLogin). When this parameter is set via an API method, it overrides the value of the identical parameter in Global Conf (the global configuration object).

If this parameter is not set for the API method, the value from Global Conf is used. If the parameter is not set in Global Conf, the login session uses the default.

Defaults: 

  • When RaaS is enabled for the API Key, default expiration is 0 (when the browser closes).
  • When using Social Login (RaaS is not enabled), default expiration is -2 (the session is valid forever and only terminates when the user logs out or the cookie is deleted).
showTermsLinkBooleanShow or hide the Terms link. Clicking the "Terms" link opens Gigya's Legal Notices page.
showTooltipsBooleanThe 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.
showWhatsThisBooleanIndicates 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.
whatsThisTextstringThis 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".
facepilePositionstring Deprecated . This parameter is ignored by the Gigya API.
useHTMLBoolean 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.
includeiRankBoolean 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 .

Unable to render {include} The included page could not be found.

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

FieldTypeDescription
   
eventName string The name of the event.
source string The 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.
contextobject 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

FieldTypeDescription
   
eventName string The name of the event.
source string The 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.
contextobject The context object passed by the application as parameter to the API method, or null if no context object has been passed.
errorCodeintegerThe 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.
errorMessagestringA short textual description of an error, associated with the errorCode, for logging purposes.
errorDetailsstringThis field will contain the exception info, if available.

onClose Event Data

FieldTypeDescription
   
eventName string The name of the event.
source string The 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.
contextobject 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

FieldTypeDescription
eventNamestringThe name of the event: 'login'.
sourcestringThe 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).
contextobjectThe context object passed as a parameter to the plugin/method that triggered this event, or null if no object was passed.
loginModestringThe type of login:
  • standard - the user is logging into an existing account.
  • reAuth the user is proving ownership of an account by logging into it.
providerstringThe 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".
UIDstringThe 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.

UIDSignature stringThe signature that should be used for login verification, as described under the Validate the UID Signature in the Social Sign-On Process section.
userUser objectUser object with updated information for the current user.
signatureTimestamp stringThe 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.

* 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

FieldTypeDescription
   
eventName string The name of the event.
source string The 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.
contextobject The context object passed by the application as parameter to the API method, or null if no context object has been passed.
buttoncustomButton objectThe 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.

You can read more about onLogin event data and Events.

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 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.