转化 API 端到端实现

转化 API 可以为广告主的营销活动提供支持，为消费者提供适当的数据透明度以及控制权，同时还可以帮助广告主持续提供个性化体验。借助 API，您可以直接从服务器分享数据，无需再通过浏览器进行分享。

集成的优势

深层漏斗可见性：与 Meta Pixel 像素代码相比，您可借助转化 API 分享的数据更为多样。通过使用转化 API，您在决策时可以综合考虑更多信息，例如 CRM 数据、下层漏斗事件（包括符合条件的潜在客户），以及网站和实体营业点的多站点转化路径。
数据控制：通过“仅限服务器”实现方法（例如，无 Meta Pixel 像素代码）使用转化 API 时，您可以加强对所分享数据的控制。您可以选择为事件附加成效分析，提供产品利润率或历史信息（例如客户价值分数）等数据。
信号可靠性与弹性：与仅使用基于浏览器的方式（例如借助 Meta Pixel 像素代码）相比，通过转化 API 分享数据可能更可靠。转化 API 经过专门设计，受浏览器崩溃或网络连接问题等状况的影响较小。新的行业数据传输限制可能会限制 Cookie 以及 Pixel 像素代码追踪的效率，因此在分享 Pixel 像素代码可能不会再捕获的信号时，您可借助转化 API 加以控制。

其他资源：请参阅转化 API 直接集成开发者手册 (PDF) 和直接集成开发者网络研讨会

概览

您可以分 2 个主要阶段考虑转化 API 集成：

准备阶段 — 选择适合您的集成类型、定义要发送的事件，以及查看适用的优化选项。
执行阶段 — 了解如何实现转化 API。在这个阶段，您也可以使用合作伙伴集成。

完整集成流程的简要说明如下：

要求	完全集成	优化
在征得用户同意的情况下，选择要与 Meta 分享的事件（如有）。设置您的业务资产：Meta Pixel 像素代码、Meta 应用程序、商务管理平台、服务器连接、系统用户。	第 1 步：发送 1 个事件 — 发送任意事件，可以选择手动发送或使用系统用户口令自动发送。完成此步骤即表示您已正确设置身份验证。第 2 步：完全集成 — 您需要发送一些自动化事件才算完成集成。完成这个重要步骤后，即使您停止使用 Pixel 像素代码或 Pixel 像素代码遭到屏蔽，您也可以针对转化 API 进行优化。	完全集成后，必须发送足够数量的自动化漏斗事件才算完全启用。随后，请根据“事件匹配质量”中的指导优化匹配率。请确保：可以通过任一渠道（浏览器或服务器）发送事件，并且系统不会重复计算事件。尽可能实时发送事件。提供客户信息参数，以便用于匹配用户身份。

要求

完全集成

优化

在征得用户同意的情况下，选择要与 Meta 分享的事件（如有）。

设置您的业务资产：Meta Pixel 像素代码、Meta 应用程序、商务管理平台、服务器连接、系统用户。

第 1 步：发送 1 个事件 — 发送任意事件，可以选择手动发送或使用系统用户口令自动发送。完成此步骤即表示您已正确设置身份验证。

第 2 步：完全集成 — 您需要发送一些自动化事件才算完成集成。完成这个重要步骤后，即使您停止使用 Pixel 像素代码或 Pixel 像素代码遭到屏蔽，您也可以针对转化 API 进行优化。

完全集成后，必须发送足够数量的自动化漏斗事件才算完全启用。随后，请根据“事件匹配质量”中的指导优化匹配率。

请确保：

可以通过任一渠道（浏览器或服务器）发送事件，并且系统不会重复计算事件。
尽可能实时发送事件。
提供客户信息参数，以便用于匹配用户身份。

现有的 Pixel 像素代码用户

如果您已有 Meta Pixel 像素代码集成，则应将转化 API 集成构建为该 Pixel 像素代码集成的扩展程序，而不是完全不同的连接。

一般同意

如果您在分享 Pixel 像素代码数据方面拥有控制同意的逻辑，请在通过转化 API 分享数据时使用相同逻辑。

替代方案

如果您想要针对应用事件优化您的广告，请使用应用事件 API。

准备工作

选择集成类型

首先，请选择您想要实现的集成选项：

设置方法说明

