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.
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.
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.
The above code will result in a Screen-Set that appears like the following.
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:
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:
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.
|||apiKey||string||The identifier of the site to which these configurations apply. An API Key may be obtained from the Sites page on the Console.|
|||actionCounterPath||string||For 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).|
|||bypassCookiePolicy||string||Determines 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:|
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:
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.
|||dateFormat||string||The format of the date. The days, months, and years can be represented as follows: |
For example: dateFormat: "%d/%M/%yy" - > 29/5/12, or dateFormat: "%MMMM %d, %yyyy" - > May 29, 2012.
defaultRegScreenSet / defaultMobileRegScreenSet
|string||For 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:
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, odnoklassniki, orangefrance, paypaloauth, qq, renren, sina, spiceworks, twitter, vkontakte, wechat, wordpress, xing, 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".
|||enableSSOToken||boolean||In an SSO group environment, this parameter must be set to true prior to calling accounts.setSSOToken. See Blocked Third-Party Cookies for additional information.|
|||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, 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.|
|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 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.
|||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.|
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:
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):
|||newUsersPendingRegistration||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.
|||oauth_token||string||The 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.
|||provider||string||The 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.
|||regSource||string||Origin 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:
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:
To determine your data center see Finding Your Data Center.
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.
|||signIDs||Boolean||The 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.|
|||storageDomainOverride||string||The name of your domain on which you wish to store SAP Customer Data Cloud cookies, instead of on gigya.com. This may be used in certain SSO scenarios. This parameter should only be defined on the parent site of your site group.|
|||trackAddressBarShares||Boolean||false The default value of this parameter is ''. 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.
|||facebookInitParams||JSON object||An object with Facebook initialization parameters, which can override the original FB.init parameters. This includes channelUrl and other Facebook initialization parameters.|
WebSDK Configuration in a Site Group Scenario
For example, parent site A has only Facebook listed under enabled social providers: This is the configuration for child site B: 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: Now the user of child site B will be offered both Facebook and Twitter as social login options.
For example, parent site A has only Facebook listed under enabled social providers:
This is the configuration for child site B:
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:
Now the user of child site B will be offered both Facebook and Twitter as social login options.
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:
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+:
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.