记录实时用户事件

本页面介绍了如何记录实时用户事件。面向零售业的 Vertex AI Search 使用实时用户事件生成推荐内容和搜索结果。 记录尽可能多的用户事件类型和有效的产品信息可以提高结果的质量。

本页面上的记录过程适用于推荐和搜索。录制后 两种服务都能使用这些事件，因此您无需上传 如果您使用两项服务，则会看到两次相同的数据。

如需详细了解用户事件（包括所有类型的用户事件类型和示例 JSON），请参阅用户事件简介。

您可以通过多种方式记录用户事件：

• 使用 JavaScript 像素。

• 从您的后端服务器直接向 API 发送事件。

• 使用跟踪代码管理器标记。

您可以在以下所有方法中找到记录 detail-page-view 类型的用户事件的示例。对于其他 事件类型，请参阅用户事件简介。

您也可以导入历史用户事件。记录足够的用户事件数据来训练模型可能需要相当长的时间。您可以通过从过去的事件中批量导入用户事件数据来加速初始模型训练。请参阅导入历史用户事件。

如果您要记录的用户事件是用户第一次根据先前提供的建议或搜索结果与产品互动，包括可启用效果指标的归因令牌。如需使用 Vertex AI Search for Retail，必须添加归因令牌 工作。如需了解如何使用归因令牌，请参阅归因令牌。

记录用户事件时，必须提供访问者 ID。有关访问者 ID 和用户 ID 的信息 请参阅用户信息简介。

注意：使用唯一标识符的安全形式，让用户对 Vertex AI Search for Retail 保持匿名并保护用户的隐私。您需要负责从数据中隐去个人身份信息 (PII)，例如电子邮件地址或家庭住址。

教程：写入用户事件

本教程介绍如何使用 userEvents.write 方法。

---

如需遵循有关此任务的分步指导，请直接在 Cloud Shell Editor 中点击操作演示：

操作演示

---

准备工作

在记录用户事件前，您应该：

• 创建了一个 Google Cloud 项目并设置了身份验证。

• 有效的 API 密钥（用于 JavaScript Pixel 或跟踪代码管理器），或者有效的服务账号（如果使用 API 直接编写，则分配 Retail Editor 角色）。

  如需了解更多信息，请参阅准备工作。

记录用户事件的最佳做法

面向零售业的 Vertex AI Search 需要高质量的数据才能生成高质量的 结果。如果数据不完整或不正确，则结果质量将受到影响。

记录用户事件时，请确保实现以下最佳做法：

• 如果您在导入目录之前或导入目录时记录用户事件，请在目录导入完成之前重新联接记录的任何事件。

  您可以导入目录 在记录用户事件之前、之后或同时进行。如果目录很大并且有大量用户事件，则并行执行这些任务可以节省时间。目录导入完成后，您必须使用 API 重新联接在导入完成之前上传的事件。

  零售业 Vertex AI Search 尝试将记录的用户事件与 创建用户事件时收集到的商品清单中的元数据。只有成功联接的事件将用于训练，因此请确保重新联接在完全导入目录之前记录的所有事件。如果事件所引用的项在目录中不存在，系统会舍弃该项，或不能将其与正确的产品相关联。同样，如果您从过去导入用户事件，则该目录必须包含其引用的所有产品；您可以将较旧的产品标记为 OUT_OF_STOCK，而不是从目录中将其移除。

• 使目录保持最新状态。

  当您记录用户事件时，用户事件中包含的产品将与当前目录相关联。如果您录制了某次事件 当前目录中未列出的商品，因此无法用于训练 模型。这称为“未联接”事件。如果您录制事件的时间早于 您的目录已完全导入，则必须重新加入 事件。预计会有一些未联接的事件。但是，如果未联接事件的百分比达到用户事件总数的 5% 或更多，请确保您的目录为最新状态，重新联接目录完全更新之前记录的事件，以及调查用户创建未联接的事件的原因。

  您可以使用事件过滤条件查看未联接的事件。了解详情。

• 提供尽可能多的用户事件信息。

  每种用户事件类型所需和所接受的信息各不相同。如需了解详情，请参阅用户事件简介。

• 设置 Cloud Monitoring 提醒，以便了解自己是否 用户事件记录流程出现任何中断的情况。

• 对于批量用户事件导入，请限制您要导入的数据大小。

  批量用户事件导入最多可能需要 24 小时才能完成。

  每个文件的大小不得超过 2 GB。您最多可以在一次导入请求中包含 100 个文件。一种方法是一次只导入一天的用户事件。

• 批量导入后，请查看错误报告，以确保您的数据已正确导入。

• 导入用户事件数据时，为每个用户事件添加准确的时间戳，并避免导入时间戳相同的连续用户事件。

  按照 RFC 3339 指定的格式，在 eventTime 字段中提供时间戳。

• 如果您导入的用户事件不正确，请与您的 Vertex AI Search for Retail 联系人联系，了解如何更正该问题。

