此页面由 Cloud Translation API 翻译。

媒体用户事件简介

本页介绍了媒体搜索和推荐应用的用户事件，包括用户事件类型、要求以及用户事件类型的示例。媒体应用需要用户事件。

如需了解有关媒体搜索和推荐的一般信息，请参阅媒体搜索和推荐简介。

如需有关记录用户事件方面的帮助，请参阅记录实时用户事件。如需批量导入过往用户事件，请参阅导入历史用户事件。

用户事件类型

当最终用户浏览或搜索您的网站时，您可以记录以下类型的用户事件：

用户事件名称	用户操作
`view-item`	查看文档的详细信息。
`view-home-page`	查看首页。
`search`	搜索数据存储区。
`media-play`	点击媒体内容中的“播放”。
`media-complete`	停止播放媒体内容，表示观看结束。

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

媒体搜索和推荐的事件要求

您需要哪些类型的用户事件取决于您的应用是搜索应用还是推荐应用、目标（点击率、转化率或观看时长），以及（仅限推荐应用）您选择的模型类型。如需详细了解推荐模型类型和优化目标，请参阅媒体应用推荐类型简介。

如需确定需要收集哪些用户事件，请参阅下表。

事件	`search`	`view-home-page`	`view-item`	`media-play`	`media-complete`
搜索使用场景
	必需	不需要	必需	必需	必需
“为您推荐”模型类型（按目标）
点击率	不需要	对于首页上下文，此参数为必需参数对于一般上下文，此参数不是必需参数	必须提供 `view-item` 或 `media-play`		强烈建议如果启用了历史记录降级，则为必需
转化率	不需要	对于首页上下文，此参数为必需参数对于一般上下文，此参数不是必需参数	必须提供 `view-item` 或 `media-play`		必需
观看时长	不需要	对于首页上下文，此参数为必需参数对于一般上下文，此参数不是必需参数	必须提供 `view-item` 或 `media-play`		必需
“您可能喜欢的其他商品”模型类型（按目标）
点击率	不需要	不需要	必须提供 `view-item` 或 `media-play`		强烈建议如果启用了历史记录降级，则为必需
转化率	不需要	不需要	必须提供 `view-item` 或 `media-play`		必需
观看时长	不需要	不需要	必须提供 `view-item` 或 `media-play`		必需
按目标划分的“类似内容”模型类型
点击率	不需要	不需要	必须提供 `view-item` 或 `media-play`		如果历史记录降级功能已开启，则必须提供
转化率	不需要	不需要	必须提供 `view-item` 或 `media-play`		必需
观看时长	不需要	不需要	必须提供 `view-item` 或 `media-play`		必需
按目标划分的最受欢迎的模型类型
点击率	不需要	不需要	必须提供 `view-item` 或 `media-play` 中的一个		不需要
转化率	不需要	不需要	不需要	不需要	必需

媒体用户事件的要求

确保您的用户事件满足以下要求，以便媒体应用可以生成高质量的结果。

事件类型	要求	影响
所有事件	请勿添加合成数据或重复的事件。	合成事件或重复事件会对结果质量产生负面影响，并可能导致您无法部署应用。重复事件可能会导致指标值不正确。
	对于提取的每种事件，请添加至少 100 个唯一身份用户伪 ID。	请务必添加这些 ID，以便媒体推荐应用有足够的数据来生成高质量的结果。
	在事件导入或事件记录以及媒体推荐请求中，用户伪 ID 的格式必须完全相同。	为用户伪 ID 使用一致的格式有助于媒体推荐应用正确识别访问者模式，并根据用户行为提供更优质的结果。
	所有文档都必须包含 `DocumentInfo.name` 字段或 `DocumentInfo.id` 字段。	如果文档没有 `DocumentInfo.name` 字段或 `DocumentInfo.id` 字段，则媒体推荐应用无法使用包含这些文档的事件。
	事件中包含的文档应存在于您的数据存储区中。	未联接事件的比例应尽可能低。较高的比例会对结果的质量产生负面影响。
	某些用户事件应具有相同的用户伪 ID。	为了构建有效的行为序列历史记录，媒体推荐应用必须能够看到具有相同用户伪 ID 的多个事件。例如，`visitor123` 已观看 5 个项目，并点击了其中 2 个项目的播放按钮。如果这些事件始终提供格式一致的相同用户伪 ID，媒体推荐应用可以在其结果中考虑该行为序列。
