用户事件简介

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

媒体推荐应用必须记录用户事件。媒体推荐应用使用实时用户事件生成推荐内容。其他应用类型不需要用户事件。

下表列出了哪些类型的应用需要上传用户事件：

应用类型 是否需要用户事件？
媒体推荐 是
媒体搜索 否，但强烈建议
一般建议 否
宽泛搜索 否，但强烈建议

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

用户事件类型

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

用户事件名称 用户操作
view-category-page 查看类别页面，例如“首页”>“电视”>“剧情片”“首页”>“电影”>“动作片”。
view-item 查看文档的详细信息页面。
view-home-page 查看首页。
search 搜索数据存储区。
media-play 点击媒体内容的“播放”按钮。
media-complete 停止播放媒体内容，表示观看结束。

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

适用于媒体应用的用户事件要求和最佳实践

下表列出了用户事件类型的要求和最佳实践 媒体推荐应用使用的应用检查用户事件是否符合这些要求，以便您的应用可以生成高质量的结果。

另请参阅媒体应用推荐类型简介，其中列出了根据您计划使用的推荐类型和优化目标所需的用户事件类型。

媒体推荐的事件类型优先级

下表介绍了媒体的用户事件类型的优先级 建议。必须有某些用户事件才能使用媒体推荐。 其他属性虽然有助于提升效果，但并非必需。

优先级 用户事件
对于包含媒体推荐的首次实时实验，必须执行此操作

view-item

view-home-page

media-play

media-complete
对于不断提高媒体推荐结果质量非常重要

view-category-page

媒体推荐要求

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

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

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

合成事件或重复事件会对结果质量产生负面影响， 可能会妨碍您部署应用重复事件可能会导致 指标值不正确。

为每种类型的事件添加至少 100 个唯一身份用户伪 ID 提取的内容

这可确保媒体推荐应用有足够的数据来生成高质量的结果。

用户伪 ID 的格式在事件导入或事件记录以及媒体推荐请求中必须完全相同。

使用一致的用户伪 ID 格式有助于媒体 推荐应用正确识别访问者的模式 根据用户行为获取更优质的结果。

所有文档都必须包含 DocumentInfo.name 字段或 DocumentInfo.id 字段。

如果文档没有 DocumentInfo.name 字段或 DocumentInfo.id 字段，则媒体推荐应用无法使用包含这些文档的事件。

事件中包含的文档应存在于您的数据存储区中。

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

某些用户事件应具有相同的用户伪 ID。

为了构建有效的行为序列历史记录，媒体推荐应用必须能够看到具有相同用户伪 ID 的多个事件。

例如，visitor123 查看了 5 项内容，并点击了 2 项内容的“播放”。如果这些事件提供的用户伪 ID 格式一致且相同，媒体推荐应用便可以在其结果中考虑该行为序列。

view-item

每个事件只包含一个文档。

如果不存在文档，则无法使用该事件。如果有多个文件 则事件格式错误，无法使用。

media-play

每个活动只能包含一个文档。

如果包含多个文档，则事件格式错误，无法 。

用户事件类型示例和架构

本部分介绍了 媒体推荐。

同时还提供了 JavaScript Pixel 的示例。对于 BigQuery，提供了每种类型的完整表架构。

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

请注意以下事项：

  • 只有在您运行 A/B 实验时，才需要 tagIds 字段。
  • attributionToken 字段为可选字段；它用于衡量效果。 通过媒体推荐点击生成的 search 和 view-item 事件应包含归因令牌，以便将这些事件关联回生成它们的推荐。

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

view-category-page

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

至少需要的“view-category-page”对象

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

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

JavaScript 像素

var user_event = {
  "eventType": "view-category-page",
  "userPseudoId": "user-pseudo-id",
  "eventTime": "2020-01-01T03:33:33.000001Z",
  "pageInfo": {
    "pageCategory": "category1 > category2"
  }
};

BigQuery

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

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

请注意，要导入包含以下内容的事件：eventTime BigQuery。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": "pageCategory",
        "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 用户事件数据格式。

至少需要 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"
  }]
};

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",
};

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 或 pageCategory 字段之一：

  • 对于用户输入文本查询的搜索事件，请提供 searchQuery。

  • 当用户通过浏览（即点击类别，而不是输入文本查询）找到感兴趣的内容时，提供 pageCategory。

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

JavaScript 像素

var user_event = {
  eventType: "search",
  userPseudoId: "user-pseudo-id",
  eventTime: "2020-01-01T03:33:33.000001Z",
  searchInfo: {
    searchQuery: "search-query",
  },
  pageInfo: {
    pageCategory: "category1 > category2",
  },
  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": "documents",
    "type": "RECORD",
    "mode": "REPEATED",
    "fields": [
      {
        "name": "id",
        "type": "STRING",
        "mode": "NULLABLE"
      }
    ]
  }
]

媒体播放

下面显示了 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。

请注意，要导入包含以下内容的事件：eventTime BigQuery。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 用户事件格式的必填字段。

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": 1.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 像素导入事件时，您必须按照 RFC 3339 指定的格式在 eventTime 字段中提供时间戳。

后续步骤