这是 Recommendations AI、Retail Search 和新的 Retail 控制台的文档。如需在受限 GA 阶段使用 Retail Search,请与 Cloud 销售人员联系

如果您仅使用 Recommendations AI,请保留在 Recommendations 控制台上并参阅 Recommendations AI 文档

记录实时用户事件

本页面介绍了如何记录实时用户事件。Retail API 使用实时用户事件来生成推荐内容和搜索结果。记录尽可能多的用户事件类型和有效的产品信息可以提高结果的质量。

本页面上的记录过程适用于 Recommendations AI 和 Retail Search。将数据记录到 Retail API 后,这两项服务都可以使用这些事件,因此,如果同时使用这两项服务,则无需上传两次相同的数据。

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

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

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

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

如果您要记录的用户事件是用户第一次根据先前提供的建议或搜索结果与产品互动,包括可启用 Retail API 的归因令牌性能指标。添加归因令牌并非强制要求,但我们强烈建议您这样做。如需了解如何使用归因令牌,请参阅归因令牌

如需详细了解访问者 ID 和用户 ID,请参阅用户信息简介字段。

准备工作

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

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

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

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

记录用户事件的最佳做法

Retail API 需要使用高品质数据生成高质量的结果。如果数据不完整或不正确,则结果质量将受到影响。

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

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

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

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

  • 使目录保持最新状态

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

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

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

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

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

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

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

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

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

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

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

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

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

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

  • 使用唯一标识符的安全形式,让用户对 Retail 保持匿名并保护用户的隐私。您需要负责从数据中隐去个人身份信息 (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

export GOOGLE_APPLICATION_CREDENTIALS=/tmp/my-key.json
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',
           '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"

Java

public static UserEvent writeUserEvents(UserEvent eventToWrite)
    throws IOException, InterruptedException {
  UserEventServiceClient userEventsClient = getUserEventServiceClient();

  WriteUserEventRequest request = WriteUserEventRequest.newBuilder()
      .setParent(DEFAULT_CATALOG_NAME)
      .setUserEvent(eventToWrite)
      .build();

  UserEvent writtenUserEvent = userEventsClient.writeUserEvent(request);

  userEventsClient.shutdownNow();
  userEventsClient.awaitTermination(2, TimeUnit.SECONDS);

  return writtenUserEvent;
}

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

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

在设置过程中做出的一些决策取决于您使用的是 Google Analytics(分析)还是 Google Analytics(分析)电子商务。您可以使用 Google Analytics(分析)4 或增强型电子商务实现 Google Analytics(分析)电子商务。Cloud Retail 标记同时支持这两者。

不需要 Google Analytics(分析)和 Google Analytics(分析)电子商务;如果您不使用它们,则可以在创建 Cloud Retail 代码时配置变量 - 电子商务,也可以在创建代码后手动填充网站的数据层代码。

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

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

创建访问者 ID 变量

Retail API 使用值 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。

如需将 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”的跟踪代码管理器变量。

接下来,在跟踪代码管理器中创建 Cloud Retail 代码。此代码将使用您刚刚创建的访问者 ID 变量。

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

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

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

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

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

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

  5. 输入您的 API 密钥。

    请使用您创建的密钥来设置 Retail API。

    API 密钥可从 Cloud Console 中的 API 和服务 > 凭据页面获得。

  6. 输入启用了 Retail API 的 Google Cloud 项目的项目编号。

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

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

    • 数据层(推荐):如果您的实现将是以下其中一项,请选择此类型:

      • 您已通过跟踪代码管理器实现 Google Analytics(分析)电子商务。将数据层重复用作事件数据源,而不是填充新的数据源。它使用 Google Analytics(分析)4 架构(如果存在)。否则,它会使用 UA 增强型电子商务。使用此数据源时,您只能记录 add-to-cartpurchase-completedetail-page-viewsearch 事件。search 事件是结合使用电子商务展示和搜索查询来记录的(请参阅创建搜索查询变量)。

      • 您使用的是 Google Analytics(分析)电子商务,并且可以手动填充数据层代码。请参阅跟踪代码管理器开发者指南

    • 变量 - Cloud Retail:选择用 Retail 的必填字段填充跟踪代码管理器变量。如果您未使用 Google Analytics(分析)电子商务,或者 Google Analytics(分析)电子商务没有 Retail 所需的数据,则可以选择此选项。如果您要从旧版“数据层 - Cloud Retail”选项切换到此来源,请同时创建一个带有键 cloud_retail数据层变量,并将它与此 变量 - Cloud Retail 选项相关联。

    • 变量 - 电子商务:如果您的数据层中不使用 Google Analytics(分析)电子商务,并且无法手动填充数据层代码,请选择此选项。

      在出现的从用户变量中读取电子商务数据字段中,选择一个变量。这样一来,Retail API 便可从您创建的自定义变量中读取 Google Analytics(分析)电子商务用户事件数据。

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

  8. 点击 + 覆盖 UserEvent 消息中的值按钮。

  9. 对于字段选择器,选择 visitorId 作为字段,对于字段值,选择您在创建访问者 ID 变量中创建的新访问者 ID 变量。

  10. 点击保存

    Cloud Retail 标记已创建。

旧版数据源选项

以前,数据层 - 电子商务数据层 - Cloud Retail 作为数据源选项提供。新代码中不提供这些旧版选项。如果您将现有代码切换到新的数据源,请在部署前使用跟踪代码管理器预览代码以验证它。切换时:

  • 如果您使用数据层 - 电子商务,则可以切换到数据层。它使用 Google Analytics(分析)4 架构(如果存在)。否则,它会使用 UA 增强型电子商务。

  • 如果您使用的是数据层 - Cloud Retail,请切换到变量 - Cloud Retail 选项。创建带有键 cloud_retail数据层变量,并使它与变量 - Cloud Retail 选项相关联。

下一步:

创建搜索查询变量

如果您使用的是 Retail Search,则可以在跟踪代码管理器中为搜索查询创建变量,并将其附加到您的 Cloud Retail 代码。这允许 Retail API 从 Analytics(分析)获取搜索查询。

您创建的变量类型取决于您的用户事件数据源。

  • 变量 - 电子商务,或具有 Google Analytics(分析)电子商务架构的数据层:在跟踪代码管理器中创建网址或 DOM 元素变量并将其附加到您的 Cloud Retail 代码。此外,请为代码启用选项以使用 Google Analytics(分析)电子商务展示构建搜索事件。
  • 变量 - Cloud Retail 或手动填充的数据层:在跟踪代码管理器中创建网址或 DOM 元素变量并将其附加到您的 Cloud Retail 代码。为了让 Retail API 确定用户事件类型是否为 search,您还必须执行以下任一操作:
    • 为搜索事件类型创建常量类型变量并将其附加到代码。
    • 在数据层或 Cloud Retail 变量中设置搜索事件类型。

创建并附加网址或 DOM 元素变量

如果您使用 Retail Search,则可以创建一个网址或 DOM 元素变量,该变量将填入您网站上输入的搜索查询。

作为此过程的替代方案,您可以配置数据层以提供搜索查询信息。但是,如果您无法访问数据层,或者不想配置数据层,则可以选择使用跟踪代码管理器变量。

您可以创建网址类型变量或 DOM 元素类型变量。创建的类型及其配置方式取决于网站的实现方式:

  • 网址变量会从网站的搜索结果网址中获取搜索查询。如果您的网站在搜索结果的网址中包含查询字符串,请使用此变量。
  • DOM 元素变量会从网站的文档对象模型 (DOM) 获取搜索查询信息。您无需修改 DOM 即可使用此变量。但是,您应该能够阅读和理解 DOM,以便正确配置此变量。

首先,创建一个网址或 DOM 元素类型变量:

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

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

  3. 输入您的变量设置:

    网址类型

    1. 变量类型设置为网址

    2. 组件类型设置为查询

    3. 如果您指定查询键,请将其设置为网址中位于搜索查询前面的键。

      例如,如果网址为 http://example.com/?q=shoes,则查询键为 q。在此示例中,变量的值将设置为 shoes

    DOM 元素类型

    1. 变量类型设置为 DOM 元素

    2. 设置选择方法,并输入搜索查询的元素 ID 或元素选择器。

      此设置取决于网站是使用元素 ID 还是 CSS 选择器来识别搜索查询。

    3. 如果您指定属性,请将其设置为包含搜索查询字词的属性。

      例如,如果 DOM 中的搜索查询为 <id="search" value="shoes">,则属性为 value。在此示例中,变量的值将设置为 shoes

  4. 点击保存保存变量。

接下来,将变量附加到您的 Cloud Retail 代码:

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

  2. 如果代码的用户事件数据源是变量 - 电子商务或者您将数据层与 Google Analytics(分析)电子商务架构结合使用,请选中使用增强型电子商务展示构建搜索事件复选框。

    这样一来,Retail API 便可根据从该代码中获得的搜索数据,确定用户事件类型是否为 search

  3. 用户事件数据部分,点击 + 覆盖 UserEvent 消息中的值按钮。

  4. 字段选择器中选择 searchQuery,并将搜索查询变量设置为字段值

  5. 保存代码。

下一步:

创建并附加常量变量

如果您选择变量 - Cloud Retail 或手动填充的数据层作为 Cloud Retail 代码的用户事件来源,则可以使用此过程。

为搜索事件创建常量类型变量并将其设置为 Cloud Retail 代码上的用户事件替换,使 Retail API 能够确定用户事件的类型为 search

作为此过程的替代方案,您可以通过用作代码的事件来源的数据层或 Cloud Retail 变量来指定 search 用户事件类型。否则,请按照以下步骤设置事件类型。

首先,创建一个常量类型变量:

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

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

  3. 变量类型设置为常量

  4. 字段中输入 search

  5. 点击保存保存变量。

接下来,将变量附加到您的 Cloud Retail 代码:

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

  2. 用户事件数据部分,点击 + 覆盖 UserEvent 消息中的值按钮。

  3. 字段选择器中选择 eventType,并将搜索查询变量设置为字段值

  4. 保存代码。

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

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

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

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

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

您通常将代码设置为当用户查看任何具有 Retail 所需的事件(例如首页、商品详情页面、购物车页面或结帐完成页)时触发的网页。在这种情况下,该代码应在网页加载完毕后触发,以便 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 宏创建一个自定义触发器。如需详细了解自定义触发器,请参阅自定义事件触发器

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

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

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

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

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

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

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

  3. 保存触发器。

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

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

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

  3. 保存代码。

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

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

重复使用 Google Analytics(分析)电子商务触发器

如果您已通过跟踪代码管理器实现 Google Analytics(分析)电子商务,请重复使用 Google Analytics for Retail 中的事件触发器。

使用此数据源时,您只能记录 add-to-cartpurchase-completedetail-page-viewsearch 事件。search 事件是结合使用电子商务展示和搜索查询来记录的(请参阅创建搜索查询变量)。

下表显示了 Google Analytics(分析)电子商务和增强型电子商务事件如何映射到 Retail 事件。

Google Analytics(分析)4 增强型电子商务 Retail
add_to_cart add add-to-cart
purchase purchase purchase-complete
view_item detail detail-page-view
view_item_listview_search_results impressions search(如果与字段 searchQuery 结合使用)

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

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

如要重复使用 Google Analytics(分析)电子商务触发器,请执行以下操作:

  1. 跟踪代码管理器标记页面上,点击您的 Google Analytics(分析)电子商务代码(代码类型 Google Analytics - Universal AnalyticsGoogle Analytics - GA4 Event)以编辑它。

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

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

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

  4. 保存代码。

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

如果您使用 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 中的 Monitoring 和 Analytics 页面,看看是否存在错误。此页面会记录大多数错误,但语法错误通常只出现在请求结果中。

您可以按照以下步骤使用 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 的控制台标签页,了解数据层中的语法错误。

监控导入运行状况

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

后续步骤