用户事件简介

本页面介绍用户事件对象，包括列出潜在的用户事件类型，并提供所有用户事件类型的示例数据。

适用于零售业的 Vertex AI Search 使用实时用户事件生成商品推荐和搜索结果。上传数据时，推荐和搜索都可以使用这些数据，因此如果您使用这两项服务，则无需两次上传相同的事件。

如需有关录制用户事件的帮助，请参阅记录实时用户事件。

用户事件类型

当用户浏览您的零售网站时，您可以记录以下几种用户事件类型：

用户事件名称 用户操作
add-to-cart 将商品添加到购物车。
category-page-view 查看销售页面或促销页面等特殊页面。
detail-page-view 查看商品详情页面。
home-page-view 查看首页。
purchase-complete 完成结账。
search 搜索目录。
shopping-cart-page-view 查看购物车。

如需详细了解 UserEvent 对象，请参阅 UserEvent。

事件类型优先级

为获得最高质量结果，我们建议您记录所有事件类型的用户事件。下表介绍了不同用户事件类型的优先级。您必须记录优先级最高的用户事件才能实现高质量的数据模型。

优先级 用户事件
初始实验必须提供

add-to-cart

detail-page-view

purchase-complete

home-page-view（用于提供建议）

search（用于搜索网络）
对于随着时间的推移改进推荐模型质量非常重要

category-page-view

search

shopping-cart-page-view

用户事件要求和最佳做法

下表列出了有关建议和搜索使用的用户事件类型的要求和最佳实践。请检查您的用户事件是否满足这些要求，以便零售专用 Vertex AI Search 能够生成优质结果。

本部分列出了以下内容：

如果您使用推荐模型，另请参阅模型类型数据要求，其中列出了其他要求，具体取决于您计划使用的建议模型类型和优化目标。

您可以在 Search for Retail 控制台的数据质量页面上查看搜索的数据质量指标。这些指标显示符合建议的数据质量标准的产品和用户事件所占的百分比。如需了解如何查看搜索数据质量，请参阅解锁搜索性能层级。

关于用户事件的要求

请确保您的用户事件满足以下要求，以便面向零售业的 Vertex AI Search 能够生成优质结果。这些设置同时适用于推荐和搜索。

事件类型 要求 影响
所有事件

请勿添加合成数据或重复的事件。

合成事件或重复事件会对模型质量产生负面影响，通常会导致模型训练失败。 重复的事件可能会导致指标值不正确。

对于提取的每种事件，请添加至少 100 个唯一身份访问者 ID。

这样可确保适用于零售业的 Vertex AI Search 有足够的数据来生成优质结果。

在事件导入或事件记录过程中，以及在 API 请求中，访问者 ID 的格式必须完全相同。

对访问者 ID 使用一致的格式有助于正确识别访问者模式，并根据用户行为提供更优质的结果。

事件中包含的商品应存在于您的商品目录中。

未联接事件的比例应尽可能低。较高的比例会对推荐或搜索结果的质量产生负面影响。

未联接的事件数据不会用于训练模型。不过，未联接的事件可以在提取关联商品后联接。如需了解详情，请参阅重新联接用户事件。

某些用户事件应具有相同的访问者 ID。

为了构建有效的行为序列历史记录，面向零售业的 Vertex AI Search 必须能够看到具有相同访问者 ID 的多个事件。

例如，visitor123 查看了 5 个商品详情页面，将 3 件产品添加到了购物车，然后在原 5 件产品中购买了其中 2 件。如果这些事件都提供格式一致的同一访问者 ID，则 Vertex AI Search for Retail 可以在其模型中考虑该行为序列。

detail-page-view

每个事件只包括一个商品。

如果没有任何商品，则无法使用该事件。如果加入了多个商品，该事件格式有误，无法使用。
add-to-cart

每个事件只包括一个商品。

如果加入了多个商品，该事件格式有误，无法使用。
purchase-complete

包含 purchase_transaction.revenue。

缺少 revenue 字段的 purchase-complete 事件不会用于训练模型。

在所有购买事件中仅包含一个 purchase_transaction.currency_code。

没有默认货币代码；必须提供代码。

不含此字段的购买事件会导致收入指标不正确。

检查某些购买事件是否包含多件商品。

针对多件商品设置一些购买事件有助于模型学习共同购买模式。

特定于建议的要求

如果要使用推荐功能，请确保您的用户事件满足以下要求。

如果您使用推荐模型，另请参阅模型类型数据要求，其中列出了其他要求，具体取决于您计划使用的建议模型类型和优化目标。

事件类型 要求 影响
purchase-complete

请勿将含有多件商品的购物篮展平到多个购买事件中。它们应保持为包含多个商品的单个购买事件。

这可确保生成有效的合并购买模式。

搜索要求

如果您使用搜索，请确保您的用户事件满足以下最低要求，才能获取结果。

事件类型 要求 影响
search

