JavaScript Integration & Tracking

Integrating your business with Exponea is the first step in getting closer to your customers. After a quick integration, you will immediately see actions that customers do in your business. If you need any assistance in deciding which API is the best for your business, please contact our integration specialist.

When should I integrate through JavaScript?

Integration through JavaScript is recommended for a web browser business or for a business coded in other languages that still make use of JavaScript.


Basic integration

To integrate with Exponea using JavaScript, you need to copy-paste the following 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.

<script type="text/javascript">!function(i,t){function e(e){return function(){var n=arguments;if("initialize"==e&&n&&n[0].modify&&n[0].modify.overlay&&"loading"==t.readyState){var a="__inf__overlay__";t.write('<div id="'+a+'" style="position:absolute;background:#fff;left:0;top:0;width:100%;height:100%;z-index:1000000"></div>'),setTimeout(function(){var e=t.getElementById(a);e&&t.body.removeChild(e),i.exponea.__=!0},n[0].modify.delay||500)}this._.push([e,arguments])}}if(!i.exponea){var n,a,o="initialize identify update track trackLink trackEnhancedEcommerce getHtml showHtml showForm ping getAbTest".split(" "),r=t.createElement("script"),d="https:"===t.location.protocol?"https:":"http:";for(i.exponea={_:[]},a=0;a<o.length;a++)n=o[a],i.exponea[n]=e(n);r.type="text/javascript",r.async=!0,r.src=d+"//api.exponea.com/js/exponea.min.js",t.getElementsByTagName("head")[0].appendChild(r)}}(window,document);</script>
<script type="text/javascript">
    exponea.initialize({
        token: 'PROJECT TOKEN'
    });
</script>

This will initialize Exponea with your project token (your unique project identifier) so that every action will be tracked into your project correctly. You can find your project token inside the Project overview by clicking Overview in the left menu. This code must be included in every page where you want to track actions of your customers.

How do I know that I initialized Exponea correctly?

After copy-pasting the initialization code, open your web business in a new window. This single page visit should be enough to identify whether your basic integration is working. Check if you integrated successfully in Project > Data management > Events section. Contact our JavaScript integration specialist.


Tracking events

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.

Tip: 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.

You can delete events you tracked at any time easily.

Why should I track events?

Customers in your business make various actions. We call these actions events. If you want to have detailed overview of customer behaviour, you need to track these events. By tracking the most significant events you can define your customer’s journey and respond to them with specific actions. For instance, send an email after registration or show a banner after second visit. You can also create segmentations based on your customers’ behaviour and then create a specific campaign for each segment.

Which events should I track?

You can define any event types for each of your project based on your business model or your current goals. If you have product e-commerce website, your basic customer journey will probably/most likely be:

  • Visiting your website
  • Searching for specific product
  • Product page
  • Adding product to the cart
  • Going through ordering process
  • Payment

So the possible events for tracking will be: ‘search’, ‘product view’, ‘add product to cart’, ‘checkout’, ‘purchase’. Remember that you can define any event names you wish. Our recommendation is to make them self-descriptive and human understandable.

What are event attributes?

Each event can have numerous attributes. Usually an attribute is used for enhancing the event data, e.g. for each purchase event you would want to track total price. If you have total price as an attribute, you can easily create analysis with revenue, average order price or event compute CLV. Another usage of attributes is that you can drill-down report by them: for instance, drill-down purchases by countries, or products by categories or visits by UTM campaigns.

Which event attributes should I track?

We recommend to track all attributes that enrich the information about the event. Example of adding more detail into event for purchase_item event will be product name, category, or purchase ID. You should add attributes that can be aggregated for a customer or to create a metric. Usually numbers or counts, such as item price, total price or count of items.

What are the recommended events to track and how to track them?

When integrating your project, there are several basic events that are recommended to start tracking. They are fully customisable in Exponea, however here are some predefined events and their attributes that we encourage you to track:

