这是仅与 Recommendations AI 相关的文档。如需在受限 GA 阶段试用 Retail Search 和统一 Retail 控制台,请与 Cloud 销售人员联系如果您不打算使用 Retail Search,请保留在 Recommendations 控制台上,直到收到进一步的通知。

如果您使用的是 v1beta 版 Recommendations AI,请迁移到 Retail API 版本

记录实时用户事件

本页面介绍了如何记录实时用户事件。Recommendations AI 利用实时用户事件生成下一项推荐。记录尽可能多的用户事件类型和有效的产品信息可以提高推荐质量。

如需详细了解用户事件(包括所有类型的用户事件类型和示例 JSON),请参阅用户事件

您可以通过多种方式记录用户事件:

您可以在以下所有方法中找到记录 detail-page-view 类型的用户事件的示例。对于其他事件类型,请参阅用户事件

您还可以导入历史用户事件。可能需要相当长的时间才能记录足够的用户事件数据来训练模型。您可以通过从过去的事件中批量导入用户事件数据来加速初始模型训练。请参阅导入历史用户事件

如果您要记录的用户事件是用户第一次根据先前提供的建议与产品互动的,包括可启用 Recommendations AI 提供推荐效果指标的归因令牌,该归因令牌是可选的。如需了解如何使用归因令牌,请参阅归因令牌

如需详细了解 userInfo 字段,请参阅关于用户信息对象

准备工作

在记录用户事件前,您应该:

  • 创建了一个 Google Cloud 项目并设置了身份验证。

  • 有效的 API 密钥(用于 JavaScript Pixel 或跟踪代码管理器),或者有效的服务帐号(如果使用 API 直接编写,则分配 Retail Editor 角色)。

    如需了解更多信息,请参阅准备工作

记录用户事件的最佳做法

Recommendations AI 需要使用高品质数据进行高品质的预测。如果数据不完整或不正确,则预测质量将受到影响。

记录用户事件时,请确保实现以下最佳做法:

  • 如果您在导入目录之前或导入目录时记录用户事件,请在目录导入完成之前重新联接记录的任何事件

    您可以在记录用户事件之前、之后或同时导入目录到 Recommendations AI 中。如果目录很大并且有大量用户事件,则并行执行这些任务可以节省时间。目录导入完成后,您必须使用 API 重新联接在导入完成之前上传的事件。

    创建用户事件时,Recommendations AI 会尝试将记录的用户事件与商品清单中的元数据联接。只有成功联接的事件将用于训练,因此请确保重新联接在完全导入目录之前记录的所有事件。如果事件所引用的项在目录中不存在,系统会舍弃该项,或不能将其与正确的产品相关联。同样,如果您从过去导入用户事件,则该目录必须包含其引用的所有产品;您可以将较旧的产品标记为 OUT_OF_STOCK,而不是从目录中将其移除。

  • 使目录保持最新状态

    当您记录用户事件时,用户事件中包含的目录项将与当前目录相关联。如果您为当前目录之外的目录项记录事件,则 Recommendations AI 不会使用它来训练模型。此类事件称为“未联接”事件。如果您在目录完全导入之前记录事件,则必须重新联接导入期间记录的事件。预计会有一些未联接的事件。但是,如果未联接事件的百分比达到用户事件总数的 5% 或更多,请确保您的目录为最新状态,重新联接目录完全更新之前记录的事件,以及调查用户创建未联接的事件的原因。

    您可以使用事件过滤条件查看未联接的事件。了解详情

  • 请务必提供尽可能多的用户事件信息。

    每种用户事件类型所需和所接受的信息各不相同。如需了解详情,请参阅用户事件

  • 设置提醒,以便了解用户事件记录进程是否遇到了服务中断的情况。

  • 对于批量用户事件导入,请限制您要导入的数据大小。

    批量用户事件导入最多可能需要 24 小时才能完成。

    每个文件的大小不得超过 2 GB。您最多可以在一次导入请求中包含 100 个文件。一种方法是一次只导入一天的用户事件。

  • 批量导入后,请查看错误报告,以确保您的数据已正确导入。

  • 导入用户事件数据时,为每个用户事件添加准确的时间戳,并避免导入时间戳相同的连续用户事件。

    按照 RFC 3339 指定的格式,在 eventTime 字段中提供时间戳。

  • 如果您导入的用户事件不正确,请与您的 Recommendations AI 联系人联系,了解如何更正该问题。

  • 请尽可能保证用户事件数据连续。

    用户事件数据缺口会降低模型质量。

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

