Integration

Integration

To integrate your website with Exponea using our Javascript SDK, you need to copy-paste the integration snippet into the header of your webpage. This step is the essential prerequisite for identifying your customers, tracking their actions, and running campaigns. It will initialize Exponea with your project token (your unique project identifier) so that every action will be tracked into your project correctly.

Therefore, however, please make sure you have obtained and stored consent from your customers before initializing Exponea JS SDK.

To find the integration snippet, open your Exponea project and go to Settings > Web integration.

Click on the Copy to clipboard button and paste the snippet into every page of your website where you want to track your customers. Make sure to paste the snippet into the <head> tag of the page.

📘

Note that the new integration snippet is available in Exponea app since version 1.172.

Using the older integration snippet

If you've been integrated with Exponea for a while, it is possible that you are using an older integration snippet. The older snippet looked like this:

<script>(function(b,c){if(!b.exponea){var a=function(a,g){function k(d){return function(){var e=arguments;""==a&&"initialize"==d&&e&&e[0].modify&&e[0].modify.overlay // ... the rest of the snippet ... </script>
<script type="text/javascript">
    exponea.initialize({
        "token": "xxxx-xxx-xxxxxxxxx-xxxxx-xxxx"
        //, customer: window.loggedInCustomer // replace window.loggedInCustomer with id of your web site customer, e.g. "[email protected]"
});
</script>

You can notice that the most important visible difference is that the old snippet contains a call to exponea.initialize(), whereas the new snippet contains a call to exponea.start().

This snippet is now quite old. If you are still using it on your website, it is recommended that you update to the newer integration snippet mentioned in the top of this page, if you have the chance. Simply delete the old snippet from your website and follow the steps on this page to use the new one.

The new integration snippet has support for Non-flickering experiments and some additional features which the old snippet lacks. Plus, the old snippet contains some really old code that is not used by SDK anymore.

Initialization

When you initialize SDK, it starts communicating with Exponea - tracking the customer and their events, showing web layers, experiments, etc. By default, SDK is initialized as part of the integration snippet by calling exponea.start() (see the snippets above).

The SDK integration snippet takes in a configuration object. By default, this configuration is pre-filled with your project token and the API target. You can also customize other SDK options, see the Configuration page and also the Configuration section on this page. Here's how:

!function(e,n,t,i,r,a,c){function // ... the rest of the snippet ...
    target: "https://api.exponea.com",
    token: "323d7a16-ba47-12c9-8c2d-0a770a310d68",
    customer: "[email protected]",
    ping: {
      enabled: true
    }
    
    // other configuration options go here
});

start()

📘

This function is only supported in the newest integration snippet (from the release 1.172). If you are still using the older integration snippet, please update it to the newest version.

When called, SDK is initialized and starts doing its job. This function is part of the default integration snippet so you don't have to call it manually in your code. The function can take 1 optional parameter, which is a configuration object. If specified, this configuration extends the existing configuration specified in the integration snippet.

🚧

Note that some configuration options such as target and token can only be used in the configuration section of the integration snippet, and not in the call to start().

Arguments

Name

Value

Description

options (optional)

object

Configuration object which extends the existing configuration in the integration snippet. See the Configuration page and the Configuration section on this page for the list of supported options.

Examples

Initialize SDK with the configuration specified in the integration snippet:

exponea.start();

Extend the SDK configuration and initialize it. This can be useful if you have to request a configuration value asynchronously and then initialize SDK asynchronously using that value. For example, you can request your customer ID and use it when initializing Exponea SDK:

// requestCustomerId would be your implementation
requestCustomerId()
  .then(id => {
    exponea.start({
      customer: {
        system_id: id
      }
    });
  });

Configuration

As you saw above in sections, the behaviour of SDK is configured using a configuration object passed into the snippet and the start() method. The supported options which control the behaviour of SDK are described in Configuration. However, there are a couple of special options which control the behaviour of the integration snippet itself. These options are described below:

🚧

Note that these configuration options 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

target

'https://api.exponea.com'

string

URL of the Exponea API. This value is pre-filled in the integration snippet provided by the Exponea app.

token

none (this value is required)

string

Token of your Exponea project. This value is pre-filled in the integration snippet provided by the Exponea app. The SDK tracks data into this project.

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 (see below)

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.

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.

Examples

Here's how to overwrite the SDK file URL:

🚧

Only use the file_path option if you know what you're doing. Using an incorrect SDK file could break your integration.

exponea.start({
  file_path: 'https://api.exponea.com/js/exponea.min.js',
});

Here's how to enable the new experiments in async mode and customize the options:

exponea.start({
  new_experiments: {
    mode: 'async',
    timeout: 1000,
    hide_class: 'exponea-hide',
  },
});

Utilities

version

You can use exponea.version to find out what version of SDK you are using.

console.log(exponea.version);

snippetVersion

You can use exponea.snippetVersion to find out what version of the integration snippet you have on your website.

console.log(exponea.snippetVersion);

Updated about a month ago


What´s next?

Continue by learning how to configure SDK.

Configuration

Integration


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