View tracking

To be able to provide good personalization and useful analytics, Hello Retail can collect information about where visitors came from and what pages and products a visitor is looking at. This is done through view tracking.

The Hello Retail javascript will automatically track page views. So in many situations this is not something that has to be configured manually.

There are however cases where it might make sense to implement view tracking your self. This could for instance be in SPAs where the page is not reloaded on every page change. We have more information about this specific case in our SPA guide.

If you want to handle view tracking your self you have to disable the automatic view tracking. This is done by passing a parameter in the initialization code for the Hello Retail script.

The parameter is called trackPageView and it should be set to false to opt out of the automatic page view tracking. Adding the parameter looks like this in the initialization code:

<script async src="https://helloretailcdn.com/helloretail.js"></script>
<script>
    window.hrq = window.hrq || [];
    hrq.push(['init', 
        {
            trackPageView: false
        }
    ]);
</script>

This will disable the automatic view tracking.

Manual view tracking using the SDK

Page and product views can be tracked manually by calling the SDK method trackPageView. The method accepts two optional parameters. The first one is the canonical url of the current page, the second is the product number of the product currently being viewed. If the url is not passed, the value of document.location.href is used. The server will try to find a product from your product catalog that matches the passed information and register that the product has been viewed. If a product number is passed then it will try that first. If a product number is not passed or a product is not found it will try using the url instead. Remember that you have to make sure that the script is ready before tracking. If you don't want to pass a custom url or product number, then view tracking would look like this:

hrq = window.hrq || [];
hrq.push([
    "trackPageView"
]);

Passing a product number but no url will look like this:

hrq = window.hrq || [];
hrq.push([
    "trackPageView",
    null,
    "{product id}"
]);

Manual view tracking using the REST API

The Hello Retail SDK uses a REST API endpoint to track the page view. This API can also be used directly.

Request

The endpoint is available at https://core.helloretail.com/serve/collect/pageview. You use it by sending a HTTP POST request with a JSON body. The content type must be application/json or text/plain ¹.

Example of the structure the JSON body must have:

{
    "location": "https://shop.example.com/campaigns/summer/shoes-123",
    "trackingUserId": "{tracking user id}",
    "websiteUuid": "{website uuid}",
    "referrer": "https://google.com/",
    "url": "https://shop.example.com/products/shoes-123",
    "productNumber": "{product number}"
}

More information about each part of the JSON body

Name	Type	Description
trackingUserId	String	Tracking user id that has been generated by Hello Retail. You can read more about the tracking user here
websiteUuid	String	The id identifying the website in Hello Retail. This can be found on my.helloretail.com
location	String (optional)	The url of the current page. We use this to associate the view with a specific location. It has to be a valid URL with http protocol, domain and everything.
referrer	String (optional)	The value of the referer HTTP header of the request that the vistor made to fetch the current page. In the browser it is available in document.referrer
url	String (optional)	The canonical url for the page. This is used to find a product in your product catalog in Hello Retail, in order to associate the view with that product. If the url is identical to location then you dont have to pass it. You also don't have to pass it if you identify the product using the productNumber parameter instead
productNumber	String (optional)	This is used to find a product in your product catalog in Hello Retail, in order to associate the view with that product. If you use the url or location to identify the product then you dont have to pass this parameter

Response

The response will indicate if the tracking succeeded. A success response will have the 200 response code. The body of the response will look like this:

{
    "success": true,
    "message": "Page view tracked"
}

If the tracking fails because of invalid input the response will have the 400 response code. An example could be not supplying the websiteUuid. This will result in the following response:

{
    "success": false,
    "message": "websiteUuid is required"
}

If the tracking fails for other reasons it will fail with the 500 response code. If you experience this please contact Hello Retail support

---

1. The reason for supporting text/plain is to allow requests to this endpoint, made from the browser, to be categorized as simple thereby avoiding CORS preflight requests. You can read more here https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS#simple_requests ↩