複数アカウントコントロールプレーンAPIのためのコンバージョンAPIゲートウェイ

パートナー連携

概要

複数アカウントコントロールプレーンAPIのためのコンバージョンAPIゲートウェイは、ゲートウェイインスタンスから公開されたGraphQL APIのセットです。このAPIを利用することにより開発者は、ゲートウェイインスタンスのアカウント、データソース、その他の設定内容をプログラムにより管理することができます。パートナーは、APIを統合して広告主向けUIを構築し、広告主にシームレスなオンボーディングおよび管理フローを提供することができます。

考えられる使用例

広告主はパートナーのUIを使用してゲートウェイにオンボーディングし、ゲートウェイ管理者設定によってフォローアップアクションを実行します。これにはコントロールプレーンAPIの部分的な統合が必要です。
広告主は、パートナーのUIでゲートウェイへのオンボーディングやフォローアップアクションなどのすべてのアクションを実行します。ゲートウェイUIを公開したくないものの、広告主のためのサービスとしてゲートウェイを提供したいパートナーにぴったりの使用例となります。これにはコントロールプレーンAPIの完全な統合が必要です。

統合ステップの詳細については、以下のセクションをご覧ください。

このドキュメントで使用されている、複数アカウントコントロールプレーンAPIのためのコンバージョンゲートウェイまたはゲートウェイ という用語は、どちらも同じものを指しています。

統合ガイド

使用例に応じて、(以下の図に示すような)次の2つの統合パスがあります。

コントロールプレーンAPIの部分的な統合。これには広告主からの認証は必要ありません。
コントロールプレーンAPIの完全な統合。これには、Meta Business拡張機能(MBE)またはトークンの手動生成いずれかを使用する広告主からの認証が必要です。

前提条件

どちらの統合パスについても、パートナーはまず以下の手順を完了する必要があります。

ステップ1: ゲートウェイインスタンスのホストとしてオンボードする

ステップ2: APIアカウント名とAPI secret keyを生成する

まず

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

[ホスト設定]タブに移動し、[APIアカウントの管理]ページを選択し、[APIアカウントを追加]ボタンをクリックします。

パスワードを再入力します。[次へ]をクリックします。

APIアカウントの名前を入力します。[次へ]をクリックします。

アカウント名には文字と数字のみを使用してください。スペースを含めることはできません。上限は20文字です。

生成されたsecret keyをコピーして保存します。再び表示することはできません。

APIアカウントを削除するには、[APIアカウントを削除]をクリックします。このアクションは元に戻せないため、APIを使用している広告主のアプリケーションやサービスに混乱が生じる可能性があることにご注意ください。

部分統合

部分的な統合に関する使用例

広告主はパートナーのUIを使用してゲートウェイサービスにオプトインします。
パートナーが招待リンクを生成します。広告主はそのリンクを使用してパスワードを設定し、ゲートウェイアカウントの作成を完了することができます。
広告主は、ゲートウェイUIの機能を使用して、データソース管理やアカウントユーザー、ドメイン、ルーティング管理などのアクションを実行します。
パートナーは広告主のアカウント使用状況を取得し、それに応じて請求します。

ハイレベルのユーザーフローは以下のように場合があります。

上記のようにするために、パートナーはコントロールプレーンAPIのサブセットを統合することができます。

APIアクセストークンを取得する
広告主のためのアカウントを作成する
請求などのためにアカウントの使用状況を取得する

完全な統合

完全な統合に関する使用例

広告主はパートナーのUIを使用してゲートウェイサービスにオプトインします。
パートナーは広告主のゲートウェイアカウントにオンボーディングし、アカウントの管理権限を受け取ります。広告主は、Meta Business拡張機能(MBE)またはトークンの手動生成を使用してパートナーを認証します。
広告主は、パートナーのUIでアカウントユーザー、ドメイン、ルーティング管理のほか、データソース管理を行うことができます。
パートナーは広告主のアカウント使用状況を取得し、それに応じて請求します。

ハイレベルのユーザーフローは以下のように場合があります。

この統合パスでは、パートナーは広告主に代わってイベントを送信するために、認証をリクエストし、認証によってシステムユーザーアクセストークンを取得する必要があります。

認証

パートナーには、管理されていないMetaピクセルのための次の2つの認証オプションがあります。

オプション1 - Meta Business拡張機能(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とUIパリティ

Metaでは、ゲートウェイUIで使用されるAPIエンドポイントと同じものを公開して、APIとUIパリティを強化しています。ただし、APIリファレンスに掲載されていないAPIエンドポイントは、今後の開発において変更される可能性があります。予期せぬ影響を最小限にするために、未掲載のAPIエンドポイントではエラーコード: 418が返されます。APIを使用することはできますが、自己責任でお願いします。