Event purchase tracks the basic purchase transaction of your customers and the most important event of e-commerce. You can track overall performance of you business, evaluate campaigns, calculate life-time value of your customer and much more. Of course your event doesn’t have to be named purchase and it doesn’t have to have this set of attributes. 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. In this event, we recommend tracking the following attributes:

  • status (string -> success/fail)
  • items (array -> list of products inside of the order)
  • total_price (integer)
  • payment_method (string -> cash/credit_card/bank_transfer/…)

Here is an example of how to track event Purchase:

<script type="text/javascript">
    exponea.track('purchase', {
        item: 'Flying carpet',
        total_price: 7.99,
        payment_method: 'credit_card',
        status: 'success'
    });
</script>

 

Event purchase_item is a partial event of the event purchase. It consists of a product inside of a purchase, and can be used for recommendations. Within this event we recommend tracking the following attributes:

  • status (string -> success/fail)
  • item_id (string -> a unique ID of a product)
  • item_price (integer)
  • item_name (string)
  • quantity (number)
  • category (string -> name or ID of product’s category)

Here is an example of how to track purchase_item:

<script type="text/javascript">
    exponea.track('purchase_item', {
        item_id: 123456,
        item_price: 123,
        item_name: 'product name',
        quantity: 2,
        category: 'category name',
        status: 'success'
    });
</script>

 

Event cart_update is tracked whenever customer adds or removes a product from the shopping cart. Typical use case in which this event plays a core role is Cart Abandonment. We recommend tracking of the following attributes:

  • current_items (array -> list of current cart items and their quantities in JSON array)
  • action (string -> add/remove/empty -> the last change)
  • item_id (string)
  • item_name (string)
  • item_price (integer)
  • item_quantity (integer)
  • category (string)
  • total_price (integer)

Here is an example of how to track cart_update:

<script type="text/javascript">
   exponea.track('cart_update', {
    'current_items': "[{item_id: 1234, item_quantity:3}, {item_id: 2345, item_quantity:2}]",
    'action': "add, remove, empty",
    'item_id': "1234",
    'item_price': 54.99,
    'item_name': "Toy toy",
    'category': "Party toys",
    'item_quantity': 1,
    'total_price': "123",
});
</script>

 

Event Item_visit tracks an user action during which the user opens up product page. This allows you to know how many users are interested in each product. We recommend tracking of the following attributes:

  • item_id (string -> unique ID of a product)
  • item_name (string)
  • item_price (integer)
  • category (string)

Here is an example of how to track item_visit:

<script type="text/javascript">
exponea.track('item_visit', {
    'item_id': "123456",
    'item_price': "123",
    'item_name': "Lenovo ThinkPad",
    'category': "Notebooks",
});
</script>

 

Event category_visit tracks the action of a user during which he opens up a category page. This information is useful when determining what are your strongest categories. Within this event we recommend tracking of the following attributes:

  • category_id (integer)
  • category_name (string)

Here is an example of how to track category_visit:

<script type="text/javascript">
exponea.track('category_visit', {
 'category_id': "123456",
 'category_name': "Notebooks"
});
</script>

 

Event checkout is used to track several steps of the purchasing process, including the customer data acquisition, payment, shipping and transaction thank-you page. Tracking these steps is vital when determining churned customers. Knowing each step of this process allows you to target churned customers and bring them back to your website. There are plentiful trackable attributes within this event, these are some of the most important ones:

-> action (steps of a checkout); first_name; last_name; delivery_option; street; postal_code; city; country; customer_id; phone; refferer; location; total_price; products; payment_type; etc.

Here is an example of how to track checkout:

<script type="text/javascript">
exponea.track('checkout', {
    'action': "shipping_options",
    'first_name': "Gordon",
    'last_name': "Freeman",
    'delivery_option': "courier",
    ...
});
</script>

 

Event registration is tracked when a new user registers on the website. This event allows you to keep track about your customers, and use their allocated data for analyses and marketing automations. In combination with the ‘exponea.update’ function, the attributes this event tracks will be attributed directly to the customer profile. Within the registration event, we recommend tracking of the following attributes:

  • email (string)
  • first_name (string)
  • last_name (string)
  • phone (string)

Here is an example of how to track registration:

