! Skip to main content
Sign in

JavaScript interaction API

Louise MacBean
  • Updated

The Ometria JavaScript API allows the collection of page view and other interaction events on your ecommerce store

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

This information can be used to trigger automated campaigns in the Ometria platform. The triggering event will only be fired after the session has ended, which can be up to 30 minutes after the user was last active on the website.

Contents

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 an identifier assigned by Ometria. When writing an integration plugin, the script provides a global object, called ometria, with methods that need to be called depending on what 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 can also optionally provide a storeId value which is a string that should match the values used to send order data. See List of page types.
  2. If the current user is logged in (or otherwise their email address is known) call ometria.identify. See Identifying visitors.
  3. If the current user has an active basket, call ometria.setBasket as below. See Setting basket contents.
  4. If this page is an order confirmation page, call ometria.trackTransaction. See Tracking orders.
  5. Call additional event methods (ometria.trackAddToBasket, ometria.identify) as needed when the user completes specific actions on the page.

An example of a full initialisation sequence is shown below:

ometria.init("product", {"pid":"11111"}, "uk");         // Product page ID 11111 
ometria.identify("user@example.com");                   // 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);

Please see list of page types for more details.

Identifying visitors

When the identity of the visitor is known (e.g. if they login or signup to a newsletter), he or she should be identified using their email address or profile id:

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

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

Note that the identity of the contact will be remembered across sessions and if this email address does not exist in your Ometria account, it will be created.

When users are not identified on website

Sometime when you make front-end changes to your website, e.g. adding new form fields or a new footer, the JS tracker is disturbed and the ometria.identify event will not run even if the user submits their email. In other words the user will not be identified.

If you have made any changes on your front-end, please notify Support so they can test your form fields. You do not want to miss any chances to identify visitors on your website when they enter their email address to be identified.

If for any other reason you suspect that signups are not being identified on your website, please notify Support.

After testing the form fields, if they are indeed not running the ometria.identify event,

  1. we will make changes to the JS tags for those form fields on your website 
  2. and send you the amended JS tags to insert in your webpages with instructions.

Page types

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

  • pageType: One of the page types listed below
  • pageData: A Javascript object with keys depending on the page type, listed below.
  • storeID: A string representing the store the visitor is currently active on. This must match the storeID parameter used in the ecommerce data API in order to properly match orders to visits. Note, the storeID is case sensitive and must match the case used in the ecommerce data API. See Data API conventions.

The following page types are supported by the Ometria tracking API.

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 dedicated to showing the current contents of the current user's basket.

E.g.

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

checkout

Any stage of the checkout (apart from final thank-you 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");

In addition, at this stage of the checkout an order is already placed, so prepare the order_id to be called with trackTransaction(order_id).

E.g.

ometria.trackTransaction("7573626");

product

The product page. The product IDs used must correspond to the products which have been passed to Ometria via the data API.

Page data:

  • pid (string): An identifier of this product.

E.g.

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

Setting basket contents

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

Note: you can provide this information numerous times but it will only trigger an event within Ometria's systems if the contents of the basket have been modified since the last update.

To create this object, use the following data:

  • basket_id (string): A unique identifier for this basket.
  • total (decimal): Sum of the cost of all items in the basket.
  • currency (string): ISO 4217 currency code.
  • items (array): An array of line items with the following data available for each item:
    • product_id (string): An identifier for the product associated with this line item.
    • quantity (int): Amount of items in this line item.
    • price (decimal): Cost of the single line item.
    • variant_id (string): An identifier for the variant product associated with this line item.
  • URL (string): The deeplink URL to be used when reinflating the basket. E.g. a direct link back to this basket. (optional)

Using this data, the basket object can be constructed in the following way:

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 should be used to ensure the basket information is tracked accurately in Ometria (as it's possible that someone adds something to a basket and then leaves the website).

Providing product_id is required when calling trackAddToBasket(). quantity is an optional argument. If no quantity is specified then we assume a quantity of 1.

Tracking orders

When an order is placed the following method call should be made:

ometria.trackTransaction(orderId)

The parameter orderid should be the same order ID used as the ID parameter in orders sent via the Ecommerce data API.  

If the orderId  that will be passed on the order record is not available in the data layer, you may pass a webId  instead. This should correspond with the web_id parameter in the order record.    

Typically this call is placed on 'thank you for your order' page(s). 

Debugging

To debug the plugin and see if it is correctly sending data to Ometria, append the #om_debug to the URL eg. http://www.example.com/resource/12345#om_debug, then reload the page (you may also have to refresh as a final step).

Messages will now appear in the debug window in the upper right corner of the page. The debug window will list the data events that have been registered by the plugin.

For further details on the data passed by the plugin open the browser console and click on the messages in the debug window.

The script will print additional information in the browser console associated with the message.

Here is a list of those messages and the circumstances they appear in:

Action Message Debug data printed to the console on click
User first arrives on the site with no previous cookie NEW COOKIE ID -
A new session is started NEW SESSION: session_id -
An existing session is continued EXISTING SESSION: session_id -
The active session is identified Identified: email_address -
On every page where page_type is defined Event: pageview (page_type) Page types
Shown when a setBasket event is called Event: setbasket Basket object
An item has been added to the basket Event: addtobasket Product ID and quantity of items added to basket
An order/transaction has been completed, where id is the order/transaction identifier Event: transaction (orderId) Order ID or Web ID
User logs in or enters their email address Event: identify User identification information

Related articles

Comments

0 comments

Please sign in to leave a comment.