`view-item`	每个事件只包括一个文档。	如果没有任何文档，则无法使用该事件。如果加入了多个文档，该事件格式有误，无法使用。
`search`	包含 `attributionToken`。 `attributionToken` 由 search 方法与搜索或浏览结果一起返回。	`attributionToken` 可让 Vertex AI Search 将搜索事件准确归因于特定的搜索响应。
`media-play`	每个事件只包括一个文档。	如果加入了多个文档，该事件格式有误，无法使用。

A/B 测试的用户事件标记

如果您要进行 A/B 测试，请务必为收集的所有用户事件添加代码 ID，并为每个测试组添加一个代码。

例如，为当前模型中的用户事件添加 "tagIds": ["original"] 标记，并为 Vertex AI Search for Media 中的用户事件添加 "tagIds": ["google"] 标记。

用户事件类型示例和架构

本部分提供了媒体推荐支持的每种事件类型的数据格式。同时还提供了 JavaScript Pixel 的示例。对于 BigQuery，提供了每种类型的完整表架构。

对于所有用户事件类型，userId 是可选的。

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

view-item

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

至少需要 view-item 对象

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

大多数情况下，documents 包含关联文档的详细信息。

JavaScript 像素

var user_event = {
  "eventType": "view-item",
  "userPseudoId": "user-pseudo-id",
  "eventTime": "2020-01-01T03:33:33.000001Z",
  "documents": [{
    "id": "document-id"
  }]
  "panels": [
     {
       "panelId": "HOME_RFY_1",
       "documents": [
         {
           "id": "123"
         },
         {
           "id": "456"
         }
       ],
       "panelPosition": 1,
       "totalPanels": 2
     }
  ]
};

BigQuery

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

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

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

[
  {
    "name": "eventType",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "name": "userPseudoId",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "name": "eventTime",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "name": "userInfo",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "userId",
        "type": "STRING",
        "mode": "NULLABLE"
      },
      {
        "name": "userAgent",
        "type": "STRING",
        "mode": "NULLABLE"
      }
    ]
  },
  {
    "name": "pageInfo",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "pageviewId",
        "type": "STRING",
        "mode": "NULLABLE"
      },
      {
        "name": "uri",
        "type": "STRING",
        "mode": "NULLABLE"
      },
      {
        "name": "referrerUri",
        "type": "STRING",
        "mode": "NULLABLE"
      }
    ]
  },
  {
    "name": "attributionToken",
    "type": "STRING",
    "mode": "NULLABLE"
  },
  {
    "name": "documents",
    "type": "RECORD",
    "mode": "REPEATED",
    "fields": [
      {
        "name": "id",
        "type": "STRING",
        "mode": "NULLABLE"
      }
    ]
  },
  {
    "name": "tagIds",
    "type": "STRING",
    "mode": "REPEATED"
  },
  {
    "name": "attributes",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "example_text_attribute",
        "type": "RECORD",
        "mode": "NULLABLE",
        "fields": [
          {
            "name": "text",
            "type": "STRING",
            "mode": "REPEATED"
          }
        ]
      },
      {
        "name": "example_number_attribute",
        "type": "RECORD",
        "mode": "NULLABLE",
        "fields": [
          {
            "name": "numbers",
            "type": "NUMERIC",
            "mode": "REPEATED"
          }
        ]
      }
    ]
  }
]

完整的 view-item 对象示例

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

JavaScript 像素