• 请尽可能保证用户事件数据连续。

  用户事件数据缺口会降低模型质量。

• 使用唯一标识符的安全形式，让用户对 Vertex AI Search for Retail 保持匿名并保护用户的隐私。您需要负责从数据中隐去个人身份信息 (PII)，例如电子邮件地址或家庭住址。

使用 JavaScript 像素记录用户事件

以下示例使用 JavaScript 像素记录 detail-page-view UserEvent。

<script type="text/javascript">
var user_event = {
  "eventType" : "detail-page-view",
  "visitorId": "visitor-id",
  "userInfo": {
      "userId": "user-id"
  },
  "attributionToken": "attribution-token",
  "experimentIds": "experiment-id",
  "productDetails": [
      {
        "product": {"id": "123"}
      }
  ]
};

var _gre = _gre || [];
// Credentials for project.
_gre.push(['apiKey', 'api-key']);
_gre.push(['logEvent', user_event]);
_gre.push(['projectId', 'project-id']);
_gre.push(['locationId', 'global']);
_gre.push(['catalogId', 'default_catalog']);

(function() {
  var gre = document.createElement('script'); gre.type = 'text/javascript'; gre.async = true;
  gre.src = 'https://www.gstatic.com/retail/v2_event.js';
  var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(gre, s);
})();

</script>

如果您使用 Google Analytics 360 导入用户事件，请将 visitorID 设置为 Google Analytics 客户端 ID。请注意，Google Analytics 客户端 ID 仅是完整 _ga Cookie 名称的一部分（例如，客户端 ID 123456789.123456789 是 _ga Cookie GA1.3.123456789.123456789 的一部分）。

如需详细了解如何获取客户端 ID，请参阅 Google Analytics 文档。

以下是一个缩略的示例，其中包含在用户事件中设置客户端 ID 的格式。替换“G-XXXXXX”与您的 Google Analytics 跟踪 ID。

<script type="text/javascript">
var tracker = ga.getByName('G-XXXXXX');
var user_event = {
      "visitorId": tracker.get('clientId')
};
</script>

使用 userEvents.write 方法记录用户事件

您可以使用 userEvents.write 方法从后端服务器直接将用户事件发送到 API。

如要记录用户事件，请向 userEvents.write 方法发送 POST 请求，并提供相应的请求正文。

curl

export GOOGLE_APPLICATION_CREDENTIALS=/tmp/my-key.json
curl -X POST \
     -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     --data "{
         'eventType': 'detail-page-view',
         'visitorId': 'visitor0',
         'eventTime': '2020-01-01T03:33:33.000001Z',
         'experimentIds': ['321'],
         'attributionToken': 'ABC',
         'attributes': {
            'example_text_attribute': {
              'text': ['text_1', 'text_2']
            },
            'example_number_attribute': {
               'numbers': [3.14, 42, 1.2345]
            }
         },
         'productDetails': [{
           'product': {
             'id': 'abc'
           }
          }],
         'userInfo': {
           'userId': 'abc',
           'ipAddress': '8.8.8.8',
           'userAgent': 'Mozilla/5.0',
           'directUserRequest': true
         },
         'uri': 'http://example',
         'referrerUri': 'http://example',
         'pageViewId': 'currentPageUri'
}" \
"https://retail.googleapis.com/v2/projects/PROJECT_ID/locations/global/catalogs/default_catalog/userEvents:write"

Java

public static UserEvent writeUserEvents(UserEvent eventToWrite)
    throws IOException, InterruptedException {
  UserEventServiceClient userEventsClient = getUserEventServiceClient();

  WriteUserEventRequest request = WriteUserEventRequest.newBuilder()
      .setParent(DEFAULT_CATALOG_NAME)
      .setUserEvent(eventToWrite)
      .build();

  UserEvent writtenUserEvent = userEventsClient.writeUserEvent(request);

  userEventsClient.shutdownNow();
  userEventsClient.awaitTermination(2, TimeUnit.SECONDS);

  return writtenUserEvent;
}

使用 Google Analytics 4 记录用户事件

您可以记录 Google Analytics 4 用户事件数据， Vertex AI Search for Retail。

查看数据源

请确保您要导入的用户事件数据格式正确无误。

对于 Vertex AI Search for Retail 的 Google Analytics 4 字段表， 以及它们映射到的零售业 Vertex AI Search 字段， 请参阅 Google Analytics 4 用户事件字段。

如需了解所有 Google Analytics 事件参数，请参阅 Google Analytics 事件参考文档。

请检查：

1. 如果您要导入某些 Vertex AI Search for Retail 模型所需的购买事件，您的事件报告将包含货币代码。请参阅 Google Analytics 文档中的 purchase 事件参数。

