取得資產編號和存取權杖

用戶安裝 Facebook Business 擴充功能且您取得其使用者存取權杖（用於發出使用者的 API 呼叫）後，您需要向使用者取得像素編號、Instagram Business 編號、粉絲專頁編號、企業管理平台編號、廣告帳號編號、目錄編號（選用）或存取權杖，才能設定相關功能。這些編號將用於 API 端點和商家設定。

若使用 OBO 解決方案，除了用戶端企業管理平台管理員的存取權杖之外，用戶端還可以使用合作夥伴企業管理平台管理系統用戶的存取權杖。

收集用於 API 端點和商家設定的編號

收集這些資訊的方法如下：

• Webhook—凡有意在 App Store 上架的平台合作夥伴，此為必要項目
• 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 的提示更新，企業每次安裝或解除安裝 FBE 時我們都會觸發 Webhook 事件。

每當用戶安裝或修改 FBE，您的應用程式就應檢查 Webhook 設定，從而瞭解該用戶與您的應用程式連線時所修改、新增或移除的資產。應用程式的運作方式應根據最新連結的資產進行更新。

設定需求

1. 在可以處理 Facebook 要求的安全伺服器上建立端點，該伺服器要能處理這些要求：驗證要求 (GET) 和事件通知 (POST)。
2. 在應用程式主控板中設定 FBE Webhook 訂閱：
   • 在應用程式主控板的 Facebook Business 擴充功能區段中，進入設定頁籤，向下捲動至 Webhook 頁籤卡，然後點擊編輯回傳網址。
   • 在回傳網址欄位中輸入端點的網址，接著在驗證權杖欄位中輸入字串。我們會在所有的驗證要求中附加這個字串。
   • 在您點擊驗證並儲存後，我們會傳送驗證要求至您的端點，您必須確認這項要求。
   • 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 要求更新可自訂的功能。

此模型不同於 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,
    },
  ],
  ...
}

後續步驟

• 設定企業功能
• 觸發像素事件
• 更新目錄