var user_event = {
  eventType: "view-item",
  userPseudoId: "visitor0",
  eventTime: "2020-01-01T03:33:33.000001Z",
  userInfo: {
    userId: "abc@example.com",
    userAgent: "Mozilla/5.0",
  },
  pageInfo: {
    pageViewId: "currentPageUri",
    uri: "http://example",
    referrerUri: "https://google",
  },
  attributionToken: "abcd",
  documents: [
    {
      id: "abcd",
    },
  ],
  tagIds: ["Treatment_B"],
  attributes: {
    example_text_attribute: {
      text: ["text_1", "text_2"],
    },
    example_number_attribute: {
      numbers: [3.14, 42, 1.2345],
    },
  },
  panels [
         {
           panelId: "HOME_RFY_1",
           documents: [
             {
               id: "123"
             },
             {
               id: "456"
             }
           ],
           panelPosition: 1,
           totalPanels: 2
         }
      ]
};

BigQuery

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

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

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

[
  {
    "name": "eventType",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "name": "userPseudoId",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "name": "eventTime",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "name": "userInfo",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "userId",
        "type": "STRING",
        "mode": "NULLABLE"
      },
      {
        "name": "userAgent",
        "type": "STRING",
        "mode": "NULLABLE"
      }
    ]
  },
  {
    "name": "pageInfo",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "pageviewId",
        "type": "STRING",
        "mode": "NULLABLE"
      },
      {
        "name": "uri",
        "type": "STRING",
        "mode": "NULLABLE"
      },
      {
        "name": "referrerUri",
        "type": "STRING",
        "mode": "NULLABLE"
      }
    ]
  },
  {
    "name": "attributionToken",
    "type": "STRING",
    "mode": "NULLABLE"
  },
  {
    "name": "documents",
    "type": "RECORD",
    "mode": "REPEATED",
    "fields": [
      {
        "name": "id",
        "type": "STRING",
        "mode": "NULLABLE"
      }
    ]
  },
  {
    "name": "tagIds",
    "type": "STRING",
    "mode": "REPEATED"
  },
  {
    "name": "attributes",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "example_text_attribute",
        "type": "RECORD",
        "mode": "NULLABLE",
        "fields": [
          {
            "name": "text",
            "type": "STRING",
            "mode": "REPEATED"
          }
        ]
      },
      {
        "name": "example_number_attribute",
        "type": "RECORD",
        "mode": "NULLABLE",
        "fields": [
          {
            "name": "numbers",
            "type": "NUMERIC",
            "mode": "REPEATED"
          }
        ]
      }
    ]
  }
]

view-home-page

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

至少需要 view-home-page 对象

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

JavaScript 像素

var user_event = {
  "eventType": "view-home-page",
  "userPseudoId": "user-pseudo-id",
  "eventTime": "2020-01-01T03:33:33.000001Z",
  "panels": [
     {
       "panelId": "HOME_RFY_1",
       "documents": [
         {
           "id": "123"
         },
         {
           "id": "456"
         }
       ],
       "panelPosition": 1,
       "totalPanels": 2
     }
  ]
};

BigQuery

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

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

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

[
  {
    "name": "eventType",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "name": "userPseudoId",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "name": "eventTime",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "name": "userInfo",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "userId",
        "type": "STRING",
        "mode": "NULLABLE"
      },
      {
        "name": "userAgent",
        "type": "STRING",
        "mode": "NULLABLE"
      }
    ]
  },
  {
    "name": "pageInfo",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "pageviewId",
        "type": "STRING",
        "mode": "NULLABLE"
      },
      {
        "name": "uri",
        "type": "STRING",
        "mode": "NULLABLE"
      },
      {
        "name": "referrerUri",
        "type": "STRING",
        "mode": "NULLABLE"
      }
    ]
  },
  {
    "name": "attributionToken",
    "type": "STRING",
    "mode": "NULLABLE"
  },
  {
    "name": "documents",
    "type": "RECORD",
    "mode": "REPEATED",
    "fields": [
      {
        "name": "id",
        "type": "STRING",
        "mode": "NULLABLE"
      },
      {
        "name": "quantity",
        "type": "INT64",
        "mode": "NULLABLE"
      }
    ]
  },
  {
    "name": "tagIds",
    "type": "STRING",
    "mode": "REPEATED"
  },
  {
    "name": "attributes",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "example_text_attribute",
        "type": "RECORD",
        "mode": "NULLABLE",
        "fields": [
          {
            "name": "text",
            "type": "STRING",
            "mode": "REPEATED"
          }
        ]
      },
      {
        "name": "example_number_attribute",
        "type": "RECORD",
        "mode": "NULLABLE",
        "fields": [
          {
            "name": "numbers",
            "type": "NUMERIC",
            "mode": "REPEATED"
          }
        ]
      }
    ]
  }
]

