SAP Customer Data Cloud Positions

WebSDK Configuration

Skip to end of metadata
Go to start of metadata


Define the configuration for your site or site group, accessible by the SAP Customer Data Cloud Web SDK, hosted by SAP Customer Data Cloud and edited within the Console. These configurations (previously called "Global Configuration") apply to all the pages of your site or site group which load the Web SDK. If necessary, you can then manually add additional parameters to the global Conf JSON object on a page-by-page basis. You can add any supported parameters to the WebSDK CONF object that are supported by any of the JS APIs; then, when calling an API via the WebSDK, if the API accepts a parameter that is predefined in the CONF object, it will use the values there, unless overridden in the actual API call. Note that only the most commonly used parameters are listed on this page and you can insert any parameters unless otherwise noted that they are specifically not supported in their respective API documentation. It is also important to remember that the values defined in the CONF object will apply to ALL methods that accept that parameter as valid.

WebSDK Configuration 

To access the WebSDK Configuration tab in the Console, navigate to the Site Settings of the site you want to edit and select WebSDK Configuration from the left-hand menu.

For available Events that can be customized using the WebSDK Configuration, see Overriding the Default Event Map.

Remember to save your changes after editing this file.

Mobile Support

The parameters defined in the WebSDK Configuration work by default on mobile devices. This provides for great flexibility, such as the ability to define custom buttons for a SAML provider, that appear in your login screens across devices. 

Common Use Cases

  • Define the enabled social providers
    (Requires removing any providers listed in the Social Login widget of all your screens)

  • Set the default language (see Advanced Customizations and Localization and the description for the lang parameter on this page)
  • Create custom buttons for SAML providers (see the following example)


