归因令牌是 Vertex AI Search 商务解决方案生成的唯一 ID，随每个搜索请求一起返回。它们可让 Vertex AI Search 商务解决方案将搜索请求与其匹配的搜索事件相关联，从而使重新排名模型能够提高搜索回答的质量。此外，Vertex AI Search 商务解决方案的搜索事件还需要归因令牌，以便生成准确的报告。
归因令牌的工作原理
从用户搜索的 API 响应中收集 attributionToken。每次搜索都有一个新的归因令牌；归因令牌不会重复。
搜索展示事件中必须包含归因令牌，但对于任何其他事件（例如点击、添加到购物车和购买），都不得发送归因令牌。当 Vertex AI Search for Commerce 处理搜索或推荐请求时，会在响应中返回唯一的 attributionToken：
Vertex AI Search for Commerce 使用事件数据来训练其模型。归因令牌提供了一种将事件与请求相关联的方式，通过编码完整搜索请求和响应来包含所请求的过滤条件、商品详情和响应商品 ID。如果搜索事件中没有令牌，这些事件会被视为不是来自 Google Vertex AI Search，并且可能会被错误地用作来自其他搜索提供商的事件。
如果搜索事件来自其他搜索提供商（例如在 A/B 实验期间），则没有令牌是正常（且预期）的。不过，对于包含令牌的搜索 API 请求，搜索事件通常会以 1:1 的比例进行映射。
缺少令牌的不利影响
如果 attributionToken 不在同一位访问者的相关后续用户事件中，Vertex AI Search for Commerce 会将这些事件视为并非源自其搜索服务。
[[["易于理解","easyToUnderstand","thumb-up"],["解决了我的问题","solvedMyProblem","thumb-up"],["其他","otherUp","thumb-up"]],[["很难理解","hardToUnderstand","thumb-down"],["信息或示例代码不正确","incorrectInformationOrSampleCode","thumb-down"],["没有我需要的信息/示例","missingTheInformationSamplesINeed","thumb-down"],["翻译问题","translationIssue","thumb-down"],["其他","otherDown","thumb-down"]],["最后更新时间 (UTC)：2025-08-18。"],[],[],null,["# 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.\n| **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.\n\nHow attribution tokens work\n---------------------------\n\nYou collect the `attributionToken` from the API response of a user's search. There is a\nnew attribution token for every search; attribution tokens are not repeated.\n| **Important:** Attribution tokens are required in search impression events, but they are not to be sent for any other events, such as click, add-to-cart, and purchase.\n\nWhen Vertex AI Search for commerce serves a search or recommendation request, it returns a unique `attributionToken` in its response:\n\n- 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.\n- 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.\n\nA `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:\n\n- `search` (YES) → `add-to-cart` (YES)\n- `search` (YES) → `detail-page-view` (YES)\n- `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.)\n\n### Attribution token behavior\n\nAttribution tokens are:\n\n- **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.\n\n- **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`.\n\n\n 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.\n\n### Attribution tokens in the Search API\n\nEach response that the Vertex AI Search for commerce method returns includes a unique `attributionToken` at the end of the search response body. For example: \n\n```json\n{\n \"results\": [\n {\n \"id\": \"727121\",\n \"product\": {\n...\n }\n ],\n \"totalSize\": 19600,\n \"attributionToken\": \"dfB0CgwIgKrltAYQ8afX4AIQARokNjZjMGEwYjEtMDAwMC0yNjAyLTk0Y2UtNTgyNDI5Y2JkMzUwKgUxMjM0NTIkxcvzF6OAlyLo5KotmNa3LY6-nRW3t4wtwvCeFdSynRWb1rctOg5kZWZhdWx0X3NlYXJjaGgB\",\n \"nextPageToken\": \"AM1MDZiNWOyQjM4UTLlNGN50iMwYjMtADMwATLwIGMhBzY2YDJaIw-bCbxQYAt1PJgIwgExEgC\"\n...\n```\n\nThis token **must** be included in the subsequent search event: \n\n```json\n{\n\"eventType\": \"search\",\n\"searchQuery\":\"red t-shirt\", \n\"productDetails\":[\n {\"product\":{\"id\":\"727121\"}}, {\"product\":{\"id\": ...\n }\n] ,\n\"visitorId\":\"GA1.1.1383176924.1721324981\",\n\"attributionToken\":\"dfB0CgwIgKrltAYQ8afX4AIQARokNjZjMGEwYjEtMDAwMC0yNjAyLTk0Y2UtNTgyNDI5Y2JkMzUwKgUxMjM0NTIkxcvzF6OAlyLo5KotmNa3LY6-nRW3t4wtwvCeFdSynRWb1rctOg5kZWZhdWx0X3NlYXJjaGgB\"\n}\n```\n\nVertex 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.\n\nIt's fine (and expected) to have search events without tokens if they are served from another search provider, during an [A/B experiment](/retail/docs/a-b-testing) for example. However, there typically is a 1:1 mapping for search API **requests** to search **events** with tokens.\n\nAdverse effect of missing tokens\n--------------------------------\n\nIf 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.\n\nThis can lead to:\n\n- Inaccurate model training.\n- Incorrect metrics and performance analysis.\n- Potential issues with achieving [higher performance tiers](/retail/docs/data-quality) (like Tier 3) that require sufficient attributable events.\n- Errors reported in the [Data quality dashboard](https://console.cloud.google.com/ai/retail/catalogs/default_catalog/data_quality/) in the Search for commerce if the percentage of events with attribution tokens is less than 95%.\n\nTo learn from user behavior and optimize search results, Vertex AI Search for commerce requires accurate attribution for the initial search event only.\n\nAttribution token data quality\n------------------------------\n\nThe [Data quality dashboard](https://console.cloud.google.com/ai/retail/catalogs/default_catalog/data_quality/) 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:\n\nThe 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](/retail/docs/data-quality#tiers) see the [Data quality](/retail/docs/data-quality#tiers) page of this documentation.\n\nAttribution tokens for recommendations\n--------------------------------------\n\nRecommendations from Vertex AI Search automatically create synthetic tokens for events attributable to `predict` requests.\n\nFor 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.\n\nLog displayed recommendations as part of [`panelInfo`](/retail/docs/reference/rest/v2/projects.locations.catalogs.userEvents#panelinfo) and set: \n\n panelInfo.attributionToken=PredictResponse.attributionToken"]]