设置	方法说明
冗余设置（推荐）	同时通过 Pixel 像素代码和转化 API 发送所有事件。如果用户希望保留网站中的 Pixel 像素代码并且可以充分采用转化 API，则推荐使用这种设置。为成功完成设置，您必须能够为 Pixel 像素代码事件以及转化 API 事件生成固定的 `event_id`。这意味着您需要同时使用 Pixel 像素代码事件以及转化 API 事件发送相同的 `event_name` 和 `event_id`，以便删除重复的相同事件。与仅使用浏览器 Pixel 像素代码相比，此设置的表现有过之而无不及。服务器可以捕获浏览器可能无法追踪的事件，例如发生在独立网站中的购物、潜在客户转化或通话。
拆分设置	通过 Pixel 像素代码和转化 API 发送不同类型的事件。例如，您可以通过 Pixel 像素代码发送 `PageView` 和 `ViewContent`，通过转化 API 发送 `Lead` 或 `Purchase`。虽然此选项不如冗余设置理想，但如果您不想使用完全冗余设置，则可以考虑采用此选项。请注意，在实施浏览器更改的同时，您可能需要完成一些额外工作。
仅限服务器的实现方式	仅通过转化 API 发送事件，而不通过浏览器。建议您先实施冗余设置或拆分设置，而后再切换到这种方式。

冗余设置（推荐）

同时通过 Pixel 像素代码和转化 API 发送所有事件。如果用户希望保留网站中的 Pixel 像素代码并且可以充分采用转化 API，则推荐使用这种设置。

为成功完成设置，您必须能够为 Pixel 像素代码事件以及转化 API 事件生成固定的 event_id。这意味着您需要同时使用 Pixel 像素代码事件以及转化 API 事件发送相同的 event_name 和 event_id，以便删除重复的相同事件。

与仅使用浏览器 Pixel 像素代码相比，此设置的表现有过之而无不及。服务器可以捕获浏览器可能无法追踪的事件，例如发生在独立网站中的购物、潜在客户转化或通话。

拆分设置

通过 Pixel 像素代码和转化 API 发送不同类型的事件。例如，您可以通过 Pixel 像素代码发送 PageView 和 ViewContent，通过转化 API 发送 Lead 或 Purchase。

虽然此选项不如冗余设置理想，但如果您不想使用完全冗余设置，则可以考虑采用此选项。请注意，在实施浏览器更改的同时，您可能需要完成一些额外工作。

仅限服务器的实现方式

仅通过转化 API 发送事件，而不通过浏览器。建议您先实施冗余设置或拆分设置，而后再切换到这种方式。

定义要发送的事件

选择集成方式后，您可以定义要发送的事件。信号在与 Meta 用户编号相符时最为有效，因此请务必仔细考虑通过事件发送给我们的参数以及发送频率。

事件选项

请发送与您业务相关度最高的事件。您可以查看支持的 Meta 标准事件和 Meta 自定义事件的完整清单。

事件参数

您可以在每个事件中发送多个参数。请查看转化 API 使用的参数，详细了解相关字段。

您可以向事件添加多种类型的编号，其中包括 event_id、external_id 以及 order_id。请务必了解这些参数之间的差异：

编号描述使用方式

编号	描述	使用方式
外部编号	特定客户的专属编号。	详细了解外部编号。
事件编号	特定事件的专属编号。	用于删除重复事件。如果您要同时通过浏览器 Pixel 像素代码和转化 API 发送事件，此字段至关重要。
订单编号	特定订单的专属编号。此参数仅适用于购物事件，并且 `custom_data` 中将包含 `order_id` 字段。	此实现方式仅适用于少数 Meta 合作伙伴。如需获取访问权限，请联系您的 Meta 代表。如果您同时通过浏览器 Pixel 像素代码和转化 API 发送事件，此字段可用于删除重复的购物事件。在您向我们发送第 1 个订单后，我们会在发生以下情况时放弃第 2 个订单：您在特定时间范围内发送了另一个具有相同 `order_id` 的事件，同时我们判定这两个订单由同一用户完成。您可以在两个时间范围内删除重复购物事件：48 小时（推荐）或 28 天。这里的时间范围是指相同事件第 1 次与第 2 次发送之间的相隔时间。

外部编号

特定客户的专属编号。

详细了解外部编号。

事件编号

特定事件的专属编号。

用于删除重复事件。如果您要同时通过浏览器 Pixel 像素代码和转化 API 发送事件，此字段至关重要。

订单编号

特定订单的专属编号。此参数仅适用于购物事件，并且 custom_data 中将包含 order_id 字段。

