SDK is configured using a configuration object passed into the integration snippet and the exponea.start() method. Almost all configuration options are optional and have a default value. You can change them by setting their value in the configuration object.

See the Initialization section for more information about how to initialize SDK. This page documents all configuration options, their default and possible values, and their description.

Example

!function(e,n,t,i,r,a,c){function // ... the rest of the snippet ...
    target: "https://api.exponea.com",
    token: "323d7a16-ba47-12c9-8c2d-0a770a310d68",
    customer: "[email protected]",
    ping: {
      enabled: true
    }
    
    // other configuration options go here
});

Global options

🚧
Note that the configuration options target and token can only be used in the configuration section of the integration snippet, and not in the call to start().

Name	Default value	Possible values	Description
`token` (required)	none	string	Your project token. Find your project token in the project settings. See Tracking for more information.
`target`	`'https://api.exponea.com'`	Valid API endpoint URL string. It is recommended to always use the `https` protocol.	The API endpoint SDK will use for sending and requesting data. For example, SDK will use this URL to send tracked events and request web layers.
`utm_always`	`false`	boolean	If `true`, the UTM parameters specified in `utm_params` are added as properties to every tracked event.
`utm_params`	`[ 'utm_source', 'utm_medium', 'utm_campaign', 'utm_term', 'utm_content', 'gclid', 'campaign_id', ]`	array of strings	The list of UTM parameters added to tracked events if `utm_always` is enabled. The parameters are always added to session events `session_start` and `session_end`.
`track_hash_changes` (deprecated since version `v2.2.0`)	`true`	boolean	This parameter is deprecated. Use `spa_reloading.on_hash_change` instead.
`transfer_identity`	`true`	boolean	If `true`, customer identity is obtained from the URL. This is useful, for example, when a customer clicks on a link in an email you sent them with Email campaigns.
`debug` (new since version `v2.0.0`)	`false`	boolean	Controls whether SDK prints debug messages to the console.
`file_path`	SDK target + `'/js/exponea.min.js'`	string	If specified, the integration snippet uses this URL to load the SDK file. Note that you have to provide a full URL to a Javascript file including the file name and the protocol.
`new_experiments` (new since version `v2.4.0`)	`false`	boolean or an object with options	Used to enable and control how Experiments are applied on your page. This option specifically enables the improved implementation. Read more in the documentation for experiments.
`new_experiments.mode` (new since version `v2.4.0`)	`async`	`sync` or `async`	Specifies whether experiments are applied synchronously (blocking the page rendering) or asynchronously (hiding the page while they are loading).
`new_experiments.timeout` (new since version `v2.4.0`)	`4000`	number	Maximum amount of time (in milliseconds) that the main page is blocked or hidden while the experiments are loading. Read more in Integrating and using Experiments. Note that the integration snippet does not contain any validation for correct values here. It only makes sense to provide a positive number for this option so have that in mind. `0` is also not valid here and the snippet will use the default timeout value instead.
`new_experiments.hide_class` (new since version `v2.4.0`)	`xnpe_async_hide`	string	The CSS class name of the element used to hide the main page content. This is only used in the `async` mode.
`service_worker_path` (new since version `v2.20.0`)	`/service-worker.js`	string	Enables you to customize a file path for the service worker. Configuring a service worker is required when `new_experiment.mode` is set to `sync`. Read more about synchronous solutions with a service worker in our guide.

Examples

Basic SDK configuration:

!function(e,n,t,i,r,a,c){function // ... the rest of the snippet ...
    target: "https://api.exponea.com",
    token: "323d7a16-ba47-12c9-8c2d-0a770a310d68",
});

Customer options

Name	Default value	Possible values	Description
`customer`	`{}`	number, string, or an object with customer IDs	Allows you to identify your customer. If a number or a string is passed, this is used as the customer ID named registered. Otherwise, you can pass in an object with customer IDs (see the example below). Read more about tracking customers in Tracking.

Examples

Identify a customer with an email:

exponea.start({
  customer: '[email protected]'
});

Specify more customer IDs:

exponea.start({
  customer: {
    registered: '[email protected]',
    my_id: 12
  }
});

Tracking options

