取得資產編號和存取權杖

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

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

收集用於 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_managementcatalog_management,需視您的使用情況而定。

access_token 欄位:可以傳遞用戶存取權限 (user_access_token) 或合作夥伴企業管理平台的管理系統用戶存取權杖 (partner_bm_admin_system_user_token)。深入瞭解企業存取權杖

Webhook 的 token_type 欄位註明所收到的 access_token 是用戶存取權杖抑或系統用戶存取權杖。

若用戶使用 Instagram 安裝 FBE,Webhook 會傳回該名系統用戶的存取權杖(在用戶端企業管理平台上產生的),因此您不需要呼叫這個 API。

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 承載內容

回應欄位

欄位說明
ad_account_id

類型:字串

用戶在 FBE 中選擇的廣告帳號編號。如果應用程式擁有 ads_management 權限,則您可以使用此廣告帳號來管理廣告。請參閱 installed_features 清單的已連結資產。

business_manager_id

類型:字串

用於 FBE 的企業管理平台編號。請參閱 installed_features 清單的已連結資產。

catalog_id

類型:字串

用戶使用 FBE 選擇的目錄編號。用戶可以使用此編號來管理其商品目錄。請參閱 installed_features 清單的已連結資產。

fbe_event

類型:字串

FBE 事件,註明事件通知是安裝抑或解除安裝。請參閱 installed_features 清單的已連結資產。

flow

類型:字串

流程,註明用戶所採用的設置流程(例如 COMMERCECREATIVE 等等)。請參閱 installed_features 清單的已連結資產。

commerce_merchant_settings_id

類型:字串

商務商家設定編號,可用來讓合作夥伴讀取所選 FBE 商務商家設定的相關資訊。請參閱 installed_features 清單的已連結資產。

onsite_eligible

類型:布林值

站內商務資格。指出所選擇的資產是否有資格進行站內商務。商家必須仍有站內意願,並在合作夥伴網站上選擇退貨/寄送/付款。請參閱 installed_features 清單的已連結資產。

profiles

類型:陣列

個人檔案清單(Facebook 粉絲專頁編號和/或 Instagram 商業檔案編號)。使用這些編號為您可能擁有的其他 Facebook 整合建立個別的圖形 API 要求。請參閱 installed_features 清單的已連結資產。

pages

類型:陣列

Facebook 粉絲專頁編號清單。使用這些編號為您可能擁有的其他 Facebook 粉絲專頁整合建立個別的圖形 API 要求。請參閱 installed_features 清單的已連結資產。

instagram_profiles

類型:陣列

Instagram 商業檔案編號清單。使用這些編號為您可能擁有的其他 Facebook/Instagram 整合建立個別的圖形 API 要求。如果未包含此欄位,表示這只是 Instagram 相關範圍。例如,instagram_basic 未包含在存取權杖內,和/或商家未將任何 Instagram 商業檔案與 FBE 連結。請參閱 installed_features 清單的已連結資產。

pixel_id

類型:字串

此商家的專屬像素編號,您應該儲存此編號並用來觸發像素事件。請參閱 installed_features 清單的已連結資產。

token_type

類型:字串

權杖類型。指出所收到的 access_token 是預設用戶存取權杖,還是系統用戶存取權杖。

installed_features

類型:陣列

此商家已透過初始設定流程整合/安裝的功能清單。請參閱目前的功能清單

feature_instance_id

類型:陣列

代表每個已安裝功能的專屬編號。未來可用來修改或解除安裝特定實例。這與功能配置 APIWebhook 中參照的 feature_instance_id 相同。

feature_type

類型:字串

已安裝的功能類型。功能清單表格中有完整的可用功能集。您只需要追蹤已啟用的功能。

connected_assets

類型:陣列

每個功能特定的相關資產清單。資產說明對應於此表格最上方提及的說明。

additional_info

類型:陣列

已連結功能的其他相關資訊。


收到全新安裝的 Webhook 事件時,您必須:1) 保持 business_idpixel_id 的對應,因為商家的像素編號不會重複,而且您應使用此編號觸發標準像素事件,以及 2) 使用其中一個目錄 PUSH API(如果啟用)更新該商家的庫存。


範例 — 含布林值 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」清單之連線資產中的事實來源:

欄位說明

token_type

類型:字串

權杖類型,註明所收到的 access_token 是預設的用戶存取權杖抑或系統用戶存取權杖。

installed_features

類型:陣列

此商家已透過設置流程整合/安裝之功能的清單。

feature_instance_id

類型:字串

不重複的編號,代表所安裝的每一項功能。未來可用來修改或解除安裝特定實例。與功能設定 API 和 Webhook 中的所參照的 feature_instance_id 相同。

feature_name

類型:字串

某項特定功能的名稱。

feature_type

類型:字串

所安裝之功能的類型。您只需要追蹤已啟用的功能。

connected_assets

類型:陣列

每項功能所專用之資產的清單。

additional_info

類型:字串

已連結功能的其他相關資訊,包括 shop_statusshop_status_info,指出商店是否會受到近期變更的影響。shop_status 值可以是「inactive_other」、「inactive_offsite」、「active」或「no_longer_available」。

「Active」表示商店會顯示。「Inactive_offsite」表示因為商店不是使用現場結帳,所以不會顯示。「Inactive_other」表示商店因為某個與結帳方式無關的原因,而不會顯示。「No_longer_available」表示此商店不在美國或主要市場,已無法使用。

功能配置 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,
    },
  ],
  ...
}