Attribution tokens

Attribution tokens are unique IDs generated by AI Commerce Search and returned with each search request. They enable AI Commerce Search 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 AI Commerce Search search events for accurate reporting.

How attribution tokens work

You collect the attributionToken from the API response of a user's search. There is a new attribution token for every search; attribution tokens are not repeated.

When AI Commerce Search serves a search or recommendation request, it returns a unique attributionToken in its response.

A placements.search response should be sent back in a search or browse user event and immediately in the event a user interacts with a product. This includes user journeys such as:

  • search (YES) → add-to-cart (YES)
  • search (YES) → detail-page-view (YES)
  • search (YES) → purchase (NO) (The user isn't directly interacting with a product at the time of purchase in the same way as with a click or add-to-cart, though the purchase is still attributed to the original search.)

Attribution token behavior

Attribution tokens are:

  • Visitor-specific: The attributionToken is associated with a specific search response served to a particular `visitorId. Only the search event itself needs to be tagged with the token. All the subsequent non-search events are not to be tagged with a token.

  • Associated with events directly following search: The attributionToken is particularly important for user events that represent a direct interaction with the search results of that specific search. This includes purchase-complete events: The purchase is still linked through the product IDs and visitorId.

    Note: If a single user performs multiple searches, each new search request generates an attribution token, and the subsequent search event should carry that new token. An attribution token from a previous search event is not reused for a subsequent search event, because each search initiates a new token.

Attribution tokens in the Search API

Each response that the AI Commerce 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"
}

AI Commerce Search 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 AI Commerce 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.

Adverse effect of missing tokens

If the