JavaScript tracker

Ometria's JavaScript tracker allows the collection of page views and other interaction events on your store website.

When fully installed, the JavaScript tracker collects behaviour based information, such as which products users have been viewing and which products they have added to their basket.

📘

Interaction events limit

Ometria records up to 1000 interaction events per visit. This limit is in place to deter bots.

This information can be used to trigger automation campaigns in Ometria.

Installation

To inject the JavaScript file, place a <script> tag at the top of the page pointing at the assigned URL:

<script src="//cdn.ometria.com/tags/<ometria_account_id>.js"></script>

🚧

Note

This CDN tag must reside at the top of the page to make sure it is loaded before any of the inits are fired.

The <ometria_account_id> in the example above should be replaced by your account ID, provided by Ometria.

When writing an integration plugin the script provides a global object called ometria with methods that need to be called depending on which page is being displayed and the state of the visitor.

The Ometria JavaScript API should be called in the following order:

1. Call ometria.init to start event tracking, supplying the pageType and pageData parameters depending on the page being viewed. You should also provide a storeId value, which is a string that must match the values used to send order data.
2. If the current user is logged in (or their email address is known), call ometria.identify.
3. If the current user has an active basket, call ometria.setBasket.
4. If this page is an order confirmation page, call ometria.trackTransaction.
5. Call additional event methods (ometria.trackAddToBasket, ometria.identify) as needed when the user completes specific actions on the page.

Example of a full initialisation sequence:

ometria.init("product", {"pid":"11111"}, "uk");         // Product page ID 11111 
ometria.identify("[email protected]");                   // E.g. if logged in 
var basket = new ometria.Basket();                      // User has active basket 
basket.setId("453dfa34"); basket.setTotal(100.0, "GBP");
 basket.addLineItem("12345", 1, 50);
 basket.addLineItem("12365", 1, 50);
 ometria.setBasket(basket);

Identifying visitors

When the identity of the visitor is known (e.g. if they login or signup to a newsletter), they are identified using their email address or profile ID.

It's safe to call this method for each page view, as a network call is only carried out to Ometria's servers when the parameter changes.

ometria.identify(visitor_email);
 ometria.identify(profile_id);

If you're using profile_id, you should include omid: and the profile ID, e.g. ometria.identify("omid:2cd4-b62835-0264e4b8")

This can be extracted from the cookie as a unique user ID.

🚧

Note

The identity of the contact will be remembered across visit sessions. If this email address does not exist in your Ometria account, it will be created as a new contact.

See Debugging JavaScript tracking if you encounter any problems identifying contacts.

Passing customer data in JavaScript

You can pass customer data in the Ometria identify event.

This can include standard fields and custom fields.

Pass custom fields in the properties object within the call:

ometria.identify('[email protected]',
  {'firstname':'Dave',
  'properties':
    {'custom_field': 'custom field value'}
  }
  );

🚧

Note

Additional data passed in this call will only be saved to the profile 30 minutes after the session has completed.

Page types

The ometria.init(pageType, pageData, storeID) method accepts three parameters:

These are the required page types supported by the JavaScript tracker:

homepage

The main index page of the website. E.g.:

ometria.init('homepage', null, "storeID");

listing

This kind of page includes search results, listing of products in a group, category, collection or any other page that presents a list of products. E.g.:

ometria.init('listing', null, "storeID");

basket

The page displaying the contents of the visitor's basket. E.g.

ometria.init('basket', null, "storeID");

checkout

Any stage of the checkout (apart from the confirmation page). E.g.:

ometria.init('checkout', null, "storeID");

confirmation

The final 'thank you' page of the checkout process. E.g.:

ometria.init('confirmation', null, "storeID");

At this stage of the checkout an order is already placed, so you should also prepare the order_id to be called with trackTransaction(order_id). This order_id must match the order_ID or web_id used in order API E.g.:

ometria.trackTransaction("7573626");

product

The product page. The product IDs you use here must match the products which have been passed to Ometria via the product endpoint.

Page data:

pid (string): An identifier of this product.

E.g.:

ometria.init('product',{
   pid:"573672" 
}, "storeID");

Other page types

We require that you use all of the pageTypes listed above, but if there are pages on your site which don't fall into those listed, you can use any name you like ​for the pageType, as long as you make sure you're using the appropriate storeID e.g.:

ometria.init('other', null, "store_id")

Setting basket contents

On every page that gives access to items currently held in a basket, or at least when this data changes state, call a setBasket() method which accepts an ometria.Basket object.

🚧

Note

You can provide this information numerous times but it will only trigger an event in Ometria if the contents of the basket have been changed since the last update.

To create this object, use the following data:

Using this data, the basket object can be constructed like this:

var basket = new ometria.Basket();
 basket.setId("453dfa34");
 basket.setUrl("http://example.com/basket/3454sdf98");
 basket.setTotal(100.0, "GBP");
 basket.addLineItem("12345", 1, 50);
 basket.addLineItem("54321", 2, 75, "54321-a")
 ometria.setBasket(basket);

You can also call trackAddToBasket() when someone clicks an Add to basket button:

ometria.trackAddToBasket(product_id, quantity);

Both calls must be used to ensure the basket information is tracked accurately in Ometria (as it's possible for a visitor to add something to a basket and then leave the website).

product_id is required when calling trackAddToBasket().

quantity is an optional argument. If no quantity is specified then we assume a quantity of 1.

Remove from basket

To remove a product from a basket, reinitialise the basket with the decremented quantities/lineItems and call setBasket again.

Tracking orders

When an order is placed the following method must be called:

ometria.trackTransaction(order_id)

order_id must be the same order ID used as the ID parameter in orders sent via the order endpoint.

This order_id or web_id must match the order ID used in order endpoint.

Typically this call is placed on 'thank you for your order' pages.

Tagging attributes to pages

You can tag your pages with imported attributes and use these to create abandoned category campaigns in Ometria.

Creating new attributes

To create a new attribute, use the push endpoint of our data API to set the type, id and label of the attribute.

This payload represents a single attribute being pushed to Ometria:

```json
[
   {
     "@type": "attribute",
     "type": "category",
     "id": "fathers-day",
     "label": "Father’s day"
   }
]
```

The above attribute data could be submitted to Ometria via CURL using this command:

```bash

curl -X POST -H 'X-Ometria-Auth: YOUR_ACCESS_TOKEN' -H "Content-Type: application/json" -d '[{"@type":"attribute","type":"category","id":"fathers-day","label":"Father’s day"}]' 'https://api.ometria.com/v2/push'

```

Tagging attributes to pages

Once you’ve created your attributes, the page attribute needs to be passed to the ‘init’ method of the Ometria JavaScript Interaction API as a pageData object for any page type.

For example:

ometria.init('homepage', pageData, "storeID");

The required pageData is a JSON object, in which you’ll need to specify an "attributes" key containing a list of objects representing the "id" and "type" of each attribute for a given page:

• The "id" key is your unique identifier represented by a string.
• The "type" key is the attribute type represented by a string.

For example:

{ "attributes": [ { "id": "dresses", "type": "category" },
 { "id": "celebrations", "type": "category" } ] }

Simply pass your desired attributes via the ‘init’ method as follows:

ometria.init("listing",
 { "attributes": [ { "id": "dresses", "type": "category" },
 { "id": "celebrations", "type": "category" } ] }, "storeID");

📘

Note

The “id” and “type” passed into the Ometria JavaScript API must match the “id” and “type” of a previously defined (existing) attribute.