自定义应用的用户事件简介

本页面介绍了自定义搜索和推荐应用的用户事件，包括用户事件类型、要求和用户事件类型示例。

虽然自定义应用不需要用户事件，但我们强烈建议您使用。

Google 建议您至少每天上传一次事件，以保持良好的数据质量。在导入历史事件时，请确保数据分布偏向最近的时间戳。最后一个时间戳日期的事件数应等于或大于每日平均事件数。

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

用户事件类型

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

用户事件名称 用户操作
view-item-list 查看面板或有序的文档列表。
view-item 查看文档的详细信息。
view-home-page 查看首页。
search 搜索应用。

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

用户事件类型示例和架构

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

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

请注意：

  • 只有在您运行 A/B 实验时，才需要 tagIds 字段。

  • attributionToken 字段为可选字段；它用于衡量效果。从推荐点击生成的 search 和 view-item 事件应包含归因令牌，以便将事件关联回生成这些事件的推荐。

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

view-item

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

view-item 事件的搜索优化要求

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

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

事件指标 事件数量/频率 说明
view-item 事件的数量 25 万个查看项

为了根据注入的事件优化搜索体验，必须至少有 25 万个查看项。

至少需要 view-item 对象

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

documents 对象包含文档的 ID (id) 及其资源 名称 (name)。

  • 当您在数据存储区级别注入或记录用户事件时，可以提供 文档的 ID (id) 或资源名称 (name)。
  • 当您在位置级别注入或记录事件时，必须提供 文档的资源名称 (name)，因为它表示文档的完整路径 并引用文档所在的数据存储区。您可以提供 文档的 ID 作为可选的附加信息。

JavaScript 像素

var user_event = {
  "eventType": "view-item",
  "userPseudoId": "USER_PSEUDO_ID",
  "engine": "APP_ID",
  "eventTime": "2020-01-01T03:33:33.000001Z",
  "documents": [{
    "name": "DOCUMENT_NAME"
  }]
};

BigQuery

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

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

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

[
  {
    "name": "eventType",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "name": "userPseudoId",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "name": "engine",
    "type": "STRING",
    "mode": "NULLABLE"
  },
  {
    "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 用户事件格式的必填字段。

documents 对象包含文档的 ID (id) 及其资源 名称 (name)。

  • 当您在数据存储区级别注入或记录用户事件时，可以提供 文档的 ID (id) 或资源名称 (name)。
  • 当您在位置级别注入或记录事件时，必须提供 文档的资源名称 (name)，因为它表示文档的完整路径 并引用文档所在的数据存储区。您可以提供 文档的 ID 作为可选的附加信息。

JavaScript 像素

var user_event = {
  "eventType": "view-home-page",
  "userPseudoId": "USER_PSEUDO_ID",
  "engine": "APP_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": "engine",
    "type": "STRING",
    "mode": "NULLABLE"
  },
  {
    "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 事件的搜索优化要求

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

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

事件指标 事件数量/频率 说明
search 事件的数量 10 万次搜索

至少需要 10 万次搜索，才能根据注入的事件优化搜索体验。

至少需要 search 对象

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

至少需要 searchQuery 或 pageCategory 字段中的一个字段：

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

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

attributionToken 会随搜索查询或浏览结果一起返回。

documents 对象包含文档的 ID (id) 及其资源 名称 (name)。

  • 当您在数据存储区级别注入或记录用户事件时，可以提供 文档的 ID (id) 或资源名称 (name)。
  • 当您在位置级别注入或记录事件时，必须提供 文档的资源名称 (name)，因为它表示文档的完整路径 并引用文档所在的数据存储区。您可以提供 文档的 ID 作为可选的附加信息。

JavaScript 像素

var user_event = {
  "eventType": "search",
  "userPseudoId": "USER_PSEUDO_ID",
  "engine": "APP_ID",
  "eventTime": "2020-01-01T03:33:33.000001Z",
  "searchInfo": {
    "searchQuery": "SEARCH_QUERY",
  }, 
  "pageInfo": {
    "pageCategory": "CATEGORY_1 > CATEGORY_2",
  }, 
  "attributionToken": "ATTRIBUTION_TOKEN",
  "documents": [
    {
      "name": "DOCUMENT_NAME_1",
    },
    {
      "name": "DOCUMENT_NAME_2",
    },
  ]
};

BigQuery

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

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

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

[
  {
    "name": "eventType",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "name": "userPseudoId",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "name": "engine",
    "type": "STRING",
    "mode": "NULLABLE"
  },
  {
    "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"
      }
    ]
  }
]

关于用户信息

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

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

关于时间戳

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

后续步骤