獲取資產編號和存取憑證

在用戶安裝了 Facebook Business 擴充功能，而您亦得到其用戶存取憑證（用於為用戶執行 API 呼叫）後，您需要從用戶處獲取其像素編號、Instagram 商業編號、專頁編號、企業管理平台編號、廣告帳戶編號、目錄編號（選用）或存取憑證，以配置相關功能。這些編號將用於 API 端點和企業配置。

有了 OBO 解決方案，客戶也可使用合作夥伴企業管理平台的管理員系統用戶之存取憑證來獲取存取憑證，而非只能使用客戶的企業管理平台的管理員存取憑證。

收集 API 端點編號及企業配置編號

您可按以下方式獲得有關資訊：

• Webhook — 如果平台合作夥伴希望在應用程式商店上架，此為必要條件
• FBE 安裝 API 端點 — 建議自行託管的企業使用此方式

建立系統用戶

用戶安裝 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，我們都會觸發 Webhook 事件，以便您及時接收有關安裝、解除安裝和重新配置 FBE 的更新。

每次用戶安裝或修改 FBE 時，您的應用程式都應檢查 Webhook 配置，以了解用戶修改、新增或從應用程式的連結中移除了哪些資產。您應用程式的行為應根據最新的已連結資產來作更新。

設定要求

1. 在安全的伺服器上建立端點，伺服器應能處理來自 Facebook 的要求：驗證要求 (GET) 和事件通知 (POST)。
2. 在應用程式管理中心配置 FBE Webhooks 訂閲：
   • 在應用程式管理中心的 Facebook Business 擴充功能部分，前往設定分頁，向下捲動至 Webhooks 資訊卡，然後點擊「編輯回呼網址」。
   • 在回呼網址欄位中輸入您端點的網址，並在驗證憑證欄位中輸入一個字串。我們會在所有驗證要求中加入此字串。
   • 點擊「驗證並儲存」後，我們便會傳送驗證要求給您的端點，而您必須驗證此要求。
   • 系統將自動訂閲 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 回應

模型包含每項功能的功能實例編號和欄位，這些欄位由該企業安裝的所有此類功能的陣列組成（例如多個專頁 CTA）。

對於不可自訂的功能，系統只會顯示功能實例編號和已啟用標記。POST 要求只能用於更新可自訂的功能。

此模型不同於 Facebook Business 擴充功能安裝 API，因為前者會提供已連結資產以外的其他功能資訊，包括已啟用狀態和具體的功能自訂項目。呼叫 Facebook Business 擴充功能安裝 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,
    },
  ],
  ...
}

後續步驟

• 配置企業功能
• 觸發像素事件
• 更新目錄