Vertex AI Search for retail is being renamed to Vertex AI Search for commerce. We're updating content to reflect the new branding.

Attribution tokens
Stay organized with collections Save and categorize content based on your preferences.

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. Send back that token generated by the visitor from that specific interaction in the user events.

Attribution token behavior

Attribution tokens are:

Visitor-specific: The attributionToken is associated with a specific search response served to a particular `visitorId. Therefore, the token you received in the response to a search made by visitorId 'A' should be sent back with the subsequent events originating from the same visitorId 'A' that are a direct consequence of that search.
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:
- Subsequent search events: If the same user performs another search right after the initial one (such as refining their query), the attributionToken from the first search response should ideally be included in the user event for the second search if the second search is a continuation of the first.
- Detail-page-view events: When the user clicks on a product in the search results and views its details, the attributionToken from the search response that contained that product should be included in the detail-page-view user event. This is often done by passing the attributionToken as a URL parameter to the product page.
- Add-to-cart events: If the user adds a product to their cart directly from the search results or after viewing the details of a product found through that search, the attributionToken from the originating search response should be included in the add-to-cart event.
- Purchase-complete events: If intermediate, already-attributed interactions occurred, like detail-page-views or add-to-cart actions, the attributionToken isn't sent with the purchase-complete event. The purchase is still linked through the product IDs and visitorId.
Facilitating search event and request mapping: Including the attributionToken in subsequent user events is crucial for accurately mapping user behavior back to the specific search request and its results served by Vertex AI Search for commerce.

This linking allows Vertex AI Search to understand:
- Which search queries and results led to user engagement (clicks, views, adds to cart, purchases).
- The relevance and effectiveness of the search ranking.
- Whether or not to generate positive and negative examples for training the ranking model.
- How to compute per-search metrics like Click-Through Rate (CTR), Conversion Rate (CVR), and Revenue per Search.
- How to attribute conversions to the specific search that led to them, especially in A/B testing scenarios.

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. Ensure that the attributionToken from a search response is associated with the specific visitor who made that search. It must be in the user events from the search interaction they generated, especially for search, detail-page-view, and add-to-cart events.

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:

Alt text

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

Because there's no specific user event for recommendations, don't include attribution tokens from predict responses in any events. However, it's highly recommended to include the PredictResponse.attribution_token in subsequent user events resulting from a recommendation (such as detail-page-view or add-to-cart).

Implementation requires passing the recommended product's attribution token in a URL parameter to the product page URL. Then, use that parameter to populate the attributionToken field of the corresponding user 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.