accounts.showScreenSet JS

Skip to end of metadata
Go to start of metadata

Description

This method loads a screen-set, binds it to its functionality, and, by default renders, the initial screen of the screen-set. 

Note: If you plan on integrating Gigya's Accounts API, we highly recommend reading the Registration-as-a-Service Guide. Registration-as-a-Service (RaaS) is a premium platform that requires separate activation. If RaaS is not part of your site package, please contact Gigya by filling in a support form through the Console. You can access the support page by clicking Support on the upper menu after logging into the Gigya Console.

Syntax

 

Parameters

The following table lists the available parameters:

RequiredNameTypeDescription
 

screenSetstring

A reference to the screen-set to be presented. The value of this parameter is the ID of a screen-set. The screen-set is either defined on the same page from which this method is called, or it is stored on Gigya servers. For the default screen-set names, see Default Screen-sets.

Important: When using custom screen-sets, ensure that the default screen-sets in your Site's Policies are defined and configured correctly. 

  • When a user is redirected back to your site, the previous screen-set data is lost and if any errors are triggered, the necessary screens to display will be determined from the default screen-set as defined within your Site Policies .


containerIDstring An ID of a <div> element on the page in which you want to display the screens. If this parameter is not  specified then the screens will be displayed as a dialog (popup) at the center of the page.
authFlow stringUsing 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 below). 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.
    The context object will not be passed when authFlow: 'redirect'.
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.
contextobjectA developer created object that will be passed back unchanged to the event handlers of any event triggered as a consequence of using this screen-set. The context object will be passed as one of the fields of the  eventObj  received by the event handler (see the  Events  sections below).
customButtonsarray 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": "//developers.gigya.com/download/attachments/15795144/IDP.png",
        "logoURL": "",
        "lastLoginIconURL":"//developers.gigya.com/download/attachments/15795144/IDP.png",
        "position":"3"
    },
    {   // customButton object #2
        "type": "saml",
        "providerName":"Gateway Two",
        "idpName":"testIdp-gig02",
        "iconURL": "//developers.gigya.com/download/attachments/15795144/IDP.png",
        "logoURL": "",
        "lastLoginIconURL":"//developers.gigya.com/download/attachments/15795144/IDP.png",
        "position":"4"
    },
    {   // customButton object #3 - IMPORTANT: openID Only works in showLoginUI version 1!
        "type": "openID",
        "providerName":"Flickr",
        "iconURL": "https://s3.amazonaws.com/wikifiles.gigya.com/images/flickr.png",
        "logoURL": "https://s3.amazonaws.com/wikifiles.gigya.com/images/flickr_large.png",
        "lastLoginIconURL":"https://s3.amazonaws.com/wikifiles.gigya.com/images/flickr.png",
        "position":"5",
        "openIDURL": "https://me.yahoo.com/$USERNAME$"
    },
	{   // customButton object #4 - IMPORTANT: oidc Only works in showLoginUI version 2!
        "type": "oidc",
        "providerName":"Gateway Four",
        "opName":"testOIDC-gig04",
        "iconURL": "http://developers.gigya.com/download/attachments/15795144/IDP.png",
        "logoURL": "",
        "lastLoginIconURL":"//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 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.

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 objectDeprecated, use customButtons, above.
 
customLangJSON objectA JSON object consisting of key/value pairs. For a complete list of editable keys, see Customizing Screen-Set Error Messages.
dialogStylestring

Specifies the container style of the screen-set. Options are:

  • modern - (Default) Uses the default updated and responsive dialog style for the screen-set.
  • legacy - Retains pre-October 26th, 2015 dialog style, however, screens remain responsive.

Note: The default value of modern only applies to screen-sets created after October 26th, 2015. Screen-Sets created before this date will default to legacy

deviceTypestring

Specifies the type of the device the UI is to be displayed on. 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 document <title></title> section of your page!
<meta name="viewport" content="width=device-width"> 

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

enabledProvidersstring

A comma-delimited list of provider names to include in the method execution. This parameter enables you to dynamically change the providers displayed in the screen-set. If you do not set this parameter, by default all the providers are enabled (i.e., the screen-set will display all connected providers).
For example, if you would like the screen-set to only show 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).  