对于搜索事件，必须存在 searchQuery；对于浏览事件，必须存在 pageCategories。

如果不添加此字段，可能会对搜索结果质量和指标产生严重的负面影响。

搜索请求中的访问者 ID 应与随该搜索请求相关的事件发送的访问者 ID 相匹配。

如果它们不匹配，则事件格式不正确，指标可能不正确。

搜索事件中的商品 ID 列表必须与整个商品向用户展示的商品列表相匹配。

如果不一致，则对搜索结果质量的负面影响可能非常严重，而且指标也会有误。

如果搜索使用过滤条件，filter 必须存在并可以正确解析。

如果此字段不存在，则 Vertex AI Search for Retail 将无法使用数据的过滤条件部分，这可能会对搜索结果质量产生负面影响。

添加 attribution_token 字段可将其他事件链接回搜索事件。

不添加搜索令牌会对搜索质量和指标准确性产生严重的负面影响。

搜索优化要求

若要让搜索功能根据整体用户趋势自动优化搜索体验，请上传以下数据。

活动应至少每天上传一次，最长有 24 小时的延迟。

事件指标 事件音量/频率 说明
search 项事件的数量 过去 90 天内达到 2,000,000 次

过去 90 天内至少要有 200 万个事件，才能根据提取的事件优化搜索体验。

我们建议您至少每天上传一次事件，以保持良好的数据质量。在导入历史事件期间，请确保数据分布偏向于最近的时间戳。最后一个时间戳日期的事件数量应等于或大于平均每日事件数。
归因于 search 事件的 detail-page-view 量 过去 30 天内的 50 万人 如需使用用户事件优化搜索结果，需要至少 500,000 个事件。
每个产品归因于 search 事件的平均 detail-page-view 事件数 过去 30 天内有 10 项 必需使用注入的事件优化搜索结果（除非上传了过去 21 天的事件）。
采用可解析过滤条件的 search 事件的比例 过去 30 天内为 0.1 建议用于优化搜索响应中动态分面的顺序。
搜索到的包含价格的商品所占的比例 过去 30 天内的评分为 0.95 必需使用注入的事件优化搜索结果。
每个定价产品归因于 search 事件的平均 add-to-cart 事件数 过去 30 天内有 0.5 人 建议用于提高收入的搜索结果。
每件可搜索定价商品可归因于一次 search 事件的平均 purchase-complete 事件数 过去 30 天内有 0.5 人 建议用于提高收入的搜索结果。

搜索个性化要求

Google 搜索需要以下数据才能根据用户的活动情况对文本搜索进行个性化设置并浏览搜索结果。

在您上传以下数据后，Google 搜索可以自动个性化结果。

事件指标 事件音量/频率 说明
搜索带来的 search 事件的数量 过去 30 天内达 10 万人

在过去 30 天内，必须至少有 10 万个由 Google 搜索提供的事件才能提供个性化服务。
搜索结果不会缓存 在最近的 10 万个用户事件中，不到 1%

如果您打算使用个性化功能，请勿缓存针对文本搜索或浏览搜索的搜索结果。对访问者重复使用相同的结果会导致 Google 搜索无法为任何指定用户提供真正个性化的搜索结果，并存在泄露用户的隐私数据的风险。如果检测到缓存，Google 搜索会自动关闭个性化功能。

如果您只缓存搜索结果，搜索功能仍然可以对浏览结果进行个性化设置。相反，如果您仅缓存浏览结果，搜索功能仍然可以对文本查询搜索结果进行个性化设置。

SearchRequests 与用户事件之间的访问者 ID 匹配 与最近的 10 万个用户事件匹配率超过 10% 请确保 SearchRequests 和用户事件的访问者 ID 间距和格式一致。一致的访问者 ID 格式可确保搜索功能可以正确识别用户活动。

用户事件类型示例和架构

本部分提供每种支持的事件类型的数据格式。

同时还提供了 JavaScript Pixel 和跟踪代码管理器的示例。对于 BigQuery，提供了每种类型的完整表架构。

对于所有用户事件类型，userId 是可选的。商品信息字段（priceInfo 和 availability）为选填字段。

请注意：

  • 只有在您运行 A/B 实验时，才需要 experimentIds 字段。
  • attributionToken 字段为可选字段；它用于衡量效果。点击生成的 predict、search 和 detail-page-view 事件应包含归因令牌，以便将这些事件关联回生成它们的搜索或推荐。
  • 请确保所有事件都使用同一币种，尤其是当您计划使用 Google Cloud 控制台来获取收入指标时。Vertex AI Search for Retail API 不支持每个目录使用多种货币。

如需详细了解用户事件对象，请参阅 UserEvent API 参考文档。

加入购物车

下面显示了 add-to-cart 用户事件格式。

至少需要 add-to-cart 对象

以下示例仅显示 add-to-cart 用户事件格式的必填字段。