如需了解 panels 对象，请参阅关于面板。

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

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

JavaScript 像素

var user_event = {
  eventType: "view-home-page",
  userPseudoId: "visitor0",
  eventTime: "2020-01-01T03:33:33.000001Z",
  userInfo: {
    userId: "abc@example.com",
    userAgent: "Mozilla/5.0",
  },
  pageInfo: {
    pageViewId: "currentPageUri",
    uri: "http://example",
    referrerUri: "https://google",
  },
  attributionToken: "abcd",
  documents: [
    {
      id: "abcd",
      quantity: 2,
    },
  ],
  tagIds: ["Treatment_B"],
  attributes: {
    example_text_attribute: {
      text: ["text_1", "text_2"],
    },
    example_number_attribute: {
      numbers: [3.14, 42, 1.2345],
    },
  },
  panels [
         {
           panelId: "HOME_RFY_1",
           documents: [
             {
               id: "123"
             },
             {
               id: "456"
             }
           ],
           panelPosition: 1,
           totalPanels: 2
         }
      ]
};

BigQuery

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

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

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

[
  {
    "name": "eventType",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "name": "userPseudoId",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "name": "eventTime",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "name": "userInfo",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "userId",
        "type": "STRING",
        "mode": "NULLABLE"
      },
      {
        "name": "userAgent",
        "type": "STRING",
        "mode": "NULLABLE"
      }
    ]
  },
  {
    "name": "pageInfo",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "pageviewId",
        "type": "STRING",
        "mode": "NULLABLE"
      },
      {
        "name": "uri",
        "type": "STRING",
        "mode": "NULLABLE"
      },
      {
        "name": "referrerUri",
        "type": "STRING",
        "mode": "NULLABLE"
      }
    ]
  },
  {
    "name": "attributionToken",
    "type": "STRING",
    "mode": "NULLABLE"
  },
  {
    "name": "documents",
    "type": "RECORD",
    "mode": "REPEATED",
    "fields": [
      {
        "name": "id",
        "type": "STRING",
        "mode": "NULLABLE"
      },
      {
        "name": "quantity",
        "type": "INT64",
        "mode": "NULLABLE"
      }
    ]
  },
  {
    "name": "tagIds",
    "type": "STRING",
    "mode": "REPEATED"
  },
  {
    "name": "attributes",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "example_text_attribute",
        "type": "RECORD",
        "mode": "NULLABLE",
        "fields": [
          {
            "name": "text",
            "type": "STRING",
            "mode": "REPEATED"
          }
        ]
      },
      {
        "name": "example_number_attribute",
        "type": "RECORD",
        "mode": "NULLABLE",
        "fields": [
          {
            "name": "numbers",
            "type": "NUMERIC",
            "mode": "REPEATED"
          }
        ]
      }
    ]
  }
]

搜索

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

至少需要 search 对象

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

为用户输入了文本查询的搜索事件提供 searchQuery。

attributionToken 会与搜索查询结果一起返回。

documents 应包含在搜索结果中向最终用户显示的文档 ID 列表。

JavaScript 像素

var user_event = {
  eventType: "search",
  userPseudoId: "user-pseudo-id",
  eventTime: "2020-01-01T03:33:33.000001Z",
  searchInfo: {
    searchQuery: "search-query",
  }, 
  attributionToken: "attribution-token",
  documents: [
    {
      id: "document-id1",
    },
    {
      id: "document-id2",
    },
  ]
};