2. 如果您打算导入 search 个事件，则事件报告将包含搜索 查询。

   支持导入 search 事件，但 search 事件从 Google Analytics 4 映射的方式与其他事件类型不同，因为 Google Analytics 4 本身不支持零售专用 Vertex AI Search search 事件类型。在导入过程中，系统会通过将 view_item_list 和 search_term 事件参数中的信息相结合，从 Google Analytics 4 构建 search 事件。

   请参阅 search 事件参数 Google Analytics 文档。

记录 Google Analytics 4 事件

通过在您的 对 userEvents.collect 方法的调用。

对于 prebuilt_rule 参数，请使用值 ga4_bq。

为了方便阅读，以下使用 userEvents.collect 调用的示例首先将 GA4_EVENT 设置为包含示例事件的原始 JSON 数据的变量。然后，示例中的 userEvents.collect 调用会使用 GA4_EVENT 变量对事件数据进行网址编码。

1. 为了以后更轻松地进行网址编码，您可以将 GA4_EVENT 设置为变量 其中包含事件数据此示例展示了 add-to-cart 事件。

   GA4_EVENT='{
     "event_timestamp": 1622994083878241,
     "event_name": "add_to_cart",
     "user_pseudo_id": "352499268.1622993559",
     "items": [
       {
         "item_id": "11",
         "price": 29.99,
         "quantity": 3
       }
     ],
     "event_params": [
       {
         "key": "currency",
         "value": {
           "string_value": "CAD"
         }
       }
     ],
     "user_id": "Alice"
   }'

2. 发出包含用户事件的网址编码原始 JSON 数据的 userEvents.collect 调用：

   curl \
   -G \
   --data-urlencode "raw_json=${GA4_EVENT}" \
   -i \
   "https://retail.googleapis.com/v2/projects/PROJECT_ID/locations/global/catalogs/default_catalog/userEvents:collect?key=EXAMPLEKEY1&prebuilt_rule=ga4_bq'"

使用 Google 跟踪代码管理器记录用户事件

通过使用跟踪代码管理器，可以管理和测试多个代码，而不需要对您的网站更改很多服务器端代码。

在设置过程中做出的一些决策取决于您使用的是 Google Analytics 还是 Google Analytics 电子商务。您可以使用 Google Analytics 4 或增强型电子商务实现 Google Analytics 电子商务。Cloud Retail 标记同时支持这两者。

不需要 Google Analytics 和 Google Analytics 电子商务；如果您不使用它们，则可以在创建 Cloud Retail 代码时配置变量 - 电子商务，也可以在创建代码后手动填充网站的数据层代码。

Google Analytics 电子商务是 通过 Google Analytics 传递商品名、ID、价格和交易信息 以及其他结构化电子商务数据传送到 Google Analytics。 Vertex AI Search for Retail 可以自动使用 Google Analytics 电子商务数据层，因此，如果您已设置增强型电子商务图层，配置过程会更加简单。如果您没有为 Google Analytics 配置 Google Analytics 电子商务，但希望使用该功能，请参阅 GA4 开发者指南或增强型电子商务开发者指南中的更多详细信息和设置说明。

使用一次性过程，在跟踪代码管理器中设置 Cloud Retail 代码以记录用户事件。

创建访问者 ID 变量

值 visitorId 用于跟踪用户。visitorId 通常是会话 ID，所有事件都需要此参数。设置将会话 ID 设置为 visitorId 的变量。

如果您使用的是 Google Analytics，则可以使用 Google Analytics 访问者 ID。如需进行此项配置，请按照以下步骤替换 Cloud Retail 标记的访问者 ID 值。这会将第一方 Cookie“_ga”映射到一个名为“GA visitorId”的跟踪代码管理器变量。您可以对任何会话 ID Cookie 执行相同的操作；就不必来自 Google Analytics。

此过程假设您正在使用 Google Analytics。否则，您可以使用其他 Cookie 或变量，或者从 cloud_retail 数据层获取访问者 ID。

注意：正确填写 visitorID 字段非常重要。在记录用户事件、导入用户事件和发送预测请求时，此字段应一致。使用不一致的访问者 ID 不会返回错误，但会导致用户事件的历史记录不完整，这将会降低模型个性化服务的质量。

如需将 visitorID 值设置为 Cloud Retail 标记的变量，请执行以下操作：

1. 在跟踪代码管理器中，转到变量标签页，然后点击新建创建新用户定义的变量。

2. 在对话框的顶部为变量命名，例如“GA visitorId”。

