Visitor Tracking

How Clerk.io tracks visitors to give you insights and improve the algorithmic performance.

Tracking visitor behavior is an essential feedback-loop for Clerk.io. Tracking allows us to accurately determine how much Clerk.io affects your store's sales and provide you with better results since tracking feedback is actively used by our algorithms.

📘

Info

By using any default Clerk.io setup all of the following will automatically be handled by Clerk.js.

There are 4 things that need to be set up for the tracking to function:

  1. A unique visitor ID must be set for each device visiting the site.
  2. That ID must be sent as the visitor parameter for each API request made to Clerk.io on behalf of the visitor.
  3. Click tracking must be added to all products returned from Clerk.io.
  4. Sales / Order tracking must be set up on the order success page.

This allows us to know exactly (1) what we present to the individual customer, (2) what they click on and ultimately (3) what they buy.

From this data, we can determine exactly how Clerk.io affected this session, present this in your dashboards, and use as feedback for our algorithms so that they get smarter with every order.

How to set up visitor tracking in an API integration

🚧

Important

Setting up visitor-tracking is only necessary if you have integrated Clerk.io via pure backend API calls. With our recommended JavaScript setup, this is all handled automatically.

1. Give each visitor (device) a unique tracking ID

The first step is to give each visitor a unique ID.

Clerk.io supports fully cookieless, anonymous session tracking which is enabled by default in Clerk.js, but can also be set explicitly with visitor: 'auto'

<script type="text/javascript">
  Clerk('config', {
    visitor: 'auto'
  });
</script>

Alternatively, you can generate your own custom IDs.

We recommend an 8 character string from the set [a-zA-Z0-9] eg. aR9Km32l.

This ID should then be stored in a persistent storage cush as a cookie.

A visitor ID should only be unique to the device. Cross-device association is handled automatically by Clerk.io if we detect that a customer ID is used with multiple visitor IDs.

When generated the visitor ID should always be set for Clerk.js like this:

<script type="text/javascript">
  Clerk('config', {
    visitor: 'aR9Km32l'
  });
</script>

2. Send the visitor ID along with every API call

Every time you make an API request you must send the visitor ID of the visitor you make the request on behalf of. This should be sent as the visitor parameter for the API request.

You should also add a tracking label for each location. This is used in Clerk.io's reporting to attribute where the sale came from as the labels parameter.

$ curl -X POST \
       -H 'Content-Type: application/json' \
       -d '{"key":      "your_api_key",
            "visitor":  "aR9Km32l",
            "limit":    4,
            "labels":   ["Complementary Products"] \
       http://api.clerk.io/v2/recommendations/visitor/complementary

3. Add click tracking

Click tracking makes sure we only track a sale of a product via Clerk.io if the customer actually clicked on the presented product.

This is most easily done by adding ?clerk_product=1234 to the URL of the product where 1234 is the product ID. When this website is visited we will track the click through Clerk.js.

If you don't want any trace in the URL you can also just add the attribute data-clerk-product-id="1234" for each product element in your HTML like this:

<ul class="product-list from-clerk">
  <li class="product" data-clerk-product-id="123">
    <a href="/green-lightsaber">
      <img src="/images/green-lightsaber.jpg" />
      Green Lightsaber
      <button>Add To Basket</button>
  </li>
  <li class="product" data-clerk-product-id="456">
    <a href="/super-death-star">
      <img src="/images/super-death-star.jpg" />
      Super Death Star
      <button>Add To Basket</button>
  </li>
</ul>

Then, run this function after the page has finished loading the results from Clerk.io:

This automatically enables click tracking on all elements (as long as Clerk.js is loaded on the page).

4. Track sales from the visitor

The last step is just to setup sales-tracking so orders are tracked correctly.
Remember to include the visitor ID in the sales-tracking call as well.

Identifying visitor IDs

If you need to identify what your current visitor ID is, assuming you are running Clerk.js with the auto cookieless solution, the following endpoint will show you what your visitor ID is:
https://api.clerk.io/v2/misc/visitor_id?visitor=auto&key=INSERT_STORE_KEY

Simply replace INSERT_STORE_KEY with the public key of your store. The response will look like this:

{
  "status": "ok",
  "visitor": "ezMqdTjU"
}