Name	Default value	Possible values	Description
`track.auto`	`true`	boolean	Enables automatic tracking set up in Data manager > Automatic web tracking in your Bloomreach Engagement project.
`track.visits`	`false`	boolean	If `true`, SDK tracks `page_visit` events for each page visited. This event contains the current URL and the referrer.
`track.visits_query_params`	`[ 'pers_position', 'pers_content' ]`	array of strings	Allows you to specify which URL query parameters are parsed and added to the `page_visit` event. Ignored if `track.visits` is `false`.
`track.activity`	`false`	boolean	Enables tracking of user activity. If `true` and the customer is active on the page, SDK tracks `user_active` events with start, end, and duration properties.
`track.unloads`	`false`	boolean	If `true`, SDK tracks a `web_unload` event once the customer unloads the page.
`track.exits`	`true`	boolean or a function (see examples below)	If `true`, SDK automatically tracks all links with the `data-exponea-track` attribute. When a customer clicks on the link, SDK tracks a `web_exit` event with current URL and the link's `href` URL. Alternatively, you can specify a function returning a custom event name and properties. This function is called with the link element as the only argument.
`track.default_properties`	`{}`	object	Event properties added to every tracked event.
`track.google_analytics`	`true`	boolean	If `true`, SDK uses Google Analytics SDK on the page to track Google Analytics ID for the current customer.

Examples

Tracking page visits with custom URL parameters:

exponea.start({
  track: {
    visits: true,
    visits_query_params: [
      'product_id' // this would work with https://www.example.com/?product_id=123
    ]
  }
});

Tracking web exits:

exponea.start({
  track: {
    exits: true
  }
});

Using a custom event name and properties for tracking web exits:

exponea.start({
  track: {
    exits: link => {
      return {
        type: 'custom_exit',
        properties: {
          current_url: location.href,
          target_url: link.href
        }
      };
    }
  }
});

Ping options

Name	Default value	Possible values	Description
`ping.enabled`	`true`	boolean	If `true`, SDK tracks customer sessions, including `first_session`, by tracking `session_start` and `session_end` events. This is done by periodically "pinging" our servers while the customer is active.
`ping.interval`	`120`	number	How often, in seconds, SDK pings our servers while the customer is active.
`ping.activity` (new since version `v2.0.2`)	`false`	boolean or an object with specified activity types, see examples below	If `true`, the customer session is tracked only while the customer is active on the page. When the customer stops using the page, their session ends and the `session_end` event is tracked. If `false`, SDK does not check for user activity and only ends the session when the customer closes the page. You can also pass in an object with specific customer events enabled/disabled. In such case, only these will be considered a customer activity. See examples below. Read more about this feature in a dedicated page about Ghost sessions.
`ping.properties`	`{}`	object	Allows you to add custom properties to the `session_start` and `session_end` events.

Examples

Enable session tracking:

exponea.start({
  ping: {
    enabled: true
  }
});

Here's how to specify which events to consider as a customer activity:

exponea.start({
  ping: {
    activity: {
      click: true, // clicks are considered an activity
      move: false, // moving the mouse is not
      scroll: false // and neither is scrolling on the page
      
      // 'key' property is left as default, true, which means that pressing keys
      // is considered an activity
    }
  }
});

Specify custom event properties:

exponea.start({
  ping: {
    properties: {
      current_path: location.pathname,
      last_product: localStorage.getItem('last_product_id')
    }
  }
});

Cookies options

Name	Default value	Possible values	Description
`cookies.cross_subdomain`	`true`	boolean or string	If `true`, SDK cookies are valid on both the current domain and all its subdomains. If `false`, the cookies are restricted only to the current (sub)domain. You can also specify the domain name manually by passing in a string.
`cookies.path` (new since SDK version `v2.16.0`)	`/`	string	Allows you to modify the path for cookies set by the SDK.
`cookies.retrieve_callback`	`null`	function	If specified, this callback function is called with the customer's cookie when SDK initializes.
`cookies.expires` (new since SDK version `v2.12.0` and integration snippet version `v2.3.0`)	`{ tracking: 94608000, ab_test: 94608000, time: 3600, }`	number, Date, or an object	Expiration setting for cookies used by the SDK. If you use a number, this is used as the maximum age of cookies in seconds. If you use a `Date` object, this is used as the expiration date. You can either specify a single value for all cookies, or an object with separate expiration for each cookie category – `tracking`, `ab_test`, and `time`. By default, `tracking` and `ab_test` cookies expire in 3 years and `time` cookies expire in 1 hour.