3. 输入您的变量设置。

   您可以使用 Client-ID 或 Cookie ID 来设置为访问者的来源 。在提取历史数据和 实时用户事件

   客户端 ID

   在 Google Analytics 360 BigQuery 中 变量映射到clientID Universal Analytics BigQuery Export 架构。 在 Google Analytics 4 中，此变量映射到 user_pseudo_id字段（在 Google Analytics 4 BigQuery Export 架构。

   1. 将变量类型设置为自定义 JavaScript。

   2. 在自定义 JavaScript 字段中输入以下脚本。

      将“G-XXXXXX”替换为您的 Google Analytics 跟踪 ID。如要查找您的跟踪 ID，请参阅我的跟踪 ID 怎么了？ 如需详细了解如何获取客户端 ID，请参阅 Google Analytics 文档。

      function() {
       var tracker = ga.getByName('G-XXXXXX');
       return tracker.get('clientID');
      }

   3. 点击保存保存变量。

   Cookie ID

   1. 选择第一方 Cookie 作为变量类型。

   2. 在 Cookie 名称字段中，输入 _ga。

   3. 点击 Format Value，选择 Convert undefined to..，然后输入 ""（空字符串）。

   4. 点击保存保存变量。

      这会将第一方 Cookie“_ga”映射到一个名为“GA visitorId”的跟踪代码管理器变量。

接下来，在跟踪代码管理器中创建 Cloud Retail 代码。此代码将使用您刚刚创建的访问者 ID 变量。

创建 Google 跟踪代码管理器标记

在跟踪代码管理器中设置代码，以将用户事件信息发送到 Vertex AI Search for Retail。

1. 登录跟踪代码管理器 然后为您的网站选择容器

2. 转到代码标签页，然后点击新建以添加新代码。

3. 在面板顶部为代码命名（占位符是 无标题变量），例如“Vertex AI Search for Retail”。

4. 点击代码配置，然后选择 Cloud Retail 标记以打开代码配置面板。

5. 输入您的 API 密钥。

   在设置 Vertex AI Search for Retail 时，请使用您创建的密钥。

   您可以通过 API 和服务 >凭据 页面。

6. 输入启用了 Vertex AI Search for Retail 的 Google Cloud 项目的项目编号。

   项目编号可从 Google Cloud 控制台信息中心获取。

7. 对于用户事件数据源字段：

   • 数据层（推荐）：如果您的实现将是以下其中一项，请选择此类型：

     • 您已通过 跟踪代码管理器。将数据层用作事件数据源，而无需填充新的数据源。使用 Google Analytics 4 个架构（如果存在）。否则，它会使用 UA 增强型电子商务。 使用此数据源时，您只能记录 add-to-cart、purchase-complete、detail-page-view 和 search 事件。search 事件是结合使用电子商务展示和搜索查询来记录的（请参阅创建搜索查询变量）。

     • 您使用的是 Google Analytics 电子商务，并且可以手动填充数据层代码。请参阅跟踪代码管理器开发者指南。

   • 变量 - Cloud Retail：选择用 Vertex AI Search for Retail 的必填字段填充跟踪代码管理器变量。如果您未使用 Google Analytics 电子商务，或者 Google Analytics 电子商务没有 Vertex AI Search for Retail 所需的数据，则可以选择此选项。如果您要从旧版“数据层 - Cloud Retail”选项切换到此来源，请同时创建一个带有键 cloud_retail 的数据层变量，并将它与此 变量 - Cloud Retail 选项相关联。

   • 变量 - 电子商务：如果您的数据层中不使用 Google Analytics 电子商务，并且无法手动填充数据层代码，请选择此选项。

     在出现的从用户变量中读取电子商务数据字段中，选择一个变量。这样一来，Vertex AI Search for Retail 便可从您创建的自定义变量中读取 Google Analytics 电子商务用户事件数据。

     该变量应该与 GA4 开发者指南或增强型电子商务开发者指南中记录的格式一致。如要用正确的格式构建变量，您可以使用增强型电子商务对象构建器、跟踪代码管理器社区模板库中的自定义变量模板。社区模板并非由 Google 维护。如要使用此模板，请参阅 Google Analytics 电子商务对象构建器图库页面，查看文档和其他资源。

8. 点击 + 覆盖 UserEvent 消息中的值按钮。

9. 对于字段选择器，选择 visitorId 作为字段， 字段值，选择您在其中创建的新访问者 ID 变量 创建访问者 ID 变量。

10. 点击保存。

    Cloud Retail 标记已创建。

旧版数据源选项

以前，数据层 - 电子商务和数据层 - Cloud Retail 作为数据源选项提供。新代码中不提供这些旧版选项。如果您将现有代码切换到新的数据源，请在部署前使用跟踪代码管理器预览代码以验证它。切换时：

• 如果您使用数据层 - 电子商务，则可以切换到数据层。它使用 Google Analytics 4 架构（如果存在）。否则，它会使用 UA 增强型电子商务。

• 如果您使用的是数据层 - Cloud Retail，请切换到变量 - Cloud Retail 选项。创建带有键 cloud_retail 的数据层变量，并使它与变量 - Cloud Retail 选项相关联。

下一步：

• 如果您使用搜索功能 为搜索查询创建变量，并将其附加到您的新 标记前面。
• 为代码创建事件触发器。

创建搜索查询变量

如果您使用的是搜索广告系列，则可以在跟踪代码管理器中为搜索查询创建变量，并将其附加到您的 Cloud Retail 代码。这允许 Vertex AI Search for Retail 从 Google Analytics 获取搜索查询。

