Recommendation tokens

This page describes how you use recommendation tokens to improve recommendation performance over time.

Recommendation tokens are unique IDs, generated by Recommendations AI and returned with each prediction request, that enable Recommendations AI to associate user actions and recommendations with each other, to provide revenue and conversion rate metrics.

Including recommendation tokens in your user events is optional. If you do not provide recommendation tokens, Recommendations AI approximates the recommendation tokens by aligning the recommendations in the prediction response and the ingested user events based on the visitor ID and timestamps. Learn more.

How recommendation tokens work

Each recommendation that the predict method returns includes a unique recommendationToken in its response body. For example:

{
  "results": [{"id": "352"}, {"id": "456"}],
  "recommendation_token": "abc123"
}

When your website shows a product based on a recommendation from Recommendations AI, you must return the recommendation token from that recommendation when the user interacts with a recommended product (for example, a view, or add-to-cart click). This feedback loop enables Recommendations AI to provide information about how your recommendations are impacting your business. For more information, see Measuring Recommender Performance.

How you return the recommendation token

You return the recommendation token by including it in the user event you record for any action the user takes with the recommended product. What actions a user can take with a recommended product depends on the design of your website; common actions include adding a product to a favorites list, requesting a detailed view, adding it to a shopping cart or a one-click purchase.

To return the recommendation token, you must first associate it with the product as it is displayed in a recommendation panel on your website. A common way to do this is to append it to all urls associated with actions that can be taken on the recommendation panel. For example:

https://www.example.com/54321/?rtoken=abc123

Then, when the user interacts with that product in the recommendation panel (which generates a user event), the recommendation token can be parsed from the URL link and inserted into the user event you send to Recommendations AI for that interaction.

For example, suppose you request a prediction associated with showing a product to a user. Recommendations AI returns a set of recommended catalog IDs, along with an associated recommendation token.

{
  "results": [{"id": "352"}, {"id": "456"}],
  "recommendation_token": "abc123"
}

Your website displays the recommended items in a recommendation panel, and includes the returned recommendation token for that prediction with each url in the recommendation panel. When the user clicks on one of the recommended products to see a more detailed view of that product, you include the recommendation token with the detail-page-view user event you record on that click. The user event would look similar to the following example:

{
  "eventType" : "detail-page-view",
  "userInfo": {
    "visitorId": "visitor1",
    "userId": "user1"
   },
   "eventDetail": {
     "recommendationToken": "abc123",
   },
   "productEventDetail": {
      "productDetails": [{
        "catalogItemId": "123",
        "originalPrice": 49.00,
        "displayPrice": 44.00,
        "currencyCode": "USD"
       }
     ]
   }
}

When the user interacts with a product displayed due to a recommendation, and you include the recommendation token with the user event for that interaction, Recommendations AI uses that information for evaluation.

For example, suppose the user sees a product in a recommendation panel, and uses the recommendation panel to add that product to her wishlist and also to get a detailed view of the product. You must include the recommendation token for both of the user events generated from the recommendation panel (add-to-list and detail-page-view).

Now suppose that same user adds that product to her cart from the detailed view. You do not need to include the recommendation token with that action, because it was taken from the detailed view, not the recommendation panel. Similarly, if that user ultimately purchases the product, but not directly from the recommendation panel, there's no benefit to returning the recommendation token with the purchase event.

What's next