BigQuery

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

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

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

[
  {
    "name": "eventType",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "name": "userPseudoId",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "name": "eventTime",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "name": "searchInfo",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "searchQuery",
        "type": "STRING",
        "mode": "NULLABLE"
      }
    ]
  },
  {
    "name": "pageInfo",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "pageCategory",
        "type": "STRING",
        "mode": "NULLABLE"
      }
    ]
  },
  {
    "name": "attributionToken",
    "type": "STRING",
    "mode": "NULLABLE"
  },
  {
    "name": "documents",
    "type": "RECORD",
    "mode": "REPEATED",
    "fields": [
      {
        "name": "id",
        "type": "STRING",
        "mode": "NULLABLE"
      }
    ]
  }
]

media-play

下面显示了 media-play 用户事件格式。

至少需要 media-play 对象

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

JavaScript 像素

var user_event = {
  "eventType": "media-play",
  "userPseudoId": "user-pseudo-id",
  "eventTime": "2020-01-01T03:33:33.000001Z",
  "documents": [
    {
      "id": "document-id1"
    }
  ]
};

BigQuery

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

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

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

[
  {
    "name": "eventType",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "name": "userPseudoId",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "name": "eventTime",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "name": "userInfo",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "userId",
        "type": "STRING",
        "mode": "NULLABLE"
      },
      {
        "name": "userAgent",
        "type": "STRING",
        "mode": "NULLABLE"
      }
    ]
  },
  {
    "name": "pageInfo",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "pageviewId",
        "type": "STRING",
        "mode": "NULLABLE"
      },
      {
        "name": "uri",
        "type": "STRING",
        "mode": "NULLABLE"
      },
      {
        "name": "referrerUri",
        "type": "STRING",
        "mode": "NULLABLE"
      }
    ]
  },
  {
    "name": "attributionToken",
    "type": "STRING",
    "mode": "NULLABLE"
  },
  {
    "name": "documents",
    "type": "RECORD",
    "mode": "REPEATED",
    "fields": [
      {
        "name": "id",
        "type": "STRING",
        "mode": "NULLABLE"
      }
    ]
  },
  {
    "name": "tagIds",
    "type": "STRING",
    "mode": "REPEATED"
  },
  {
    "name": "attributes",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "example_text_attribute",
        "type": "RECORD",
        "mode": "NULLABLE",
        "fields": [
          {
            "name": "text",
            "type": "STRING",
            "mode": "REPEATED"
          }
        ]
      },
      {
        "name": "example_number_attribute",
        "type": "RECORD",
        "mode": "NULLABLE",
        "fields": [
          {
            "name": "numbers",
            "type": "NUMERIC",
            "mode": "REPEATED"
          }
        ]
      }
    ]
  }
]

完整的 media-play 对象示例

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

JavaScript 像素

var user_event = {
  eventType: "media-play",
  userPseudoId: "visitor0",
  eventTime: "2020-01-01T03:33:33.000001Z",
  userInfo: {
    userId: "abc@example.com",
    userAgent: "Mozilla/5.0",
  },
  pageInfo: {
    pageViewId: "currentPageUri",
    uri: "http://example",
    referrerUri: "https://google",
  },
  attributionToken: "abcd",
  documents: [
    {
      id: "abcd",
    },
  ],
  tagIds: ["Treatment_B"],
  attributes: {
    example_text_attribute: {
      text: ["text_1", "text_2"],
    },
    example_number_attribute: {
      numbers: [3.14, 42, 1.2345],
    },
  },
};

BigQuery

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

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

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