导入事件时，您必须采用 RFC 3339 指定的格式在 eventTime 字段中提供时间戳。

其他字段可能为必填项，具体取决于所使用的 API 方法或是否使用了其他字段。（例如，如果用户事件与实体相关联，请务必指定 entity 字段。）如需了解每个字段的完整详情以及何时需要提供这些字段，请参阅 UserEvent API 参考文档。

JavaScript 像素

var user_event = {
  "eventType": "add-to-cart",
  "visitorId": "visitor-id",
  "productDetails": [{
    "product": {
      "id": "product-id"
    },
    "quantity": product-quantity
  }]
};

跟踪代码管理器 

<script>
    dataLayer = dataLayer || [];
    dataLayer.push({
      'cloud_retail': {
        'eventType': 'add-to-cart',
        'visitorId': 'visitor-id',
        // You can also define the visitor ID
        // directly on the Tag Manager tag.
        'productDetails': [{
          'product': {
            'id': 'product-id'
          },
          'quantity': product-quantity
        }]
      }
    });
</script>

BigQuery

这是此用户事件类型的完整 JSON 架构。在 BigQuery 中为此用户事件类型创建表时指定此架构。

必填字段的模式设置为 REQUIRED 或 REPEATED。可选字段的模式设置为 NULLABLE。

请注意，要使用 BigQuery 导入事件，必须使用 eventTime。eventTime 是时间戳格式的字符串。

[
 {
   "name": "eventType",
   "type": "STRING",
   "mode": "REQUIRED"
 },
 {
   "name": "visitorId",
   "type": "STRING",
   "mode": "REQUIRED"
 },
 {
   "name": "eventTime",
   "type": "STRING",
   "mode": "REQUIRED"
 },
 {
   "name": "experimentIds",
   "type": "STRING",
   "mode": "REPEATED"
 },
 {
   "name": "attributionToken",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "productDetails",
   "type": "RECORD",
   "mode": "REPEATED",
   "fields": [
     {
       "name": "product",
       "type": "RECORD",
       "mode": "REQUIRED",
       "fields": [
         {
           "name": "id",
           "type": "STRING",
           "mode": "REQUIRED"
         }
       ]
     },
     {
       "name": "quantity",
       "type": "INTEGER",
       "mode": "REQUIRED"
     }
   ]
 },
 {
   "name": "cartId",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "userInfo",
   "type": "RECORD",
   "mode": "NULLABLE",
   "fields": [
     {
       "name": "userId",
       "type": "STRING",
       "mode": "NULLABLE"
     },
     {
       "name": "ipAddress",
       "type": "STRING",
       "mode": "NULLABLE"
     },
     {
       "name": "userAgent",
       "type": "STRING",
       "mode": "NULLABLE"
     },
     {
       "name": "directUserRequest",
       "type": "BOOLEAN",
       "mode": "NULLABLE"
     }
   ]
 },
 {
   "name": "uri",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "referrerUri",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "pageViewId",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "entity",
   "type": "STRING",
   "mode": "NULLABLE"
 }
]

类别页面视图

下面显示了 category-page-view 用户事件格式。

至少需要 category-page-view 对象

以下示例仅显示 category-page-view 用户事件格式的必填字段。

虽然通常只有一个网页会关联一个类别，但 pageCategories 字段还支持类别层次结构，您可以将该层次结构作为列表提供。

导入事件时，您必须采用 RFC 3339 指定的格式在 eventTime 字段中提供时间戳。

其他字段可能为必填项，具体取决于所使用的 API 方法或是否使用了其他字段。（例如，如果用户事件与实体相关联，请务必指定 entity 字段。）如需了解每个字段的完整详情以及何时需要提供这些字段，请参阅 UserEvent API 参考文档。

JavaScript 像素

var user_event = {
  "eventType": "category-page-view",
  "visitorId": "visitor-id",
  "pageCategories": ["category1 > category2"]
};

跟踪代码管理器 

<script>
    dataLayer = dataLayer || [];
    dataLayer.push({
      'cloud_retail': {
        'eventType': 'category-page-view',
        'visitorId": 'visitor-id',
        // You can also define the user ID and visitor ID
        // directly on the Tag Manager tag.
        'pageCategories': ['category1 > category2']
      }
    });
</script>

BigQuery

这是此用户事件类型的完整 JSON 架构。在 BigQuery 中为此用户事件类型创建表时指定此架构。

必填字段的模式设置为 REQUIRED 或 REPEATED。可选字段的模式设置为 NULLABLE。

请注意，要使用 BigQuery 导入事件，必须使用 eventTime。eventTime 是时间戳格式的字符串。

