适用于服务器端 Google 标签管理工具 (GTM) 的转化 API

转化 API 旨在将您的营销数据与帮助在 Meta 技术方案中优化广告定位、降低单次操作费用和衡量成效的系统建立直接关联。您可以配置自己在 Google Cloud Platform (GCP) 或任何其他云服务提供商设置的服务器，以通过转化 API 发送关键网站事件和线下事件数据。借助此项设置，您在配置 Google Analytics（分析）4 (GA4) 网站标签之后，可以将该数据发送至您在 Google Cloud Platform (GCP) 上托管的自有服务器，并最终通过转化 API 发送至 Meta。

转化 API 标签由 Meta 根据 Google 自定义标签模板进行编写和维护。如果您对 Google 产品设置或 Google 开发者文档有任何疑问，请联系 Google。

本文档概述如下：

• 前提条件，包括如何创建服务器容器
• 如何配置容器，以支持您实现 GA4 网站标签
• 如何将数据从您的网站发送至您的 GCP 服务器
• 如何使用转化 API 与 Meta 分享相关数据
• 常见问题

前提条件

在继续集成之前，建议您：

1. 熟悉转化 API 集成和有关设置的最佳实践
2. 熟悉服务器端标签和自定义标签模板。

如果系统使用的版本低于 GA4，在继续集成之前，您需要升级现有标签管理工具设置，才能使用 GA4。

集成

创建 GTM 服务器容器

您需要配置服务器容器和网站容器：

• 网站容器：如果这是您第一次使用 GTM，您应先在账户上安装网站容器。详情请参阅此处。
• 服务器容器：您需要在 GTM 网站中创建服务器容器，以设置标签服务器网址。进一步了解此步骤。

设置服务器容器需要配置标签服务器。在设置服务器容器时可以完成默认 GCP 部署，请参考以下指导。对于任何其他云服务提供商（例如，AWS 或 Microsoft Azure），请参阅服务器手动设置指南。

配置网站容器和服务器容器

1. 在您的网站容器上创建以下工件：
   • GA4 配置（用于配置标签服务器网址）。
   • GA4 事件（用于配置要发送至服务器的事件架构）。
2. 在您的服务器容器上创建以下工件：
   • GA4 客户端（侦听程序，用于侦听将事件触发至 Meta 的事件）。
   • Meta 转化 API 标签（服务器端标签，可将 GA4 客户端的标准事件模型转换成转化 API 事件架构，并将其发送至 graph.facebook.com）。

第 1 步：GA4 配置 – 配置您的标签服务器网址

配置您的网站容器，以将您的网站数据发送至已创建的标签服务器。详细了解如何配置 Google Analytics（分析）：GA4 配置标签。

• 如果您选择发送到服务器容器，则将服务器容器网址设置为标签服务器网址。
• 如果您不选择发送到服务器容器，则在要设置的字段下，点击添加行，然后设置以下内容：

  • 字段名称：transport_url
  • 字段值：您的标签服务器网址

您可以为所有事件中要发送的任何其他参数配置额外字段。

• 将 first_party_collection 标记设置为 true。您必须执行此操作，才能将 user_data 参数传递至服务器端 GTM。在要设置的字段下，点击添加行，然后设置以下内容：

  • 字段名称：first_party_collection
  • 字段值：true

使用现有的 GA4 配置标签

如果您拥有已设置的现有 GA4 配置，则可修改此配置，或为服务器端 GTM 创建额外的配置标签。

如果这是您第一次设置服务器端 GTM，则当您添加服务器容器网址后，系统开始将所有流量发送至服务器容器。如果您想将数据继续发送至 GA4，则需要在服务器容器中添加 GA4 服务器端标签，确保该标签可对所有事件触发。您可能需要创建额外的 GA4 事件标签或修改现有标签，才能确保完全映射到 Meta Pixel 像素代码事件。

发送 Meta 浏览器编号和 Meta 点击编号