此实现方式仅适用于少数 Meta 合作伙伴。如需获取访问权限，请联系您的 Meta 代表。

如果您同时通过浏览器 Pixel 像素代码和转化 API 发送事件，此字段可用于删除重复的购物事件。

在您向我们发送第 1 个订单后，我们会在发生以下情况时放弃第 2 个订单：
您在特定时间范围内发送了另一个具有相同 order_id 的事件，同时我们判定这两个订单由同一用户完成。

您可以在两个时间范围内删除重复购物事件：48 小时（推荐）或 28 天。这里的时间范围是指相同事件第 1 次与第 2 次发送之间的相隔时间。

数据新鲜度

建议您通过转化 API 实时发送事件，或是根据特定的时间线分批次发送事件。实时发送事件或者在 1 小时内发送事件有助于确保事件可以用于归因分析，并能够针对广告投放进行优化。

如果在事件发生至少 2 小时后才发送事件，则针对这些事件进行优化的广告在表现上可能大打折扣。如果在 24 小时或更长时间后才发送事件，则在归因以及优化广告投放方面可能会出现严重问题。

如果所发送事件的转化期较长，请在完成完全转化后尽量实时发送事件。

做好下列准备后，请转到下一步：

要发送的事件的清单。
要随每个事件一同发送的特定字段。
定义事件发送频率。

备选的优化类型

转化 API 提供以下优化类型：

优化选项	描述
转化优化	优化广告投放，向最有可能完成转化的用户展示广告。
价值优化（也称作“广告花费回报优化”）	优化广告投放，向最有可能完成特定价值转化（例如消费超过 50 美元）的用户展示广告。
动态商品广告	优化广告投放，向最有可能购买特定商品的用户展示此商品的广告。

执行阶段

您可以通过以下 2 种方式实现集成：

直接集成 — 广告主直接实现转化 API。
集成即平台 — 营销合作伙伴以服务的方式向客户提供转化 API。

通过我们任一营销合作伙伴使用转化 API 的广告主应遵循合作伙伴的实施准则。

直接集成

第 1 步：设置要求

在使用转化 API 前，请设置以下资产：

资产	描述
Meta Pixel 像素代码	在您通过转化 API 发送事件时，系统会处理和存储事件，其方式与通过 Pixel 像素代码发送事件时相同。实现转化 API 时，选择您想要将事件发送到的 Pixel 像素代码。通过将转化 API 事件发送到 Pixel 像素代码，您便可使用转化 API 事件进行成效衡量、归因分析以及广告投放优化，方式与使用基于浏览器的 Pixel 像素代码事件无异。建议您通过浏览器和服务器将事件发送到相同的 Meta Pixel 像素代码编号。
商务管理平台	您需要拥有商务管理平台才能使用转化 API。通过商务管理平台，广告主可以整合 Meta 市场营销工作，包括所在公司开展的工作以及与外部合作伙伴合作开展的工作。如果您没有商务管理平台，请参阅帮助中心内有关如何创建商务管理平台的文章。
访问口令	如要使用转化 API，您需要拥有访问口令。您可以通过以下 2 种方式获取访问口令：通过事件管理工具（推荐）使用您自己的应用

资产

描述

Meta Pixel 像素代码

在您通过转化 API 发送事件时，系统会处理和存储事件，其方式与通过 Pixel 像素代码发送事件时相同。实现转化 API 时，选择您想要将事件发送到的 Pixel 像素代码。

通过将转化 API 事件发送到 Pixel 像素代码，您便可使用转化 API 事件进行成效衡量、归因分析以及广告投放优化，方式与使用基于浏览器的 Pixel 像素代码事件无异。建议您通过浏览器和服务器将事件发送到相同的 Meta Pixel 像素代码编号。

商务管理平台

您需要拥有商务管理平台才能使用转化 API。通过商务管理平台，广告主可以整合 Meta 市场营销工作，包括所在公司开展的工作以及与外部合作伙伴合作开展的工作。如果您没有商务管理平台，请参阅帮助中心内有关如何创建商务管理平台的文章。

访问口令

如要使用转化 API，您需要拥有访问口令。您可以通过以下 2 种方式获取访问口令：

通过事件管理工具（推荐）
使用您自己的应用

各项资产准备就绪后，请转到实现 API 步骤。务必保存资产编号，因为您会在 API 调用中用到这些编号。

第 2 步：实现 API