使用 JavaScript 像素记录用户事件

以下示例使用 JavaScript 像素记录 detail-page-view UserEvent

<script type="text/javascript">
var user_event = {
  "eventType" : "detail-page-view",
  "visitorId": "visitor-id",
  "userInfo": {
      "userId": "user-id"
  },
  "attributionToken": "attribution-token",
  "experimentIds": "experiment-id",
  "productDetails": [
      {
        "product": {"id": "123"}
      }
  ]
};

var _gre = _gre || [];
// Credentials for project.
_gre.push(['apiKey', 'api-key']);
_gre.push(['logEvent', user_event]);
_gre.push(['projectId', 'project-id']);
_gre.push(['locationId', 'global']);
_gre.push(['catalogId', 'default_catalog']);

(function() {
  var gre = document.createElement('script'); gre.type = 'text/javascript'; gre.async = true;
  gre.src = 'https://www.gstatic.com/retail/v2_event.js';
  var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(gre, s);
})();

</script>

如果您使用 Google Analytics 360 导入用户事件,请将 visitorID 设置为 Google Analytics(分析)客户端 ID。请注意,Google Analytics(分析)客户端 ID 仅是完整 _ga Cookie 名称的一部分(例如,客户端 ID 123456789.123456789 是 _ga Cookie GA1.3.123456789.123456789 的一部分)。

如需详细了解如何获取客户端 ID,请参阅 Google Analytics(分析)文档

以下是一个缩略的示例,其中包含在用户事件中设置客户端 ID 的格式。将“UA-XXXXXX-N”替换为您的 Google Analytics(分析)跟踪 ID

<script type="text/javascript">
var tracker = ga.getByName('UA-XXXXXX-N');
var user_event = {
      "visitorId": tracker.get('clientId')
};
</script>

使用 userEvents.write 方法记录用户事件

您可以使用 userEvents.write 方法从后端服务器直接将用户事件发送到 API。

如要记录用户事件,请向 userEvents.write 方法发送 POST 请求,并提供相应的请求正文。

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     --data "{
         'eventType': 'detail-page-view',
         'visitorId': 'visitor0',
         'eventTime': '2020-01-01T03:33:33.000001Z',
         'experimentIds': '['321'],
         'attributionToken': 'ABC',
         'attributes': {
            'example_text_attribute': {
              'text': ['text_1', 'text_2']
            },
            'example_number_attribute': {
               'numbers': [3.14, 42, 1.2345]
            }
         },
         'productDetails': [{
           'product': {
             'id': 'abc'
           }
          }],
         'userInfo': {
           'userId': 'abc@example.com',
           'ipAddress': '8.8.8.8',
           'userAgent': 'Mozilla/5.0',
           'directUserRequest': true
         },
         'uri': 'http://example',
         'referrerUri': 'http://example',
         'pageViewId': 'currentPageUri'
}"
"https://retail.googleapis.com/v2/projects/[PROJECT_ID]/locations/global/catalogs/default_catalog/userEvents:write"

使用 Google 跟踪代码管理器记录用户事件

通过使用跟踪代码管理器,可以管理和测试多个代码,而不需要对您的网站更改很多服务器端代码。

在设置过程中做出的一些决策取决于您使用的是 Google Analytics(分析)还是增强型电子商务。两者均非必需;如果您不使用电子商务,则可以在创建 Cloud Retail 代码时配置电子商务变量,或者在创建代码后手动填充网站的数据层代码。