如果您已设置自定义域，并且 GTM 标签服务器域是第一方，则系统会自动发送 Meta 浏览器编号和 Meta 点击编号。

如果您使用提供的默认域，或发现在事件管理工具中未发送“浏览器编号”和“点击编号”字段，则可按以下操作进行配置：

• 前往变量部分，为 Meta 浏览器编号和 Meta 点击编号新建用户定义的变量。使用以下变量类型：第一方 Cookie。

  • 对于 Meta 浏览器编号，将 Cookie 名称设置为 _fbp
  • 对于 Meta 点击编号，将 Cookie 名称设置为 _fbc
• 保存这些变量。
• 在 GA4 配置标签中，点击要设置的字段下的添加行，然后设置以下内容：

  • 字段名称：x-fb-ck-fbp
  • 字段值：Meta 浏览器编号变量
• 再添加一行，以设置点击编号：
• 字段名称：x-fb-ck-fbc
• 字段值：Meta 点击编号变量

为各个 GTM 常见事件架构的 user_data 参数创建数据层变量。详细了解如何设置数据层变量。例如，如要将邮箱传递至服务器端 GTM，您需要创建一个变量（例如 user_data_email_address），此变量应能与数据层变量名称 eventModel.user_data.email_address 相映射。

如果您不使用数据层，则为要使用的每个参数（如下所示）配置变量。下方列表显示了 Meta 和 GTM user_data 参数的所有映射，以及各参数在帮助提高事件匹配质量方面的一般优先级。为充分发挥 Meta 广告的效用，建议您在设置集成时遵循转化 API 最佳实践。如果您已设置转化 API，建议考虑遵循上述最佳实践，以改善现有设置。这些转化 API 最佳实践可能会有助于降低您的单次操作费用，从而提升广告表现。

第 2 步：GA4 事件 – 配置要发送至服务器的事件架构

• 配置网站容器，以将网站数据发送至已创建的标签服务器，从而添加 Google Analytics（分析）。详细了解如何配置 Google Analytics（分析）：GA4 配置标签。

• 将 Google Analytics（分析）：GA4 事件标签从模板库添加到您的工作区：

  • 为标签设置事件名称。您可以将其设为静态值，或配置为从变量中读取。对于某些标准事件，我们将 Google Analytics（分析）标准事件映射到 Meta 对等事件。对于这类事件，您可以使用 Google Analytics（分析）事件名称或 Meta 事件名称。对于其他所有标准事件，则使用 Meta 事件名称。对于自定义事件，使用自定义事件的名称。了解详情。

• 在“事件参数”部分：

  • 如果您使用 Meta Pixel 像素代码，则添加事件编号参数。使用 event_id 作为参数名称，并使用为事件编号创建的变量作为参数值。如需创建事件编号变量和修改 Meta Pixel 像素代码的相关指导，请查看删除重复事件部分。
  • 映射要配置的每个参数。系统会使用常见事件架构来读取变量名称。例如，如要将邮箱设置为事件参数，您必须将其定义为以下参数名称：user_data.email_address；并将值设置为可读取 email_address 的变量名称（之前已在第一部分定义）。
  • 如需完整列表，请查看下文自定义数据参数部分。

第 3 步：创建侦听程序，用于侦听将事件触发至 Meta 的事件

每个 GTM 服务器端容器都默认包含 GA4 客户端，用于侦听使用其 GA4 网站标签配置的事件。GA4 客户端会侦听您标签服务器网址上的 /g/collect 路由，并将 eventModel 发送至下游标签。如果您已在“客户端”部分下的服务器容器中安装默认的 GA4 客户端，则可继续执行第 4 步。

第 4 步：创建 Meta 转化 API 标签，此服务器端标签可将标准事件模型由 GA4 客户端转换成转化 API 事件架构，并将其发送至 graph.facebook.com