[
 {
   "name": "eventType",
   "type": "STRING",
   "mode": "REQUIRED"
 },
 {
   "name": "visitorId",
   "type": "STRING",
   "mode": "REQUIRED"
 },
 {
   "name": "eventTime",
   "type": "STRING",
   "mode": "REQUIRED"
 },
 {
   "name": "experimentIds",
   "type": "STRING",
   "mode": "REPEATED"
 },
 {
   "name": "attributionToken",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "productDetails",
   "type": "RECORD",
   "mode": "REPEATED",
   "fields": [
     {
       "name": "product",
       "type": "RECORD",
       "mode": "REQUIRED",
       "fields": [
         {
           "name": "id",
           "type": "STRING",
           "mode": "REQUIRED"
         }
       ]
     }
   ]
 },
 {
   "name": "pageCategories",
   "type": "STRING",
   "mode": "REPEATED"
 },
 {
   "name": "userInfo",
   "type": "RECORD",
   "mode": "NULLABLE",
   "fields": [
     {
       "name": "userId",
       "type": "STRING",
       "mode": "NULLABLE"
     },
     {
       "name": "ipAddress",
       "type": "STRING",
       "mode": "NULLABLE"
     },
     {
       "name": "userAgent",
       "type": "STRING",
       "mode": "NULLABLE"
     },
     {
       "name": "directUserRequest",
       "type": "BOOLEAN",
       "mode": "NULLABLE"
     }
   ]
 },
 {
   "name": "uri",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "referrerUri",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "pageViewId",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "entity",
   "type": "STRING",
   "mode": "NULLABLE"
 }
]

详情页面浏览

下面显示了 detail-page-view 用户事件数据格式。

至少需要 detail-page-view 对象

以下示例仅显示 detail-page-view 用户事件格式的必填字段。

大多数情况下，productDetails 包含关联商品的详细信息，除非是同时销售一组商品。

导入事件时，您必须采用 RFC 3339 指定的格式在 eventTime 字段中提供时间戳。

其他字段可能为必填项，具体取决于所使用的 API 方法或是否使用了其他字段。（例如，如果用户事件与实体相关联，请务必指定 entity 字段。）如需了解每个字段的完整详情以及何时需要提供这些字段，请参阅 UserEvent API 参考文档。

JavaScript 像素

var user_event = {
  "eventType": "detail-page-view",
  "visitorId": "visitor-id",
  "productDetails": [{
    "product": {
      "id": "product-id"
    }
  }]
};

跟踪代码管理器 

<script>
    dataLayer = dataLayer || [];
    dataLayer.push({
      'cloud_retail': {
        'eventType': 'detail-page-view',
        'visitorId': 'visitor-id',
        // You can also define the visitor ID directly on
        // the Tag Manager tag.
        'productDetails': [{
          'product': {
            'id': 'product-id'
          }
        }]
      }
    });
</script>

BigQuery

这是此用户事件类型的完整 JSON 架构。在 BigQuery 中为此用户事件类型创建表时指定此架构。

必填字段的模式设置为 REQUIRED 或 REPEATED。可选字段的模式设置为 NULLABLE。

请注意，要使用 BigQuery 导入事件，必须使用 eventTime。eventTime 是时间戳格式的字符串。

[
 {
   "name": "eventType",
   "type": "STRING",
   "mode": "REQUIRED"
 },
 {
   "name": "visitorId",
   "type": "STRING",
   "mode": "REQUIRED"
 },
 {
   "name": "eventTime",
   "type": "STRING",
   "mode": "REQUIRED"
 },
 {
   "name": "experimentIds",
   "type": "STRING",
   "mode": "REPEATED"
 },
 {
   "name": "attributionToken",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "productDetails",
   "type": "RECORD",
   "mode": "REPEATED",
   "fields": [
     {
       "name": "product",
       "type": "RECORD",
       "mode": "REQUIRED",
       "fields": [
         {
           "name": "id",
           "type": "STRING",
           "mode": "REQUIRED"
         }
       ]
     }
   ]
 },
 {
   "name": "userInfo",
   "type": "RECORD",
   "mode": "NULLABLE",
   "fields": [
     {
       "name": "userId",
       "type": "STRING",
       "mode": "NULLABLE"
     },
     {
       "name": "ipAddress",
       "type": "STRING",
       "mode": "NULLABLE"
     },
     {
       "name": "userAgent",
       "type": "STRING",
       "mode": "NULLABLE"
     },
     {
       "name": "directUserRequest",
       "type": "BOOLEAN",
       "mode": "NULLABLE"
     }
   ]
 },
 {
   "name": "uri",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "referrerUri",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "pageViewId",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "entity",
   "type": "STRING",
   "mode": "NULLABLE"
 }
]

首页浏览

下面显示了 home-page-view 用户事件格式。

至少需要 home-page-view 对象

以下示例仅显示 home-page-view 用户事件格式的必填字段。

导入事件时，您必须采用 RFC 3339 指定的格式在 eventTime 字段中提供时间戳。