In order to use this parameter to dynamically load providers in your screen-set, make sure not to define providers in the UI Builder or in markup. If you define providers directly in the screen-set (in the UI Builder or in markup), those settings will override this parameter.

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

Defines a language to automatically translate Screen-Set error messages. The supported languages and their codes can be found in our Language Support guide.

For example:

lang: "zh-hk"; // Traditional Chinese (Hong Kong)

It is important to note that the lang parameter only changes the language of the returned on-screen errors, to have screen-sets display in a language other than English you must create a Screen-Set Collection for each language you require.

mobileScreenSetstringA screen-set to use on mobile devices. This screen-set should be opened to cover the entire screen and not resized when switching screens.
redirectMethodstringThis parameter is only applicable when redirectURL is specified and it determines how the user info data is passed to the redirectURLs. This parameter accepts two values: 
  • get (default) -  The user info values should be passed as query string parameters.
  • post - The user info should be passed as POST fields.
redirectURLstring

A URL to which to redirect the user when the login process has successfully completed. You must provide an absolute URL - relative URLs are not supported.

 The following additional parameters are 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, provider. 

These parameters are equivalent to the User object fields. Please find the parameters' description in the User object reference page.

 When redirectURL is explicitly defined by the partner the user object fields should always be sent with the redirect regardless of the authFlow mode.

This parameter is required if using authFlow: 'redirect' (above).

Note: We strongly advise providing a secure (sslHTTPS URL.


regSourcestring

Records the source of the registration. The default value is the URL of the current page but it can be any string value. regSource is stored in the account and can be used by verification emails to determine which page should be opened (see accounts.set Policies). Can also be set via the Global Conf object.

regTokenstringA ticket that is used to complete the registration process. This parameter may be used in a scenario where a user may begin registration via social login on one page but the site redirects them to a registration page to complete his registration.
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 set the session expiration via individual API methods or with each request, such as when the site session is controlled by a CMS (e.g., Drupal). 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).
startScreenstringSpecifies which screen of the screen-set to render initially. The value of this parameter is the ID of a screenBy default, if this parameter is not specified, Gigya will initially present the first screen defined within the screen-set. For names of screens within the default screen-sets, see the  Default Screen-sets.

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

Events Registration Parameters


x
onErrorfunction refA reference to an event handler function that will be called when an error occurs.

x
onBeforeSubmitfunction refA reference to an event handler function that will be called before a form is submitted. This event gives you an opportunity to perform certain actions before the form is submitted, or cancel the submission.

x
onAfterSubmitfunction refA reference to an event handler function that will be called after a form is submitted.

x
onBeforeScreenLoadfunction refA reference to a function that will be called before a new screen is rendered. This event gives you an opportunity to cancel the navigation.

x
onAfterScreenLoadfunction refA reference to a function that will be called after a new screen is rendered. 

x
onFieldChangedfunction refA reference to an event handler function that will be called when a field is changed in a managed form.

x
onHidefunction refA reference to an event handler function that will be called when a user clicks the "X" (close) button or the screen is hidden following the end of the flow.

 

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.

Registering Event Listeners

Alongside the screenSet Events listed above, Gigya's events are divided into two types - plugin events and global events.

To register a handler for a plugin event, pass the event handler method name as an argument of the method that generates the plugin.
For example:

function errorHandler(eventObj) {
    alert("failed with error" + eventObj.eventName);
    //Some error handling
}

function formCheck(eventObj){
    if (eventObj.formData.email != eventObj.profile.email){
        alert("you are about to change your email!");
    }
}

gigya.accounts.showScreenSet({ 
    screenSet: '<myScreenSet_name>',
    onError: errorHandler,
    onBeforeSubmit: formCheck
});
Run this example

