Attribution tokens

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

Attribution tokens are unique IDs generated by Vertex AI Search for retail and returned with each predict or search request. They enable Vertex AI Search for retail to associate user actions and results with each other, and to train re-ranking models to improve the quality of results.

Including attribution tokens in your user events is optional. If you do not provide attribution tokens, Vertex AI Search for retail approximates the attribution tokens by aligning the results in the predict or search response and the ingested user events based on the visitor ID and timestamps.

How attribution tokens work

Each response that the predict or search method returns includes a unique attributionToken in its response body. For example:

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

When your website shows a product based on a result from Vertex AI Search for retail, you must return the attribution token from that result when the user interacts with a returned product (for example, a view, or add-to-cart click). This feedback loop enables Vertex AI Search for retail to provide information about how your results are impacting your business.

How you return the attribution token

Return the attribution token by including it in the user event you record for any action the user takes with the product in a recommendation or search result. What actions a user can take with that 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 attribution token, you must first associate it with the product as it is displayed in the recommendation panel or search results 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 or search results. For example:

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

When the user interacts with that product in the recommendation panel or search results (which generates a user event), the attribution token can be parsed from the URL link and inserted into the user event you send to Vertex AI Search for retail for that interaction.

For example, suppose you request a prediction associated with showing a product to a user. Vertex AI Search for retail returns a set of recommended catalog IDs, along with an associated attribution token.

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

Your website displays the recommended items in a recommendation panel, and includes the returned attribution token for that prediction with each URL in the recommendation panel. You should have your site configured to record that event to send to Vertex AI Search for retail. For an example of the user event object, see the search user event. When the user clicks one of the products in a result to see a more detailed view, you include the attribution token with the user event you record on that click. The user event would look similar to the following example:

{
  "eventType" : "detail-page-view",
  "visitorId": "visitor1",
  "userInfo": {
    "userId": "user1"
   },
   "attributionToken": "abc123",
   "productDetails": [{
     "product": {
        "id": "abc"
       }
     }]
}

When the user interacts with a product displayed due to a recommendation or search result, and you include the attribution token with the user event for that interaction, Vertex AI Search for retail uses that information for evaluation.

For example, suppose the user sees a product in a search result, and uses the result to add that product to her wishlist and also to get a detailed view of the product. You must include the attribution token for both of the user events generated from the search result (add-to-cart 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 attribution token with that action, because it was taken from the detailed view, not the search result. Similarly, if that user ultimately purchases the product, but not directly from the search result, there's no benefit to returning the attribution token with the purchase event.