其他字段可能为必填项，具体取决于所使用的 API 方法或是否使用了其他字段。（例如，如果用户事件与实体相关联，请务必指定 entity 字段。）如需了解每个字段的完整详情以及何时需要提供这些字段，请参阅 UserEvent API 参考文档。

JavaScript 像素

var user_event = {
  "eventType": "home-page-view",
  "visitorId": "visitor-id",
};

跟踪代码管理器 

<script>
    dataLayer = dataLayer || [];
    dataLayer.push({
      'cloud_retail': {
        'eventType': 'home-page-view',
        'visitorId': 'visitor-id'
        // You can also define the visitor ID
        // directly on the Tag Manager tag.
      }
    });
</script>

BigQuery

这是此用户事件类型的完整 JSON 架构。在 BigQuery 中为此用户事件类型创建表时指定此架构。

必填字段的模式设置为 REQUIRED 或 REPEATED。可选字段的模式设置为 NULLABLE。

请注意，要使用 BigQuery 导入事件，必须使用 eventTime。eventTime 是时间戳格式的字符串。

[
 {
   "name": "eventType",
   "type": "STRING",
   "mode": "REQUIRED"
 },
 {
   "name": "visitorId",
   "type": "STRING",
   "mode": "REQUIRED"
 },
 {
   "name": "eventTime",
   "type": "STRING",
   "mode": "REQUIRED"
 },
 {
   "name": "experimentIds",
   "type": "STRING",
   "mode": "REPEATED"
 },
 {
   "name": "attributionToken",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "productDetails",
   "type": "RECORD",
   "mode": "REPEATED",
   "fields": [
     {
       "name": "product",
       "type": "RECORD",
       "mode": "REQUIRED",
       "fields": [
         {
           "name": "id",
           "type": "STRING",
           "mode": "REQUIRED"
         }
       ]
     },
     {
       "name": "quantity",
       "type": "INTEGER",
       "mode": "REQUIRED"
     }
   ]
 },
 {
   "name": "userInfo",
   "type": "RECORD",
   "mode": "NULLABLE",
   "fields": [
     {
       "name": "userId",
       "type": "STRING",
       "mode": "NULLABLE"
     },
     {
       "name": "ipAddress",
       "type": "STRING",
       "mode": "NULLABLE"
     },
     {
       "name": "userAgent",
       "type": "STRING",
       "mode": "NULLABLE"
     },
     {
       "name": "directUserRequest",
       "type": "BOOLEAN",
       "mode": "NULLABLE"
     }
   ]
 },
 {
   "name": "uri",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "referrerUri",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "pageViewId",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "entity",
   "type": "STRING",
   "mode": "NULLABLE"
 }
]

购买完成

下面显示了 purchase-complete 用户事件数据格式。

至少需要 purchase-complete 对象

以下示例仅显示 purchase-complete 用户事件格式的必填字段。

导入事件时，您必须采用 RFC 3339 指定的格式在 eventTime 字段中提供时间戳。

其他字段可能为必填项，具体取决于所使用的 API 方法或是否使用了其他字段。（例如，如果用户事件与实体相关联，请务必指定 entity 字段。）如需了解每个字段的完整详情以及何时需要提供这些字段，请参阅 UserEvent API 参考文档。

JavaScript 像素

var user_event = {
  "eventType": "purchase-complete",
  "visitorId": "visitor-id",
  "productDetails": [{
    "product": {
      "id": "product-id"
    },
    "quantity": product-quantity
  }],
  "purchaseTransaction": {
    "revenue": revenue,
    "currencyCode": "currency-code"
  }
};

跟踪代码管理器 

<script>
    dataLayer = dataLayer || [];
    dataLayer.push({
      'cloud_retail': {
        'eventType': 'purchase-complete',
        'visitorId': 'visitor-id',
        // You can also define the visitor id directly on
        // the Tag Manager tag.
        'productDetails': [{
          'product': {
            'id': 'product-id'
          },
          'quantity': product-quantity
        }],
        'purchaseTransaction': {
          'revenue': revenue,
          'currencyCode': 'currency-code'
        }
      }
    });
</script>

BigQuery

这是此用户事件类型的完整 JSON 架构。在 BigQuery 中为此用户事件类型创建表时指定此架构。

必填字段的模式设置为 REQUIRED 或 REPEATED。可选字段的模式设置为 NULLABLE。

请注意，要使用 BigQuery 导入事件，必须使用 eventTime。eventTime 是一个采用时间戳格式的字符串。 

