Initialization

To integrate with Exponea using JavaScript, you need to copy-paste the initialization code into the header of the webpage your business is running in. This step is an essential prerequisite for identifying your customers and tracking their actions. This 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 initialization code, go to Settings > Web integration.

Here, you can find the initialisation snippet

This code must be included in every page where you want to track the actions of your customers.

In order to keep your page speed loading time as low as possible, the Exponea JS SDK is loaded asynchronously. But you are still able to use some calls, which are listed below before the SDK is loaded. Those calls are pushed to a stack, which is processed once the SDK is loaded.

Exponea JS SDK will not initialize for bot traffic.

List of calls you may use before the SDK is loaded:

  • initialize
  • identify
  • update
  • track
  • trackLink
  • trackEnhancedEcommerce
  • getHtml
  • showHtml
  • showBanner
  • getAbTest
  • ping

exponea.initialize(config)

As you can see in the example above, the initialize call takes one argument, which is a config object. The basic config object is generated for you and it includes your project token and basic tracking options.

You can modify this object and set your custom configuration. For more information, look at the Config Object section below.

Customer

You can store up to 255 customer attributes with maximum value size of 128Kbit per attribute.

The customer parameter can use any object with identifier same as exponea.identify(). When string is used, it will use identifier registered only.

Only use ASCII characters for attributes naming.

identify()

To know your customers better, you need to identify them with a unique identifier, such as e-mail or username. Copy-paste the example into the code where it is possible to identify the customer for the first time (for example right after login or registration) so that every event the customer creates from this point on will be tracked correctly and directly to him.

The example will identify the customer with a username [email protected] Without identification, events are added to anonymous customers. Please note that you don’t lose any information about these events after you identify the customer – these events will be transferred to a newly identified customer.

Arguments

Name
Value
Description

customerIds (Required)

String / Number / Object

Customer's unique identifier

customerProperties

Object

Pass customer attributes

successCallback

Function

Defines a success callback function. Function is called after HTTP request is processed successfully. At this point, there is no knowledge of how request was processed by Exponea backend.

errorCallback

Function

Defines an error callback function. Function is called after HTTP request is processed unsuccessfully. At this point, there is no knowledge of how request was processed by Exponea backend.

immediate

Boolean

Defaults to FALSE. If true, SDK sends the request right away. Otherwise it waits 100ms and sends this request in bulk with other requests that happen in those 100ms

Best practice

Email

Always make sure that you pass lowercased and trimmed email.

var email = customerEmailFromWebsite.toLowerCase().trim();

Custom IDs

When using other identity (for instance user_id from your system), always make sure that this attribute is created in your Exponea project (Administration -> Projects -> Your project -> Identifiers). Otherwise, these calls will be discarded.

If you are not Instance admin, contact your Consultant or CSM.

Cookies

Do not set a cookie field value, this value will be ignored.

Example

If you only pass one customer ID, it will be matched against hard ID your customers. The hard ID used in this example is registered, however, your hard ID may differ, so replace it as applicable. If you are unsure ask your CSM, Consultant or VDM.

exponea.identify('[email protected]');
exponea.identify(
  {
    'registered':'[email protected]', //the registered attribute is handled as hard ID and required
    'user_id': 'user_id_123',
  },
  {
    'first_name':'Gordon',
    'last_name':'Freeman',
    ...
  },
  function(){
    //successCallback
  },
  function(){
    //errorrCallback
  },
  false
);

Please note that in you obtain another identity parameter over time and you want to identify customer (previously identified by email) with your customer_id for instance, you need to call identify with BOTH customer identifiers. Otherwise, if you only pass user_id into the second identify call, a new customer will be created.

We recommend you to use something unique. It might be your internal database userId or email.

When using caching on your web server, you need to make sure not to put identifying customer script into this part.

update()

Every customer in Exponea has a set of attributes. Attributes can be used to contact the customer using a campaign, or to specify the customer in your business more accurately. Copy-paste the following snippet into the code where you want to update customer attributes.

If a customer property doesn’t exist at the time the code is executed, the property will be created. You can create properties as you need them without worrying about their management. If you don’t need them anymore, you can delete them easily.

