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:
- 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.
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:
Parameter | Description |
---|---|
pageType | The page type on your website. |
pageData | A JavaScript object with keys depending on the page type. |
storeID | A string representing the store the visitor is currently active on. This must match the storeID parameter used in the order endpoint of the data API to properly match orders to visits. |
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, 'storeI');
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 |
---|---|---|
basket_id | String | A unique identifier for this basket. |
total | Float | Sum of the cost of all items in the basket. |
size | Number | The count of the items in the basket. |
currency | String | ISO 4217 currency code, e.g. GBP, USD. |
items | Array | An array of line items with the following data available for each item: |
items[].product_id | String | An identifier for the product associated with this line item. |
items[].quantity | Integer | The amount of items in this line item. |
items[].price | Float | The cost of the single line item. |
items[].variant_id | String | An identifier for the variant product associated with this line item. |
url | 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
.
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.
Updated 14 days ago