“零售”已重命名为 Vertex AI Search 零售解决方案。我们正在更新内容，以反映新的品牌形象。

此页面由 Cloud Translation API 翻译。

用户事件简介

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

面向零售业的 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`

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 可以生成高质量的结果。

本部分列出了以下内容：

用户事件要求：常规用户事件要求。无论您使用的是推荐功能还是搜索功能，都需要满足这些要求。
推荐功能的特定要求：推荐功能的用户事件要求。
Google 搜索的具体要求：针对搜索的用户事件要求。

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

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

针对用户事件的要求

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

事件类型	要求	影响
所有事件	请勿添加合成数据或重复的事件。	合成事件或重复事件会对模型质量产生负面影响，并且通常会导致模型训练失败。重复的事件可能会导致指标值不正确。
	对于提取的每种事件，请添加至少 100 个唯一身份访问者 ID。	这可确保 Vertex AI Search for Retail 有足够的数据来生成高质量的结果。
	事件导入或事件记录中的访问者 ID 以及 API 请求中的访问者 ID 的格式必须完全相同。	使用一致的访问者 ID 格式有助于正确识别访问者模式并提供更优质的结果根据用户行为
	事件中包含的商品应存在于您的商品目录中。	未联接事件的比例应尽可能低。较高的比例会对推荐或搜索结果的质量产生负面影响。未联接的事件数据不会用于训练模型。但是，未联接的关联产品后，提取的内容如需了解详情，请参阅重新联接用户事件。
	部分用户事件应具有相同的访问者 ID。	为了构建有效的行为序列历史记录，Vertex AI Search for Retail 必须能够看到具有相同访问者 ID 的多个事件。例如，`visitor123` 查看了五个商品详情页面，将三件商品添加到购物车，然后购买了原始五件商品中的两件。如果这些事件都提供相同的格式一致的访问者 ID，零售企业的 Vertex AI Search 可以在其模型中考虑该行为序列。
`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` 字段以将其他事件关联回搜索事件。	不添加归因令牌将在 Search for Retail 中触发错误，并对搜索产生严重的负面影响质量和指标准确性。

搜索优化要求

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

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

事件指标	事件量/频率	说明
`search` 事件的数量	过去 90 天内达到 25 万	必须在过去 90 天内至少有 25 万个事件，系统才能根据提取的事件优化搜索体验。我们建议您至少每天上传一次事件，以保持良好的数据质量。在导入历史事件期间，请确保数据分布偏向最近的时间戳。最后一个时间戳日期的事件数应等于或高于每日平均事件数。
可归因于以下来源的`detail-page-view`数量 `search` 个事件	过去 30 天达 50 万人	为了优化搜索广告，必须提供至少 50 万个事件使用用户事件。
由于以下原因，平均可归因 `detail-page-view` 个事件：每件商品 `search` 个事件	过去 30 天内有 10 封	除非上传过去 21 天内的事件，否则必须使用提取的事件来优化搜索结果。
具有可解析过滤条件的 `search` 事件的比例	过去 30 天内为 0.1	建议用于优化搜索响应中的动态细分属性的顺序。
搜索到的含价格的商品所占的比例	过去 30 天：0.95	必须使用事件优化搜索结果提取的内容
每个定价商品可归因于 `search` 事件的平均 `add-to-cart` 事件数	过去 30 天内为 0.5	建议用于收入优化搜索结果。
每个可搜索的定价商品与 `search` 事件相关联的平均 `purchase-complete` 事件数	过去 30 天为 0.5	建议针对以提高收入为目标进行优化的搜索结果使用此功能。

个性化搜索要求

搜索服务需要以下数据，才能根据用户的活动记录为用户提供个性化的文本搜索结果和浏览搜索结果。

上传以下数据后，搜索功能便可自动为您提供个性化搜索结果。

“事件”指标事件量/频率说明

“事件”指标	事件量/频率	说明
搜索投放的 `search` 个事件的数量	过去 30 天 100,000 次	过去 30 天内通过搜索提供的至少 10 万个事件天以提供个性化体验。
搜索结果未缓存	占最近 10 万个用户事件的比例低于 1%	不缓存搜索结果以进行文本搜索或浏览。重复使用相同的结果会导致搜索无法真正提供为任何给定用户提供个性化搜索结果的风险，私有数据搜索功能自动关闭个性化。如果您仅缓存搜索结果，搜索功能仍可为您提供个性化的浏览结果。反之，如果只缓存了“浏览” 搜索结果，Google 搜索仍可对文本查询搜索进行个性化设置结果。
`SearchRequests` 和用户事件之间的访问者 ID 匹配	与最近 10 万个用户事件有超过 10% 的匹配	确保访问者 ID 的间距和格式在 `SearchRequests` 和用户事件中保持一致。一致的访问者 ID 格式可确保搜索功能能够正确识别用户活动。

搜索投放的 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 字段仅适用于 Vertex AI Search for Retail。它用于衡量效果。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": { "value": 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"
 }
]

完整的 add-to-cart 对象示例

以下示例包含 add-to-cart 用户事件的必填字段和可选字段。如果您要添加价格信息，则 currencyCode 字段为必填字段。

JavaScript Pixel

var user_event = {
  "eventType": "add-to-cart",
  "visitorId": "visitor0",
  "eventTime": "2020-01-01T03:33:33.000001Z",
  "experimentIds": ["321"],
  "attributes": {
    "example_text_attribute": {
      "text": ["text_1", "text_2"]
    },
    "example_number_attribute": {
      "numbers": [3.14, 42, 1.2345]
    }
  },
  "attributionToken": "abc",
  "productDetails": [{
    "product": {
      "id": "abc"
    },
    "quantity": 2
  }],
  "cartId": "mobile",
  "userInfo": {
    "userId": "abc@example.com",
    "ipAddress": "8.8.8.8",
    "userAgent": "Mozilla/5.0",
    "directUserRequest": true
  },
  "uri": "http://example",
  "referrerUri": "http://example",
  "pageViewId": "currentPageUri",
  "entity": "entity_1"
};

跟踪代码管理器

<script>
    dataLayer = dataLayer || [];
    dataLayer.push({
      'cloud_retail': {
        'eventType': 'add-to-cart',
        'visitorId': 'visitor0',
        // You can also define the user ID and visitor ID
        // directly on the Tag Manager tag.
        'eventTime': '2020-01-01T03:33:33.000001Z',
        'experimentIds': ['321'],
        'attributes': {
          'example_text_attribute': {
            'text': ['text_1', 'text_2']
          },
          'example_number_attribute': {
            'numbers': [3.14, 42, 1.2345]
          }
        },
        'attributionToken': 'abc',
        'productDetails': [{
          'product': {
            'id': 'abc'
          },
          'quantity': 2
        }],
        'cartId': 'mobile',
        'userInfo': {
          'userId': 'abc@example.com',
          'ipAddress': '8.8.8.8',
          'userAgent': 'Mozilla/5.0',
          'directUserRequest': true
        },
        'uri': 'http://example',
        'referrerUri': 'https://google',
        'pageViewId': 'currentPageUri',
        'entity': 'entity_1'
      }
    }];
</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。

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"
 }
]

完整的 category-page-view 对象示例

以下示例包含 category-page-view 用户事件的必填字段和可选字段。

JavaScript Pixel

var user_event = {
  "eventType": "category-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"
    }
  }],
  "pageCategories": ["Sales > New Year Deals"],
  "userInfo": {
    "userId": "abc@example.com",
    "ipAddress": "8.8.8.8",
    "userAgent": "Mozilla/5.0",
    "directUserRequest": true
  },
  "uri": "http://example",
  "referrerUri": "https://google",
  "pageViewId": "currentPageUri",
  "entity": "entity_1"
};

跟踪代码管理器

<script>
    dataLayer = dataLayer || [];
    dataLayer.push({
      'cloud_retail': {
        'eventType': 'category-page-view',
        'visitorId': 'visitor0',
        // You can also define the visitor ID and user ID
        // directly on the Tag Manager tag.
        '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'
          }
        }],
        'pageCategories': ['Sales > New Year Deals'],
        'userInfo': {
          'userId': 'abc@example.com',
          'ipAddress': '8.8.8.8',
          'userAgent': 'Mozilla/5.0',
          'directUserRequest': true
        },
        'uri': 'http://example',
        'referrerUri': 'https://google',
        'pageViewId': 'currentPageUri',
        'entity': 'entity_1'
      }
    });
</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 字段中提供时间戳。

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"
 }
]

完整的 detail-page-view 对象示例

以下示例包含 detail-page-view 用户事件的必填字段和可选字段。

JavaScript Pixel

var user_event = {
  "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@example.com",
    "ipAddress": "8.8.8.8",
    "userAgent": "Mozilla/5.0",
    "directUserRequest": true
  },
  "uri": "http://example",
  "referrerUri": "https://google",
  "pageViewId": "currentPageUri",
  "entity": "entity_1"
};

跟踪代码管理器

<script>
    dataLayer = dataLayer || [];
    dataLayer.push({
      'cloud_retail': {
          'eventType': 'detail-page-view',
          'visitorId': 'visitor0',
          // You can also define the visitor ID and user ID
          // directly on the Tag Manager tag.
          '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@example.com',
            'ipAddress': '8.8.8.8',
            'userAgent': 'Mozilla/5.0',
            'directUserRequest': true
          },
          'uri': 'http://example',
          'referrerUri': 'https://google',
          'pageViewId': 'currentPageUri',
          'entity': 'entity_1'
      }
    });
</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"
 }
]

完整的 home-page-view 对象示例

以下示例包含 home-page-view 用户事件的必填字段和可选字段。

JavaScript Pixel

var user_event = {
  "eventType": "home-page-view",
  "visitorId": "visitor0",
  "eventTime": "2020-01-01T03:33:33.000001Z",
  "experimentIds": ["321"],
  "attributes": {
    "example_text_attribute": {
      "text": ["text_1", "text_2"]
    },
    "example_number_attribute": {
      "numbers": [3.14, 42, 1.2345]
    }
  },
  "attributionToken": "abc",
  "productDetails": [{
    "product": {
      "id": "abc"
    },
    "quantity": 2
  }],
  "userInfo": {
    "userId": "abc@example.com",
    "ipAddress": "8.8.8.8",
    "userAgent": "Mozilla/5.0",
    "directUserRequest": true
  },
  "uri": "http://example",
  "referrerUri": "https://google",
  "pageViewId": "currentPageUri",
  "entity": "entity_1"
};

跟踪代码管理器

<script>
    dataLayer = dataLayer || [];
    dataLayer.push({
      'cloud_retail': {
        'eventType': 'home-page-view',
        'visitorId': 'visitor0',
        // You can also define the visitor ID and user ID
        // directly on the Tag Manager tag.
        'eventTime': '2020-01-01T03:33:33.000001Z',
        'experimentIds': ['321'],
        'attributes': {
          'example_text_attribute': {
            'text': ['text_1', 'text_2']
          },
          'example_number_attribute': {
            'numbers': [3.14, 42, 1.2345]
          }
        },
        'attributionToken': 'abc',
        'productDetails': [{
          'product': {
            'id': 'abc'
          },
          'quantity': 2
        }],
        'userInfo': {
          'userId': 'abc@example.com',
          'ipAddress': '8.8.8.8',
          'userAgent': 'Mozilla/5.0',
          'directUserRequest': true
        },
        'uri': 'http://example',
        'referrerUri': 'https://google',
        'pageViewId': 'currentPageUri',
        'entity': 'entity_1'
    });
</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 字段中提供时间戳。

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"
 }
]

完整的 purchase-complete 对象示例

以下示例包含 purchase-complete 用户事件的必填字段和可选字段。在本示例中，提供的是所购商品的全价信息产品。在提取和处理用户事件时，如果提供了 priceInfo 信息，则使用此信息来替换存储的商品价格信息。

JavaScript 像素

var user_event = {
  "eventType": "purchase-complete",
  "visitorId": "visitor0",
  "eventTime": "2020-01-01T03:33:33.000001Z",
  "experimentIds": ["321"],
  "attributes": {
    "example_text_attribute": {
      "text": ["text_1", "text_2"]
    },
    "example_number_attribute": {
      "numbers": [3.14, 42, 1.2345]
    }
  },
  "attributionToken": "abc",
  "productDetails": [{
    "product": {
      "id": "abc",
      "priceInfo": {
        "price": 99.99,
        "originalPrice": 129.99,
        "currencyCode": "EUR"
      }
    },
    "quantity": 2
  }],
  "cartId": "mobile",
  "purchaseTransaction": {
    "revenue": 10.0,
    "currencyCode": "EUR"
  },
  "userInfo": {
    "userId": "abc@example.com",
    "ipAddress": "8.8.8.8",
    "userAgent": "Mozilla/5.0",
    "directUserRequest": true
  },
  "uri": "http://example",
  "referrerUri": "https://google",
  "pageViewId": "currentPageUri",
  "entity": "entity_1"
};

跟踪代码管理器

<script>
    dataLayer = dataLayer || [];
    dataLayer.push({
      'cloud_retail': {
        'eventType': 'purchase-complete',
          'visitorId': 'visitor0',
          // You can also define the visitor ID and user ID
          // directly on the Tag Manager tag.
          'eventTime': '2020-01-01T03:33:33.000001Z',
          'experimentIds': ['321'],
          'attributes': {
            'example_text_attribute': {
              'text': ['text_1', 'text_2']
            },
            'example_number_attribute': {
              'numbers': [3.14, 42, 1.2345]
            }
          },
          'attributionToken': 'abc',
          'productDetails': [{
            'product': {
              'id': 'abc',
              'priceInfo': {
                'price': 99.99,
                'originalPrice': 129.99,
                'currencyCode': 'EUR'
              }
            },
            'quantity': 2
          }],
          'cartId': 'mobile',
          'purchaseTransaction': {
            'revenue': 10.0,
            'currencyCode': 'EUR'
          },
          'userInfo': {
            'userId': 'abc@example.com',
            'ipAddress': '8.8.8.8',
            'userAgent': 'Mozilla/5.0',
            'directUserRequest': true
          },
          'uri': 'http://example',
          'referrerUri': 'https://google',
          'pageViewId': 'currentPageUri',
          'entity': 'entity_1'
      }
    });
</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"
     }
    ]
 }
]

完整的 search 对象示例

以下示例包含 search 用户事件的必填字段和可选字段。

JavaScript 像素

var user_event = {
  "eventType": "search",
  "visitorId": "visitor0",
  "searchQuery": "Rainbow Unicorn",
  "filter": "(brands: ANY(\"brand_1\") AND price: IN(0, 100))",
  "orderBy": "rating",
  "offset": 60,
  "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"
      }
    }, {
      "product": {
        "id": "def"
      }
    }
  ],
  "pageCategories": ["Sales > New Year Deals"],
  "userInfo": {
    "userId": "abc@example.com",
    "ipAddress": "8.8.8.8",
    "userAgent": "Mozilla/5.0",
    "directUserRequest": true
  },
  "uri": "https://awesome",
  "referrerUri": "https://google",
  "pageViewId": "currentPageUri",
  "entity": "entity_1",
  "completionDetail": {
    "completionAttributionToken": "efg",
    "selectedSuggestion": "Rainbow Unicorn",
    "selectedPosition": 3
  }
};

跟踪代码管理器

<script>
    dataLayer = dataLayer || [];
    dataLayer.push({
      'eventType': 'search',
      'visitorId': 'visitor0',
      // You can also define the visitor ID and user ID
      // directly on the Tag Manager tag.
      'searchQuery': 'Rainbow Unicorn',
      'filter': '(brands: ANY(\"brand_1\") AND price: IN(0, 100))',
      'orderBy': 'rating',
      'offset': 60,
      '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'
          }
        }, {
          'product': {
            'id': 'def'
          }
        }
      ],
      'pageCategories': ['Sales > New Year Deals'],
      'userInfo': {
        'userId': 'abc@example.com',
        'ipAddress': '8.8.8.8',
        'userAgent': 'Mozilla/5.0',
        'directUserRequest': true
      },
      'uri': 'http://example',
      'referrerUri': 'https://google',
      'pageViewId': 'currentPageUri',
      'entity': 'entity_1',
      "completionDetail": {
        "completionAttributionToken": "efg",
        "selectedSuggestion": "Rainbow Unicorn",
        "selectedPosition": 3
      }
      }
    });
</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"
 }
]

完整的 shopping-cart-page-view 对象示例

以下示例包含 shopping-cart-page-view 用户事件的必填字段和可选字段。

JavaScript Pixel

var user_event = {
  "eventType": "shopping-cart-page-view",
  "visitorId": "visitor0",
  "eventTime": "2020-01-01T03:33:33.000001Z",
  "experimentIds": ["321"],
  "attributes": {
    "example_text_attribute": {
      "text": ["text_1", "text_2"]
    },
    "example_number_attribute": {
      "numbers": [3.14, 42, 1.2345]
    }
  },
  "attributionToken": "abc",
  "productDetails": [{
    "product": {
      "id": "abc"
    },
    "quantity": 2
  }],
  "cartId": "mobile",
  "userInfo": {
    "userId": "abc@example.com",
    "ipAddress": "8.8.8.8",
    "userAgent": "Mozilla/5.0",
    "directUserRequest": true
  },
  "uri": "http://example",
  "referrerUri": "https://google",
  "pageViewId": "currentPageUri",
  "entity": "entity_1"
};

跟踪代码管理器

<script>
    dataLayer = dataLayer || [];
    dataLayer.push({
      'cloud_retail': {
        'eventType': 'shopping-cart-page-view',
        'visitorId': 'visitor0',
        // You can also define the visitor ID and user ID
        // directly on the Tag Manager tag.
        'eventTime': '2020-01-01T03:33:33.000001Z',
        'experimentIds': ['321'],
        'attributes': {
          'example_text_attribute': {
            'text': ['text_1', 'text_2']
          },
          'example_number_attribute': {
            'numbers': [3.14, 42, 1.2345]
          }
        },
        'attributionToken': 'abc',
        'productDetails': [{
          'product': {
            'id': 'abc'
          },
          'quantity': 2
        }],
        'cartId': 'mobile',
        'userInfo': {
          'userId': 'abc@example.com',
          'ipAddress': '8.8.8.8',
          'userAgent': 'Mozilla/5.0',
          'directUserRequest': true
        },
        'uri': 'http://example',
        'referrerUri': 'https://google',
        'pageViewId': 'currentPageUri',
        'entity': 'entity_1'
      }
    });
</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 字段中提供时间戳。

后续步骤

了解如何记录用户事件。

用户事件简介

用户事件类型

事件类型优先级

用户事件要求和最佳做法

针对用户事件的要求

推荐功能专属要求

搜索要求

搜索优化要求

个性化搜索要求

用户事件类型示例和架构

加入购物车

至少需要 add-to-cart 对象

JavaScript 像素

跟踪代码管理器

BigQuery

完整的 add-to-cart 对象示例

JavaScript Pixel

跟踪代码管理器

BigQuery

类别页面视图

至少需要 category-page-view 对象

JavaScript 像素

跟踪代码管理器

BigQuery

完整的 category-page-view 对象示例

JavaScript Pixel

跟踪代码管理器

BigQuery

详情页面浏览

至少需要 detail-page-view 对象

JavaScript 像素

跟踪代码管理器

BigQuery

完整的 detail-page-view 对象示例

JavaScript Pixel

跟踪代码管理器

BigQuery

首页浏览

至少需要 home-page-view 对象

JavaScript 像素

跟踪代码管理器

BigQuery

完整的 home-page-view 对象示例

JavaScript Pixel

跟踪代码管理器

BigQuery

购买完成

至少需要 purchase-complete 对象

JavaScript 像素

跟踪代码管理器

BigQuery

完整的 purchase-complete 对象示例

JavaScript 像素

跟踪代码管理器

BigQuery

搜索

至少需要 search 对象

JavaScript 像素

跟踪代码管理器

BigQuery

自动补全

JavaScript 像素

跟踪代码管理器

BigQuery

完整的 search 对象示例

JavaScript 像素

跟踪代码管理器

BigQuery

购物车页面视图

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

JavaScript 像素

跟踪代码管理器

BigQuery

完整的 shopping-cart-page-view 对象示例

JavaScript Pixel

跟踪代码管理器

BigQuery

Google Analytics 4 用户事件字段

自定义属性

关于用户信息