Examples

Set a 6 month expiration for all cookies:

exponea.start({
  cookies: {
    expires: 182 * 24 * 3600 // = 182 days
  }
});

Set a 1 year expiration for tracking cookies, 1 month expiration for AB test cookies, and leave the time cookie expiration as default:

exponea.start({
  cookies: {
    expires: {
      tracking: 365 * 24 * 3600, // = 1 year
      ab_test: 30 * 24 * 3600, // = 30 days
    }
  }
});

Here's how to use a Date to set the expiration date of cookies.

🚧
When using a Date, never use an absolute date for expiration. Always calculate the expiration date from the current date.
Otherwise, when your date value in the SDK config expires - becomes date in the past, the SDK will use the default expiration values.

exponea.start({
  cookies: {
    expires: new Date(Date.now() + 3600 * 24 * 1000) // = always 1 day from now.
                                                     // careful! `expires` takes seconds but
                                                     // `new Date` takes milliseconds
  }
});

Dependency options

Name	Default value	Possible values	Description
`dependencies`	`{}`	object	Specify dependency names and their URLs. SDK uses the URL to download the dependency when it is requested.

Examples

Load the exp framework which is available by default:

exponea.start();

exponea.loadDependency('exp', error => {
  if (error) {
    console.error(error);
    return;
  }
  
  // you can use window.Exp here
});

Specify and load a custom dependency:

exponea.start({
  dependencies: {
    lodash: 'https://cdnjs.cloudflare.com/ajax/libs/lodash.js/4.17.4/lodash.js'
  }
});

exponea.loadDependency('lodash', error => {
  if (error) {
    console.error(error);
    return;
  }
  
  // you can use window._ here
});

Web optimization options

Name	Default value	Possible values	Description
`webOptimization`	`true`	boolean or an object with specific optimization types, see examples below	If `true`, SDK fetches web optimization campaigns from your project and executes them on the page. These are Web layers, Experiments, and Tag Manager tags. You can also pass in an object with specific optimization types enabled/disabled. See examples below

Name

Default value

Possible values

Description

webOptimization

true

boolean or an object with specific optimization types, see examples below

If true, SDK fetches web optimization campaigns from your project and executes them on the page. These are Web layers, Experiments, and Tag Manager tags.

You can also pass in an object with specific optimization types enabled/disabled. See examples below

Examples

Fine-tune which web optimization campaigns you want to run on the page:

exponea.start({
  webOptimization: {
    experiments: false,
    tagManager: true,
    webLayers: true
  }
});

🚧
Please be aware that by using 'webOptimization: { webLayers: false}', the weblayers are disabled entirely, not just the 'optimization' part.

Push notifications options

Name	Default value	Possible values	Description
`push.safari.websitePushID`	`null`	string	If you are using Safari Push Notifications, specify your website push ID using this option.

Single-page application options

📘
All options in this section are supported as of version v2.2.0.

Name	Default value	Possible values	Description
`spa_reloading.on_hash_change`	`true`	boolean	If `true`, SDK watches for URL hash changes and reloads the data specified.
`spa_reloading.on_url_change`	`true`	boolean	If `true`, SDK watches for URL changes and reloads the data specified.
`spa_reloading.banners`	`true`	boolean	Controls whether SDK reloads Web layers on URL change.
`spa_reloading.experiments`	`true`	boolean	Controls whether SDK reloads Experiments on URL change. Note that this only affects the old flickering experiments and not the new guaranteed experiments.
`spa_reloading.tags`	`true`	boolean	Controls whether SDK reloads Tag Manager tags on URL change.
`spa_reloading.visits`	`true`	boolean	Controls whether SDK tracks `page_visit` event on URL change.
`spa_reloading.automatic_tracking`	`true`	boolean	Controls whether SDK reloads the automatic tracking set up in Data manager > Automatic web tracking.

Examples

Disable all options at once:

exponea.start({
  spa_reloading: false
});

Ignore URL hash changes and only reload the specified data:

exponea.start({
  spa_reloading: {
    on_hash_change: false,
    on_url_change: true,
    visits: false,
    automatic_tracking: false
    // other options are true by default
  }
});