增强型电子商务是 Google Analytics(分析)的一项额外配置,可将产品名称、ID、价格、交易详情和其他结构化电子商务数据传递给 Google Analytics(分析)。 Recommendations AI 可以自动使用增强型电子商务数据层,因此如果您已设置增强型电子商务图层,配置过程会更加简单。如果您没有为 Google Analytics(分析)配置增强型电子商务,但希望使用该功能,请参阅增强型电子商务开发者指南以了解更多详情和设置说明。

使用一次性过程,在跟踪代码管理器中设置 Cloud Retail 代码以记录用户事件。

创建 Google 跟踪代码管理器代码

在跟踪代码管理器中设置代码,以便将用户事件信息发送到 Retail API。

  1. 登录跟踪代码管理器,然后选择您网站的容器。

  2. 转到代码标签页,然后点击新建以添加新代码。

  3. 在面板顶部为您的代码命名(占位符是未命名变量),例如“Recommendations AI”。

  4. 点击代码配置,然后选择 Cloud Retail 标记以打开代码配置面板。

  5. 输入您的 API 密钥。

    使用您在设置 Recommendations AI 时创建的密钥

    API 密钥可从 Cloud Console 中的 API 和服务 > 凭据页面获得。请勿使用您向 Recommendations AI 注册的任何 API 密钥进行预测调用

  6. 输入启用了 Recommendations AI 的 Google Cloud 项目的项目编号。

    项目编号可从 Cloud Console 信息中心获取。

  7. 对于用户事件数据源字段:

    • 电子商务数据层:如果您通过跟踪代码管理器实现了增强型电子商务,请选择此类型。这样一来,您就可以将增强型电子商务数据层用作事件数据源,而无需填充新的数据源。

      您只能通过此数据源记录 add-to-cartpurchase-completedetail-page-view 事件。

    • Cloud Retail 数据层:如果您未使用 Google Analytics(分析)且可以手动填充数据层代码,请选择。请参阅跟踪代码管理器开发者指南

    • Cloud Retail 用户变量:选择用 Recommendations AI 的必填字段填充跟踪代码管理器变量。如果您未使用增强型电子商务,或者增强型电子商务没有 Recommendations AI 所需的数据,则可以选择此选项。

    • 电子商务变量:如果您的数据层中不使用增强型电子商务且无法手动填充数据层代码,请选择此选项。

      在出现的从用户变量中读取电子商务数据字段中,选择一个变量。这样一来,Recommendations AI 便可从您创建的自定义变量中读取增强型电子商务用户事件数据。

      该变量应该与增强型电子商务开发者指南中记录的格式一致。如要用正确的格式构建变量,您可以使用增强型电子商务对象构建器跟踪代码管理器社区模板库中的自定义变量模板。社区模板并非由 Google 维护。如要使用此模板,请参阅增强型电子商务对象构建器图库页面,查看文档和其他资源。

  8. 点击保存

    Cloud Retail 标记已创建。

接下来,为标记创建事件触发器

为您的跟踪代码管理器代码创建事件触发器

为 Recommendations AI 模型将使用的所有用户事件创建触发器。

跟踪代码管理器代码必须具有触发器,以控制何时应在网站上“触发”代码。触发器会在事件发生时(例如,用户查看首页或向购物车添加商品)侦听,并提示您的代码将该用户事件信息发送到 Retail API。

跟踪代码管理器提供了一些标准触发器。例如,窗口已加载detail-page-view 事件的触发器。如需详细了解每种类型,请参阅跟踪代码管理器文档中的触发器类型

您通常将代码设置为当用户查看任何具有 Recommendations AI 所需的事件(例如首页、商品详情页面、购物车页面或结帐完成页)时触发的网页。在这种情况下,该代码应在网页加载完毕后触发,以便 Cookie 可用,并填充所有数据层变量。为此,请将触发器设置为在 Window LoadedDOM Ready 时触发。

您可能需要在执行操作时(而不是在网页加载时触发)触发代码(例如,当用户将商品添加到购物车时不会强制页面重新加载)。在这些情况下,您可以配置网站上的点击操作,以便同时将更新推送到数据层,并将触发器与该操作相关联。

