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()
`.
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](🔗). |
### Examples
Basic SDK configuration:
# 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:
Specify more customer IDs:
# 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:
Tracking web exits:
Using a custom event name and properties for tracking web exits:
# 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:
Here's how to specify which events to consider as a customer activity:
Specify custom event properties:
# 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:
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
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:
Specify and load a custom dependency:
# 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 |
### 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
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:
Ignore URL hash changes and only reload the specified data: