用户事件简介

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

面向零售业的 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 for Retail 可以生成高质量的结果。

本部分列出了以下内容：

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

您可以在 数据质量页面 Search for Retail 控制台。这些指标显示了 符合推荐标准的产品和用户事件所占百分比 数据质量。有关如何查看搜索数据质量的信息，请参阅 解锁搜索广告效果层级。

针对用户事件的要求

请确保您的用户事件符合以下要求，以便 适用于零售的 Vertex AI Search 可以生成高质量的结果。这些设置适用于 建议和搜索。

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

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

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

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

这可确保 Vertex AI Search for Retail 有足够的数据来生成 结果。

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

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

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

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

未联接的事件数据不会用于训练模型。但是，未联接的 关联产品后， 提取的内容如需了解详情，请参阅重新联接用户事件。

部分用户事件应具有相同的访问者 ID。

为了构建有效的行为序列历史记录，Vertex AI Search for Retail 必须能够看到使用同一访问者 ID 的多个事件。

例如，visitor123查看了 5 个商品详情 向购物车添加了三件产品 然后购买了其中两件 最初的五款产品。如果这些事件都提供相同的 格式一致的访问者 ID，零售企业的 Vertex AI Search 可以 在其模型中考虑该行为序列。

detail-page-view

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

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

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

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

包括 purchase_transaction.revenue。

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

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

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

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

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

让一些包含多件商品的购买事件有助于模型学习共同购买模式。

具体建议的要求

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

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

事件类型 要求 影响
purchase-complete

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

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

搜索要求

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

事件类型 要求 影响
search

对于搜索事件，“searchQuery”必须存在，并且 必须存在“pageCategories”，才能进行浏览事件。

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

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

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

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

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

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

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

添加 attribution_token 字段以将其他事件关联回搜索事件。

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

搜索优化要求

要让搜索功能根据具体情况自动优化搜索体验， 有关整体用户趋势的信息，请上传以下数据。

事件应至少每天上传一次，最长延迟 24 小时。

事件指标 事件量/频率 说明
search事件的数量 过去 90 天内达到 25 万

在过去 90 天内，需要至少 250,000 个事件，才能 根据注入的活动优化搜索体验。

我们建议您至少每天上传一次事件，以保持良好的数据质量。在导入历史事件期间，请确保数据分布偏向最近的时间戳。最后一个时间戳日的事件数应等于或大于每日平均事件数。

可归因于以下来源的detail-page-view数量 search 个事件 过去 30 天达 50 万人 为了优化搜索广告，必须提供至少 50 万个事件 使用用户事件生成搜索结果。
由于以下原因，平均可归因 detail-page-view 个事件： 每件商品 search 个事件 过去 30 天内有 10 封 必须使用事件优化搜索结果 注入。
具有可解析过滤条件的 search 事件的比例 过去 30 天：0.1 建议用于优化动态分面的顺序， 搜索响应。
搜索到的含价格的商品所占的比例 过去 30 天：0.95 必须使用事件优化搜索结果 提取的内容
由于以下原因，平均可归因 add-to-cart 个事件： 每个定价产品有 search 个事件 过去 30 天为 0.5 建议用于收入优化搜索结果。
由于以下原因，平均可归因 purchase-complete 个事件： 每个可搜索的定价商品对应 search 个事件 过去 30 天为 0.5 建议用于收入优化搜索结果。

搜索个性化要求

Google 搜索需要使用以下数据才能提供个性化的文本搜索 并根据用户的活动浏览搜索结果。

您上传以下数据后，Google 搜索可以为您提供个性化服务 结果。

事件指标 事件量/频率 说明
搜索投放的 search 个事件的数量 过去 30 天 100,000 次

过去 30 天内通过搜索提供的至少 10 万个事件 天以提供个性化体验。

搜索结果未缓存 在最近的 10 万次用户事件中，不到 1%

不缓存搜索结果以进行文本搜索或浏览 。重复使用相同的结果 会导致搜索无法真正提供 为任何给定用户提供个性化结果，并且可能会导致用户 私有数据搜索功能自动关闭 个性化。

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

SearchRequests 与用户事件之间的访问者 ID 匹配 有超过 10% 的比例与最近的 10 万个用户事件相匹配 请确保访问者 ID 的间距和格式设置一致 SearchRequests 和用户事件。一致的访问者 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 用户事件格式的必填字段。

导入事件时，您必须在 eventTime 字段，并采用 RFC 3339。

根据所使用的 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 字段还支持类别层次结构，您可以将该层次结构作为列表提供。

导入事件时，您必须在 eventTime 字段，并采用 RFC 3339。

根据所使用的 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 包含关联商品的详细信息，除非是同时销售一组商品。

导入事件时，您必须在 eventTime 字段，并采用 RFC 3339。

根据所使用的 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 用户事件格式的必填字段。

导入事件时，您必须在 eventTime 字段，并采用 RFC 3339。

根据所使用的 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 用户事件格式的必填字段。

导入事件时，您必须在 eventTime 字段，并采用 RFC 3339。

根据所使用的 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 列表。

导入事件时，您必须在 eventTime 字段，并采用 RFC 3339。

根据所使用的 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"
 }
]

自动补全

只有对于搜索事件，如果您要使用 自动补全。搜索时不需要。

以下示例显示了当用户输入“sh”时 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 对象。

导入事件时，您必须在 eventTime 字段，并采用 RFC 3339。

根据所使用的 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 for Retail 字段。

在从 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 for Retail 可以在多台设备上为同一用户生成更加个性化的结果， 例如移动设备和网络浏览器

关于时间戳

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

后续步骤