例如,如果您为 add-to-cart 事件创建了触发器,则可以将触发器类型选择为点击 - 仅限链接,并将其设置为在点击 ID 触发(在在此示例中为 addtocart)。然后,您需要配置自己网站上的 addtocart 链接,以在用户点击数据层时将其更新为新值:

  <a id="addtocart" href="javascript:void(0);"
         onclick="dataLayer.push({
                  'cloud_retail': {
                  'eventType': 'add-to-cart',
                  'visitorId': '456',
                  'cartId': 'mobile',
                  'productDetails': [{
                  'product': {
                  'id': '54321'
                  },
                  'quantity': 1
                  }]}});">Add to Cart</a>

对于某些用户事件,您必须创建自定义触发器。一般来说,您可以使用用户事件名称在跟踪代码管理器中创建自定义触发器。如果您无法修改前端代码,则可以使用 JavaScript 宏创建一个自定义触发器。如需详细了解自定义触发器,请参阅自定义事件触发器

如需在跟踪代码管理器中创建触发器,请按以下步骤操作:

为您的跟踪代码管理器代码创建新触发器

如果您不使用增强型电子商务,请为 Recommendations AI 模型所需的任何用户事件创建新的事件触发器。然后,将新触发器与您在跟踪代码管理器中创建的 Cloud Retail 代码相关联。

在开始执行以下步骤之前,请确保您已在跟踪代码管理器中创建了 Cloud Retail 代码。请参阅创建跟踪代码管理器代码

首先,创建触发器。对 Recommendations AI 模型需要的所有用户事件重复此过程:

  1. 跟踪代码管理器触发器页面上,点击新建 > 触发器配置

  2. 选择您要为其创建触发器的用户事件适用的触发器类型

  3. 保存触发器。

接下来,将新触发器与 Cloud Retail 标记相关联。此过程是一次性的:

  1. 跟踪代码管理器代码页面上,点击您的 Cloud Retail 代码以进行修改。

  2. 点击触发条件,选择新的触发器,然后点击添加

  3. 保存代码。

接下来,设置一个变量,将 Recommendations AI visitorId 字段设置为用户会话 ID。

重复使用增强型电子商务触发器

如果您已通过跟踪代码管理器实现增强型电子商务,则可以重复使用 Recommendations AI 的增强型电子商务中的事件触发器。

您只能通过此数据源记录 add-to-cartpurchase-completedetail-page-view 事件。

在开始这些步骤之前,请确保已经执行了以下操作:

  • 在代码类型为 Google Analytics - Universal Analytics 的跟踪代码管理器中设置代码,并为其启用了增强型电子商务。如需了解详情,请参阅跟踪代码管理器文档增强型电子商务开发者指南
  • 在跟踪代码管理器中配置您的增强型电子商务代码,以触发您计划为 Recommendations AI 记录的用户事件。
  • 在跟踪代码管理器中创建了 Cloud Retail 代码,并将增强型电子商务作为用户事件数据源(请参阅创建跟踪代码管理器代码)。

如要重复使用增强型电子商务触发器,请执行以下操作:

  1. 跟踪代码管理器代码页面上点击您的增强型电子商务代码(代码类型 Google Analytics(分析)- Universal Analytics)以进行修改。

  2. 高级设置>代码触发顺序下,选择在<增强型电子商务代码名称> 触发后触发代码。

  3. 选择 Cloud Retail 标记作为 Cleanup Tag

    选择如果 <增强型电子商务代码名称> 失败或已暂停,则不触发 <Cloud Retail 代码名称>。

  4. 保存代码。

如要完成代码设置,请使用跟踪代码管理器中的变量覆盖 visitorID 字段,以便 Recommendations AI 可以使用会话 ID 跟踪用户。

在跟踪代码管理器中设置 visitorID 字段

Recommendations AI 使用值 visitorId 跟踪用户。visitorId 通常是会话 ID,所有事件都需要此参数。设置将会话 ID 设置为 visitorId 的变量。

如果您使用的是 Google Analytics,则可以使用 Google Analytics 访问者 ID。如需进行此项配置,请按照以下步骤替换 Cloud Retail 标记的访问者 ID 值。这会将第一方 Cookie“_ga”映射到一个名为“GA visitorId”的跟踪代码管理器变量。您可以对任何会话 ID Cookie 执行相同的操作;就不必来自 Google Analytics。

此过程假设您正在使用 Google Analytics(分析)。否则,您可以使用其他 Cookie 或变量,或者从 cloud_retail 数据层获取访问者 ID。

开始执行以下步骤之前,请确保您已在跟踪代码管理器中创建了 Cloud Retail 代码(请参阅创建 Google 跟踪代码管理器代码)。

如需将 visitorID 值设置为 Cloud Retail 标记的变量,请执行以下操作:

  1. 跟踪代码管理器中,转到变量标签页,然后点击新建创建新用户定义的变量。

  2. 在对话框的顶部为变量命名,例如“GA visitorId”。

  3. 输入您的变量设置:

    Google Analytics 360

    1. 变量类型设置为自定义 JavaScript

    2. 自定义 JavaScript 字段中输入以下脚本。

      将“UA-XXXXXX-N”替换为您的 Google Analytics(分析)跟踪 ID。如要查找您的跟踪 ID,请参阅我的跟踪 ID 怎么了? 如需详细了解如何获取客户端 ID,请参阅 Google Analytics(分析)文档

      function() {
       var tracker = ga.getByName('UA-XXXXXX-N');
       return tracker.get('clientID');
      }
      
    3. 点击保存保存变量。

    Google Analytics(分析)

    1. 选择第一方 Cookie 作为变量类型。

    2. Cookie 名称字段中,输入 _ga

    3. 点击 Format Value,选择 Convert undefined to..,然后输入 ""(空字符串)。

    4. 点击保存保存变量。

      这会将第一方 Cookie“_ga”映射到一个名为“GA visitorId”的跟踪代码管理器变量。

  4. 转到代码标签页,然后点击您的 Cloud Retail 标签页进行修改。

  5. 点击代码配置,然后在“字段”下点击 + 覆盖 UserEvent 消息中的值按钮。

  6. 选择 visitorId 作为字段,选择您刚刚创建的变量作为字段值。

  7. 保存 Cloud Retail 标记。

接下来,预览代码,并设置事件记录错误的监控及其他问题,以确保 Recommendations AI 持续成功接收数据。

如果您使用 cloud_retail 数据层作为用户事件来源,请务必同时设置数据层

在跟踪代码管理器中使用 cloud_retail 数据层

如果您在跟踪代码管理器中创建了 Cloud Retail 代码,以使用 cloud_retail 数据层作为用户事件来源,请按照跟踪代码管理器开发者指南所述在源 HTML 中设置 dataLayer 变量。

数据层简介

大多数跟踪代码管理器代码都需要根据用户或网页变化的数据(例如用户 ID 或产品 ID)。对于 Cloud Retail 标记,必须通过数据层以结构化方式公开该数据,以便跟踪代码管理器可以使用它。

数据层是一种 JavaScript 对象,通常使用服务器端代码或者通过 HTML 或模板在前端添加到网页中。如果页面配置了数据层,则会包含如下代码:

dataLayer = dataLayer || [];
dataLayer.push({
  'cloud_retail': {
    'eventType': 'home-page-view',
    'visitorId': 'visitor_a',

    'userInfo': {
      'userId': '789'
    },
  }
});

此代码会创建一个 dataLayer 对象并将其分配给 cloud_retail 结构作为数组元素。

cloud_retail 数据层中的必填字段

用户事件列出了应传递给 cloud_retail 数据层的事件类型的所有必填字段和示例。

您的服务器端代码或模板应在您要从中发送事件的每个页面上包含正确的脚本标记。在每个页面上正确填充 dataLayer 对象后,您应该能够测试 Cloud Retail 标记。

