此页面由 Cloud Translation API 翻译。

用户事件简介

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

Vertex AI Search 商务解决方案使用实时用户事件来生成推荐和搜索结果。上传数据后，推荐和搜索功能都可以使用这些数据，因此如果您同时使用这两项服务，则无需上传相同的事件。

配置并实现用户事件。
详细了解用户事件类型。
详细了解归因令牌。

搜索广告归因的运作方式

归因的运作方式

用户事件类型

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

用户事件名称	用户操作	Google Analytics 4 `event_name`
home-page-view	查看首页。	`view_homepage`
搜索（搜索和浏览）	搜索目录。	`view_item_list` + [`searchQuery` 或 `pageCategories` + `filter`]
category-page-view（仅限建议）	查看销售页面或促销页面等特殊页面。	`view_item_list` + `pageCategories`
detail-page-view	查看商品详情页面。	`view_item`
add-to-cart	将商品添加到购物车。	`add_to_cart`
shopping-cart-page-view	查看购物车。	`begin_checkout`
purchase-complete	完成结账。	`purchase`

如需查看 GA4 事件字段的完整列表，请参阅 Google Analytics 4 用户事件字段。

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

事件类型优先级

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

优先级用户事件类型

优先级	用户事件类型
初始实验必须提供（事件类型取决于推荐模型类型）	`detail-page-view` `add-to-cart` `purchase-complete` `home-page-view`
搜索实时实验所需的其他事件	`search`

初始实验必须提供

（事件类型取决于推荐模型类型）

搜索实时实验所需的其他事件

用户事件要求和最佳做法

下表列出了推荐和搜索功能使用的用户事件类型的要求和最佳实践。检查用户事件是否符合这些要求，以便 Vertex AI Search 商务解决方案可以生成高质量的结果。

本部分列出了以下内容：

用户事件要求：一般用户事件要求。无论您使用的是推荐功能还是搜索功能，都需要满足这些要求。
推荐功能特定要求：推荐功能的用户事件要求。
搜索特定要求：搜索的用户事件要求。

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

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

一般用户事件要求

确保您的用户事件满足以下要求，以便 Vertex AI Search 商务解决方案可以生成高质量的结果。这些要求同时适用于推荐和搜索。

事件类型	要求	影响
所有事件	请勿添加合成数据或重复的事件。	合成事件或重复事件会对模型质量产生负面影响，并且通常会妨碍模型成功训练。重复的事件可能会导致指标值不正确。
	对于提取的每种事件，请添加至少 100 个唯一身份访问者 ID。	这可验证 Vertex AI Search 商务解决方案是否有足够的数据来生成高质量的结果。
	在事件导入或事件记录以及 API 请求中，访问者 ID 的格式必须完全相同。	使用一致的访问者 ID 格式有助于正确识别访问者模式，并根据用户行为提供更优质的结果。
	事件中包含的商品应存在于您的商品目录中。	未联接事件的比例应尽可能低。较高的比例会对推荐或搜索结果的质量产生负面影响。未联接的事件数据不会用于训练模型。不过，在关联产品被提取后，未联接的事件可以稍后联接。如需了解详情，请参阅重新加入用户事件。
	某些用户事件应具有相同的访问者 ID。	为了构建有效的行为序列历史记录，Vertex AI Search for Commerce 必须能够看到具有相同访问者 ID 的多个事件。例如，`visitor123` 浏览了 5 个商品详情页面，将 3 件商品添加到了购物车，然后购买了最初 5 件商品中的 2 件。如果这些事件都提供格式一致的相同访问者 ID，Vertex AI Search for Commerce 可以在其模型中考虑该行为序列。
