Tracking | Clerk.io

Lastly, tracking must be added to keep Clerk’s AI up-to-date and personalize a visitor’s results during their session. Clerk tracking is setup in 4 steps:

Generating a session ID for each visitor
Adding descriptive tracking labels to API calls that return results, which are used for showing analytics for individual endpoints
Logging a visitor’s clicks on products shown by Clerk
Logging each order made on the webshop

Visitor (Session) ID #

The session ID is also called the Visitor ID with Clerk. It is strictly required to log a user’s activity during a session on the webshop, including products clicked, searches made, and categories browsed. This activity is stored for each domain, and Clerk never shares it across stores.

For example, you could use PHP’s uniqid(), function to generate IDs that are unique for at least the current session. Once generated, this ID must be included in all calls to Clerk for tracking to work.

<?php

session_start();

$current_visitor = uniqid(); //Example: "646f1f0584371"

$_SESSION["clerk_visitor_id"] = $current_visitor;

?>

Labels #

Labels must be added to any call that returns results, such as search results or alternatives on a product page. The labels argument is a list containing at least one string, which should be the label of this call.

We recommend using labels that contain the page each call is used on and the type of results it shows, like “Homepage - Trending”. This makes them easy to distinguish in analytics.

curl --request POST \
     --url 'https://api.clerk.io/v2/recommendations/trending' \
     --header 'accept: application/json' \
     --header 'content-type: application/json'
     -d '{"key": "Ipkv9tKfxRdpLv3mpMhqxfWGNdqugE0c",
          "limit": 30,
          "labels": ["Homepage - Trending"],
          "visitor": $_SESSION["clerk_visitor_id"]
        }'

Logging clicks #

Then, you should log each click on a Clerk product with log/click. It’s important to only make this call when the product clicked is actually shown by Clerk and not the webshop platform itself; otherwise, it will look like all products are found through Clerk.

Include the product id product, and ideally also the api endpoint and the labels from the API call that showed this product. If this is not included, Clerk will backtrack the click to the last API call that showed this product.

curl --request POST \
     --url 'https://api.clerk.io/v2/recommendations/trending' \
     --header 'accept: application/json' \
     --header 'content-type: application/json'
     -d '{"key": "Ipkv9tKfxRdpLv3mpMhqxfWGNdqugE0c",
          "labels": ["Homepage - Trending"],
          "api": "recommendations/trending",
          "visitor": $_SESSION["clerk_visitor_id"],
          "product": 12793
        }'

Logging sales #

Lastly, use log/sale to track each order as soon as it is placed on the webshop. With the visitor ID included in this call, Clerk will understand which products were shown, clicked on, and finally purchased. This allows the AI to always stay up-to-date and change results on the fly based on customer behavior.

Important:

The id of products should match the IDs that are logged with log/click. E.g. for configurable products you should track the parents ID in both log/click and log/sale regardless of the variant bought.
price is the unit price for products. Clerk multiplies it by the quanitity in our analytics.

curl -X POST \
     -H 'Content-Type: application/json' \
     -d '{"key": "Ipkv9tKfxRdpLv3mpMhqxfWGNdqugE0",
          "sale": 567,
          "products": [
            {
              "id": 12793,
              "price": 99.95,
              "quantity": 2
            },
            {
              "id": 1546,
              "price": 14.00,
              "quantity": 2
            }
          ],
          "customer": 1234,
          "email": "theone@matrix.com",
          "visitor": $_SESSION["clerk_visitor_id"]}' \
       https://api.clerk.io/v2/log/sale

Details of the Visitor ID #

By default, Clerk.io is cookieless and uses anonymous visitor ID’s rather than storing cookies.

The ID is used for providing analytics in Clerk.io’s Dashboards and for on-site functionality like “You Previously Visited” recommendations.

For more details about how Cookieless Personalisation works, check this article.

What do we use the ID for? #

Dashboards, Analytics and Attribution.

Clerk.io tracks all orders placed on the webshop, and compares the ones impacted by Clerk.io, with the orders not impacted.

Through the visitor ID, we can track when a consumer clicks on a product in a Clerk.io element, and proceeds to place an order containing that product to allow for attribution.

On-site Functionality

Through the visitor ID, we collect the IDs of products that a consumer browses and the searches they make.

This allows us to personalise recommendations on the webshop, including banners like " Our Recommendations For You" and " You Previously Saw" that show products related to browsing on the webshop.

The visitor ID and how it works #

Every call being made to Clerk.io will contain the anonymous visitor ID described above so it can be used for the above purposes.

When a visitor writes their email address on the webshop and/or places an order, the Visitor ID is attached to their email address if sales-tracking is activated.

An email address in Clerk.io can contain multiple Visitor IDs which can be seen on the customers page in my.clerk.io:

If a user accepts cookies from your site, you can configure Clerk to add a cookie that enables long-term tracking with this generated ID. This is done simply by adding visitor: ‘persistent’ to Clerk.js.

Deactivating the ‘visitor’ ID #

By default, Clerk.js runs in cookieless mode, so if the visitor parameter is not set, we will log the session activity without adding a cookie.

Should you want to allow the visitor to choose not to be tracked in anyway, the ID can be deactivated entirely by adding ‘visitor’: null:

Clerk.js

In setups using Clerk.js, add it to the Clerk.js code for that visitor:

API

If you are using direct API calls, include it as an argument:

curl -X POST \
     -H 'Content-Type: application/json' \
     -d '{"key": "yu0tX54BcDAIuBp8RkNoldtcir9Dwip8",
          "limit": 30,
          "labels": ["Bestsellers"]
          "visitor": null}' \
     http://api.clerk.io/v2/recommendations/popular

If you are have questions regarding visitor tracking, please don’t hesitate reaching out to our Customer Success team through the live-chat in the lower right corner.

Api: Tracking