如要将事件发送至转化 API，您需要从模板库中安装 Meta 转化 API 标签。标签模板被称为转化 API 标签，提供方是 facebookincubator。您可以将此标签的触发条件设置为 GA4 客户端接收事件（前一步中）以及事件被发送至转化 API。如要安装 Meta 转化 API 标签，您需要拥有 Pixel 像素代码编号和访问口令，并指定操作来源为“网站”。使用转化 API，即表示您同意：据您所知，action_source 参数准确无误。

测试集成

建议您先使用 Google 标签管理工具的预览模式测试集成，然后再发布更新。网站容器和服务器容器都有预览模式，您可同时运行这两种容器的预览模式。

您可以使用事件管理工具中的“测试事件”功能来验证服务器事件是否已按预期方式被接收。如要找到此工具，请前往事件管理工具 > 数据源 > 您的 Pixel 像素代码 > 测试事件。

测试事件工具可生成测试编号。将测试编号作为转化 API 标签中的 test_event_code 参数发送，即可开始查看“测试事件”窗口中显示的事件活动。在发布任何更新之前，请务必移除测试编号。

通过测试事件工具，您可以查看事件是否被接收，以及是否正确去重。如果一两分钟后系统未显示事件，请查看 GTM 服务器端调试工具，以确认请求是否成功：

1. 前往 GTM 服务器端调试工具，在左侧菜单中选择要查看的相关事件。
2. 确认标签是否显示在“已触发的代码”部分下。如果是，您会看到“Conversions API Tag - Succeeded”（转化 API 标签 - 成功）或“Conversions API Tag - Failed”（转化 API 标签 - 失败）。
   • 标签未触发：检查转化 API 标签触发器和网站容器上的相关 GA4 事件触发器。在网站调试工具中确认 GA4 事件是否已触发。
   • 标签已触发：成功：点击标签，并检查测试事件代码是否正确。根据需要，更新测试事件代码，然后重新开启预览模式。
   • 标签已触发：失败：打开“请求”选项卡，然后点击发送至 https://graph.facebook.com 的传出请求。查看请求详情底部的响应正文，以了解错误情况，然后适当更新集成。在做出更改后请务必重新开启预览模式。

在系统显示事件后，请验证是否正确发送各事件的事件编号，以及是否正确显示所有预期的匹配键和自定义数据参数。测试事件工具将显示是否正确删除重复事件。如果事件编号不同，请确保触发 GA4 和 Meta Pixel 像素代码标签的触发器相同，并检查事件编号变量的实现情况。

删除重复事件

我们推荐您使用冗余事件设置，分享同时来自转化 API 以及您的 Meta Pixel 像素代码的相同事件。确保两个事件都使用相同的 event_name，而且包括 event_id 或 external_id 与 fbp 参数组合。

这有助于 Meta 删除重复事件，减少相同事件的重复报告。详细了解有关删除重复事件的内容（包括何时需要删除以及如何设置）。external_id 和 fbp 是删除重复事件的替代解决方案，还可帮助提高设置质量。我们建议尽可能包含这三个参数。

在 GTM 中，您可通过多种方式在浏览器标签及服务器标签中设置包含相同值的参数。方式之一是将相同的 GA4 事件用作触发 Meta Pixel 像素代码标签和服务器事件的触发器。为此，请执行以下操作：

