多帳號控制平面 API 的轉換 API 閘道

合作夥伴整合

總覽

多帳號控制平面 API 的轉換 API 閘道是從閘道執行個體公開的一組 GraphQL API，可讓開發人員以程式設計方式管理閘道執行個體的帳號、資料來源和其他配置。合作夥伴可以將該 API 整合到面向廣告主的用戶介面中，並為廣告主提供順暢的啟用和管理流程。

可能的使用案例：

廣告主使用合作夥伴的用戶介面來啟用閘道，並透過閘道管理設定來執行後續操作。這需要部分整合控制平面 API。
廣告主在合作夥伴的用戶介面上執行所有操作，包括啟用閘道和後續操作。對於不想公開閘道用戶介面，但仍想要為廣告主提供閘道服務的合作夥伴來說，這是個很好的使用案例。這需要完全整合控制平面 API。

請參閱下文，進一步瞭解整合步驟的詳細資訊。

在本文件中，「多帳號控制平面 API 的轉換 API 閘道」或「閘道」這兩個詞會交替使用。

整合指南

根據使用案例，會有兩種整合路徑（如下圖所示）：

部分整合控制平面 API。這不需要廣告主的驗證。
完全整合控制平面 API。這需要廣告主使用 Meta Business 擴充功能（MBE）或手動產生權杖來進行驗證。

必要條件

這兩種整合路徑都需要合作夥伴先完成以下步驟：

步驟 1：以閘道執行個體的主機身分進行啟用

步驟 2：產生 API 帳號名稱和 API 密鑰

前往：

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

導覽至主機設定頁籤，選擇管理 API 帳號頁面，然後點擊新增 API 帳號按鈕。

再次輸入密碼。點擊繼續。

輸入 API 帳號的名稱。點擊繼續。

帳號名稱僅限以字母和數字組成，不能包含空格。長度上限為 20 個字元。

複製並儲存所產生的密鑰。您無法再次查看此密鑰。

若要移除 API 帳號，請點擊刪除 API 帳號。請注意，此動作無法復原，並且可能導致使用該 API 之任何廣告主的應用程式或服務中斷。

部分整合

部分整合型使用案例：

廣告主使用合作夥伴的用戶介面選擇加入閘道服務。
合作夥伴產生邀請連結，廣告主可以使用該連結設定密碼，並完成建立閘道帳號。
廣告主使用閘道用戶介面上的功能來執行資料來源管理，以及帳號用戶、網域和路由管理等操作。
合作夥伴依情況擷取廣告主的帳號用量和帳單。

概略的用戶流程如下所示：

為了達成上述目標，合作夥伴可以整合一部分的控制平面 API，包括：

取得 API 存取權杖
為廣告主建立帳號
取得帳號用量，例如為了帳單計費

完全整合

完全整合型使用案例：

廣告主使用合作夥伴的用戶介面選擇加入閘道服務。
合作夥伴啟用廣告主的閘道帳號，並取得管理該帳號的權限；廣告主使用 Meta Business 擴充功能（MBE）或手動產生權杖來授權合作夥伴。
廣告主可以在合作夥伴的用戶介面中執行資料來源管理，以及帳號用戶、網域和路由管理。
合作夥伴依情況擷取廣告主的帳號用量和帳單。

概略的用戶流程如下所示：

若要使用此整合路徑，合作夥伴必須要求授權，並透過驗證取得系統用戶存取權杖，才能代表廣告主傳送事件。

驗證

對於非由合作夥伴管理的 Meta 像素，合作夥伴有以下兩種驗證選項：

選項 1 - Meta Business 擴充功能（MBE）

開始之前，您需要：

完成實作 MBE 的所有必備條件
聯絡您的 Meta 業務代表，將您的應用程式加入至私密權限的許可清單：open_bridge_configuration_management

MBE 會提供端點，以擷取在廣告主企業管理平台中建立的系統用戶存取權杖。合作夥伴可以按照 MBE 整合指南的步驟 4 進行操作。請確認您：

已將設定配置物件中的管道參數值設為 CONVERSIONS_API_GATEWAY_ADVERTISER。
能夠在啟用完成時收到 Webhook 回應。
使用透過 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，但需要自行承擔風險。