Configuration

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

NameDefault valuePossible valuesDescription
token (required)Noneproject token 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.
utm_alwaysfalsebooleanIf 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)truebooleanThis parameter is deprecated. Use spa_reloading.on_hash_change instead.
transfer_identitytruebooleanIf 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)falsebooleanControls 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

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:

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

Specify more customer IDs:

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

Tracking options

NameDefault valuePossible valuesDescription
track.autotruebooleanEnables automatic tracking set up in Data manager > Automatic web tracking in your Exponea project.
track.visitsfalsebooleanIf 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.activityfalsebooleanEnables 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.unloadsfalsebooleanIf true, SDK tracks a web_unload event once the customer unloads the page.
track.exitstrueboolean 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_analyticstruebooleanIf 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.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

NameDefault valuePossible valuesDescription
ping.enabledtruebooleanIf true, SDK tracks customer sessions by tracking session_start and session_end events. This is done by periodically "pinging" our servers while the customer is active.
ping.interval120numberHow often, in seconds, SDK pings our servers while the customer is active.
ping.activity (new since version v2.0.2)falseboolean 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.
ping.properties{}objectAllows you to add custom properties to the session_start and session_end events.

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

NameDefault valuePossible valuesDescription
cookies.cross_subdomaintrueboolean 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.retrieve_callbacknullfunctionIf specified, this callback function is called with the customer's cookie when SDK initializes.

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:

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

NameDefault valuePossible valuesDescription
webOptimizationtrueboolean 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:

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

Push notification options

NameDefault valuePossible valuesDescription
push.safari.websitePushIDnullstringIf 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_changetruebooleanIf true, SDK watches for URL hash changes and reloads the data specified.
spa_reloading.on_url_changetruebooleanIf true, SDK watches for URL changes and reloads the data specified.
spa_reloading.bannerstruebooleanControls whether SDK reloads Web layers on URL change.
spa_reloading.experimentstruebooleanControls whether SDK reloads Experiments on URL change.
spa_reloading.tagstruebooleanControls whether SDK reloads Tag Manager tags on URL change.
spa_reloading.visitstruebooleanControls whether SDK tracks page_visit event on URL change.
spa_reloading.automatic_trackingtruebooleanControls 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 4 months ago


What´s next?

You have now configured the Exponea SDK. Continue by tracking your customer's events and attributes.

Tracking

Configuration


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.


We rely on cookies

to optimize our communication and to enhance your customer experience. By clicking on the Accept and Close button, you agree to the collection of cookies. You can also adjust your preferences by clicking on Manage Preferences. For more information please see our Privacy policy.

Manage cookies
Accept & close

Cookies preferences

Accept & close
Back