UserEvent 消息需要使用某些字段(如 visitorId),但在填充数据层时可能无法使用。例如,visitorId 可能派生自用户的 Cookie,或 experimentIds 来自 A/B 实验框架。在这种情况下,请使用变量覆盖跟踪代码管理器代码中的字段。

您可以覆盖以下字段:

  • visitorId
  • userInfo.userId
  • attributionToken
  • experimentIds

如需了解如何在跟踪代码管理器中覆盖 UserEvent 字段,请参阅在跟踪代码管理器中设置 visitorID 字段visitorID,该过程逐步介绍了如何使用用户定义的变量覆盖 visitorId 字段值。

以下示例显示了使用跟踪代码管理器的 detail-page-view UserEvent 页面需要包含的数据层:

<script>
  dataLayer = dataLayer || [];
  dataLayer.push({
    'cloud_retail': {
      'eventType' : 'detail-page-view',
      'visitorId': 'visitor_a',
      'userInfo': {
          // The user and visitor ID fields can typically be
          // be populated from a client-side JavaScript
          // variable such as a cookie. If you set the user
          // and/or visitor ID values from the server,
          // populate the `userID`.
          'userId': 'user_a'
      },
      'attributionToken': 'attribution-token',
      // In most cases, the experiment ID field is populated from a
      // client side JavaScript variable as defined by the experiment
      // manager.
      // If you set the experiment ID value from the server,
      // populate the `experimentIds` field here.
      'productDetails': [
            {
              'product': {'id': '123'}
            }
      ],
    // You can use the 'cloud_retail' data layer element along with other
    // data layer elements.
    'ecommerce': {
      ...
    },
  }];
</script>

预览跟踪代码管理器标记

利用跟踪代码管理器的预览模式,您可以在将新代码发布到实际网站之前对其进行测试。

如需详细了解预览模式,请参阅预览模式的跟踪代码管理器文档。

请按以下步骤确认您的代码是否正确触发。

  1. 在跟踪代码管理器概览页面上,点击预览

    跟踪代码管理器的预览模式会在新的浏览器标签页中打开。

  2. 输入您的网站信息,然后点击开始启动 Tag Assistant。

    在当前浏览器标签页中,Tag Assistant 将启动,您的网站将在新标签页中打开。

  3. 在您的网站上,访问应触发 Cloud Retail 代码的任何页面。

  4. 确认 Tag Assistant 在代码部分中的代码标签页中列出了 Cloud Retail 代码。

  5. 在 Tag Assistant 中,转到数据层标签页,然后检查 cloud_retail 或电子商务数据层中显示的正确值。

检查代码错误

在预览代码时,如果某些字段不正确或缺失,代码通常会返回错误,除非根本没有触发。

您可以检查 Google Cloud Console 中的错误页面,看看是否存在错误。此页面会记录大多数错误,但语法错误通常只出现在请求结果中。

您可以按照以下步骤使用 Chrome DevTools 检查生成的错误,包括语法错误。

  1. 在 Chrome 浏览器中为您的网站在代码管理器中打开预览模式,然后访问应触发 Cloud Retail 代码的任何页面。

  2. 打开预览模式后,打开 DevTools 并点击网络标签页。

  3. 重新加载页面。

  4. 在 DevTools 中,搜索 userEvent

    “网络”标签页会显示 userEvent:collect 事件及其状态代码。

    • 200 响应表明您的代码处于良好状态。
    • 如果返回其他响应(例如 400 错误并用红色突出显示事件),则表示需要调试。
  5. 双击事件名称以执行请求,并显示包含更多错误信息的完整响应。

    例如,您可能会看到一条 400 错误,其中包含消息“'visitorId' is required, and cannot be empty”,表明 visitorId 未正确设置。

  6. 如果没有触发 userEvent,请查看 DevTools 的控制台标签页,了解数据层中的语法错误。

监控导入运行状况

成功记录用户事件对于获得高质量推荐非常重要。您应该监控事件记录错误率,并在必要时采取措施。如需了解详情,请参阅为数据上传问题设置提醒

后续步骤