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.
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:
- Call
ometria.init
to start event tracking, supplying thepageType
andpageData
parameters depending on the page being viewed. You should also provide astoreId
value, which is a string that must match the values used to send order data. - If the current user is logged in (or their email address is known), call
ometria.identify
. - If the current user has an active basket, call
ometria.setBasket
. - If this page is an order confirmation page, call
ometria.trackTransaction
. - 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:
ometria.identify(visitor_email);
ometria.identify(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.
Note
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.
See Debugging JavaScript tracking if you encounter any problems identifying contacts.
Page types
The ometria.init(pageType, pageData, storeID)
method accepts three parameters:
Parameter | Description |
---|---|
| The page type on your website. |
| A JavaScript object with keys depending on the page type. |
| A string representing the store the visitor is currently active on. This must match the |
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:
Data | Type | Description |
---|---|---|
| String | A unique identifier for this basket. |
| Float | Sum of the cost of all items in the basket. |
| Number | The count of the items in the basket. |
| String | ISO 4217 currency code, e.g. GBP, USD. |
| Array | An array of line items with the following data available for each item: |
| String | An identifier for the product associated with this line item. |
| Integer | The amount of items in this line item. |
| Float | The cost of the single line item. |
| String | An identifier for the variant product associated with this line item. |
| String | The deeplink URL to be used when re-inflating the basket. E.g. a direct link back to this basket. You must provide this for your abandoned basket campaigns to function correctly - for Magento users, this field is set automatically. |
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
.
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.
Updated 5 months ago