Attribution tokens

Attribution tokens are unique IDs generated by Vertex AI Search for commerce and returned with each search request. They enable Vertex AI Search for commerce 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 commerce 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 Vertex AI Search for commerce serves a search or recommendation request, it returns a unique attributionToken in its response:

• This token is crucial for linking subsequent user actions (like clicks, adding to cart, and purchases) back to the specific search or recommendation that led to them.
• It's important to link the correct search token into Search Events, so that Detailed Page View Events, Add-to-Cart Events, and Purchase Events can be connected properly.

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 Vertex AI Search for commerce 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 commerce 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.

Adverse effect of missing tokens

If the attributionToken isn't in the relevant subsequent user events from the same visitor, Vertex AI Search for commerce treats those events as if they did not originate from its search service.

This can lead to:

• Inaccurate model training.
• Incorrect metrics and performance analysis.
• Potential issues with achieving higher performance tiers (like Tier 3) that require sufficient attributable events.
• Errors reported in the Data quality dashboard in the Search for commerce if the percentage of events with attribution tokens is less than 95%.

To learn from user behavior and optimize search results, Vertex AI Search for commerce requires accurate attribution for the initial search event only.

Attribution token data quality

The Data quality dashboard in the Search for commerce console 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 commerce 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 of this documentation.

Attribution tokens for recommendations

Recommendations from Vertex AI Search automatically create synthetic tokens for events attributable to predict requests.

For recommendations predictions, if a user clicks on a recommended product, the PredictResponse.attribution_token should be passed as a URL parameter to the product page and then logged in the detail-page-view event.

Log displayed recommendations as part of panelInfo and set:

panelInfo.attributionToken=PredictResponse.attributionToken