多账户专用转化 API 网关控制平面 API

合作伙伴集成

概览

多账户专用转化 API 网关控制平面 API 是网关实例公开的一组 GraphQL API。它允许开发者以编程方式管理网关实例的账户、数据源及其他配置。合作伙伴可以将此 API 集成到面向广告主的用户界面中，为广告主提供流畅的加入和管理流程。

潜在用例：

广告主通过合作伙伴用户界面加入网关，并通过网关管理员设置执行后续操作。这要求集成部分控制平面 API。
广告主在合作伙伴用户界面执行所有操作，包括加入网关和执行后续操作。对于不希望公开网关用户界面但仍希望为广告主提供网关服务的合作伙伴来说，这会是一个不错的用例。这要求集成完整控制平面 API。

有关集成步骤的更多详细信息，请参阅下节。

在本文档中，多账户专用转化 API 网关控制平面 API 或网关可以互换使用。

集成指南

集成路径有两种，具体取决于用例（如下方图表所示）：

部分集成控制平面 API。不要求向广告主进行身份验证。
完整集成控制平面 API。要求通过 Meta 业务插件 (MBE) 或手动生成口令向广告主进行身份验证。

前提条件

对于这两种集成路径，合作伙伴需要首先完成以下步骤：

第 1 步：以网关实例托管者身份加入

第 2 步：生成 API 账户名称和 API 密钥

前往：

https://<Conversions API Gateway Endpoint>/hub/

导航到托管设置选项卡，选择管理 API 账户页面，然后点击添加 API 账户按钮。

重新输入密码。点击继续。

输入 API 账户的名称。点击继续。

账户名称只能包含字母和数字，不得包含空格。最大长度为 20 个字符。

复制并保存生成的密钥。您将无法再查看它。

要移除 API 账户，请点击删除 API 账户。敬请注意，此操作不可逆转，可能会导致任何使用 API 的广告主应用程序或服务中断。

部分集成

基于部分集成的用例：

广告主通过合作伙伴用户界面选择启用网关服务。
合作伙伴生成邀请链接，广告主可以使用该链接来设置密码和创建网关账户。
广告主使用网关用户界面中的功能来执行各种操作，例如数据源管理以及账户用户、网域和路由管理。
合作伙伴据此检索广告主的账户使用情况和账单。

用户流程概览可能如下所示：

为实现上述流程，合作伙伴可集成控制平面 API 的子集，包括：

获取 API 访问口令
为广告主创建账户
获取账户使用情况，例如用于收费

完整集成

基于完整集成的用例：

广告主通过合作伙伴用户界面选择启用网关服务。
合作伙伴加入广告主的网关账户并获得账户管理权限；广告主授权合作伙伴使用 Meta 业务插件 (MBE) 或手动生成口令。
广告主可以在合作伙伴用户界面中执行数据源管理以及账户用户、网域和路由管理。
合作伙伴据此检索广告主的账户使用情况和账单。

用户流程概览可能如下所示：

对于此集成路径，合作伙伴需要请求授权并通过身份验证取得系统用户访问口令，才能代表广告主发送事件。

身份验证

对于并非自行托管的 Meta Pixel 像素代码，合作伙伴有以下两种身份验证选项：

选项 1 - Meta 业务插件 (MBE)

开始之前，您需要完成以下操作：

完成实施 MBE 的所有要求
联系您的 Meta 代表，让他们将您的应用添加至白名单，以获取私人权限：open_bridge_configuration_management

MBE 会提供一个端点，用于检索在广告主的商务管理平台中创建的系统用户访问口令。合作伙伴可以继续执行 MBE 集成指南的第 4 步。请确保：

将设置配置对象的渠道参数值设置为 CONVERSIONS_API_GATEWAY_ADVERTISER。
能够在加入网关后收到 Webhooks 响应。
使用通过 MBE 返回的访问口令，并通过发出额外的 API 调用将其转换为系统用户访问口令。
在系统中保存 external_business_id、pixel_id、business_id 和系统用户访问口令的副本。

选项 2 - 客户端系统用户访问口令

使用此选项时，合作伙伴可能要求广告主：

在事件管理工具 (EM) 的设置中，通过转化 API 手动创建系统用户访问口令
与合作伙伴分享 pixel_id、business_id 和系统用户访问口令，并保存相应副本。

集成

合作伙伴可以集成整套控制平面 API。如需了解更多详细信息，请参阅 API 参考文档。

API 和用户界面使用平等性

为实现 API 和用户界面在使用方面的平等性，我们在网关用户界面中公开了相同的 API 端点。但是，API 参考文档中未涵盖的任何 API 端点可能会在未来的开发过程中发生变化。为将意外影响降至最低，这些未涵盖的 API 端点会返回错误代码 418。您仍然可以使用这些 API，但需自负风险。