アセットIDとアクセストークンを取得する

ユーザーがFacebook Business拡張機能をインストールした後、(そのユーザーのためにAPI呼び出しをするために使う)ユーザーアクセストークンを入手したら、関連機能を構成するために、ピクセルID、InstagramビジネスID、ページID、ビジネスマネージャID、広告アカウントID、カタログID (任意)、またはアクセストークンをそのユーザーから取得する必要があります。これらのIDは、APIエンドポイントとビジネス構成で使われます。

OBOソリューションを使えば、クライアントは、クライアントのビジネスマネージャの管理者のアクセストークンだけでなく、パートナービジネスマネージャの管理システムユーザーのアクセストークンを使ってアクセストークンを取得することもできます。

APIエンドポイントとビジネス構成のためのIDを収集する

この情報を取得する方法は次のとおりです。

• Webhook—アプリストアのリストに含めるすべてのプラットフォームパートナーの場合に必須
• FBEインストールAPIエンドポイント—セルフホストビジネスの場合におすすめ

システムユーザーの作成

ユーザーがFBEをインストールすると、FBEによってクライアントのビジネスマネージャに従業員システムユーザーが生成されます。この新しいシステムユーザーは、{App Name} System User (FBE)スキーマに従って命名されます。

システムユーザーとは、ビジネスマネージャが所有または管理するアセットにAPI呼び出しをするサーバーまたはソフトウェアです。

このシステムユーザーには、以下のタスクアクセス許可が付与された関連するすべてのFBEアセットに対するアクセス許可が付与されています。

1. ページ: 'MANAGE'
2. 広告アカウント: 'MANAGE'
3. カタログ: 'MANAGE'
4. ピクセル: 'EDIT'

APIを通じてシステムユーザートークンを取得する

FBEインストール後にWebhookまたはビジネスログインを介してユーザーアクセストークンを受け取った場合は、同じトークンを使ってビジネスマネージャのシステムユーザーアクセストークンを取得できます。そのためには、次のAPI呼び出しを実行します。

curl -X POST \
  -F 'app_id={app_id}' \
  -F 'scope={permissions}' \ 
  -F 'access_token={access_token}' \
  -F 'fbe_external_business_id={fbe_external_business_id}' \
  https://graph.facebook.com/<API_VERSION>/<client_business_manager_id>/access_token

scopeフィールドにはmanage_business_extensionアクセス許可を使いますが、用途によってはads_managementやcatalog_managementも必要になることがあります。

access_tokenフィールドには、ユーザーアクセストークン(user_access_token)か、またはパートナービジネスの管理システムユーザーアクセストークン(partner_bm_admin_system_user_token)を渡すことができます。ビジネスアクセストークンについて詳細をご確認ください。

Webhook

FBEのインストール、アンインストール、再構成に関する最新情報を速やかに受け取るようにするため、1つのビジネスがFBEをインストールしたり変更を加えたりアンインストールしたりするたびにWebhookイベントが起動されます。

ユーザーがFBEをインストールしたり変更を加えたりするたびに、アプリではWebhook設定を調べて、ユーザーが変更を加えたり追加したりアプリとの接続から削除したりした対象アセットがどれかを把握するようにしてください。アプリの動作は、最後に関連させたアセットに基づいて更新するというものになるようにしてください。

設定要件

1. セキュアサーバーにFacebookからの次のリクエストを処理できるエンドポイントを作成すること: 認証リクエスト(GET)とイベント通知(POST)。
2. アプリダッシュボードでFBE Webhooksサブスクリプションを設定すること。
   • アプリダッシュボードの[Facebook Business拡張機能]セクションで[設定]タブに移動し、下にスクロールしてWebhooksカードまで移動した後、[コールバックURLを編集]をクリックします。
   • エンドポイントのURLを[コールバックURL]フィールドに入力し、[トークンを認証]フィールドに文字列を入力します。この文字列は、すべての認証リクエストに含められます。
   • [確認して保存]をクリックすると、エンドポイントに認証リクエストが届くので、必ず確認してください。
   • fbe_install Webhookは自動的にサブスクリプション登録されます。カードには、必要に応じてサブスクリプションを利用解除するために使える切り替えスイッチも備わっています。

Webhookイベントの解析

インストールWebhookが受信されるたびに、アプリでは以下のアクションを実行する必要があります。

新規インストールの場合

1. アクセストークンとそのタイプを保管し、アプリによるアクセスが認可されたアセットを記録します。
2. 認可されたアセットに基づいて機能セットを有効にします。
3. 特定の機能に必要なアセットが欠けている場合は、その機能のみ無効にします。例えば、カタログへのアクセスが認可されているが、ピクセルへのアクセスは認可されていないアプリの場合、ピクセル駆動の機能ではなく、カタログ駆動の機能のみを実装します。
4. アプリが、アクセス権を付与された対象アセットに基づいてどのように動作するかに関する最新情報をユーザーに通知します。

既存のインストールの場合

1. アクセストークン、トークンのタイプ、アプリによるアクセスが認可されたアセットを更新します。
2. どのアセットが認可されているかに基づいて、このビジネスのためにアプリで実装する機能セットを更新します。
3. アプリが、アクセス権を付与された対象アセットに基づいてどのように動作するかに関する最新情報をユーザーに通知します。

アンインストール時のWebhookの解析

アンインストール時には、以下の手順を実行します。

