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.

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&&"loading"==c.readyState&&(c.write('<div id="__inf__overlay__" style="position:absolute;background:#fff;left:0;top:0;width:100%;height:100%;z-index:1000000"></div>'),setTimeout(function(){var a=c.getElementById("__inf__overlay__");a&&c.body.removeChild(a);res.__=!0},e[0].modify.delay||500));b.exponea._.push([a+d,arguments])}}var h=g.split(" "),f,d;res={_:[]};for(d=0;d<h.length;d++)f=h[d],res[f]=k(f);return res};b.exponea=a("","initialize identify update track trackLink trackEnhancedEcommerce getHtml showHtml showBanner showForm ping getAbTest");b.exponea.notifications=a("notifications.","isAvailable isSubscribed subscribe unsubscribe");var a=c.createElement("script"),g="https:"===c.location.protocol?"https:":"http:";a.type="text/javascript";a.async=!0;a.src=g+"//api.exponea.com/js/exponea.min.js";c.getElementsByTagName("head")[0].appendChild(a);b.webxpClient=b.webxpClient||{};b.webxpClient.sdk=b.exponea;b.webxpClient.sdkObjectName="exponea"}})(window,document);</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 different 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, use the initialize() function instead.

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.

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 the 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
      }
    });
  });

initialize()

Initialize Exponea SDK with a configuration object. Note that you should use the exponea.start() method instead. This method was used in the older integration snippet and is left around for legacy reasons.

πŸ“˜

If you are still using the older integration snippet using exponea.initialize(), we recommend you to upgrade to the new integration snippet in section Integration.

πŸ‘

Use exponea.start()

The exponea.start method already calls exponea.initialize internally and also performs additional logic on top. You only have to use exponea.start() in your code.

Arguments

Name

Value

Description

options

object

Configuration options for SDK. See the Configuration page and the Configuration section on this page for more information.

Examples

Initialize Exponea SDK:

exponea.initialize({
  target: "https://api.exponea.com",
  token: "323d7a16-ba47-12c9-8c2d-0a770a310d68",
  customer: "[email protected]",
});

Configuration

As you saw above in sections about exponea.start() and exponea.initialize() methods, the behaviour of SDK is configured using a configuration object passed into these methods. 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:

Name

Default value

Possible values

Description

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 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 hidden while the experiments are loading. This is only used in the async mode.

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({
  token: '313d7a16-ba44-12c9-8c9a-0a770a310d68',
  target: 'https://api.exponea.com',
  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({
  token: '313d7a16-ba44-12c9-8c9a-0a770a310d68',
  target: 'https://api.exponea.com',
  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);

Updated 7 days 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