[
 {
   "name": "eventType",
   "type": "STRING",
   "mode": "REQUIRED"
 },
 {
   "name": "visitorId",
   "type": "STRING",
   "mode": "REQUIRED"
 },
 {
   "name": "eventTime",
   "type": "STRING",
   "mode": "REQUIRED"
 },
 {
   "name": "experimentIds",
   "type": "STRING",
   "mode": "REPEATED"
 },
 {
   "name": "attributionToken",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "productDetails",
   "type": "RECORD",
   "mode": "REPEATED",
   "fields": [
     {
       "name": "product",
       "type": "RECORD",
       "mode": "REQUIRED",
       "fields": [
         {
           "name": "id",
           "type": "STRING",
           "mode": "REQUIRED"
         },
         {
           "name": "priceInfo",
           "type": "RECORD",
           "mode": "NULLABLE",
           "fields": [
             {
               "name": "price",
               "type": "FLOAT",
               "mode": "REQUIRED"
             },
             {
               "name": "originalPrice",
               "type": "FLOAT",
               "mode": "NULLABLE"
             },
             {
               "name": "currencyCode",
               "type": "STRING",
               "mode": "REQUIRED"
             },
             {
               "name": "cost",
               "type": "FLOAT",
               "mode": "NULLABLE"
             }
           ]
         }
       ]
     },
     {
       "name": "quantity",
       "type": "INTEGER",
       "mode": "REQUIRED"
     }
   ]
 },
 {
   "name": "cartId",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "purchaseTransaction",
   "type": "RECORD",
   "mode": "REQUIRED",
   "fields": [
     {
       "name": "id",
       "type": "STRING",
       "mode": "NULLABLE"
     },
     {
       "name": "revenue",
       "type": "FLOAT",
       "mode": "REQUIRED"
     },
     {
       "name": "tax",
       "type": "FLOAT",
       "mode": "NULLABLE"
     },
     {
       "name": "cost",
       "type": "FLOAT",
       "mode": "NULLABLE"
     },
     {
       "name": "currencyCode",
       "type": "STRING",
       "mode": "REQUIRED"
     }
   ]
 },
 {
   "name": "userInfo",
   "type": "RECORD",
   "mode": "NULLABLE",
   "fields": [
     {
       "name": "userId",
       "type": "STRING",
       "mode": "NULLABLE"
     },
     {
       "name": "ipAddress",
       "type": "STRING",
       "mode": "NULLABLE"
     },
     {
       "name": "userAgent",
       "type": "STRING",
       "mode": "NULLABLE"
     },
     {
       "name": "directUserRequest",
       "type": "BOOLEAN",
       "mode": "NULLABLE"
     }
   ]
 },
 {
   "name": "uri",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "referrerUri",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "pageViewId",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "entity",
   "type": "STRING",
   "mode": "NULLABLE"
 }
]

下面显示了 search 用户事件格式。

至少需要 search 对象

以下示例仅显示 search 用户事件格式的必填字段。

至少需要 searchQuery 和 pageCategories 字段中的一个字段。

productDetails 应包含在搜索结果中向最终用户显示的商品 ID 列表。

导入事件时，您必须采用 RFC 3339 指定的格式在 eventTime 字段中提供时间戳。

其他字段可能为必填项，具体取决于所使用的 API 方法或是否使用了其他字段。（例如，如果用户事件与实体相关联，请务必指定 entity 字段。）如需了解每个字段的完整详情以及何时需要提供这些字段，请参阅 UserEvent API 参考文档。

JavaScript 像素

var user_event = {
  "eventType": "search",
  "visitorId": "visitor-id",
  "searchQuery": "search-query",
  "pageCategories": ["category1 > category2"],
  "productDetails": [
    {
      "product": {
        "id": "product-id1"
      }
    }, {
      "product": {
        "id": "product-id2"
      }
    }
  ]
};

跟踪代码管理器 

<script>
    dataLayer = dataLayer || [];
    dataLayer.push({
      'cloud_retail': {
        'eventType': 'search',
        'visitorId': 'visitor-id',
        // You can also define the visitor ID
        // directly on the Tag Manager tag.
        'searchQuery': 'search-query',
        'pageCategories': ['category1 > category2'],
        'productDetails': [
          {
            'product': {
              'id': 'product-id1'
            }
          }, {
            'product': {
              'id': 'product-id2'
            }
          }
        ]
      }
    });
</script>

BigQuery

这是此用户事件类型的完整 JSON 架构。在 BigQuery 中为此用户事件类型创建表时指定此架构。

必填字段的模式设置为 REQUIRED 或 REPEATED。可选字段的模式设置为 NULLABLE。

请注意，要使用 BigQuery 导入事件，必须使用 eventTime。eventTime 是时间戳格式的字符串。

[
 {
   "name": "eventType",
   "type": "STRING",
   "mode": "REQUIRED"
 },
 {
   "name": "visitorId",
   "type": "STRING",
   "mode": "REQUIRED"
 },
 {
   "name": "eventTime",
   "type": "STRING",
   "mode": "REQUIRED"
 },
 {
   "name": "productDetails",
   "type": "RECORD",
   "mode": "REPEATED",
   "fields": [
     {
       "name": "product",
       "type": "RECORD",
       "mode": "REQUIRED",
       "fields": [
         {
           "name": "id",
           "type": "STRING",
           "mode": "REQUIRED"
         }
       ]
     }
   ]
 },
 {
   "name": "searchQuery",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "pageCategories",
   "type": "STRING",
   "mode": "REPEATED"
 },
 {
   "name": "entity",
   "type": "STRING",
   "mode": "NULLABLE"
 }
]