设置完要求后，接下来开始实现流程。在构建转化 API 时，请随时参阅开发者文档。

测试调用（可选）

如果您是首次使用 API，请先测试调用。为此，您需要拥有用于执行 API 调用的负载及方法。完成调用后，请检查事件管理工具，以便验证调用是否正常运作。

负载 API 调用方法

负载	API 调用方法
使用有效负载设置助手生成要通过调用发送的负载示例。按照此工具中所列的说明操作。负载应如下所示： { "data": [ { "event_name": "Purchase", "event_time": 1601673450, "user_data": { "em": "7b17fb0bd173f625b58636fb796407c22b3d16fc78302d79f0fd30c2fc2fc068", "ph": null }, "custom_data": { "currency": "USD", "value": "142.52" } } ] } 如果您想要通过有效负载设置助手测试您的负载，请在测试这个负载下方添加 Pixel 像素代码编号，然后点击发送到测试事件。您应该会在事件管理工具 > 您的 Pixel 像素代码 > 测试事件中看到相应事件。详细了解“测试事件”工具。	确认负载没问题后，请决定调用方式。您可以使用我们的图谱 API 探索工具（参阅指南）或您自己的服务器。如要使用自己的服务器，您可以使用 CURL 或 Meta 业务 SDK。强烈建议您使用 Meta 业务 SDK。无论采用哪种调用方式，您都应调用 `/{pixel_id}/events` 端点，并附上有效负载设置助手生成的 JSON 数据。完成调用后，您应该会收到如下响应： { "events_received": 1, "messages": [], "fbtrace_id": <FB-TRACE-ID> }

使用有效负载设置助手生成要通过调用发送的负载示例。按照此工具中所列的说明操作。负载应如下所示：

{
  "data": [
   {
    "event_name": "Purchase",
    "event_time": 1601673450,
    "user_data": {
      "em": "7b17fb0bd173f625b58636fb796407c22b3d16fc78302d79f0fd30c2fc2fc068",
      "ph": null
     },
    "custom_data": {
      "currency": "USD",
      "value": "142.52"
    }
   }
  ]
}

如果您想要通过有效负载设置助手测试您的负载，请在测试这个负载下方添加 Pixel 像素代码编号，然后点击发送到测试事件。您应该会在事件管理工具 > 您的 Pixel 像素代码 > 测试事件中看到相应事件。详细了解“测试事件”工具。

确认负载没问题后，请决定调用方式。您可以使用我们的图谱 API 探索工具（参阅指南）或您自己的服务器。如要使用自己的服务器，您可以使用 CURL 或 Meta 业务 SDK。强烈建议您使用 Meta 业务 SDK。

无论采用哪种调用方式，您都应调用 /{pixel_id}/events 端点，并附上有效负载设置助手生成的 JSON 数据。完成调用后，您应该会收到如下响应：

{
  "events_received": 1,
  "messages": [],
  "fbtrace_id": <FB-TRACE-ID>
}

完成首次调用后，请前往事件管理工具 > 您的 Pixel 像素代码 > 概览，验证您的事件。

在事件管理工具中检查完测试事件后，请转到发送和验证事件步骤。

发送和验证事件

如要开始发送事件，请向 API 的 /events 连线发出 POST 请求。为调用附加负载（如果您在生成负载时需要帮助，请访问有效负载设置助手）。请查看以下资源，以便获取更多信息和代码示例：

开始发送事件后，请前往事件管理工具，确认我们已收到您发送的事件。了解如何验证您的事件。

如果您的实现是对浏览器 Pixel 像素代码的补充，请转到去重设置。如果不是的话，您便已完成所有设置！如果您还有问题，请查看支持。

第 3 步：添加去重参数

如果您通过 Pixel 像素代码以及转化 API 发送相同的事件，则需要对通过这 2 个渠道发送的事件进行去重设置。首先，请阅读开发者文档，以便了解去重逻辑。

事件去重

如果我们发现在 48 小时内发送到同一个 Pixel 像素代码编号的相同的服务器密钥组合（event_id、event_name）和浏览器密钥组合（eventID、event），我们会弃用后发送的重复事件。

为确保对事件去重，请执行以下操作：

请确保将相应事件的以下参数设置为相同的值：
- 服务器事件中的 event_id 以及浏览器事件中的 eventID
- 服务器事件和浏览器事件中的 event_name
发送重复事件后，请前往事件管理工具确认要弃用的事件是否正确无误。
确保同时通过 Pixel 像素代码以及转化 API 发送的每个独立事件都有各自的 event_id。此编号不应与其他事件共享。