1. このビジネスのためにアプリが実装する機能を無効にします。
2. ビジネスに対して設定の変更を通知します。

Webhookペイロードの内容

応答フィールド

例 — ブーリアン型のonsite_commerce_eligibleフィールドによるペイロード

{
  "data": [{
    "ad_account_id": "<ad_account_id>",
    "business_manager_id": "<business_manager_id>",
    "catalog_id": "<catalog_id>",
    "commerce_merchant_settings_id": "<commerce_merchant_settings_id>",
    "onsite_eligible": true,
    "profiles": [
      "<page_id>",
      "<instagram_profile_id>"
    ],
    "pages": [
      "<page_id>"
    ],
    "instagram_profiles": [
      "<instagram_profile_id>"
    ],
    "pixel_id": "<pixel_id>",
    "token_type": "<token_type>",
    "installed_features": [
        {
            "feature_instance_id": "<unique_id>",
            "feature_name" : string, 
            "feature_type": enum,
            "connected_assets": {
                "ad_account_id": "<ad_account_id>",
                "business_manager_id": "<business_manager_id>",
                "catalog_id": "<catalog_id>",
                "commerce_merchant_settings_id": "<commerce_merchant_settings_id>",
                "ig_profile_id": "<instagram_profile_id>"               
                "page_id": "<page_id>",
                "pixel_id": "<pixel_id>",
            },
            "additional_info": {
                            "onsite_commerce_eligible": bool
                        },
                        {
                        "shop_status": array
                        },
                        {
                        "shop_status_info": array
                        }
                }
         ]
    }]
}

FBEインストールAPI

FBEをインストールしたビジネスでは、以下のエンドポイントを使って、基本的なインストール情報(pixel_idと、IG Business ID and/or Page IDを含むプロフィールのリスト)をクエリできます。

例

CURL -X GET 'https://graph.facebook.com/<API_VERSION>/fbe_business/fbe_installs?fbe_external_business_id=<fbe_external_business_id>&access_token=<access_token>'

応答

{
  "data": [{
    "token_type": "<token_type>"
    "installed_features": [
        {
            "feature_instance_id": "<unique_id>",
            “feature_name” : string, 
            "feature_type": enum,
            "connected_assets": {
                “ad_account_id”: "<ad_account_id>",
                “business_manager_id”: "<business_manager_id>",
                “catalog_id”: "<catalog_id>",
                “commerce_merchant_settings_id”: "<commerce_merchant_settings_id>",
                “ig_profile_id”: "<instagram_profile_id>"               
                "page_id": "<page_id>",
                "pixel_id": "<pixel_id>",
            },
            "additional_info": {
                            "onsite_commerce_eligible": bool
                        },
                        {
                        "shop_status": array
                        },
                        {
                        "shop_status_info": array
                        }
                }
         ]
    }]
}

応答には次のフィールドが含まれます。現在これらが、installed_featuresリストの関連アセットについての信頼できる情報源となります。

機能設定APIの応答

モデルには、各機能の機能インスタンスID、およびビジネスによってインストールされたそのタイプの全機能から成る配列で構成されるフィールド(複数ページCTAなど)が含まれます。

カスタマイズできない機能の場合、表示されるのは、機能インスタンスIDと有効化されているフラグだけです。POSTリクエストで更新できるのは、カスタマイズ可能な機能のみです。

このモデルはFBEインストールAPIとは異なり、関連アセットだけではなく、有効化ステータスや特定の機能カスタマイズ設定など、追加の機能情報を提供します。FBEインストールAPIを呼び出した後、機能の有効化ステータスまたは設定についてさらに情報が必要な場合は、このAPIを使用します。

読み取り

次のリクエストにより、任意のビジネスの現在の機能設定ステータスを読み取ることができます。

CURL -X GET 
'https://graph.facebook.com/<API_VERSION>/fbe_business/?fbe_external_business_id=<fbe_external_business_id>&access_token=<access_token>'

更新

すべての機能を更新するには、次のPOSTリクエストを使います。

CURL -i -X POST \   
  -F 'fbe_external_business_id=<fbe_external_business_id>' \
  -F 'business_config={business_config object}' \
  -F 'access_token=<access_token>' 
  "https://graph.facebook.com/<API_VERSION>/fbe_business"

応答

{
  "page_cta": {
     "feature_instance_id": id1,
     "enabled": true,
     "cta_button_text": "Book Now",
     "cta_button_url": "https://partner-site.com/foo-business1",
     "below_button_text": "Powered by FBE Partner"
  },
  "page_ctas": [
    {
        "feature_instance_id": id1,
        "enabled": true,
        "cta_button_text": "Book Now",
        "cta_button_url": "https://partner-site.com/foo-business1",
        "below_button_text": "Powered by FBE Partner"
    },
    {
        "feature_instance_id": id2,
        "enabled": true,
        "cta_button_text": "Book Now",
        "cta_button_url": "https://partner-site.com/foo-business2",
        "below_button_text": "Powered by FBE Partner"
    }
  ],
  “ig_cta”: {...}
  "ig_ctas": [{...}, {...}],
  “ads”: [
    {
      "feature_instance_id": id3,
      “enabled”: true,
    },
    {
      "feature_instance_id": id4,
      “enabled”: true,
    },
  ],
  ...
}

次のステップ

• ビジネス機能の構成
• ピクセルイベントの起動
• カタログの更新