Please note that if you choose to identify your customer with an email, you still need to specify the customer attribute email. This is needed because of the distinction between identification attributes and the customer email.

'Special attributes'

  • first_name, last_name, company_name
    • displayed in Customer view
  • photo
    • URL for the photo displayed in Customer view
  • email
    • used in email campaigns
  • phone
    • used in SMS campaigns
    • use full international format
      • leading +, no spaces
      • e.g. +421905123456
  • language
    • if your website has multiple language mutations or you store preferred customer's language for communication
    • two lower-case letter code ISO-639-1
  • domain
    • domainname
    • when you track multiple domains under one account

Attributes

Name
Value
Description

customerAttributes (Required)

Object

Pass customer attributes. Max 255 attributes of 128Kbit size

Example

exponea.update({
  email: '[email protected]',
  first_name: 'Gordon',
  last_name: 'Freeman',
  company: 'Blackmesa',
  ...
});

Events

You can track up to 255 event types with 255 event attributes for each event type with value up to 128Kbit for attribute.

Only use ASCII characters for events and attributes naming.

track()

Customers in your business do different actions. These actions are called events and by tracking them you gain insights vital for developing the perfect business. To track your first event, you need to copy-paste the following code into an appropriate place in your business.

Attributes

Name
Value
Description

eventName (Required)

String

Name your event

eventProperties

Object

Pass event properties (max 255 entries)

successCallback

Function

Called after the event is successfully tracked

errorCallback

Function

Called when an error occurs

Example

exponea.track('purchase', {
  purchase_status: 'success',
  product_list: [ {product_id: "abc123", quantity: 2}, {product_id: "abc456", quantity: 1} ],
  total_price: 7.99,
  payment_type: 'credit_card',
  ...
});

This will track the event named purchase with the three attributes of item, price and margin_percent to currently identified customer. For example, the attribute price has number value 7.99.

Of course your event doesn’t have to be named purchase and it doesn’t have to have this set of attributes. Other useful examples of events would be registration or added to cart. You can also get creative and make your own events with custom attributes – only you decide what to track about your customers. However, remember that in business analytics, less is more and you want to start with a few basic events only.

We recommend you to avoid using internal IDs or numbers as values for attributes where string is available. Purchase status ‘canceled’ is much more comprehensible than a purchase status 3.

Exponea JS SDK adds some default properties (which can be extended in initialize call - please refer to Config Object) to the event itself.

Property name
Description
Example

os

Customer's operating system

iOS

browser

Customer's browser

Chrome

device

Customer's device

iPhone

For automatically tracked events (first_session, session_start, session_end and page_visit) Exponea additionally tracks:

Property name
Description
Example

path

Customer's path, striped of URL parameters

/contact-us

referer

Previous location of the customer

trackLink()

You can easily track you users clicking activity by adding tracking to any element of your webpage. Just set the CSS selector (if more elements fulfill the CSS selector condition, tracking will occur on all of them).

For instance you can use this function to track visitors who are leaving your page by clicking some external link.

Attributes

Name
Value
Description

CSS selector (Required)

String

CSS selector of item(s) you want to track

eventName (Required)

String

Name your event

eventProperties

Object

Pass event properties

Example

exponea.trackLink('#exponea_link', 'external_link', {
  site: 'Exponea'
});

trackEnhancedEcommerce()

Exponea JS SDK let's you easily push your existing Google Analytics Enhanced Ecommerce tracking into Exponea.

Arguments

Name
Value
Description
Example

Ecommerce object (Required)

Object

GA EE object

See GA EE documentation

Kind (Required)

String

Name of GA EE Event

click / detail / add / remove / promoView / promoClick / checkout / checkout_option / purchase / refund / all

Example

exponea.trackEnhancedEcommerce(
  {
    // pass the same attributes as you pass to the EE GA tracking
  },
  'detail',
);

Exponea will track 'detail' event with provided properties along with default event properties and 'tracked_via':'ecommerce' attribute.

Updated 26 days ago

Tracking


Suggested Edits are limited on API Reference Pages

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