[
  {
    "name": "eventType",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "name": "userPseudoId",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "name": "eventTime",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "name": "userInfo",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "userId",
        "type": "STRING",
        "mode": "NULLABLE"
      },
      {
        "name": "userAgent",
        "type": "STRING",
        "mode": "NULLABLE"
      }
    ]
  },
  {
    "name": "pageInfo",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "pageviewId",
        "type": "STRING",
        "mode": "NULLABLE"
      },
      {
        "name": "uri",
        "type": "STRING",
        "mode": "NULLABLE"
      },
      {
        "name": "referrerUri",
        "type": "STRING",
        "mode": "NULLABLE"
      }
    ]
  },
  {
    "name": "attributionToken",
    "type": "STRING",
    "mode": "NULLABLE"
  },
  {
    "name": "documents",
    "type": "RECORD",
    "mode": "REPEATED",
    "fields": [
      {
        "name": "id",
        "type": "STRING",
        "mode": "NULLABLE"
      }
    ]
  },
  {
    "name": "tagIds",
    "type": "STRING",
    "mode": "REPEATED"
  },
  {
    "name": "attributes",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "example_text_attribute",
        "type": "RECORD",
        "mode": "NULLABLE",
        "fields": [
          {
            "name": "text",
            "type": "STRING",
            "mode": "REPEATED"
          }
        ]
      },
      {
        "name": "example_number_attribute",
        "type": "RECORD",
        "mode": "NULLABLE",
        "fields": [
          {
            "name": "numbers",
            "type": "NUMERIC",
            "mode": "REPEATED"
          }
        ]
      }
    ]
  }
]

media-complete

下面显示了 media-complete 用户事件格式。

至少需要 media-complete 对象

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

JavaScript 像素

var user_event = {
  "eventType": "media-complete",
  "userPseudoId": "user-pseudo-id",
  "eventTime": "2020-01-01T03:33:33.000001Z",
  "documents": [
    {
      "id": "document-id1"
    }
  ],
  "mediaInfo": {
    "mediaProgressDuration": "65s",
    "mediaProgressPercentage": 0.2
  }
};

BigQuery

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

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

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

[
  {
    "name": "eventType",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "name": "userPseudoId",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "name": "eventTime",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "name": "userInfo",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "userId",
        "type": "STRING",
        "mode": "NULLABLE"
      },
      {
        "name": "userAgent",
        "type": "STRING",
        "mode": "NULLABLE"
      }
    ]
  },
  {
    "name": "pageInfo",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "pageviewId",
        "type": "STRING",
        "mode": "NULLABLE"
      },
      {
        "name": "uri",
        "type": "STRING",
        "mode": "NULLABLE"
      },
      {
        "name": "referrerUri",
        "type": "STRING",
        "mode": "NULLABLE"
      }
    ]
  },
  {
    "name": "attributionToken",
    "type": "STRING",
    "mode": "NULLABLE"
  },
  {
    "name": "documents",
    "type": "RECORD",
    "mode": "REPEATED",
    "fields": [
      {
        "name": "id",
        "type": "STRING",
        "mode": "NULLABLE"
      }
    ]
  },
  {
    "name": "tagIds",
    "type": "STRING",
    "mode": "REPEATED"
  },
  {
    "name": "attributes",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "example_text_attribute",
        "type": "RECORD",
        "mode": "NULLABLE",
        "fields": [
          {
            "name": "text",
            "type": "STRING",
            "mode": "REPEATED"
          }
        ]
      },
      {
        "name": "example_number_attribute",
        "type": "RECORD",
        "mode": "NULLABLE",
        "fields": [
          {
            "name": "numbers",
            "type": "NUMERIC",
            "mode": "REPEATED"
          }
        ]
      }
    ]
  },
  {
    "name": "mediaInfo",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "mediaProgressDuration",
        "type": "STRING",
        "mode": "NULLABLE"
      },
      {
        "name": "mediaProgressPercentage",
        "type": "NUMERIC",
        "mode": "NULLABLE"
      }
    ]
  }
]

完整的 media-complete 对象示例

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

JavaScript 像素