您创建的变量类型取决于您的用户事件数据源。

• 变量 - 电子商务，或具有 Google Analytics 电子商务架构的数据层：在跟踪代码管理器中创建网址或 DOM 元素变量并将其附加到您的 Cloud Retail 代码。此外，请为代码启用选项以使用 Google Analytics 电子商务展示构建搜索事件。
• 变量 - Cloud Retail 或手动填充的数据层：在跟踪代码管理器中创建网址或 DOM 元素变量并将其附加到您的 Cloud Retail 代码。为了确定用户事件类型是否为 search，您还必须执行以下任一操作：
  • 为搜索事件类型创建常量类型变量并将其附加到代码。
  • 在数据层或 Cloud Retail 变量中设置搜索事件类型。

为搜索查询创建并附加跟踪代码管理器变量

如果您使用搜索，则可以创建网址、DOM 元素或自定义 JavaScript 变量，将会使用在您的 网站。

作为此过程的替代方案，您可以配置数据层以提供搜索查询信息。但是，如果您无法访问数据层，或者不想配置数据层，则可以选择使用跟踪代码管理器变量。

您可以创建网址类型变量、DOM 元素类型变量或自定义 JavaScript（页面）变量。具体创建流程和配置方式 具体取决于您网站的实现方式：

• 网址变量会从网站的搜索结果网址中获取搜索查询。如果您的网站在搜索结果的网址中包含查询字符串，请使用此变量。
• DOM 元素变量会从网站的文档对象模型 (DOM) 获取搜索查询信息。您无需修改 DOM 即可使用此变量。但是，您应该能够阅读和理解 DOM，以便正确配置此变量。
• 自定义 JavaScript 变量会返回由 JavaScript 函数设置格式的数据。如果您有现有数据需要采用 Cloud Retail 或电子商务架构的格式，这将非常有用。

首先，创建一个类型为“网址”、“DOM 元素”或“自定义”的跟踪代码管理器变量 JavaScript：

1. 在跟踪代码管理器中，转到变量标签页，然后点击新建创建新用户定义的变量。

2. 在对话框的顶部为变量命名，例如“search_variable”。

3. 输入您的变量设置：

   网址类型

   1. 将变量类型设置为网址。

   2. 将组件类型设置为查询。

   3. 如果您指定查询键，请将其设置为网址中位于搜索查询前面的键。

      例如，如果网址为 http://example.com/?q=shoes，则查询键为 q。在此示例中，变量的值将设置为 shoes。

   DOM 元素类型

   1. 将变量类型设置为 DOM 元素。

   2. 设置选择方法，并输入搜索查询的元素 ID 或元素选择器。

      此设置取决于网站是使用元素 ID 还是 CSS 选择器来识别搜索查询。

   3. 如果您指定属性，请将其设置为包含搜索查询字词的属性。

      例如，如果 DOM 中的搜索查询为 <id="search" value="shoes">，则属性为 value。在此示例中，变量的值将设置为 shoes。

   自定义 JavaScript 类型

   1. 将变量类型设置为自定义 JavaScript。

   2. 替换以下代码中的变量，然后将其粘贴到“自定义 JavaScript”窗格中。

   3. 在“自定义 JavaScript”窗格中，添加用于在零售架构中返回搜索事件的 JavaScript 代码。

      以下示例代码会将现有 Ecommerce Items 变量中的数据转换为 Vertex AI Search for Retail 架构使用的 productDetails 数组，并返回完整事件。如需使用此代码，请在跟踪代码管理器实现中将 Ecommerce Items、Search Query 和 Search Filter 替换为变量。

      function () {
      
        var retail;
        var items = [];
      
        for (var i = 0; i < {{Ecommerce Items}}.length; i++) {
          var item = {'product':
                      {
                        'id': {{Ecommerce Items}}[i].item_id
                      }
                     };
      
          items.push(item);
        }
      
        retail = {
          'eventType': 'search',
          'searchQuery': '{{Search Query}}',
          'filter': '{{Search Filter}}',
          'productDetails': items
        }
      
        return retail;
      }
      

4. 点击保存保存变量。

接下来，将变量附加到您的 Cloud Retail 代码：

1. 在跟踪代码管理器的代码页面上，点击您的 Cloud Retail 代码以进行修改。

2. 如果代码的用户事件数据源是变量 - 电子商务或者您将数据层与 Google Analytics 电子商务架构结合使用，请选中使用增强型电子商务展示构建搜索事件复选框。

   这样一来，Vertex AI Search for Retail 便可根据从该代码中获得的搜索数据，确定用户事件类型是否为 search。

3. 在用户事件数据部分，点击 + 覆盖 UserEvent 消息中的值按钮。

4. 从字段选择器中选择 searchQuery，并将搜索查询变量设置为字段值。

5. 保存代码。

下一步：

