Click tracking

Products returned from the Hello Retail product recommendation and search APIs will contain links that have a tracking code appended to them in the fragment part of the URL.

Example for SearchExample for Product Recommendations

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 ADDWISH_PARTNER_NS.api.tracking.track_click function 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 leave 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 options is to extract the tracking code from the url and handle calling track_click your self.

Manual click tracking using the SDK

If you want to handle the click tracking your self you have to extract the tracking code from the fragment part of the returned product urls. This the track_click method can then be called with the tracking code to register that a click on the product in the 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 your self from other information returned from the API. You should use the codes exactly as they are returned from the APIs.

To extract the tracking code from the url you can split the url string on "#aw_source=". This will give you an array with the url in the first element and the tracking code in the second element. If we imagine that the product object in the following example is a product returned in json format from the product recommendation api, then extracting the tracking code would look something like this:

const parts = product.url.split("#aw_source=");
const url = parts[0];
const trackingCode = parts[1];

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 parts = product.url.split("#aw_source=");
    const url = parts[0];
    const trackingCode = parts[1];
    const productNode = document.createElement("a");
    productNode.href = url;
    productNode.onclick = function() {
        ADDWISH_PARTNER_NS.api.tracking.track_click(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 track_click 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 ADDWISH_PARTNER_NS.api.tracking.track_click. The method accepts one required parameter, the tracking code.

Example:

ADDWISH_PARTNER_NS.api.tracking.track_click(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": "62a0317d17698aa57d369db9",
    "websiteUuid": "4bb65cc4-f2d2-4eb0-80d9-9496f912d2cf",
    "source": "pb-52a0317d17698aa57d369db9|52a0317d17698aa57d369db9|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)[https://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 ↩