var user_event = {
  eventType: "media-complete",
  userPseudoId: "visitor0",
  eventTime: "2020-01-01T03:33:33.000001Z",
  userInfo: {
    userId: "abc@example.com",
    userAgent: "Mozilla/5.0",
  },
  pageInfo: {
    pageViewId: "currentPageUri",
    uri: "http://example",
    referrerUri: "https://google",
  },
  attributionToken: "abcd",
  documents: [
    {
      id: "abcd",
    },
  ],
  tagIds: ["Treatment_B"],
  attributes: {
    example_text_attribute: {
      text: ["text_1", "text_2"],
    },
    example_number_attribute: {
      numbers: [3.14, 42, 1.2345],
    },
  },
  mediaInfo: {
    mediaProgressDuration: "65s",
    mediaProgressPercentage: 0.2,
  },
};

BigQuery

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

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

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

[
  {
    "name": "eventType",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "name": "userPseudoId",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "name": "eventTime",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "name": "userInfo",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "userId",
        "type": "STRING",
        "mode": "NULLABLE"
      },
      {
        "name": "userAgent",
        "type": "STRING",
        "mode": "NULLABLE"
      }
    ]
  },
  {
    "name": "pageInfo",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "pageviewId",
        "type": "STRING",
        "mode": "NULLABLE"
      },
      {
        "name": "uri",
        "type": "STRING",
        "mode": "NULLABLE"
      },
      {
        "name": "referrerUri",
        "type": "STRING",
        "mode": "NULLABLE"
      }
    ]
  },
  {
    "name": "attributionToken",
    "type": "STRING",
    "mode": "NULLABLE"
  },
  {
    "name": "documents",
    "type": "RECORD",
    "mode": "REPEATED",
    "fields": [
      {
        "name": "id",
        "type": "STRING",
        "mode": "NULLABLE"
      }
    ]
  },
  {
    "name": "tagIds",
    "type": "STRING",
    "mode": "REPEATED"
  },
  {
    "name": "attributes",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "example_text_attribute",
        "type": "RECORD",
        "mode": "NULLABLE",
        "fields": [
          {
            "name": "text",
            "type": "STRING",
            "mode": "REPEATED"
          }
        ]
      },
      {
        "name": "example_number_attribute",
        "type": "RECORD",
        "mode": "NULLABLE",
        "fields": [
          {
            "name": "numbers",
            "type": "NUMERIC",
            "mode": "REPEATED"
          }
        ]
      }
    ]
  },
  {
    "name": "mediaInfo",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "mediaProgressDuration",
        "type": "STRING",
        "mode": "NULLABLE"
      },
      {
        "name": "mediaProgressPercentage",
        "type": "NUMERIC",
        "mode": "NULLABLE"
      }
    ]
  }
]

自定义特性

您可以为用户事件添加其他自定义属性和功能。这样可以为用户提供更好、更具体的结果。如需添加自定义特性，请在记录用户事件时使用 attributes。

如果您为注入的用户事件提供自定义特性，则务必也在与推荐和搜索请求关联的用户事件中添加这些特性。自定义特性的格式设置必须在导入事件和随请求提供的事件之间保持一致。这样，媒体应用便可使用这些自定义属性来提高质量。

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

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

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

关于用户信息

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

记录用户事件时包括的用户信息 (UserInfo) 包含 userPseudoId 值，以及 userId 值（如果可用）。 userId 是可选项，每当用户登录您的网站时，它可用作用户在不同设备上的唯一永久性标识符。当您记录某个用户的 userId 时，媒体搜索和推荐应用可以针对使用多台设备（例如移动设备和网络浏览器）的一个用户生成个性化结果。

关于时间戳

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

面板简介

在首页上，您通常会看到一个或多个面板，例如“热门推荐”面板和“为您推荐”面板。在详情页面上，您可能还会看到一些面板，例如“您可能还喜欢”。

用户事件的面板信息

对于类型为 view-home-page 和 view-item 的推荐用户事件，需要提供面板信息。对于显示 Google 推荐内容的首页和详情页，必须提供面板信息。

