JS SDK Configuration

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** 
﻿
# Global options
﻿
Note that the configuration options `target`,  `token` and  `compliance` can only be used in the _configuration section_ of the integration snippet, and **not** in the call to `start()`.
NameDefault valuePossible valuesDescription
`token` (**required**)_none_stringYour 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.
`compliance.opt_in``false`booleanIf set to `true`, `track` commands called before the `start()` will not be executed and resets the visitor cookie after calling the `start()` command.

If set to `false` (default), commands called before the `start()` will be executed right after the `start()` command and existing visitor cookies will be used.
`utm_always``false`booleanIf `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 stringsThe 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`booleanIf `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`booleanControls whether SDK prints debug messages to the console.
`file_path`SDK target + `'/js/exponea.min.js'`stringIf 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 optionsUsed 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`numberMaximum 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`stringThe 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`stringEnables 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:
﻿
# Customer options
NameDefault valuePossible valuesDescription
`customer``{}`number, string, or an object with customer IDsAllows 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:
﻿
Specify more customer IDs:
﻿
# Tracking options
NameDefault valuePossible valuesDescription
`track.auto``true`booleanEnables automatic tracking set up in _Data manager > Automatic web tracking_ in your Bloomreach Engagement project.
`track.visits``false`booleanIf `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 stringsAllows 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`booleanEnables 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`booleanIf `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``{}`objectEvent properties added to every tracked event.
`track.google_analytics``true`booleanIf `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:
﻿
Tracking web exits:
﻿
Using a custom event name and properties for tracking web exits:
﻿
# Ping options
NameDefault valuePossible valuesDescription
`ping.enabled``true`booleanIf `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`numberHow 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 belowIf `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``{}`objectAllows you to add custom properties to the `session_start` and `session_end` events.
### Examples
Enable session tracking:
﻿
Here's how to specify which events to consider as a customer activity:
﻿
Specify custom event properties:
﻿
# Cookies options
NameDefault valuePossible valuesDescription
`cookies.cross_subdomain``true`boolean or stringIf `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`)`/`stringAllows you to modify the [path](🔗﻿) for cookies set by the SDK.
`cookies.retrieve_callback``null`functionIf 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 objectExpiration 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:
﻿
Set a 1 year expiration for tracking cookies, 1 month expiration for AB test cookies, and leave the time cookie expiration as default:
﻿
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.
﻿
# Dependency options
NameDefault valuePossible valuesDescription
`dependencies``{}`objectSpecify 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:
﻿
Specify and load a custom dependency:
﻿
# Web optimization options
NameDefault valuePossible valuesDescription
`webOptimization``true`boolean or an object with specific optimization types, see examples belowIf `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:
﻿
﻿
Please be aware that by using 'webOptimization: { webLayers: false}', the weblayers are disabled entirely, not just the 'optimization' part.
# Push notifications options
NameDefault valuePossible valuesDescription
`push.safari.websitePushID``null`stringIf 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`.
NameDefault valuePossible valuesDescription
`spa_reloading.on_hash_change``true`booleanIf `true`, SDK watches for [URL hash changes](🔗﻿) and reloads the data specified.
`spa_reloading.on_url_change``true`booleanIf `true`, SDK watches for [URL changes](🔗﻿) and reloads the data specified.
`spa_reloading.banners``true`booleanControls whether SDK reloads [Web layers](🔗﻿) on URL change.
`spa_reloading.experiments``true`booleanControls 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`booleanControls whether SDK reloads [Tag Manager](🔗﻿) tags on URL change.
`spa_reloading.visits``true`booleanControls whether SDK tracks `page_visit` event on URL change.
`spa_reloading.automatic_tracking``true`booleanControls whether SDK reloads the automatic tracking set up in _Data manager > Automatic web tracking_.
### Examples
Disable all options at once:
﻿
Ignore URL hash changes and only reload the specified data:
﻿

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.
``compliance.opt_in``	``false``	boolean	If set to ``true``, ``track`` commands called before the ``start()`` will not be executed and resets the visitor cookie after calling the ``start()`` command. If set to ``false`` (default), commands called before the ``start()`` will be executed right after the ``start()`` command and existing visitor cookies will be used.
``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](🔗).

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.

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.

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.

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