配置用户事件

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

如需配置用户事件，请执行以下操作：

1. 导入历史用户事件。

2. 记录实时用户事件。

3. 使用实体为用户事件添加代码。

4. 使用归因令牌标记用户事件。

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

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

用户事件类型

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

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

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

事件类型优先级

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

优先级	用户事件
初始实验必须提供	add-to-cart detail-page-view purchase-complete home-page-view（用于推荐） search（适用于搜索广告系列）
对于不断提高推荐模型的质量非常重要	category-page-view search shopping-cart-page-view

用户事件要求和最佳做法

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

本部分列出了以下内容：

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

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

您可以在 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 for Retail 便可以在其模型中考虑该行为序列。
detail-page-view	每个事件只包括一个商品。	如果没有任何商品，则无法使用该事件。如果加入了多个商品，该事件格式有误，无法使用。
add-to-cart	每个事件只包括一个商品。	如果加入了多个商品，该事件格式有误，无法使用。
purchase-complete	包括 purchase_transaction.revenue。	缺少 revenue 字段的 purchase-complete 事件不会用于训练模型。
	在所有购买事件中仅包含一个 purchase_transaction.currency_code。 没有默认货币代码；必须提供代码。	不含此字段的购买事件会导致收入指标不正确。
	检查某些购买事件是否包含多个商品。	包含多件商品的购买事件有助于模型学习同购模式。

推荐功能专属要求

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

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

事件类型	要求	影响
purchase-complete	请勿将含有多件商品的购物篮展平到多个购买事件中。它们应保持为包含多个商品的单个购买事件。	这可确保生成有效的合并购买模式。

搜索要求

如果您使用的是搜索广告系列，请确保您的用户事件满足以下最低要求，以便获得结果。

事件类型	要求	影响
search	searchQuery 必须针对搜索事件存在，pageCategories 必须针对浏览事件存在。	如果不添加此字段，可能会对搜索结果质量和指标产生严重的负面影响。
	搜索请求中的访问者 ID 应与随该搜索请求相关的事件发送的访问者 ID 相匹配。	如果它们不匹配，则事件格式不正确，指标可能不正确。
	搜索事件中的商品 ID 列表必须与整个商品向用户展示的商品列表相匹配。	如果不一致，则对搜索结果质量的负面影响可能非常严重，而且指标也会有误。
	如果搜索使用过滤条件，则 filter 必须存在并正确解析。	如果此字段不存在，则 Vertex AI Search for Retail 无法使用数据的过滤条件部分，这可能会对搜索结果质量产生负面影响。
	添加 attribution_token 字段以将其他事件关联回搜索事件。	如果不添加归因令牌，则会在 Retail Search 中触发错误，并对搜索质量和指标准确性产生严重的负面影响。

搜索优化要求

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

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

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

个性化搜索要求

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

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

“事件”指标	事件量/频率	说明
搜索服务提供的 search 事件量	过去 30 天内达到 10 万次	过去 30 天内通过搜索服务提供的事件必须至少达到 10 万个，系统才能提供个性化功能。
搜索结果未缓存	占最近 10 万个用户事件的比例低于 1%	如果您打算使用个性化功能，请勿缓存文本搜索或浏览搜索的搜索结果。如果针对不同的访问者重复使用相同的结果，搜索引擎将无法向任何给定用户提供真正个性化的结果，并且可能会泄露用户的私密数据。如果检测到缓存，搜索会自动关闭个性化功能。 如果您仅缓存搜索结果，搜索功能仍可为您提供个性化的浏览结果。反之，如果您仅缓存浏览结果，搜索功能仍可为文本查询搜索结果提供个性化体验。
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 用户事件格式的必填字段。

导入事件时，您必须按照 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": "[e-mail]",
    "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': '[e-mail]',
          '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 字段还支持类别层次结构，您可以将该层次结构作为列表提供。

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

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

JavaScript 像素

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

跟踪代码管理器

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

BigQuery

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

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

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

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

完整的 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": "[e-mail]",
    "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': '[e-mail]',
          '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 字段中提供时间戳。

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

JavaScript 像素

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

跟踪代码管理器

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

BigQuery

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

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

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

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

完整的 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": "[e-mail]",
    "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': '[e-mail]',
            '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 用户事件格式的必填字段。

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

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

JavaScript 像素

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

跟踪代码管理器

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

BigQuery

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

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

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

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

完整的 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": "[e-mail]",
    "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': '[e-mail]',
          '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 字段中提供时间戳。

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

JavaScript 像素

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

跟踪代码管理器

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

BigQuery

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

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

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

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

完整的 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": "[e-mail]",
    "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': '[e-mail]',
            '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 Retail 正常运行所需的最低字段数：

• 如需返回搜索结果列表，Vertex AI Search for Retail 需要同时提供 searchQuery 和 productDetails：

  • searchQuery 是从 search_term 参数或 view_search_results 事件读取的。
  • productDetails 是从 view_item_list 事件的 items 参数读取的。它应包含在搜索结果页中向最终用户显示的商品 ID 列表。

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

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

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

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

JavaScript 像素

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

跟踪代码管理器

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

BigQuery

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

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

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

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

自动补全

只有在您要使用自动补全功能时，搜索事件才需要此字段。搜索时不需要使用此属性。

以下示例展示了当用户输入“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": "[e-mail]",
    "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': '[e-mail]',
        '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": "[e-mail]",
    "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': '[e-mail]',
          '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 零售解决方案可以针对使用多台设备（例如移动设备和网络浏览器）的一个用户生成个性化结果。

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

关于时间戳

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

后续步骤

• 了解如何记录用户事件。