如果您要针对面板进行 A/B 测试，则必须记录测试中所有内容（无论来源如何）的用户事件以及面板信息。对于没有 Google 生成的面板内容的主页和详情页，建议（但不是必需）在 view-home-page 和 view-item 事件中提供面板信息。下表汇总了这些要求：

用户事件的来源（`view-home-page` 和 `view-item`）	`PanelInfo`（必需）
包括 Google 推荐的内容	是
包括 Google 不推荐且用于 A/B 测试的内容	是
包括 Google 不推荐且未在 A/B 测试中使用的内容	否

面板信息 (PanelInfo) 是一组用于描述面板各种元素的字段：

面板的 ID 编号
显示名称
面板在网页上的位置（例如，网页上的第一个面板 (e.g.,) 或第三个面板 (3)）1
页面上的面板总数
每个面板中显示的文档列表 (DocumentInfo)

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

预加载面板与延迟加载面板

在网页或移动网页上显示推荐内容有两种常见方法。您使用的方法决定了您记录的 view-home-page 用户事件的数量和内容。

预加载：通过预加载，系统会在用户到达页面时生成所有推荐商品。在这种情况下，当用户加载首页时，您会记录一个包含所有面板和文档的 view-home-page（或 view-item）用户事件。
延迟加载：采用延迟加载时，当用户进入页面时，系统不会生成面板内容，而是在用户向下滚动到面板或向右滚动以查看更多推荐内容时，动态加载内容。在这种情况下，当用户加载首页时，您会记录初始 view-home-page（或 view-item）用户事件，然后当用户滚动以生成更多推荐内容时，继续记录更多事件。在后续事件中，您只需在 panels 数组中包含正在显示的文档的增量。

示例场景

媒体公司的首页显示了两个推荐内容面板：

由最受欢迎模型提供支持的“时下热门”面板。
正在进行 A/B 测试的个性化推荐面板。部分用户会看到由为您推荐模型提供支持的建议面板（A 组），而其他用户会看到公司专有模型提供的建议（B 组）。

当分配给组 B 的用户查看此首页时，采用 JavaScript 像素格式的用户事件如下所示：

var user_event = {
  "eventType": "view-home-page",
  "userPseudoId": "4003345673.123451357",
  "eventTime": "2025-07-01T03:33:33.000001Z",
  "userInfo": {
    "userId": "jane.doe@example.com",
  },
  "tagIds": ["group-B"],
  "panels": [
    {
      "panelId": "panel-1",
      "displayId": "Trending Now",
      "documents": [
        {
          "id": "254722"
        },
        {
          "id": "2951"
        },
        ...
        {
          "id": "1201"
        }
      ],
      "panelPosition": 1,
      "totalPanels": 2
    },
    {
      "panelId": "panel-2",
      "displayId": "Recommended for You",
      "documents": [
        {
          "id": "79132"
        },
        {
          "id": "109487"
        },
        ...
        {
          "id": "164179"
        }
      ],
      "panelPosition": 2,
      "totalPanels": 2
    }
  ]
};

后续步骤

了解如何记录用户事件。

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

用户事件类型

媒体搜索和推荐的事件要求

媒体用户事件的要求

A/B 测试的用户事件标记

用户事件类型示例和架构

view-item

至少需要 view-item 对象

JavaScript 像素

BigQuery

完整的 view-item 对象示例

JavaScript 像素

BigQuery

view-home-page

至少需要 view-home-page 对象

JavaScript 像素

BigQuery

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

JavaScript 像素

BigQuery

搜索

至少需要 search 对象

JavaScript 像素

BigQuery

media-play

至少需要 media-play 对象

JavaScript 像素

BigQuery

完整的 media-play 对象示例

JavaScript 像素

BigQuery

media-complete

至少需要 media-complete 对象

JavaScript 像素

BigQuery

完整的 media-complete 对象示例

JavaScript 像素

BigQuery

自定义特性

关于用户信息

关于时间戳

面板简介

用户事件的面板信息

预加载面板与延迟加载面板

示例场景

后续步骤

媒体用户事件简介