自动补全

只有在您想使用 Autocomplete 的情况下，搜索事件才需要使用此字段。对于搜索，不需要填写此字段。

以下示例显示了当用户输入“sh”并点击建议列表中的第二个建议“shoes”以触发搜索事件时，completionDetail 字段。如果用户未点击任何建议，completionDetail 字段将留空。

eventType 必须为 "search"。

completionAttributionToken 是来自 completeQuery 响应的 attributionToken。

selectedSuggestion 应与 searchQuery 相同。

JavaScript 像素

var user_event = {
  "eventType": "search",
  "visitorId": "visitor-id",
  "searchQuery": "search-query",
  "pageCategories": ["category1 > category2"],
  "productDetails": [
    {
      "product": {
        "id": "product-id1"
      }
    }, {
      "product": {
        "id": "product-id2"
      }
    }
  ]
  "completionDetail": {
    "completionAttributionToken": "completion_token",
    "selectedSuggestion": "search-query",
    "selectedPosition": completion_position
  }
};

跟踪代码管理器 

<script>
    dataLayer = dataLayer || [];
    dataLayer.push({
      'cloud_retail': {
        'eventType': 'search',
        'visitorId': 'visitor-id',
        // You can also define the visitor ID
        // directly on the Tag Manager tag.
        'searchQuery': 'search-query',
        'pageCategories': ['category1 > category2'],
        'productDetails': [
          {
            'product': {
              'id': 'product-id1'
            }
          }, {
            'product': {
              'id': 'product-id2'
            }
          }
        ]
        "completionDetail": {
          "completionAttributionToken": 'completion_token',
          "selectedSuggestion": 'search-query',
          "selectedPosition": completion_position
        }
      }
    });
</script>

BigQuery

这是此用户事件类型的完整 JSON 架构。在 BigQuery 中为此用户事件类型创建表时指定此架构。

必填字段的模式设置为 REQUIRED 或 REPEATED。可选字段的模式设置为 NULLABLE。

请注意，要使用 BigQuery 导入事件，必须使用 eventTime。eventTime 是时间戳格式的字符串。

[
 {
   "name": "eventType",
   "type": "STRING",
   "mode": "REQUIRED"
 },
 {
   "name": "visitorId",
   "type": "STRING",
   "mode": "REQUIRED"
 },
 {
   "name": "eventTime",
   "type": "STRING",
   "mode": "REQUIRED"
 },
 {
   "name": "productDetails",
   "type": "RECORD",
   "mode": "REPEATED",
   "fields": [
     {
       "name": "product",
       "type": "RECORD",
       "mode": "REQUIRED",
       "fields": [
         {
           "name": "id",
           "type": "STRING",
           "mode": "REQUIRED"
         }
       ]
     }
   ]
 },
 {
   "name": "searchQuery",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "pageCategories",
   "type": "STRING",
   "mode": "REPEATED"
 },
 {
   "name": "completionDetail",
   "type": "RECORD"
   "mode": "NULLABLE"
   "fields": [
     {
       "name": "completionAttributionToken",
       "type": "STRING",
       "mode": "REQUIRED"
     },
     {
       "name": "selectedSuggestion",
       "type": "STRING",
       "mode": "REQUIRED"
     },
     {
       "name": "selectedPosition",
       "type": "INTEGER",
       "mode": "REQUIRED"
     }
    ]
 }
]

购物车页面视图

下面显示了 shopping-cart-page-view 用户事件数据格式。

至少需要 shopping-cart-page-view 对象

以下示例仅显示 shopping-cart-page-view 用户事件格式的必填字段。

除非购物车是空的，否则请提供 productDetails 对象。

导入事件时，您必须采用 RFC 3339 指定的格式在 eventTime 字段中提供时间戳。

其他字段可能为必填项，具体取决于所使用的 API 方法或是否使用了其他字段。（例如，如果用户事件与实体相关联，请务必指定 entity 字段。）如需了解每个字段的完整详情以及何时需要提供这些字段，请参阅 UserEvent API 参考文档。

JavaScript 像素

var user_event = {
  "eventType": "shopping-cart-page-view",
  "visitorId": "visitor-id
  "cartId": "cart-id",
  "productDetails": [{
    "product": {
       "id": "product-id"
     },
     {
       "id": "product-id"
     }
   }]
};

跟踪代码管理器 

<script>
    dataLayer = dataLayer || [];
    dataLayer.push({
      'cloud_retail': {
        'eventType': 'shopping-cart-page-view',
        'visitorId': 'visitor-id'
        // You can also define the visitor ID
        // directly on the Tag Manager tag.
        'cartId': 'cart-id',
        'productDetails': [{
          'product': {
            'id': 'product-id'
           },
           {
             'id': 'product-id'
           }
         }]
      }
    });
