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.

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:

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 ¹.

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

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.