<script type="text/javascript">
exponea.track('registration', {
    'email': "gordon.freeman@blackmesa.com",
    'first_name': "Gordon",
    'last_name': "Freeman",
    'phone': "+421987654321",
});
</script>

 

Tracking list attributes

It is possible to track list attributes, that is equivalent to JS array. It is possible to use Exponea list filters with list attributes, which is not possible with objects (as shown above in cart_update).

exponea.track('view_article', {
tags: ["finance", "red", "..." ]
});

 


Identifying your customers

To know your customers better, you need to identify them with a unique identifier, such as e-mail or username. Copy-paste the following snippet 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.

<script type="text/javascript">
    exponea.identify('gordon.freeman@blackmesa.com');
</script>

This will identify the customer with a username gordon.freeman@blackmesa.com. 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.

Tip: We recommend you to use something unique. It might be your internal database userId or email (in some cases).

Multiple identities

If there are more identities (more than registered and cookie) in the project, you need to use special identify call.

For example to identify with email_id you call:

 exponea.identify({ email_id: "example@email.com" });

If you are identifying a customer and you know all identities, you can also identify with

exponea.identify({ registered: "user_id_199191", email_id: "example@email.com" });

Warning: If using caching on your webserver, you need to make sure not to put identifying customer script into this part.


Updating the customer’s profile

In addition to tracked events, 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.

<script type="text/javascript">
    exponea.update({
        registration_date: '2014-04-10',
        email: 'gordon.freeman@blackmesa.com',
        first_name: 'Gordon',
        last_name: 'Freeman',
        company: 'Blackmesa'
    });
</script>

This will update the customer attributes registration_date, email, first_name, last_name and company.

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.


This guide should have provided you with all the basics needed to start tracking your first events. We would love to help you get started as soon as possible, so if you have any questions, please contact our integration specialist.

Advanced tracking

Customizing default tracking

Default tracking behaviour can be adjusted in the exponea.initialize(options) call:

<script type="text/javascript"> 
    exponea.initialize({
        token: 'PROJECT TOKEN',
        customer: 'Insert unique identified of your customer or remove this line (so cookie identification will used)',
        ping: { enabled: true}, // enables tracking session_start, first_session and session_end events
        track: { visits: true }  // enables tracking page_visit event
    });
</script>

You can also specify custom properties to be emitted with the session_start and session_end events.

<script type="text/javascript">
    exponea.initialize({
        token: 'PROJECT TOKEN',
        customer: 'Insert unique identified of your customer or remove this line (so cookie identification will used)',
        ping: {
            // specify your custom properties here
            properties: {
                version: 2,
                subdomain: 'www'
            }
        }
    });
</script>

Content modifying

It is also possible to enable content modifying by adding modify into the initialization:

<script type="text/javascript"> 
    exponea.initialize({
        token: 'PROJECT TOKEN',
        customer: 'Insert unique identified of your customer or remove this line (so cookie identification will used)',
        ping: { enabled: true}, // enables tracking session_start, first_session and session_end events
        track: { visits: true },  // enables tracking page_visit event
        modify: {
            enabled: true, // enables content modifying
            overlay: false, // enables/disables overlay (can be ommitted so the default = false is used)
            delay: 500 // sets the delay for how long the overlay will be displayed (only if overlay is enabled, defaults to 500 if omitted)
        }
    });
</script>

Action tracking

You can emit custom events when clicking links:

<a id="exponea_link" href="http://www.exponea.com">Exponea</a>
<script type="text/javascript">
   exponea.trackLink('#exponea_link', 'external_link', {
       site: 'Exponea'
   });
</script>

HTML campaigns

To display the content of your HTML campaign for the current user, use the following code:

<script type="text/javascript">
    exponea.showHtml('#content', 'Name of your HTML campaign node');
</script>

If you want to work with HTML yourself, use the getHtml method instead:

<script type="text/javascript">
    exponea.getHtml('Name of your HTML campaign node', function (html) {
        // Do whatever you want with html.
    });
</script>

Limitations

Characters . and $ are not allowed to be used in JSON keys. However, they can be used as values.