• 如果您选择使用 Cloud Retail 变量或手动填充的数据层作为 Cloud Retail 代码的用户事件来源，请参阅创建和附加常量变量。
• 为代码创建事件触发器。

创建并附加常量变量

如果您选择变量 - Cloud Retail 或手动填充的数据层作为 Cloud Retail 代码的用户事件来源，则可以使用此过程。

为搜索事件创建常量类型变量并将其设置为用户 事件替换项可让 Vertex AI Search for Retail 确定用户事件的类型是否为 search。

作为此过程的替代方案，您可以通过用作代码的事件来源的数据层或 Cloud Retail 变量来指定 search 用户事件类型。否则，请按照以下步骤设置事件类型。

首先，创建一个常量类型变量：

1. 在跟踪代码管理器中，转到变量标签页，然后点击新建创建新用户定义的变量。

2. 在对话框的顶部为变量命名，例如“search_constant”。

3. 将变量类型设置为常量。

4. 在值字段中输入 search。

5. 点击保存保存变量。

接下来，将变量附加到您的 Cloud Retail 代码：

1. 在跟踪代码管理器的代码页面上，点击您的 Cloud Retail 代码以进行修改。

2. 在用户事件数据部分，点击 + 覆盖 UserEvent 消息中的值按钮。

3. 从字段选择器中选择 eventType，并将搜索查询变量设置为字段值。

4. 保存代码。

接下来，为标记创建事件触发器。

为您的跟踪代码管理器标记创建事件触发器

为 Vertex AI Search for Retail 模型将使用的所有用户事件类型创建触发器。

跟踪代码管理器代码必须具有触发器，以控制何时应在网站上“触发”代码。触发器会在事件发生时（例如，用户查看首页或向购物车添加商品）侦听，并提示您的代码将该用户事件信息发送到 Vertex AI Search for Retail。

跟踪代码管理器提供了一些标准触发器。例如，窗口已加载是 detail-page-view 事件的触发器。如需详细了解每种类型，请参阅跟踪代码管理器文档中的触发器类型。

您通常需要将代码设置为在用户浏览包含 Vertex AI Search for Retail 所需的活动（例如首页、商品详情） 页面、购物车页面或结账完成页面）。在这种情况下，该代码应在网页加载完毕后触发，以便 Cookie 可用，并填充所有数据层变量。为此，请将触发器设置为在 Window Loaded 或 DOM Ready 时触发。

您可能需要在执行操作时（而不是在网页加载时触发）触发代码（例如，当用户将商品添加到购物车时不会强制页面重新加载）。在这些情况下，您可以配置网站上的点击操作，以便同时将更新推送到数据层，并将触发器与该操作相关联。

例如，如果您为 add-to-cart 事件创建了触发器，则可以将触发器类型选择为点击 - 仅限链接，并将其设置为在点击 ID 触发（在在此示例中为 addtocart）。然后，您需要配置自己网站上的 addtocart 链接，以在用户点击数据层时将其更新为新值：

  <a id="addtocart" href="javascript:void(0);"
         onclick="dataLayer.push({
                  'cloud_retail': {
                  'eventType': 'add-to-cart',
                  'visitorId': '456',
                  'cartId': 'mobile',
                  'productDetails': [{
                  'product': {
                  'id': '54321'
                  },
                  'quantity': 1
                  }]}});">Add to Cart</a>

对于某些用户事件，您必须创建自定义触发器。一般来说，您可以使用用户事件名称在跟踪代码管理器中创建自定义触发器。如果您无法修改前端代码，则可以使用 JavaScript 宏创建一个自定义触发器。如需详细了解自定义触发器，请参阅自定义事件触发器。

如需在跟踪代码管理器中创建触发器，请按以下步骤操作：

• 如果您尚未配置触发器：为您的跟踪代码管理器代码创建新触发器
• 如果您已经设置了 Google Analytics 电子商务触发器：您可以重复使用为 Google Analytics 电子商务配置的触发器，而无需创建新的触发器。请参阅重复使用 Google Analytics 电子商务触发器。

为您的跟踪代码管理器标记创建新触发器

如果您不使用 Google Analytics 电子商务，请为任何 用于零售的 Vertex AI Search 模型所需的用户事件。然后，将新触发器与您在跟踪代码管理器中创建的 Cloud Retail 代码相关联。

在开始执行以下步骤之前，请确保您已在跟踪代码管理器中创建了 Cloud Retail 代码。请参阅创建跟踪代码管理器代码。

首先，创建触发器。对 面向零售业的 Vertex AI Search 模型需要：

1. 在跟踪代码管理器的触发器页面上，点击新建 > 触发器配置。

2. 选择您要为其创建触发器的用户事件适用的触发器类型。

3. 保存触发器。

接下来，将新触发器与 Cloud Retail 标记相关联。此过程是一次性的：

1. 在跟踪代码管理器的代码页面上，点击您的 Cloud Retail 代码以进行修改。

2. 点击触发条件，选择新的触发器，然后点击添加。

3. 保存代码。