Registering to global events is done by calling the addEventHandlers method.

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.
  • In some cases it is necessary to connect/login the user to a provider ? prior to calling the API method. You can learn more in the Social Login guide.

Event Data

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

For information regarding the onLogin global event, see the onLogin Event Data section.

Note: In some cases the e vent handler function may return a Boolean value. This is specified below each table.

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.
screenstringThe ID of the screen that contains the form that failed.
formstringThe ID of the form that failed.
responseJSONThe response of the encapsulated API call that failed.

onBeforeSubmit 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.
screenstringThe ID of the screen that contains the form that is about to be submitted.
formstringThe ID of the form that is about to be submitted.
profileProfile objectA JSON object holding the user's profile fields, as known before the form submission. 
formDataJSON objectA JSON object holding a copy of the form data which is about to be sent. Note that changes to this data will not affect the actual form data submitted.
nextScreenstringThe ID of the screen about to be loaded.

Return Value: The event handler function may return "false" to cancel the submission.

onAfterSubmit 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.
screenstringThe ID of the screen that contains the form that is about to be submitted.
formstringThe ID of the form that is about to be submitted.
profileProfile objectA JSON object holding the user's profile fields, as known after the form submission. 
dataJSON objectA JSON object holding site custom data fields related to the user, as known before the form submission.
responseJSON objectThe response of the form's submit operation (the response of the encapsulated Account API  call).

onBeforeScreenLoad 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.
currentScreenstringThe ID of the current screen, before the screen switch.
formstringThe ID of the form that triggered this screen switch.
profileProfile objectA JSON object holding the user's profile fields. You may modify the values of the fields in this object, and the modified data will be used in subsequent screens.
dataJSON objectA JSON object holding site custom data fields related to the user, as known before the form submission. You may modify the values of the fields in this object, and the modified data will be used in subsequent screens.
nextScreenstringThe ID of the screen about to be loaded.
responseJSONThe response of the previous screen's submit operation (the response of the encapsulated Account API call).

Return Value: The event handler function may return "false" to cancel the next screen load or "true" to continue loading the screen.

onAfterScreenLoad 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.
currentScreenstringThe ID of the current screen, before the screen switch.
formstringThe ID of the form that triggered this screen switch.
profileProfile objectA JSON object holding the user's profile fields. You may modify the values of the fields in this object, and the modified data will be used in subsequent screens.
dataJSON objectA JSON object holding site custom data fields related to the user, as known before the form submission. You may modify the values of the fields in this object, and the modified data will be used in subsequent screens.
responseJSONThe response of the previous screen's submit operation (the response of the encapsulated Account API call).

onFieldChanged 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.
screenstringThe ID of the screen that contains the form that contains the changed field.
formstringThe ID of the form that contains the changed field.
fieldstringThe name of the form field that changed.
isValidBooleanIndicates whether the field is currently valid or in an error state.
errMsgstringThe error message associated with the field, if it is in an error state (this the same value that would be displayed in " gigya-error-msg ").
valuestringThe value of the field.

onHide 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.
reasonstringThe reason the screen-set closed; can be either "canceled" or "finished".

 

 

Code Sample

<!-- the screen-set definition -->
<div  class="gigya-screen-set"  id="my-screen-set"  data-start-screen="screen1" style="display:none">
    <div class="gigya-screen"  id="screen1">   ...  </div>
    <div class="gigya-screen"  id="screen2" >   ...  </div>
    ...
</div>
...
<div id="userScreensDiv"><!-- the screens are displayed here --></div> 
...
<script>
// Load screen-set
var params={
    screenSet: "my-screen-set", 
    containerID:"userScreensDiv"
}
gigya.accounts.showScreenSet(params);
</script>

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.
  • In some cases it is necessary to connect/login the user to a provider ? prior to calling the API method. You can learn more in the Social Login guide.

You may find working examples using accounts.showScreenSet in Screen-sets Hosted on Gigy's demo site and on the Screen-set on Page demo.