• 对 Meta Pixel 像素代码自定义 HTML 标签和 GA4 事件标签使用相同的触发器。例如，您可以根据订单确认页面网址定义触发器条件。
• 在两种标签中使用相同的 event_id：

  1. 在 GA 客户端中设置唯一编号：在 gtag 事件中设置自定义参数 (x-fb-event_id)。使用 Javascript 方法（或使用 Google 标签管理工具自定义 Javascript 变量）在网站上（按事件）生成一个唯一编号，并将事件中的值设置为：

  gtag('event', 'purchase', {
   'x-fb-event_id': generateEventId(),
  ...:...
  
   });

  您可以创建一个变量，以指示上方所示的自定义 Javascript。每当引用该变量时，系统就会以行的形式加载下方 Javascript：

  function() {
  var gtmData = window.google_tag_manager[{{Container ID}}].dataLayer.get('gtm');
  return gtmData.start + '.' + gtmData.uniqueEventId;
  }

  2. 创建并填入数据层变量：您可以在网站容器中创建自己的变量，以便从 event_id 中读取此值。为此，您可以新建一个数据层变量，例如 FBEventIdVar，并将其命名为 eventModel.event_id。
  3. 设置变量后，您可以将变量插入自定义 HTML 标签中的网站事件，并将其作为额外的 GA4 事件参数添加至服务器事件。
  4. 在网站上，您可以在 Google 标签管理工具网站容器中设置您的 Meta 标签，以便从变量中读取 event_id。

  fbq('track', Purchase, {..}, {eventID: FBEventIDVar });

  配置 GA4 事件，以发送名为 event_id 的额外参数，将参数值设置为 FBEventIdVar 变量。

自定义数据参数

如要发送自定义数据，请在 GA4 事件标签中使用以下映射：

将数据从您的网站发送至您的 GCP 服务器

配置好网站容器和服务器容器后，您便可以从网站发送示例事件以验证服务器事件。完成参数配置的事件示例如下：

 gtag('event', 'purchase', 
  {
    'event_id': generateEventId(),
    'transaction_id': 't_12345',
    'currency': 'USD',
    'value': 1.23,
    user_data: {
      email_address: '<HASHED_DATA>',
      phone_number: '<HASHED_DATA>',
      address: {
        first_name: '<HASHED_DATA>',
        last_name: '<HASHED_DATA>',
        city: '<HASHED DATA>',
        region: '<HASHED_DATA>',
        postal_code: '<HASHED_DATA>',
        country: '<HASHED_DATA>'     
      },    
    },
    items: [
      {
        item_id: '1',
        item_name: 'foo',
        quantity: 5,
        price: 123.45,
        item_category: 'bar',
        item_brand: 'baz'     
      }
    ], 
  });      
     

事件触发后，应该会看到系统向 www.analytics.example.com/g/collect（仅为示例链接）发送包含已配置参数的请求。您可以将测试事件代码添加至 Meta 转化 API 标签，以验证发送至转化 API 的事件。测试事件代码应只用于测试。在发送生产负载时，您需要移除测试事件代码。

在发布更新后，您可以参考此验证设置页面，通过查看“验证设置 - 转化 API”，确认是否已正确发送事件，并检查此优质集成是否遵循最佳实践。

常见问题

是否计划添加发送自定义参数的功能？如果是，此功能会在何时推出？
答：我们已为 GTM 架构中支持的大多数转化 API 的标准自定义参数添加了映射功能。我们还提供了自定义映射功能。详情请参阅此处。

单个服务器或集群能否运行多个容器？
答：目前，GTM 仅支持一对一映射。请阅读有关如何配置容器的建议。

服务器端 GTM 是否需要浏览器标签才能触发事件？
答：是

是否可以将 GA4 与服务器端单独集成？
答：如要单独集成 GA4 和服务器端 GTM，您可以在 Google Analytics 中创建一个额外的成效衡量编号。使用此成效衡量编号为服务器端 GTM 创建一个单独的 GA4 配置标签，然后再按上述步骤操作。在此情况下，现有 GA4 配置标签会将 GA 流量继续发送至网站容器，而新的配置标签会将数据发送至服务器容器。按照第 2 步创建额外的 GA4 事件标签，以使用新的配置标签将事件发送至服务器端

GTM 转化 API 集成是否适用于 GCP 以外的云托管解决方案？
答：GTM 转化 API 集成应该适用于 GCP 或您选择的任何其他平台。有关手动配置详情，请参阅此处。

详细了解

• 转化 API
• 删除重复的 Meta Pixel 像素代码和转化 API 事件