获取资产编号和访问口令

在用户安装 Facebook 业务插件，且您拥有他们的用户访问口令（用于为用户调用 API）后，您需要从用户处获取 Pixel 像素代码编号、Instagram Business 编号、公共主页编号、商务管理平台编号、广告帐户编号、目录编号（可选）或访问口令，以配置相关功能。这些编号将用于 API 端点和企业配置。

借助 OBO 解决方案，客户也可以使用合作伙伴商务管理平台管理员系统用户的访问口令（而不是仅使用客户商务管理平台管理员的访问口令），来获得所需访问口令。

收集 API 端点和企业配置的编号

获取以上编号信息的方法如下：

• Webhooks — 想要列于 App Store 中的所有开放平台合作伙伴都必须使用这个方法
• FBE 安装 API 端点 — 推荐自托管企业使用这个方法

系统用户创建

在用户安装 FBE 后，此插件将在客户的商务管理平台上生成工作人员系统用户。我们会遵循 {App Name} System User (FBE) 模式为此新系统用户命名。

系统用户是指对商务管理平台拥有或管理的资产发起 API 调用的服务器或软件。

此系统用户拥有所有关联 FBE 资产的权限，以及以下任务权限：

1. 公共主页：'MANAGE'
2. 广告帐户：'MANAGE'
3. 目录： 'MANAGE'
4. Pixel 像素代码：'EDIT'

通过 API 获取系统用户口令

如果安装 FBE 后，您通过 Webhooks 或企业登录收到用户访问口令，便可使用该口令获取商务管理平台的系统用户访问口令。为此，请发起以下 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)。详细了解企业访问口令。

Webhooks

为接收有关安装、卸载和重新配置 FBE 的提示更新，我们将在每次您为企业安装、修改或卸载 FBE 时触发 Webhooks 事件。

每次用户安装或修改 FBE 时，您的应用都应检查 Webhooks 配置，以了解用户修改或添加了哪些资产或取消了哪些资产与您应用的关联。您应用的行为应该根据最新的关联资产进行更新。

设置要求

1. 在可以处理以下 Facebook 请求的安全服务器上创建端点：验证请求 (GET) 和事件通知 (POST)。
2. 在应用面板中配置 FBE Webhooks 订阅：
   • 在应用面板的 Facebook 业务插件部分，前往设置选项卡，向下滚动到 Webhooks 图卡，然后点击编辑回调网址。
   • 在回调网址字段中输入您的端点网址，并在验证口令字段中输入一个字符串。我们会在所有验证请求中加入此字符串。
   • 点击验证并保存后，我们将向您的端点发送一个验证请求，而您必须完成验证。
   • 系统将自动订阅 fbe_install Webhooks。Webhooks 图卡还具有一个切换开关，可在需要时用来停用订阅。

解析 Webhooks 事件

每次收到安装 Webhooks 时，您的应用都需要执行以下操作。

新安装

1. 存储访问口令及其类型，并记录企业已授权您应用访问的资产。
2. 根据已授权的资产启用一系列功能。
3. 如果缺少特定功能所需的资产，请仅禁用该功能。例如，如果您的应用获得访问目录的授权，但是未获得 Pixel 像素代码的访问权限，则只实现目录支持的功能，而不实现 Pixel 像素代码支持的功能。
4. 根据应用有权访问的资产，通知用户有关应用运行情况的更新。

已安装

1. 更新访问口令、口令类型以及已授权您应用访问的资产的记录。
2. 根据已授权的资产，更新您的应用要为相关企业实现的一系列功能。
3. 根据应用有权访问的资产，通知用户有关应用运行情况的更新。

卸载时解析 Webhooks

在卸载时，执行以下步骤：

1. 禁用您的应用为相关企业实现的功能。
2. 通知企业有关其配置的变更。

Webhooks 负载的内容

响应字段

示例 — 使用布尔型 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,
    },
  ],
  ...
}

后续步骤

• 配置企业功能
• 触发 Pixel 像素代码事件
• 更新目录