接下来，预览您的代码，并 设置监控事件录制错误和其他问题 确保继续成功接收数据。

如果您使用 cloud_retail 数据层作为用户事件来源，请务必同时设置数据层。

重复使用 Google Analytics 电子商务触发器

如果您已通过跟踪代码管理器实现 Google Analytics 电子商务，请重复使用 Google Analytics Ecommerce for Vertex AI Search for Retail 中的事件触发器。

使用此数据源时，您只能记录 add-to-cart、purchase-complete、detail-page-view 和 search 事件。search 事件使用 电子商务展示次数加搜索查询次数之和（请参阅 创建搜索查询变量）。

下表显示了 Google Analytics 电子商务和增强型电子商务事件如何映射到 Vertex AI Search 中的零售事件。

Google Analytics 4	增强型电子商务	针对零售的 Vertex AI Search
add_to_cart	add	add-to-cart
purchase	purchase	purchase-complete
view_item	detail	detail-page-view
view_item_list 或 view_search_results	impressions	search（如果与字段 searchQuery 结合使用）

在开始这些步骤之前，请确保已经执行了以下操作：

• 在代码类型为 Google Analytics - Universal Analytics 或 Google Analytics - GA4 Event 的跟踪代码管理器中设置代码，并为其启用了增强型电子商务或 GA4。如需了解详情，请参阅跟踪代码管理器文档、GA4 开发者指南或增强型电子商务开发者指南。
• 已在跟踪代码管理器中配置您的增强型电子商务或 GA4 代码，以触发您计划为 Vertex AI Search for Retail 记录的用户事件。
• 在跟踪代码管理器中创建了 Cloud Retail 代码，将“数据层”或“变量 - 电子商务”用作用户事件数据源（请参阅创建跟踪代码管理器代码）。

如要重复使用 Google Analytics 电子商务触发器，请执行以下操作：

1. 在跟踪代码管理器、标记页面上，点击您的 Google Analytics 电子商务代码（代码类型 Google Analytics - Universal Analytics 或 Google Analytics - GA4 Event）以编辑它。

2. 在高级设置 > 代码触发顺序下，选择在 <增强型电子商务或 GA4 代码名称> 触发后触发代码。

3. 选择 Cloud Retail 标记作为 Cleanup Tag。

   选择如果 <增强型电子商务或 GA4 代码名称> 失败或已暂停，则不触发 <Cloud Retail 代码名称>。

4. 保存代码。

接下来，预览代码，并设置事件记录错误的监控及其他问题，以确保继续成功接收数据。

如果您使用 cloud_retail 数据层作为用户事件来源，请务必同时设置数据层。

在跟踪代码管理器中使用 cloud_retail 数据层

如果您在跟踪代码管理器中创建了 Cloud Retail 代码，以使用 cloud_retail 数据层作为用户事件来源，请按照跟踪代码管理器开发者指南所述在源 HTML 中设置 dataLayer 变量。

数据层简介

大多数跟踪代码管理器代码都需要根据用户或网页变化的数据（例如用户 ID 或产品 ID）。对于 Cloud Retail 标记，必须通过数据层以结构化方式公开该数据，以便跟踪代码管理器可以使用它。

数据层是一种 JavaScript 对象，通常使用服务器端代码或者通过 HTML 或模板在前端添加到网页中。如果页面配置了数据层，则会包含如下代码：

dataLayer = dataLayer || [];
dataLayer.push({
  'cloud_retail': {
    'eventType': 'home-page-view',
    'visitorId': 'visitor_a',

    'userInfo': {
      'userId': '789'
    },
  }
});

此代码会创建一个 dataLayer 对象并将其分配给 cloud_retail 结构作为数组元素。

cloud_retail 数据层中的必填字段

用户事件简介列出了以下各项的所有必填字段和示例： 事件类型。cloud_retail

您的服务器端代码或模板应在您要从中发送事件的每个页面上包含正确的脚本标记。在每个页面上正确填充 dataLayer 对象后，您应该能够测试 Cloud Retail 标记。

UserEvent 消息需要使用某些字段（如 visitorId），但在填充数据层时可能无法使用。例如，visitorId 可能派生自用户的 Cookie，或 experimentIds 来自 A/B 实验框架。在这种情况下，请使用变量覆盖跟踪代码管理器代码中的字段。

您可以覆盖以下字段：

• visitorId
• userInfo.userId
• attributionToken
• experimentIds

如需了解如何在跟踪代码管理器中覆盖 UserEvent 字段，请参阅在跟踪代码管理器中设置 visitorID 字段visitorID，该过程逐步介绍了如何使用用户定义的变量覆盖 visitorId 字段值。

注意： 确保 visitorID 字段正确无误。在记录用户事件、导入用户事件和发送预测请求时，此字段应一致。使用不一致的访问者 ID 不会返回错误，但会导致用户事件的历史记录不完整，这将会降低模型个性化服务的质量。

