SDK is configured using a configuration object passed into the exponea.start
or the exponea.initialize
functions. 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
exponea.initialize({
target: 'https://api.exponea.com',
token: '313a6a16-b422-11e8-1230-0a580a211c63',
customer: '[email protected]',
track: {
visits: true
}
});
Global options
Name | Default value | Possible values | Description |
---|---|---|---|
| None | project token string | Your project token. Find your project token in the project settings. See Tracking for more information. |
|
| Valid API endpoint URL string. It is recommended to always use the | 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. |
|
| boolean | If |
|
| array of strings | The list of UTM parameters added to tracked events if |
|
| boolean | This parameter is deprecated. Use |
|
| boolean | If |
|
| boolean | Controls whether SDK prints debug messages to the console. |
Examples
Basic SDK configuration:
exponea.initialize({
target: 'https://api.exponea.com',
token: '313a6a16-b422-11e8-1230-0a580a211c63',
});
Customer options
Name | Default value | Possible values | Description |
---|---|---|---|
|
| 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.initialize({
customer: '[email protected]'
});
Specify more customer IDs:
exponea.initialize({
customer: {
registered: '[email protected]',
my_id: 12
}
});
Tracking options
Name | Default value | Possible values | Description |
---|---|---|---|
|
| boolean | Enables automatic tracking set up in Data manager > Automatic web tracking in your Exponea project. |
|
| boolean | If |
|
| array of strings | Allows you to specify which URL query parameters are parsed and added to the |
|
| boolean | Enables tracking of user activity. If |
|
| boolean | If |
|
| boolean or a function (see examples below) | If 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. |
|
| object | Event properties added to every tracked event. |
|
| boolean | If |
Examples
Tracking page visits with custom URL parameters:
exponea.initialize({
track: {
visits: true,
visits_query_params: [
'product_id' // this would work with https://www.example.com/?product_id=123
]
}
});
Tracking web exits:
exponea.initialize({
track: {
exits: true
}
});
Using a custom event name and properties for tracking web exits:
exponea.initialize({
track: {
exits: link => {
return {
type: 'custom_exit',
properties: {
current_url: location.href,
target_url: link.href
}
};
}
}
});
Ping options
Name | Default value | Possible values | Description |
---|---|---|---|
|
| boolean | If |
|
| number | How often, in seconds, SDK pings our servers while the customer is active. |
|
| boolean or an object with specified activity types, see examples below | If 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. |
|
| object | Allows you to add custom properties to the |
Examples
Enable session tracking:
exponea.initialize({
ping: {
enabled: true
}
});
Here's how to specify which events to consider as a customer activity:
exponea.initialize({
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.initialize({
ping: {
properties: {
current_path: location.pathname,
last_product: localStorage.getItem('last_product_id')
}
}
});
Cookies options
Name | Default value | Possible values | Description |
---|---|---|---|
|
| boolean or string | If You can also specify the domain name manually by passing in a string. |
|
| function | If specified, this callback function is called with the customer's cookie when SDK initializes. |
Dependency options
Name | Default value | Possible values | Description |
---|---|---|---|
|
| 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.initialize();
exponea.loadDependency('exp', error => {
if (error) {
console.error(error);
return;
}
// you can use window.Exp here
});
Specify and load a custom dependency:
exponea.initialize({
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 |
---|---|---|---|
|
| boolean or an object with specific optimization types, see examples below | If 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.initialize({
webOptimization: {
experiments: false,
tagManager: true,
webLayers: true
}
});
Push notifications options
Name | Default value | Possible values | Description |
---|---|---|---|
|
| 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 |
---|---|---|---|
|
| boolean | If |
|
| boolean | If |
|
| boolean | Controls whether SDK reloads Web layers on URL change. |
|
| boolean | Controls whether SDK reloads Experiments on URL change. |
|
| boolean | Controls whether SDK reloads Tag Manager tags on URL change. |
|
| boolean | Controls whether SDK tracks |
|
| boolean | Controls whether SDK reloads the automatic tracking set up in Data manager > Automatic web tracking. |
Examples
Disable all options at once:
exponea.initialize({
spa_reloading: false
});
Ignore URL hash changes and only reload the specified data:
exponea.initialize({
spa_reloading: {
on_hash_change: false,
on_url_change: true,
visits: false,
automatic_tracking: false
// other options are true by default
}
});
Updated 8 days ago
What´s next?
You have now configured the Exponea SDK. Continue by tracking your customer's events and attributes.
Tracking |