`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 Commerce 无法使用数据的过滤条件部分，这可能会对搜索结果质量产生负面影响。
	添加 `attribution_token` 字段以将其他事件关联回搜索事件。	如果不添加归因令牌，则会在“面向商务的搜索”中触发错误，并对搜索质量和指标准确性产生严重的负面影响。

搜索优化要求

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

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

“事件”指标	活动量/活动频率	说明
`search` 个活动的门票数量	过去 90 天内达到 25 万	为了根据已注入的事件优化搜索体验，必须在过去 90 天内至少有 25 万个事件。我们建议您至少每天上传一次事件，以保持良好的数据质量。在导入历史事件期间，请确保数据分布偏向最近的时间戳。最后一个时间戳日期的事件数应等于或大于日均事件数。
归因于 `search` 事件的 `detail-page-view` 量	过去 30 天内达到 50 万	至少需要 50 万个事件才能使用用户事件优化搜索结果。
每个商品的可归因于 `search` 事件的 `detail-page-view` 事件的平均数量	10（过去 30 天）	必需，用于使用已提取的事件优化搜索结果，除非上传了过去 21 天的事件。
具有可解析过滤条件的 `search` 事件的比例	0.1（过去 30 天）	建议用于优化搜索响应中动态分面的顺序。
搜索到的包含价格的商品的比例	过去 30 天内为 0.95	必需，用于使用提取的事件优化搜索结果。
每个付费产品可归因于 `search` 事件的 `add-to-cart` 事件的平均数量	0.5（过去 30 天）	建议使用此功能，以获得经过收入优化的搜索结果。
每个可搜索的付费产品可归因于 `search` 事件的 `purchase-complete` 事件的平均数量	0.5（过去 30 天）	建议使用此功能，以获得经过收入优化的搜索结果。

个性化搜索要求

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

上传以下数据后，搜索功能可以自动实现个性化结果。

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

“事件”指标	活动量/活动频率	说明
搜索服务的 `search` 事件量	过去 30 天内达到 10 万	至少需要有 10 万个由搜索服务在过去 30 天内促成的事件，才能提供个性化。
搜索结果未缓存	最近 10 万个用户事件中不到 1%	如果您打算使用个性化功能，请勿缓存文字搜索或浏览搜索的搜索结果。如果对所有访问者重复使用相同的结果，搜索功能就无法向任何给定用户提供真正个性化的结果，并且可能会泄露用户的私密数据。如果检测到缓存，搜索会自动关闭个性化功能。如果您仅缓存搜索结果，搜索仍可对浏览结果进行个性化处理。相反，如果您仅缓存浏览结果，搜索仍可对文本查询搜索结果进行个性化处理。
`SearchRequests` 与用户事件之间的访问者 ID 匹配情况	最近 10 万个用户事件的匹配率超过 10%	确保 `SearchRequests` 和用户事件中的访问者 ID 间距和格式一致。一致的访问者 ID 格式可验证搜索能否正确识别用户活动。

搜索服务的 search 事件量

过去 30 天内达到 10 万

至少需要有 10 万个由搜索服务在过去 30 天内促成的事件，才能提供个性化。

搜索结果未缓存

最近 10 万个用户事件中不到 1%

如果您打算使用个性化功能，请勿缓存文字搜索或浏览搜索的搜索结果。如果对所有访问者重复使用相同的结果，搜索功能就无法向任何给定用户提供真正个性化的结果，并且可能会泄露用户的私密数据。如果检测到缓存，搜索会自动关闭个性化功能。

如果您仅缓存搜索结果，搜索仍可对浏览结果进行个性化处理。相反，如果您仅缓存浏览结果，搜索仍可对文本查询搜索结果进行个性化处理。

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

用户事件类型示例和架构

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

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

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

请注意：

只有在您运行 A/B 实验时，才需要 experimentIds 字段。
attributionToken 字段仅对 Vertex AI Search for Commerce 是必需的。它用于衡量效果。不应将归因令牌发送到 predict、search 和 detail-page-view 或点击事件。
确保您的事件都使用一种货币，尤其是如果您计划使用Google Cloud 控制台获取收入指标。Vertex AI Search for Commerce API 不支持每个目录使用多种货币。

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

加入购物车

以下示例仅使用必填字段，展示了 add-to-cart 用户事件格式。

add-to-cart 事件中的商品数量必须是一个增量值，表示与相应特定用户事件关联的商品数量。例如，如果将两件商品添加到购物车中，相应 add-to-cart 事件的数量字段应为 2。对于 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": { "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': {
            'value': 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 用户事件格式的必填字段。

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

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

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

大多数情况下，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 用户事件格式的必填字段。

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

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': {
            'value': 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 用户事件格式的必填字段。

导入事件时，您必须按照 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': {
              'value': 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 对象

以下是 Vertex AI Search for Commerce 返回搜索结果列表所需的最低字段：

searchQuery 从 search_term 参数或 view_search_results 事件中读取。
productDetails 是从 view_item_list 事件的 items 参数中读取的。应包含在搜索结果中向最终用户显示的商品 ID 列表。
userEvents 会捕获 Retail API 需要了解的所有元数据信息，以了解最终用户如何与客户的网站互动。

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

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

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”并点击建议列表中的第二个建议“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"
     }
    ]
 }
]

完整的 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 用户事件格式的必填字段。

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

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

JavaScript 像素

var user_event = {
  "eventType": "shopping-cart-page-view"",
  "visitorId": "VISITOR-ID"
  "cartId": "CART-ID",
  "productDetails": [{
      "product": {
        "id": "PRODUCT-ID"
      },
      "quantity": PRODUCT-QUANTITY
    }]
};

将 PRODUCT-ID、PRODUCT-QUANTITY、VISOTOR-ID 和 CART-ID 分别替换为您的商品 ID、商品数量、会话 ID 和购物车 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'
            },
            'quantity': PRODUCT-QUANTITY
          }]
      }
    });
</script>

将 PRODUCT-ID、PRODUCT-QUANTITY、VISOTOR-ID 和 CART-ID 分别替换为您的商品 ID、商品数量、会话 ID 和购物车 ID。

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': {
            'value': 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 Commerce 字段。

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

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`

后续步骤

了解如何记录用户事件。

用户事件简介 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

搜索广告归因的运作方式

用户事件类型

事件类型优先级

用户事件要求和最佳做法

一般用户事件要求

与推荐相关的要求

搜索广告专属要求

搜索优化要求

个性化搜索要求

用户事件类型示例和架构

加入购物车

JavaScript 像素

跟踪代码管理器

BigQuery

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

JavaScript Pixel

跟踪代码管理器

BigQuery

类别页面浏览

JavaScript 像素

跟踪代码管理器

BigQuery

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

JavaScript Pixel

跟踪代码管理器

BigQuery

详情页面浏览

JavaScript 像素

跟踪代码管理器

BigQuery

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

JavaScript Pixel

跟踪代码管理器

BigQuery

首页浏览

JavaScript 像素

跟踪代码管理器

BigQuery

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

JavaScript Pixel

跟踪代码管理器

BigQuery

购买完成

JavaScript 像素

跟踪代码管理器

BigQuery

完整的 purchase-complete 对象示例

JavaScript 像素

跟踪代码管理器

BigQuery

搜索

至少需要 search 对象

JavaScript 像素

跟踪代码管理器

BigQuery

自动补全

JavaScript 像素

跟踪代码管理器

BigQuery

完整的 search 对象示例

JavaScript 像素

跟踪代码管理器

BigQuery

购物车页面浏览

JavaScript 像素

跟踪代码管理器

BigQuery

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

JavaScript Pixel

跟踪代码管理器

BigQuery

Google Analytics 4 用户事件字段

后续步骤

用户事件简介