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.


# 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``''`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
```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](🔗).
```{}`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: