마이그레이션 가이드: MBE v2에서 MBE v3로 마이그레이션

이 가이드에서는 MBE v3와 호환되도록 Meta Business 확장 도구(MBE, v2)의 기존 비즈니스 앱을 마이그레이션하는 데 필요한 변경 사항을 설명합니다. 향후 MBE에서는 이러한 업데이트가 필수이며 다음 버전의 그래프 API에서는 기존 버전을 지원하지 않습니다.

MBE v3의 주요 장점

MBE v3를 사용하면 타사 앱 개발자는 다음과 같은 장점을 누릴 수 있습니다.

1. 비즈니스에 더욱 간소화된 온보딩 플로를 제공합니다.

2. 이탈을 줄이는 데 도움이 됩니다.

3. 비즈니스가 각 비즈니스 앱에 활성화하고자 하는 기능을 유연하게 관리할 수 있도록 합니다. 예를 들어 온라인 판매자는 처음에 비즈니스 앱으로 메시지 기능을 설정했다가 나중에 같은 앱으로 Facebook Shop을 활성화할 수 있습니다. 이는 비즈니스에 여러 FBE 기능을 업셀링하기에 좋은 방법입니다.

4. FBE와의 통합에 여러 비즈니스 유형을 포함합니다. 예를 들어 타사 앱은 광고주 도구만 필요한 비즈니스의 하위 집합에 한 가지 유형의 통합을 제공하고, 메시지 도구만 필요한 비즈니스에 다른 유형의 통합을 별도로 제공할 수 있습니다.

시작하기 전에

도움이 필요할 때 적절한 지원을 받을 수 있도록 Meta 파트너 관리자에게 이 업그레이드를 한다는 것을 알립니다.

개요

용어

기능: 비즈니스에 결과를 제공할 수 있는 특정 통합입니다. 각 통합에는 고유한 구현 요구 사항이 있으며, 활성화하고자 하는 기능을 설정할 수 있습니다. 예를 들어 page_cta, chat_plugin 등이 포함될 수 있습니다. 전체 리스트는 이 기능 리스트를 참조하세요.

업종: 비즈니스 유형을 나타냅니다. 서비스를 제공하는 비즈니스 유형에 따라 하나 이상의 업종과 통합할 수 있습니다. 비즈니스의 요구 사항에 따라 하나 이상의 업종에 단일 비즈니스를 설정할 수도 있습니다. 전체 리스트는 이 업종 리스트를 참조하세요.

인텐트: 인텐트는 특정 사용 사례에 대한 MBE 이름입니다. 예를 들어 CATALOG_ADS 인텐트는 앱이 카탈로그 광고를 게재하고, 카탈로그의 제품과 서비스를 동기화 및 홍보할 수 있는 사용 사례의 이름입니다. 인텐트는 기능 메뉴에 표시되고 비즈니스가 얻는 여러 기능 세트에 매핑됩니다.

v3를 사용하는 인텐트는 v2의 '채널'과 유사합니다. 로그인 플로에서 인텐트를 구성하는 것은 필수가 아니지만 인텐트를 구성한다면 기능 메뉴에서 나머지 사용 가능한 인텐트를 표시하기 전에 판매자 또는 광고주에게 지정된 인텐트로 온보딩을 완료하라는 메시지가 표시됩니다. 로그인 플로에서 인텐트를 제외하면 판매자 또는 광고주에게 업종에 따라 모든 사용 가능한 기능 메뉴를 표시하고 MBE 시작 시 자신의 인텐트를 선택할 수 있도록 합니다.

전체 리스트는 이 업종별 인텐트 리스트를 참조하세요.

v2와 v3의 핵심적 차이

MBE v3는 온보딩 시 비즈니스에서 활성화할 수 있는 기능을 더욱 세밀하고 효과적으로 제어합니다. 따라서 Facebook에서는 이러한 기능 디테일 수준을 반영하여 UI를 업그레이드하고 Webhooks와 API 응답을 변경하고 있습니다.

활성화하고자 하는 기능과 비즈니스에 전달하는 업종에 따라 MBE는 온보딩 플로 내에 기능 메뉴를 표시하며, 여기에서 비즈니스는 설치하고자 하는 기능을 선택할 수 있습니다. 그러면 비즈니스는 관리 보기에서 이러한 기능을 관리하고 자신의 환경에서 플로에 다시 들어가거나 관리 보기 환경을 통해 더 많은 기능을 추가할 수 있습니다.

권장 사항

비즈니스에서 활성화하는 기능 세트는 동적이며 선택 사항이므로 기록을 보관하기 위한 프레임워크를 빌드하는 것이 좋습니다. 각 비즈니스에 대한 권장 사항은 다음과 같습니다.

1. 활성화된 기능 리스트 및 관련 자산을 보관합니다.
2. Meta API와 동기화하여 이러한 활성화된 기능에 대한 기록이 정확하고 최신 상태를 유지하도록 합니다.

요구 사항

비즈니스 사용자는 MBE v3를 통해 다음과 같은 작업을 수행할 수 있습니다.

• 관련 있는 앱 기능의 하위 집합을 옵트인합니다.

• 다른 기능과 관계없이 시간이 지남에 따라 기능을 추가하거나 삭제합니다.

따라서 앱 통합은 다음을 수행해야 합니다.

1. 업데이트를 수신합니다. 비즈니스가 플로를 거치거나 비즈니스에서 활성화한 기능을 업데이트할 때마다 Webhooks를 전송합니다.

2. Webhooks를 수신한 후 FBE 설치 API를 호출하여 어떤 기능이 활성화되었는지 확인합니다. 비즈니스가 플로를 거칠 때마다 기능을 활성화하거나 비활성화할 수 있습니다.

3. 플랫폼에서 이 비즈니스에 대해 활성화된 기능의 기록을 업데이트합니다.

4. 기능 리스트의 파트너 구현 상세 정보에 따라 각 기능을 활성화합니다. 예를 들어 별도의 자체 카탈로그가 필요한 여러 기능을 활성화한 경우 각 카탈로그에 동기화를 유지해야 합니다. 추가적인 기능 정보가 필요할 경우 기능 구성 API에서 가져오세요.

앱은 앱이 지원하는 모든 자산이 반환될 것이라고 가정해서는 안 됩니다. 예를 들면 다음과 같습니다.

• Shop을 설정하는 비즈니스는 Instagram 계정으로만 Shop을 설정할 수도 있습니다. 그러므로 앱은 이 기능을 활성화하기 위해 비즈니스에 페이지를 설정하도록 요구해서는 안 됩니다.

• 광고 성과를 개선하기 위해 전환 피드를 설정하는 비즈니스는 페이지 또는 Instagram 행동 유도(CTA) 버튼을 설정하지 않아도 됩니다. 앱은 이 기능을 활성화하기 위해 비즈니스에 페이지 또는 Instagram 계정을 설정하도록 요구해서는 안 됩니다.

v3로의 통합 업데이트

이 섹션에서는 MBE v3를 사용하기 위한 필수적인 변경 사항을 적용하여 통합을 업데이트하는 방법을 설명합니다. MBE v3는 근본적으로 MBE v2와 다르기 때문에 이러한 구현 가이드라인을 준수하여 사용자의 잠재적인 서비스 중단을 최소화하는 것이 좋습니다.

1단계: 기능 설정 및 업데이트 대응

• Webhooks 플로 업데이트: 비즈니스가 활성화하고자 하는 기능 세트를 업데이트했음을 나타내는 Webhooks를 수신합니다.

• FBE 설치 API와의 통합 업데이트: FBE 설치 API를 호출하고 기록을 업데이트하여 비즈니스에서 활성화한 기능을 파악합니다.

• 기능 구성 API와의 통합 업데이트: 각 기능을 구성하고 기능 구성 API를 호출하여 필요에 따라 각 기능에 대한 추가 정보를 가져옵니다.

2단계: 앱에서 지원하는 기능 구성

기능 메뉴에서 판매자에게 표시되는 기능은 MBE 개발자 패널 내에서 구성하는 기능입니다.

3단계: 업종 구성

업종을 구성할 때 business_vertical의 추가(extras) 구성에서 각 비즈니스에 적절한 업종을 보내야 합니다. 예를 들어 미용실일 경우 ‘APPOINTMENTS’를 보내고, 제품을 판매하는 Shop일 경우 ‘ECOMMERCE'를 보냅니다.

비즈니스가 두 가지 이상의 업종에 속할 경우 (비즈니스가 달성하려는 목표에 따라) 환경의 각 진입점에 대해 다른 업종을 보냅니다. 예를 들어 미용실에서 예약을 제공하고 헤어 제품도 판매하는 경우 진입점 1에서는 ‘APPOINTMENTS’를 보내고 진입점 2에서는 ‘ECOMMERCE’를 보낼 수 있습니다. 각 진입점은 제대로 작동하도록 구성된 업종별 기능이 있어야 합니다.

동일한 external_id를 사용할 경우 두 업종을 모두 온보딩하는 판매자 또는 광고주는 각 업종에 대해 동일한 비즈니스 관리자에 '잠금'됩니다. 판매자가 온보딩한 첫 번째 업종의 자산(페이지, 픽셀, 카탈로그)은 두 번째 업종에서 미리 선택되지만 판매자에게 두 번째 업종에서 다른 자산을 선택하는 옵션이 제공됩니다. 판매자가 설치한 모든 기능은 기능 구성 API에서 읽을 수 있습니다.

4단계: UI 변경 사항

업데이트된 온보딩 플로(최소 온보딩)는 '기능 메뉴'를 보여줍니다. 이를 통해 비즈니스에 활성화된 기능 하나 이상을 묶은 번들에 해당하는 인텐트 리스트가 표시됩니다. 비즈니스는 설치하려는 인텐트를 선택할 수 있습니다. 비즈니스가 특정 인텐트를 먼저 설치한 다음 기능 메뉴를 보게 하려면 setup 개체에서 intent 매개변수를 전달하세요. 이 매개변수에 대한 인텐트 리스트에서 선택할 수 있습니다. UI 업데이트에 대해 실험을 수행하기를 원하거나 이 새로 업데이트된 UI를 원하지 않는 경우 flow_config 개체의 use_minimal_onboarding 매개변수가 어떤 UI를 표시할지 결정합니다. Use_minimal_onboarding을 false로 설정하면 MBE v2 UI가 유지됩니다.

5단계: 관리 보기

v3의 관리 보기는 비즈니스가 설치한 모든 기능을 표시하고 다른 기능을 설치하기 위한 링크를 제공합니다. 관리 보기 링크는 다음과 같이 업데이트되었습니다.

<a href=”https://business.facebook.com/latest/business_app_store/manage_external_business_connection?asset_id=<page_id>&business_id=<business_id>&app_id=<app_id>&external_business_id=<external_business_id>"><button>Launch Management View</button></a>

6단계: 기능 변경 사항 지원

이러한 기능 변경 사항을 활성화하기 위해 다음의 API를 업데이트했습니다.

Webhooks에 대한 업데이트

Webhooks는 각 설치 및 제거에 대해 전송되며, 비즈니스에서 설치한 기능으로만 구성됩니다.

제거의 경우에도 Webhooks가 설치된 기능으로만 구성된 응답(예: 제거된 기능 미포함)을 포함하여 전송됩니다. Webhooks를 전송할 때마다 FBE 설치 API에서 정보 출처에 대해 가져옵니다.

응답

{
  "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
            }
        }
    
  }]
}

응답 필드

FBE 설치 API에 대한 업데이트

업데이트된 API 모델은 비즈니스에서 활성화한 각 기능 리스트와 각 기능에 연결된 자산을 전송합니다. 주요 변경 사항은 installed_features 필드를 추가한 것입니다. 이 페이로드는 Webhooks 응답과 동일합니다.

Webhooks를 수신한 후 다음의 권장 절차를 따르세요.

1. 수신한 외부 비즈니스 ID와 액세스 토큰으로 FBE 설치 API를 호출합니다. 이 API에는 설치된 기능과 해당 기능에 연결된 자산의 정보 출처가 포함되어 있습니다. 이러한 기능 구성에 대한 적절한 기록을 보관합니다.

2. 해당 비즈니스에 대해 이러한 기능을 활성화하고('활성화'의 의미에 대한 자세한 내용은 기능 리스트 표 참조), 기능 구성 API에서 기능에 필요한 추가 정보를 가져옵니다.

다음의 코드 샘플은 FBE 설치 API에 대한 요청 예시와 해당 API 응답을 보여줍니다. 응답 내에서 추가적인 v3 필드가 강조 표시됩니다.

요청

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": [{
    "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>",
<!--UPDATES BELOW-->
    "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
            }
        }
    ]
  }]
}

기능 구성 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,
    },
  ],
  ...
}

테스트

테스트 전에 Meta 담당자에게 다음을 보내세요.

1. 활성화하고자 하는 기능.

2. 플로를 테스트할 개인의 사용자 ID.

3. v3에 대해 해당 앱을 허용 리스트에 추가하기 위한 테스트 앱 ID.

4. 테스트에 도움이 필요한 경우 Meta 담당자에게 테스트 앱에 대한 역할 부여.

이러한 v3 변경 사항을 테스트하려면 온보딩 플로를 거치면서 다음과 같은 작업을 수행합니다.

1. 설치 및 제거 시 Webhooks를 수신합니다.

2. Webhooks, 설치 API 및 기능 구성 API의 경우 앞서 언급한 업데이트가 적용됩니다(설치 및 제거된 기능을 정확하게 표시).

3. 기능 메뉴는 비즈니스에서 설치하고자 하는 기능을 반영합니다(업종 기준).

온보딩 플로의 테스트 방법:

1. 비즈니스 로그인을 사용합니다.

2. 비즈니스 앱(해당할 경우)을 사용합니다.

원하는 기능과 비즈니스 로그인 및 비즈니스 앱에서 보고자 하는 UI에 대해 정확한 비즈니스 구성 개체를 보내세요.

기능 리스트

MBE v3는 비즈니스에서 활성화할 수 있는 다음과 같은 기능을 제공합니다. 이러한 모든 기능은 (설치 플로 중에) FBE 설치 API를 통해 전달될 수 있지만, 표에 나와 있듯이 모든 기능을(판매자 또는 광고주가 이미 MBE를 설치한 후에) 기능 구성 API를 통해 구성할 수 있는 것은 아닙니다.

messenger_chat에 대한 샘플 코드

<div class="fb-customerchat"
            page_id=PAGE_ID 
</div>

업종 리스트

앱이 속한 업종을 확인하세요.

업종별 인텐트(사용 사례)

광고

크리에이티브

이커머스

예약

예약

식품 및 음료

잠재 고객용 광고

측정 및 최적화

데이터 통합