Skip to content

Click tracking

Products returned from the Hello Retail Product Recommendation, Search, and Pages APIs will feature two distinct URL types: one with a tracking code appended within the URL fragment, and the other being the original URL without the tracking fragment.

https://shop.example.com/best-product.html#aw_source=ps-3335d0a7-5dd1-4044-ba76-d089348abf31

https://shop.example.com/awesome-product.html#aw_source=pb-9cb4857e6ff3911d1c76ab6a

This tracking code allows the Hello Retail script to track clicks on products Search, Pages and Product Recommendations.

When using the managed Hello Retail services the tracking codes will automatically be extracted from the links and automatically passed to the trackClick method whe a product is clicked.

If you use the API or SDK manually to perform searches, fetch product recommendations or serve category pages, you have two options. You can either use the url response item which contains the tracking codes on the product urls. Whenever a product is clicked, the tracking code will be part of the URL the customer goes to. The Hello Retail script will see this code in the fragment, track the click, and then remove the tracking code from the fragment. The other option is to use the originalUrl and trackingCode items from the response and call our trackClick yourself.

Manual click tracking using the SDK

As previously mentioned, should you wish to manage click tracking yourself rather than using the URL with the appended tracking fragment, you must call our trackClick method. This requires the trackingCode item, which can be found in the product response object. Executing this method will register a click on the product within the given context.

The tracking code contains information about which product was clicked, and if it was in Search, product Recommendations or Pages. It might also contain other information that allows us to do more detailed tracking of exactly what was clicked. The tracking code should be considered an opaque string. The structure of it might change over time as our tracking needs change. So you should not attempt to construct the tracking code yourself, only use the information exactly as it was returned from the API.

More information about this part of the JSON body:

Name Type Example
url String https://shop.example.com/best-product.html#aw_source=pb-3335d0a7-5dd1-4044-ba76-d089348abf31
originalUrl String https://shop.example.com/best-product.html
trackingCode String pb-9cb4857e6ff3911d1c76ab6a

Once you have extracted the tracking code you need to implement an event handler that triggers the click tracking whenever a visitor interacts with the product. The following example shows how a simple function that renders a product in html and attaches a click handler. Typically you would use some form of templating language server side, or a javascript frontend framework to implement this type of rendering. This is just meant as a simple example.

function renderProduct(product) {
    const productNode = document.createElement("a");
    productNode.href = product.originalUrl;
    productNode.onclick = function() {
        hrq = window.hrq || [];
        hrq.push([
            "trackClick",
            product.trackingCode
        ]);
    };
    productNode.innerHTML = `<p>${product.title}</p><img src="${product.imgUrl} width="200"></a>`;
    return productNode;
}

You have to make sure the Hello Retail SDK is ready before calling it. Since you would typically not have any content to track without the SDK already being ready this is not an issue.

Verify tracking

To verify that the click tracking works, you can click one of the links that should track clicks with the network tab open in the browser developer console. Immediately when calling trackClick you should see a POST request to https://core.helloretail.com/serve/collect/click. The body of the request will be a JSON document containing among other things, the tracking code.

Click tracking SDK

As mentioned above click tracking can be done using the Hello Retail SDK method trackClick. The method accepts one required parameter, the tracking code.

Example: 

hrq = window.hrq || [];
hrq.push([
    "trackClick",
    trackingCode
]);

Manual click tracking using the REST API

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

Request

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

Example of the structure the JSON body must have:

{
    "trackingUserId": "{tracking user id}",
    "websiteUuid": "{website uuid}",
    "source": "pb-{tracking code}|{tracking code}|1|2|3"
}

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
source String Tracking code that is the source of the click. This is the tracking code returned as part of the product urls in the product recommendations, searchs and pages

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": "Click 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 ↩