事件去重的替代方案

事件编号虽然向来是最理想的事件去重方式，不过实施起来却相当复杂。您可以通过 external_id 或 fbp 参数使用备选解决方案。如果您配置了同时通过浏览器和服务器传递 external_id 或 fbp 参数，则如果我们看到在 48 小时内具有相同 external_id 或 fbp 参数的相同事件，将自动对事件去重。

第 4 步（可选）：了解业务 SDK 的功能

Meta 业务 SDK 拥有专为转化 API 用户设计的高级功能：

异步请求 — 如果您不想阻止程序执行以等待请求完成，请使用此功能。通过这种方法，您可以发出请求，而服务器在完成请求后会传回信号。在您等候响应期间，程序可以继续执行。
并发批量处理 — 使用异步请求，通过提升资源利用率来提高吞吐量。创建批量处理请求以支持事件请求工作程序、cron 作业等用例。
HTTP 服务接口 — 覆盖业务 SDK 的默认 HTTP 服务，并使用您偏好的方法或库实现自己的自定义服务。

集成即平台

以下说明适用于向广告主提供转化 API 服务的合作伙伴。

第 1 步：设置要求

您的应用应具备以下功能和权限：

访问权限级别：高级访问级别
功能：广告管理标准访问级别
权限：ads_management、pages_read_engagement 以及 ads_read。

第 2 步：代表客户发送事件

首先，按照直接集成步骤操作，测试集成。然后，您可以请求授权，以便代表客户发送事件。您可选用以下身份验证方法：

Meta 业务插件方法（推荐）

Meta 业务插件通过以下流程返回代表客户发送事件所需的所有必要信息。Meta 业务插件会提供端点，用于获取在客户的商务管理平台中创建的系统用户访问口令。此流程会用到发送服务器事件的权限，并且会以安全可靠的方式自动完成。

端点需要用户访问口令作为输入参数。如果您是 Meta 业务插件的新用户，在完成 Meta 业务插件的设置后，请调用此端点，以便获取系统用户访问口令。如果您是现有用户，需要请求重新验证身份，然后才能调用新的 API 端点。

Facebook Business 扩展程序目前仅供已获批准的合作伙伴使用。如果您有兴趣成为我们的合作伙伴，请联系您的 Meta 代表，要求获取使用权限。

客户系统用户访问口令

让您的客户前往 Pixel 像素代码设置，通过转化 API 手动创建系统用户访问口令。然后，使用该口令向广告主的 Pixel 像素代码发送事件。

系统用户或管理员级系统用户必须安装用于生成访问口令的应用。完成此项设置后，您的应用即可代表该系统用户或管理员级系统用户调用 API。

客户将 Pixel 像素代码分享到合作伙伴的商务管理平台

借助此选项，客户可通过商务管理平台设置或 API 将其 Pixel 像素代码分享给合作伙伴，随后您可以将合作伙伴系统用户分配到客户的 Pixel 像素代码，并且可以生成访问口令，以便发送服务器事件。

第 3 步：将事件归因到您的平台

如要将转化 API 事件归因到您的平台，请使用 partner_agent 字段。如此一来，在代表客户发送事件时，您便可以设置自己的平台标识符。如果您是有专人服务的合作伙伴，请与您的 Meta 代表合作协定平台标识符。标识符的值应少于 23 个字符，并且至少应包含 2 个字母。然后，在发送所有服务器事件时一并发送该值。

请务必为希望在您的平台中启用集成的广告主提供最新的设置指南。

支持

对于所有合作伙伴

请查看调试信息以及 Business 帮助中心文章。

对于有专人服务的合作伙伴

请为您的 Meta 代表提供以下信息，以便他们可以帮助您测试集成并解答疑难：商务管理平台编号、应用编号以及 Pixel 像素代码编号。

API 文档

入门指南 — 通过您自己的商务管理平台测试 API
使用 API
最佳实践 — 转化 API
设置转化 API 作为平台
Meta 标准事件
Meta 自定义事件
参数
有效负载设置助手
转化 API 与线下转化 API 的数据处理选项
如果您想要针对应用事件进行优化，请使用应用事件 API
如果事件为店内销量，请使用线下转化 API — 除店内销量外，其他线下事件均符合转化 API 的使用条件