以下示例显示了使用跟踪代码管理器的 detail-page-view UserEvent 页面需要包含的数据层：

<script>
  dataLayer = dataLayer || [];
  dataLayer.push({
    'cloud_retail': {
      'eventType' : 'detail-page-view',
      'visitorId': 'visitor_a',
      'userInfo': {
          // The user and visitor ID fields can typically be
          // be populated from a client-side JavaScript
          // variable such as a cookie. If you set the user
          // and/or visitor ID values from the server,
          // populate the `userID`.
          'userId': 'user_a'
      },
      'attributionToken': 'attribution-token',
      // In most cases, the experiment ID field is populated from a
      // client side JavaScript variable as defined by the experiment
      // manager.
      // If you set the experiment ID value from the server,
      // populate the `experimentIds` field here.
      'productDetails': [
            {
              'product': {'id': '123'}
            }
      ],
    // You can use the 'cloud_retail' data layer element along with other
    // data layer elements.
    'ecommerce': {
      ...
    },
  }];
</script>

预览跟踪代码管理器代码

利用跟踪代码管理器的预览模式，您可以在将新代码发布到实际网站之前对其进行测试。

如需详细了解预览模式，请参阅预览模式的跟踪代码管理器文档。

请按以下步骤确认您的代码是否正确触发。

1. 在跟踪代码管理器概览页面上，点击预览。

   跟踪代码管理器的预览模式会在新的浏览器标签页中打开。

2. 输入您的网站信息，然后点击开始启动 Tag Assistant。

   在当前浏览器标签页中，Tag Assistant 将启动，您的网站将在新标签页中打开。

3. 在您的网站上，访问应触发 Cloud Retail 代码的任何页面。

4. 确认 Tag Assistant 在代码部分中的代码标签页中列出了 Cloud Retail 代码。

5. 在 Tag Assistant 中，转到数据层标签页，然后检查 cloud_retail 或电子商务数据层中显示的正确值。

检查代码错误

在预览代码时，如果某些字段不正确或缺失，代码通常会返回错误，除非根本没有触发。

您可以检查 Search for Retail 控制台中的监控页面，看看是否存在错误。此页面记录了大多数错误，除了 语法错误，这些错误通常仅出现在请求结果中。

您可以按照以下步骤使用 Chrome DevTools 检查生成的错误，包括语法错误。

1. 在 Chrome 浏览器中为您的网站在代码管理器中打开预览模式，然后访问应触发 Cloud Retail 代码的任何页面。

2. 打开预览模式后，打开 DevTools 并点击网络标签页。

3. 重新加载页面。

4. 在 DevTools 中，搜索 userEvent。

   “网络”标签页会显示 userEvent:collect 事件及其状态代码。

   • 200 响应表明您的代码处于良好状态。
   • 如果返回其他响应（例如 400 错误并用红色突出显示事件），则表示需要调试。

5. 双击事件名称以执行请求，并显示包含更多错误信息的完整响应。

   例如，您可能会看到一条 400 错误，其中包含消息“'visitorId' is required, and cannot be empty”，表明 visitorId 未正确设置。

6. 如果没有触发 userEvent，请查看 DevTools 的控制台标签页，了解数据层中的语法错误。

使用服务器端代码植入记录用户事件

通过服务器端代码植入，您可以部署单个服务器端容器，并使用 许多下游客户端这样，您就可以在客户端上创建一个可信的单一数据源，并有许多服务器端使用方。这种架构会将负载从网站转移到服务器，因此非常适合希望最大限度提高网站性能的用户。

服务器端代码植入的另一个优势是，单个服务器端代码还可以支持多个上游客户端，例如网站和移动应用。不妨了解如何设置服务器端代码植入。

适用于零售的 Vertex AI Search 提供自己的原生服务器端代码。

Cloud Retail 服务器端代码需要并接受与 Cloud Retail Web 代码类似的参数，例如：

• 项目编号
• API 密钥（用于身份验证）
• 对关键字段（例如 visitorId 和 searchQuery）的替换项

Cloud Retail 代码的服务器版本与网站版本之间的主要区别在于，您无法定义数据源。数据来源 服务器代码是从 GA4 架构中的 Google 代码发送的数据流。

设置 Cloud Retail 代码

监控导入运行状况

成功记录用户事件对于获得高质量结果非常重要。您应该监控事件记录错误率，并在必要时采取措施。如需了解详情，请参阅为数据上传问题设置提醒。

查看记录的事件

在 Search for Retail 控制台的事件标签页中查看事件集成指标 数据页面。此页面会显示去年写入或导入的所有事件。数据成功提取后，指标最长可能需要 24 小时才会显示。

前往“数据”页面

后续步骤

• 详细了解用户事件。
• 重新联接时间（如果已完成目录导入之前记录了事件）。
• 了解导入和管理用户事件。
• 开始进行预测。
• 监控数据上传流程并对其进行问题排查。
• 详细了解跟踪代码管理器。