Global Configuration

Skip to end of metadata
Go to start of metadata

Description

Define the global configuration for your site or site group, accessible by Gigya's Web SDK, hosted by Gigya and edited within the Gigya Console. These configurations 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.

Global Configuration 

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

 

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

Remember to save your changes after editing this file.

Mobile Support

The parameters defined in the Global 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)

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",
        	"idpName":"testIdp-gig01",
        	"iconURL": "https://developers.gigya.com/download/attachments/15795144/IDP.png",
        	"logoURL": "",
            "lastLoginIconURL":"https://developers.gigya.com/download/attachments/15795144/Externalidp_LastLogin.png",
        	"position":"3"
    	}
	],
    
    // Bind globally to events.
    // See: https://developers.gigya.com/display/GD/Events#Events-OverridingtheDefaultEventMap
    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.

 

Global Conf JSON Object

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

<script type="text/javascript" src="https://cdns.gigya.com/js/gigya.js?apiKey=INSERT-YOUR-APIKEY-HERE">
{
  autoLogin: true,
  enabledProviders: 'facebook,twitter'
}
</script>

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

Important

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

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

Individual sites have unique API Keys within the Gigya Console. If you have multiple sites within your organization, verify the API Key you are using is the correct API for the specific site.

 

Another option is to set the global 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 global configuration object with a global variable, you must declare it before the gigya.js script is loaded.

Additionally, although the global Conf object can accept any parameter that is used by any Gigya 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 global Conf 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 application key associated with the calling application. An API Key may be obtained from the Site Dashboard page on Gigya's website.
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.

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

The customEventMap object is used to override or add to the events tracked by Gigya 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 Registration-as-a-Service 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.     
deviceTypestring

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.
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, yahoo, messenger, googleplus, linkedin, aol, foursquare, instagramrenren, qq, sina, vkontakte, blogger, wordpress, paypal, paypaloauth, amazon, netlog, orangefrance, mixi, yahoojapan, odnoklassnikispiceworks, livedoor, vznet, wechat, xing, line.
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, 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, 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.
facebookExtraPermissions

 

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

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" 
src="https://cdns.gigya.com/js/gigya.js?apiKey=INSERT-YOUR-APIKEY-HERE&lang=es">
{
  autoLogin: true,
  enabledProviders: 'facebook,twitter'
}
</script>
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, instagram, 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.

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.
sessionExpirationinteger
This parameter defines the length of time that Gigya should keep the user's login session valid. It can be configured via Global 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.

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

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

shortURLsstring
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:
    • fw.to for users of the US data center.
    • shr.gs for users of the European data center.
    • vst.to for users of the Australian data center.
    • socli.ru for users of the Russian data center.
    • s.gigya-api.cn 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:

ProviderNote
FacebookN/A
TwitterN/A
LinkedInShortened URL is posted to the social network but traffic reports show abbreviated URL (e.g., http://developers.gigya.com/display/GD/showShareBarUI+JS is abbreviated to developers.gigya.com).
MicrosoftNot for share. (Note: messenger has been replaced by microsoft, however, for backward compatibility, either can be used).
DeliciousShortened URL is posted to the social network but traffic reports show abbreviated URL (e.g., http://developers.gigya.com/display/GD/showShareBarUI+JS is abbreviated to developers.gigya.com).
WhatsAppOnly on mobile.
RedditN/A
GooglePlusN/A
Google BookmarksN/A
VKontakteN/A
nk.plN/A
XingN/A
TuentiN/A
HatenaN/A
PinterestShortened URL is posted to the social network but traffic reports show abbreviated URL (e.g., http://developers.gigya.com/display/GD/showShareBarUI+JS is abbreviated to developers.gigya.com).
BaiduN/A
FriendFeedN/A
TumblrN/A
SinaN/A
mixiN/A

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.
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.
Parameters used when initializing socialize: 
autoLoginBoolean

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.

 

Global Configuration in a Site Group Scenario

When working with site groups, the global configuration of the parent is inherited by the child sites. If you define values for the same parameters in the global conf 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 Global Conf object 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 global 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="http://cdn.gigya.com/js/gigya.js?apiKey=INSERT-YOUR-APIKEY-HERE">
{
   enabledProviders: 'facebook,twitter'
};
</script>
<script>
var conf = {
    enabledProviders:  'yahoo,googleplus'
 };
</script>
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 global Conf 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

Events

 

 

 


  • No labels