The following example demonstrates adding a customButtons array to your screen-set for a SAML or OIDC login provider. 

    // A comma-delimited list of provider names to enable.
    enabledProviders: '*',

    // Define the language of Gigya's user interface and error message.
    lang: 'en',
    // Add an OIDC Custom Button to your Screen-Sets
	customButtons: [
        	"type": "oidc",
        	"providerName":"Gateway One",
        	"iconURL": "",
        	"logoURL": "",
    // Bind globally to events.
    // See:
    customEventMap: {
        eventMap: [{
            events: '*',
            args: [function(e) {
                return e;
            method: function(e) {
                if (e.eventName === 'login') {
                    // Handle login event here.
                    console.log("login fired from global Conf");
                } else if (e.eventName === 'logout') {
                    // Handle logout event here.
                    console.log("logout fired from global Conf");


The above code will result in a Screen-Set that appears like the following.

JSON Object

The WebSDK JSON object represents a site's basic configuration: it sets variables before loading gigya.js. This allows the variables to be used when initializing the SAP Customer Data Cloud Web SDK. The stored configuration parameters that are set in this object are common to all the SAP Customer Data Cloud API calls on that page. You may override the WebSDK configuration for a specific page, using the following syntax:

<script type="text/javascript" src="">
  autoLogin: true,
  enabledProviders: 'facebook,twitter'

Note that autoLogin and enabledProviders are only examples of variables that can be set here.


The gigya.js src must be loaded in the <head> of every page within your site that uses SAP Customer Data Cloud services, and should be the first element, whenever possible.

The gigya.js src should only be called once on any page.

Another option is to set the WebSDK configuration object with a global variable, instead of the inner text of gigya.js script tag:


window.__gigyaConf = {enabledProviders:'facebook,twitter'};

If you choose to set the WebSDK configuration object with a global variable, you must declare it before the gigya.js script is loaded.

Additionally, although the WebSDK configuration can accept any parameter that is used by any SAP Customer Data Cloud API, all possible parameters are not listed in this table. The most commonly used parameters are listed below, because, although many APIs may use the same parameter, you may not necessarily want the value of that parameter to be the same for all APIs, i.e., setting the containerID parameter within the configuration JSON object will cause all APIs that accept a containerID to display in the same defined <div> overwriting any previously displayed UI.


Data Members


RequiredField NameTypeDescription
apiKeystringThe identifier of the site to which these configurations apply. An API Key may be obtained from the Sites page on the Console.
actionCounterPathstringFor use by customers implementing Signals and monitoring Page views. For an example of using actionCounterPath see Top Content configuration in Customer Insights. The actionCounterPath must start with a forward slash "/" (representing the 'root') and can be set to "path" values that were registered on the  Signals page  or through  accounts.registerCounters Setting an actionCounterPath automates page view counting: there is no need to call accounts.incrementCounters (gigya.js must be included in the page)
bypassCookiePolicystringDetermines whether gigya.js should check if third-party cookies are blocked by the user's browser (and implement a workaround if necessary). The possible values are:
  • never: The JS SDK should not check whether third-party cookies are blocked.
  • whenBlockedByDefault: The JS SDK should check if third-party cookies are blocked only if it recognizes a browser that blocks third-party cookies from unvisited websites by default (Safari).
  • always: The JS SDK should always check if third-party cookies are blocked, regardless of the user's browser.

See Blocked Third-Party Cookies for more information.

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.

This property defines whether to use the currently specified screen-set lang or not when sending system emails to the user, TFA, email verification, etc.

The default is true. When set to true, the screen-set will always send the lang parameter with the request. This is the previous legacy behavior.

If set to false, the screen-set will not send the lang parameter in the request, and the email language will be set according to the following hierarchy:

  • If the user has a locale defined and a template exists for that language, then the email will be sent in the user's locale.
  • If the user does not have a locale defined the email template defined as the default in the site's policies will be used.

The customEventMap object is used to override or add to the events tracked by SAP Customer Data Cloud in the default 'Event Map'. For detailed information on using this option, see Overriding the Default Event Map. Note that one use case of both the default Event Map and the custom one is when integrating with Google Analytics

dateFormatstringThe format of the date. The days, months, and years can be represented as follows: 
  • %d - a one-digit representation of the day of the month, 1-31
  • %dd -  a two-digit representation of the day of the month, 01-31
  • %M - a one-digit representation of the month, 1-12
  • %MM - a two-digit representation of the month, 01-12
  • %MMM - the abbreviated name of the month, e.g. Jun, Jul
  • %MMMM - the full name of the month, e.g. July, August
  • %yy - a two-digit representation of the year, 01-99
  • %yyyy - a four-digit representation of the year, 2013

For example: dateFormat: "%d/%M/%yy" - > 29/5/12, or dateFormat: "%MMMM %d, %yyyy" - > May 29, 2012.

defaultRegScreenSet / defaultMobileRegScreenSet

stringFor use by Customer Identity customers. The ID of a previously defined registration screen-set for use in new user registration. Overrides the default registration screen-set defined in accounts.setPolicies.
Customers who want to implement their own registration screen should set this parameter to blank and bind a callback function to the OnError event wherever pending registration error 206001 appears.     

Specifies the type of the device the UI is to be displayed on. The possible values are:

  • desktop
  • 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> of
    // the <head> section of your page!
    <meta name="viewport" content="width=device-width">  


    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).
For example, if you would like the method to apply to all providers except Twitter, define: disabledProviders: "twitter".
Valid provider names include:
amazon, apple, blogger, facebook, foursquare, googleplus, kakao, line, linkedin, livedoor, messenger, mixi, naver, netlog, odnoklassnikiorangefrance, paypaloauth, qq, renren, sina, spiceworks, twitter, vkontakte, wechat, wordpressxing, yahoo, yahoojapan.
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, yahoo, linkedIn, microsoft, googleplus, foursquare, vkontakte, renren, qq, sina, aol, blogger, wordpress".
In addition the following providers are supported and may be added explicitly: 
" netlog, orangefrance, mixi, yahoojapan, spiceworks, livedoor, paypal, paypaloauth, amazon".
You may use the '*' sign as an indication to include all the default providers. If you would like the API methods to apply to Netlog in addition to all the default providers, define: enabledProviders:"*,netlog".
enableSSOTokenbooleanIn an SSO group environment, this parameter must be set to true prior to calling accounts.setSSOToken. See Blocked Third-Party Cookies for additional information.
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, and  Renren. 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.


stringA 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 has already requested.
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 send text messages to the user, define: 
facebookExtraPermissions : "rsvp_event,sms "
Note: use the socialize.getRawData method to pull the extra data. 
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.

Define the language of Gigya's user interface and error message. The supported languages and their codes can be found in our Language Support guide. For example:

lang: "zh-hk";

For best practice, place the lang parameter in the url following the API Key rather than inside the Global conf object.

For Example (to return errors in Spanish):

<script type="text/javascript" 
  autoLogin: true,
  enabledProviders: 'facebook,twitter'
newUsersPendingRegistrationBooleanThe 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.
oauth_tokenstringThe OAuth token returned by Gigya's servers when consuming services in a hybrid client/server model. For more information about requesting an OAuth token, see socialize.getToken
The token is a privileged token that has almost the same permission as using an API key with the secret, and for this reason should only be passed down to the end user when necessary.
providerstringThe optional values for this parameter are: facebook, twitter, googleplus, linkedin, messenger, renren, yahoo, vkontakte, mixi, yahoojapan, odnoklassniki , wechat.

SAML providers are also supported - the format of the provider name is saml-<name> .

See specific API methods that use this parameter to determine expected results.


The number of days since consent was previously given before requesting renewed consent from the user.

regSourcestringOrigin of the registration. Can be any string value. regSource will typically hold the URL of the registration page, the default is the current URL. Can be used to set varying destination pages in accounts.setPolicies.
Note: regSource is populated automatically only when the accounts.showscreenset API call is on the page, otherwise you must populate it yourself. This value can not be changed once it is set.
This parameter defines the length of time that Gigya should keep the user's login session valid. It can be configured via WebSDK Configuration, via an individual API call, or left empty. If no value is specified, the default values are 0 or -2, depending on whether your site uses RaaS or not (see below); Global configuration overrides the default, and setting the value via individual API calls override the global configuration. 

The expected values are:

  •  0 - Session expires when the browser closes. This is the default behavior when RaaS is enabled in your site. This behavior is dependent upon the browser's cookie handling procedures, i.e., Chrome keeps processes running in the background even after the browser is technically closed, this keeps the cookies valid until the background processes are terminated. This value is not supported when using our Mobile SDKs, and the session will behave as if set to -2.

  • -1 - Session ends after a 60 second period; Gigya gives you the option of creating a cookie that is stored on the site visitor's client (browser), allowing the site to control the session length within this 60 second window, after which the session is terminated if no cookie is found. A typical use case is when the session could include sensitive data (such as credit card details), and the session should be short, with the option of restarting the duration when users perform actions. 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 define a session expiration cookie.

    This setting is not supported on Safari.

  • -2 - Session is valid forever. This is the default behavior when RaaS is not enabled in your site. 

  • Any custom integer - Defines the number of seconds the session is active, e.g., 3600  (one hour). 

Using this parameter you may determine whether to use Gigya's URL shortening service for URLs passed in the status parameter. The optional values for this parameter are:
  • 'always' (default): always try to shorten URLs. Where providers permit, URLs are shortened based on the Data Center you are using:
    • for users of the US data center.
    • for users of the European data center.
    • for users of the Australian data center.
    • for users of the Russian data center.
    • for users of the Chinese data center.
  • 'whenRequired': URLs longer than 139 characters are shortened in accordance with provider preferences.
  • 'never' - never shorten URLs. Where providers permit, URLs are left untouched.

To determine your data center see Finding Your Data Center.

URL shortening requirements vary between providers and depend on the particular type of action and its content. URL shortening is available for the following providers:

LinkedInShortened URL is posted to the social network but traffic reports show abbreviated URL (e.g., is abbreviated to
MicrosoftNot for share. (Note: messenger has been replaced by microsoft, however, for backward compatibility, either can be used).
WhatsAppOnly on mobile.
Google BookmarksN/A
PinterestShortened URL is posted to the social network but traffic reports show abbreviated URL (e.g., is abbreviated to

When Gigya's URL shortening service is active, Gigya tracks all the traffic coming from the distributed URLs. In such case, 'Referred Traffic' reports will be available to you.


signIDsBooleanThe default value is "false". If this field is set to "true", the User object returned by socialize.getUserInfo method and the Friend objects returned by socialize.getFriendsInfo or socialize.showFriendSelectorUI methods will be signed by Gigya. To learn more about signatures, please refer to the Security page of the Developer's Guide.
storageDomainOverridestringThe name of your domain on which you wish to store SAP Customer Data Cloud cookies, instead of on This may be used in certain SSO scenarios. This parameter should only be defined on the parent site of your site group.
trackAddressBarSharesBoolean The default value of this parameter is ' false '. If set to ' true ', the  referred traffic that is identified as originally shared after a URL was copied by a user and sent out (via email or other means) will be tracked and used in the Referred Traffic and Referred Traffic by Provider reports.

The frequency (in hours) of session validation for logged-in users. Once every specified amount of hours, the system will check if all required schema fields have the relevant data, and that the session is in accordance with site policies. For sites that implement Customer Consent, this is used to ensure that users who have an active long-lived session (“Remember me”), are asked to re-consent when the active version of a mandatory consent statement changes.

This configuration will not affect mobile sessions. To validate mobile sessions, you should periodically call accounts.verifyLogin.

Parameters used when initializing socialize: 

This parameter determines whether after a user logs in once to the site and visits again, he is automatically logged back into the site if he is logged into Facebook or Google+ at that time. If you set this value to 'true', make sure Native SDK Capabilties are enabled in the Providers Configurations for your app.

The default value is 'false'.

Note that once a user authorizes your app to access his social network account, if you then delete the user's account from Gigya (for whatever reason), and the user returns to your site, the app, already having the user's permissions, will attempt to automatically login the user again, and if successful, a new account will be created for the user.

To be treated as a completely fresh unknown user to your site, the user would have had to revoke your app's permissions prior to returning to your site.

facebookInitParamsJSON objectAn object with Facebook initialization parameters, which can override the original FB.init parameters. This includes channelUrl and other Facebook initialization parameters.
connectWithoutLoginBehaviorstring Deprecated.


WebSDK Configuration in a Site Group Scenario

When working with site groups, the web SDK configuration of the parent is inherited by the child sites. If you define values for the same parameters in the configuration object of both the parent and the child, the configuration for the child will override those of the parent. However, you may write custom code to have the settings of the child site appended to those of the parent, rather than override them. 

For example, parent site A has only Facebook listed under enabled social providers: 

    enabledProviders: ['facebook']

This is the configuration for child site B: 

    enabledProviders: ['twitter']

In this case, a user of child site B that wishes to log in with a social network, will be offered only Twitter as an option. To append Twitter to the existing setting (Facebook) rather than override it, the child site configuration would be: 

    enabledProviders: (siteGroupGlobalConf.enabledProviders || []).concat(['twitter'])

Now the user of child site B will be offered both Facebook and Twitter as social login options. 


Backward Compatibility

The WebSDK configuration as described here replaces an older form of a  conf  object that we still support for backward compatibility. The advantage of the new form is that the variables are set before loading gigya.js, while in the old form they are set after. 

In the old form the  conf  object was created once as a global  var and passed as the first parameter of all API calls, setting global configuration parameters. Originally all our API methods were called with two parameters,  conf  and  params . For example: 

var conf = {
  enabledProviders:  'yahoo,googleplus'
gigya.socialize.getUserInfo(conf, params);


If you are already using the old form of the  conf  object, you may keep using it, although we encourage you to move to the new form. Note that some parameters, such as autoLogin, cannot be set via the old form of the  conf  object, since they must be set before loading gigya.js.

Since we still support the  conf  object as a parameter in API calls, if you decide to pass the  conf  object to an API method, the variables set there will override any identical variables set in the global configuration object (the new form). For example, if the new form WebSDK configuration object defines Facebook and Twitter as the enabled providers, and the  conf  object defines Yahoo and Google+ as the enabled providers, the enabled providers will be Yahoo and Google+:


<script type="text/javascript" src="">
   enabledProviders: 'facebook,twitter'
var conf = {
    enabledProviders:  'yahoo,googleplus'
The  params  object, that used to be the second parameter, is now passed as the only parameter (i.e., gigya.socialize.getUserInfo(params);). The  params object enfolds all the specific parameters of the API method. In the Web SDK Reference you may find per API method the list of parameters ( params object members) that the method accepts - some are required and some are optional. The variables set in the  params  object will override any identical variables set either in the global configuration object or the  conf object if defined. 

Important Note

Be careful not to use any undefined variables inside the configuration object, you will not receive any runtime errors, however, the Web SDK will function erratically and many subsequent method calls may fail with Unauthorized User errors.


Additional Information

accounts.showScreenSet JS





  • No labels