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.
- 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:
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.
The following table lists the available parameters:
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.
|||width||string||Sets 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.|
|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.
|||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:|
|||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:|
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 the following design styles:|
The buttonSize parameter when using signInWith buttonStyle only supports the following sizes (defined in vertical height):
Attempting to set sizes not listed here will result in a corrupted button being displayed within the UI.
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.
|||customButtons||an 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
It is important to note that any unique user can only be connected to a single SAML or OIDC provider (though they may be connected to one of each). If using showLoginUI version 1 to support OpenID, you can only pass a single customButtonsobject within the customButtons array, additional objects are ignored.
For more information see Login.
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.
Specifies the type of the device the UI is to be displayed on (see the "pagingButtonStyle" parameter). The possible values are:
Otherwise, the device will be recognized as a desktop device.
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).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).
For example, if you would like the method to apply to all providers except Twitter, define: disabledProviders: "twitter".
Valid provider names include:
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).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).
For example, if you would like the method to apply only to Twitter, define: enabledProviders: "twitter".
Valid provider names include:
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.
|||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 "
|||forceAuthentication||Boolean||The 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.|
|||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.|
|||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 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.|
|||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:
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:|
|||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.|
Controls the looks of the "next/previous" buttons. The possible values are:
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.
A URL to which to redirect the user when the login completes successfully. The following additional parameters will be appended to the URL string:
If the redirectURL parameter is supplied, the onLogin global event will not be called.
|||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.|
This parameter defines the length of time that Gigya should keep the user's login session valid.
The expected values are:
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.
|||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.|
|||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".|
|||facepilePosition||string||Deprecated . This parameter is ignored by the Gigya API.|
|||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.|
|||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 .|
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
onError Event Data
|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
onLogin Event Data
|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.|
|loginMode||string||The type of login:|
|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".|
|UID||string||The User ID that should be used for login verification*.|
|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.|
|user||User object||A User object with updated information for the current user.|
|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.|
onButtonClicked Event Data
|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.