Attribution tokens

Attribution tokens are unique IDs generated by Vertex AI Search for retail and returned with each search request. They enable Vertex AI Search for retail to associate a search request with its matching search event, which allows re-ranking models to improve the quality of search responses. Attribution tokens are also required in Vertex AI Search for retail search events for accurate reporting.

Note: Attribution tokens are only required for Vertex AI Search. They're not passed to all user events. Nor are they passed in the URL.

How attribution tokens work

Each response that the Vertex AI Search method returns includes a unique attributionToken at the end of the search response body. For example:

{
  "results": [
    {
      "id": "727121",
      "product": {
…
     }
  ],
  "totalSize": 19600,
  "attributionToken": "dfB0CgwIgKrltAYQ8afX4AIQARokNjZjMGEwYjEtMDAwMC0yNjAyLTk0Y2UtNTgyNDI5Y2JkMzUwKgUxMjM0NTIkxcvzF6OAlyLo5KotmNa3LY6-nRW3t4wtwvCeFdSynRWb1rctOg5kZWZhdWx0X3NlYXJjaGgB",
  "nextPageToken": "AM1MDZiNWOyQjM4UTLlNGN50iMwYjMtADMwATLwIGMhBzY2YDJaIw-bCbxQYAt1PJgIwgExEgC"
…

This token must be included in the subsequent search event:

{
"eventType": "search",
"searchQuery":"red t-shirt", 
"productDetails":[
  {"product":{"id":"727121"}}, {"product":{"id":  …
  }
] ,
"visitorId":"GA1.1.1383176924.1721324981",
"attributionToken":"dfB0CgwIgKrltAYQ8afX4AIQARokNjZjMGEwYjEtMDAwMC0yNjAyLTk0Y2UtNTgyNDI5Y2JkMzUwKgUxMjM0NTIkxcvzF6OAlyLo5KotmNa3LY6-nRW3t4wtwvCeFdSynRWb1rctOg5kZWZhdWx0X3NlYXJjaGgB"
}

Vertex AI Search for retail uses the event data to train its models. The attribution token provides a way to link the event with the request, encoding the full search request and response with the requested filters, facets, and response product IDs. Without a token present in the search events, those events are treated as if they were not from Google Vertex AI Search and the search events might be incorrectly used as if they were from another search provider.

It's fine (and expected) to have search events without tokens if they are served from another search provider, during an A/B experiment for example. However, there typically is a 1:1 mapping for search API requests to search events with tokens.

Attribution token data quality

The Data Quality dashboard in the Search for Retail will show a Critical or a Blocking non-compliance error Status if the percentage of events with attribution tokens is under 95%. Otherwise, the Status will show as Compliant:

The data quality at TIER 3 which is the revenue optimized model will usually not train without sufficient attributable events. It is strongly not recommended to deploy Vertex AI Search for retail into production unless it is serving results in TIER 3 or TIER 4. For more information, see the Data quality section on how to unlock perforance tiers see the Data quality page.

Attribution tokens for Recommendations

Since there is no event for recommendations, there is no need to include attribution tokens from predict responses in any events.

The attribution token from the predict response can be sent in subsequent events (usually a detail-page-view or add-to-cart), but it is not required. Implementation would require passing the recommended product's attribution token in a URL parameter to the product page URL and then using that parameter to populate the attributionToken field of the detail-page-view event.

Recommendations from Vertex AI Search automatically create synthetic tokens for events attributable to predict requests. Explicitly adding the tokens can improve analytics reporting accuracy slightly. However, this is not strictly required and will have little impact on the recommendations models.