</script>

BigQuery

这是此用户事件类型的完整 JSON 架构。在 BigQuery 中为此用户事件类型创建表时指定此架构。

必填字段的模式设置为 REQUIRED 或 REPEATED。可选字段的模式设置为 NULLABLE。

请注意，要使用 BigQuery 导入事件，必须使用 eventTime。eventTime 是时间戳格式的字符串。

[
 {
   "name": "eventType",
   "type": "STRING",
   "mode": "REQUIRED"
 },
 {
   "name": "visitorId",
   "type": "STRING",
   "mode": "REQUIRED"
 },
 {
   "name": "eventTime",
   "type": "STRING",
   "mode": "REQUIRED"
 },
 {
   "name": "experimentIds",
   "type": "STRING",
   "mode": "REPEATED"
 },
 {
   "name": "attributionToken",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "productDetails",
   "type": "RECORD",
   "mode": "REPEATED",
   "fields": [
     {
       "name": "product",
       "type": "RECORD",
       "mode": "REQUIRED",
       "fields": [
         {
           "name": "id",
           "type": "STRING",
           "mode": "REQUIRED"
         }
       ]
     },
     {
       "name": "quantity",
       "type": "INTEGER",
       "mode": "REQUIRED"
     }
   ]
 },
 {
   "name": "cartId",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "userInfo",
   "type": "RECORD",
   "mode": "NULLABLE",
   "fields": [
     {
       "name": "userId",
       "type": "STRING",
       "mode": "NULLABLE"
     },
     {
       "name": "ipAddress",
       "type": "STRING",
       "mode": "NULLABLE"
     },
     {
       "name": "userAgent",
       "type": "STRING",
       "mode": "NULLABLE"
     },
     {
       "name": "directUserRequest",
       "type": "BOOLEAN",
       "mode": "NULLABLE"
     }
   ]
 },
 {
   "name": "uri",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "referrerUri",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "pageViewId",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "entity",
   "type": "STRING",
   "mode": "NULLABLE"
 }
]

Google Analytics（分析）4 用户事件字段

下表显示了 Google Analytics（分析）4 用户事件字段与 Vertex AI Search 中零售字段的对应关系。

从 Google Analytics（分析）4 导入或记录用户事件之前，请确保您的 Google Analytics（分析）4 用户事件使用以下字段，以便 Vertex AI Search for Retail 可以正确集成您的数据。

Google Analytics（分析）4 零售
ecommerce.purchase_revenue purchaseTransaction.revenue
event_name eventType
event_timestamp eventTime
items.item_id productDetails.product.id
items.price productDetails.product.priceInfo.price
items.quantity productDetails.quantity
键：
event_params.key 设置为 "currency"

值：
event_params.value.string_value		 productDetails.product.priceInfo.currencyCode
键：
event_params.key 设置为 "currency"

值：
event_params.value.string_value		 purchaseTransaction.currencyCode
键：
event_params.key 设置为 "search_term"

值：
event_params.value.string_value		 searchQuery
user_id userInfo.userId
user_pseudo_id visitorId

自定义属性

您可以为用户事件添加其他自定义属性和功能。这样，当您使用推荐功能时，就可以为用户提供更加贴合用户需求的更贴合需求的推荐内容。如需添加自定义特性，请在记录用户事件时使用 attributes。

如果您为注入的用户事件提供自定义特性，则务必也在与预测请求关联的用户事件中添加这些特性。自定义特性的格式设置必须在导入事件和随预测请求提供的事件之间保持一致。这样，就可以在训练模型和提供预测结果时使用这些自定义属性，从而提高推荐质量。

您可以使用 text 字段提供自定义文本值，也可以使用 number 字段提供自定义数值。

例如，下面显示了记录用户事件的请求的 attributes 部分：

"attributes": {
  "user_age": {"text": ["teen", "young adult"]},
  "user_location": {"text": ["CA"]}
}

关于用户信息

visitorId 表示唯一身份用户标识符，当您记录用户事件时，需要此参数。

记录用户事件时，包含的用户信息 (UserInfo) 包含 visitorId 值和 userId 值（如果有）。userId 是可选项，可用作用户在各种设备上唯一的永久性标识符，每当用户登录到您的网站时。当您记录用户的 userId 时，零售专用 Vertex AI Search 可以为一位用户在多部设备（例如移动设备和网络浏览器）上生成更加个性化的搜索结果。

关于时间戳

当您记录用户事件时，请确保添加事件发生的确切时间戳。准确的时间戳可确保以正确的顺序存储事件。对于使用跟踪代码管理器和 JavaScript 像素收集的事件，系统会自动记录时间戳。导入事件时，您必须按照 RFC 3339 指定的格式在 eventTime 字段中提供时间戳。

后续步骤