자산 ID 및 액세스 토큰 가져오기

사용자가 Facebook Business 확장 기능을 설치하였고 해당 사용자 액세스 토큰(사용자에 대한 API 호출에 사용)을 보유하고 있다면 사용자로부터 픽셀 ID, Instagram 비즈니스 ID, 페이지 ID, 비즈니스 관리자 ID, 광고 계정 ID, 카탈로그 ID(선택 사항) 또는 액세스 토큰을 가져와 관련 기능을 구성해야 합니다. 이러한 ID는 API 엔드포인트와 비즈니스 구성에 사용됩니다.

OBO 솔루션을 사용하면 클라이언트는 클라이언트 비즈니스 관리자의 운영자 액세스 토큰만 받는 대신, 파트너 비즈니스 관리자의 운영자 시스템 사용자 액세스 토큰을 사용하여 액세스 토큰을 받을 수 있습니다.

API 엔드포인트 및 비즈니스 구성의 ID 수집

이 정보를 가져오는 방법은 다음과 같습니다.

• Webhooks—App Store에 등록하려는 모든 플랫폼 파트너에 필수
• FBE 설치 API 엔드포인트—자체적으로 호스팅하는 비즈니스에 권장

시스템 사용자 생성

사용자가 FBE를 설치한 후 확장 기능에서 클라이언트 비즈니스 관리자에 직원 시스템 사용자를 생성합니다. {App Name} System User (FBE) 스키마에 따라 이 새로운 시스템 사용자에 이름을 지정합니다.

시스템 사용자는 비즈니스 관리자가 소유하거나 관리하는 자산으로 API 호출을 보내는 서버나 소프트웨어를 나타냅니다.

이 시스템 사용자는 다음의 작업 권한이 있는 모든 관련 FBE 자산에 대한 권한을 보유하고 있습니다.

1. 페이지: 'MANAGE'
2. 광고 계정: 'MANAGE'
3. 카탈로그: 'MANAGE'
4. 픽셀: '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

Facebook에서는 FBE의 설치, 제거 및 재구성에 대한 업데이트를 즉시 받을 수 있도록 비즈니스가 FBE를 설치, 수정 또는 제거할 때마다 Webhooks 이벤트를 실행합니다.

사용자가 FBE를 설치하거나 수정할 때마다 앱에서는 Webhooks 구성을 검사하여 사용자가 앱과의 연결에서 어떤 자산을 수정, 추가 또는 제거했는지 확인해야 합니다. 앱의 동작은 가장 최근에 연결된 자산을 기준으로 업데이트됩니다.

설정 요구 사항

1. Facebook의 요청을 처리할 수 있는 안전한 서버에 엔드포인트를 생성합니다(인증 요청(GET) 및 이벤트 알림(POST)).
2. 앱 대시보드에서 FBE Webhooks 구독을 구성합니다.
   • 앱 대시보드의 Facebook Business 확장 기능 섹션에서 설정 탭으로 이동하여 Webhooks 카드로 아래로 스크롤한 다음, 콜백 URL 수정을 클릭합니다.
   • 콜백 URL 필드에 엔드포인트의 URL을 입력하고 토큰 인증 필드에 문자열을 입력합니다. 이 문자열은 모든 인증 요청에 포함됩니다.
   • 인증 및 저장을 클릭하면 검증해야 하는 인증 요청이 엔드포인트로 전송됩니다.
   • fbe_install Webhooks는 자동으로 구독됩니다. 이 카드에는 필요한 경우 구독을 비활성화하는 데 사용할 수 있는 토글 스위치도 있습니다.

Webhooks 이벤트 파싱

설치 Webhooks를 수신할 때마다 앱에서 다음과 같은 작업을 수행해야 합니다.

새로운 설치의 경우

1. 액세스 토큰과 토큰 유형을 저장하고 앱에 액세스 권한이 부여된 자산을 기록합니다.
2. 액세스 권한이 부여된 자산에 따라 기능 세트를 활성화합니다.
3. 특정 기능에 필수적인 자산이 없을 경우 해당 기능만 비활성화하세요. 예를 들어 앱에 픽셀이 아닌 카탈로그에 대한 액세스 권한이 부여된 경우, 픽셀 기반 기능이 아니라 카탈로그 기반 기능만 구현하세요.
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를 설치한 모든 비즈니스는 다음의 엔드포인트를 사용하여 기본 설치 정보(IG Business ID and/or Page ID가 포함된 프로필 리스트 및 pixel_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,
    },
  ],
  ...
}

다음 단계

• 비즈니스 기능 구성
• 픽셀 이벤트 실행
• 카탈로그 업데이트