Visitor Tracking

How to set up visitor tracking in an API integration

Tracking visitor behavior is an essential feedback-loop for Clerk.io. Tracking allows us to accurately determine how much Clerk.io affects your stores sales and provide you with better results, as 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
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.

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

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

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

This ID should then be stored in a persistent storage cache as a cookie or generated based dynamically based on a ruleset.

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 identifier is used with multiple visitor IDs.

<?php
  if (isset($_COOKIE["clerk_visitor"])) {
      return $_COOKIE["clerk_visitor"];
  }
  else {
      $visitor_id = substr(uniqid(), 0, 8);
      setcookie("clerk_visitor", $visitor_id);
    	return $_COOKIE["clerk_visitor"];
  }
?>

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"]' \
       https://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 done by calling the endpoint log/click with.

$ curl -X POST \
       -H 'Content-Type: application/json' \
       -d '{"key":      "your_api_key",
            "visitor":  "aR9Km32l",
            "product": 	534' \
       https://api.clerk.io/v2/log/click

Then, run this function after the page has finished loading the results from Clerk.io:
Clerk("click", "*[data-clerk-product-id]");

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 to setup sales-tracking so new orders are sent Clerk.io.

This is done with the log/sale endpoint.

curl -X POST \
     -H 'Content-Type: application/json' \
     -d '{"key": "store_api_key",
     	"visitor": "aR9Km32l",
      	"email": "[email protected]",
        "sale": 567,
        "products": [
            {
              "id": 1,
              "price": 99.95,
              "quantity": 2
            }, 
            {
              "id": 33,
              "price": 14.00,
              "quantity": 2
            }
          ]}' \
       https://api.clerk.io/v2/log/sale