복수 계정 컨트롤 플레인 API용 전환 API 게이트웨이

파트너 통합

개요

복수 계정 컨트롤 플레인 API용 전환 API 게이트웨이는 게이트웨이 인스턴스에서 노출된 GraphQL API 세트입니다. 개발자는 이를 통해 계정, 데이터 소스 및 게이트웨이 인스턴스의 다른 구성을 프로그래밍 방식으로 관리할 수 있습니다. 파트너는 이 API를 통합하여 광고주에게 표시되는 UI를 구축하고 광고주에게 원활한 온보딩 및 관리 플로를 제공할 수 있습니다.

잠재적 사용 사례:

광고주는 파트너 UI를 사용하여 게이트웨이에 온보딩하고 게이트웨이 관리자 설정을 통해 후속 작업을 수행합니다. 이를 위해서는 컨트롤 플레인 API를 부분적으로 통합해야 합니다.
광고주는 게이트웨이 온보딩, 후속 작업 등을 포함하여 파트너 UI에서 모든 작업을 수행합니다. 이는 게이트웨이 UI를 노출하고 싶지 않으나 광고주에게 게이트웨이를 서비스로 제공하고자 하는 파트너에게 좋은 사용 사례가 될 수 있습니다. 이를 위해서는 컨트롤 플레인 API를 완전히 통합해야 합니다.

통합 단계에 대한 자세한 내용은 아래 섹션을 참조하세요.

이 문서에서 복수 계정 컨트롤 플레인 API용 전환 API 게이트웨이 또는 게이트웨이는 같은 의미로 사용됩니다.

통합 가이드

사용 사례에 따라 두 가지 통합 경로를 사용할 수 있습니다(아래 다이어그램 참조).

컨트롤 플레인 API를 부분적으로 통합합니다. 이 경우에는 광고주 인증이 필요하지 않습니다.
컨트롤 플레인 API를 전체적으로 통합합니다. 이 경우 Meta Business 확장 도구(MBE)를 사용하거나 토큰을 수동으로 생성하여 광고주의 인증을 받아야 합니다.

필수 조건

두 가지 통합 경로 모두 파트너가 먼저 아래 단계를 완료해야 합니다.

1단계: 게이트웨이 인스턴스의 호스트로 온보딩

2단계: API 계정 이름 API secret key 생성

이동 경로:

https://<Conversions API Gateway Endpoint>/hub/

호스트 설정 탭으로 이동하여 API 계정 관리 페이지를 선택하고 API 추가 계정 버튼을 클릭합니다.

비밀번호를 다시 입력합니다. 계속을 클릭합니다.

API 계정의 이름을 입력합니다. 계속을 클릭합니다.

계정 이름은 문자와 숫자로만 구성할 수 있으며 공백을 포함할 수 없습니다. 최대 길이는 20자입니다.

생성된 secret key를 복사하여 저장합니다. 이 secret key는 다시 볼 수 없습니다.

API 계정을 삭제하려면 API 계정 삭제를 클릭합니다. 이 작업은 되돌릴 수 없으며, API를 사용하는 광고주 앱이나 서비스가 중단될 수 있습니다.

부분적 통합

부분적 통합에 기반한 사용 사례:

광고주가 파트너 UI를 사용하여 게이트웨이 서비스를 옵트 인합니다.
파트너가 초대 링크를 생성합니다. 이 링크는 광고주가 비밀번호를 설정하고 게이트웨이 계정 생성을 완료하는 데 사용할 수 있습니다.
광고주는 게이트웨이 UI의 기능을 사용하여 데이터 소스 관리와 계정 사용자, 도메인 및 라우팅 관리 등과 같은 작업을 수행합니다.
파트너는 이에 따라 광고주의 계정 사용량과 청구서를 가져옵니다.

간략한 사용자 플로는 다음과 같습니다.

위와 같이 구현하기 위해서는 파트너가 다음 작업을 포함하여 컨트롤 플레인 API의 하위 집합을 통합할 수 있습니다.

API 액세스 토큰 가져오기
광고주를 위한 계정 만들기
계정 사용량 가져오기(예: 청구 목적)

완전한 통합

완전한 통합에 기반한 사용 사례:

광고주가 파트너 UI를 사용하여 게이트웨이 서비스를 옵트 인합니다.
파트너가 광고주 게이트웨이 계정을 온보딩하고 계정 관리 권한을 받습니다. 광고주가 Meta Business 확장 도구(MBE) 또는 수동 토큰 생성을 사용하여 파트너를 승인합니다.
광고주는 파트너 UI에서 계정 사용자, 도메인 및 라우팅 관리와 데이터 소스 관리를 수행할 수 있습니다.
파트너는 이에 따라 광고주의 계정 사용량과 청구서를 가져옵니다.

간략한 사용자 플로는 다음과 같습니다.

이 통합 경로의 경우 파트너는 승인을 요청하고 인증을 통해 시스템 사용자 액세스 토큰을 받아야 광고주를 대신해서 이벤트를 전송할 수 있습니다.

인증

파트너는 자신이 관리하지 않는 Meta 픽셀에 대해 다음과 같은 두 가지 인증 옵션을 사용할 수 있습니다.

옵션 1 - Meta Business 확장 도구(MBE)

시작하기 전에 다음과 같은 준비 작업이 필요합니다.

MBE를 구현하기 위한 모든 요구 사항을 완료합니다.
Meta 담당자에게 비공개 권한 open_bridge_configuration_management의 허용 리스트에 앱을 추가해줄 것을 요청합니다.

MBE는 광고주 비즈니스 관리자에서 생성한 시스템 사용자 액세스 토큰을 가져오는 엔드포인트를 제공합니다. 파트너는 MBE 통합 가이드의 4단계까지 따라 할 수 있습니다. 다음 사항을 확인하세요.

설정 구성 개체의 채널 매개변수 값을 CONVERSIONS_API_GATEWAY_ADVERTISER로 설정했는지 확인합니다.
온보딩을 완료하고 나서 Webhooks 응답을 수신할 수 있는지 확인합니다.
MBE를 통해 반환된 액세스 토큰을 사용하여 추가 API 호출을 보내 시스템 사용자 액세스 토큰으로 변환했는지 확인합니다.
시스템에 external_business_id, pixel_id, business_id의 사본과 시스템 사용자 액세스 토큰을 저장했는지 확인합니다.

옵션 2 - 클라이언트 시스템 사용자 액세스 토큰

파트너는 이 옵션을 사용하여 광고주에게 다음과 같은 기능을 제공할 수 있습니다.

이벤트 관리자(EM)의 설정 내에서 전환 API를 통해 시스템 사용자 액세스 토큰을 수동으로 생성합니다.
pixel_id, business_id 및 시스템 사용자 액세스 토큰을 파트너에게 공유하고 해당 사본을 저장합니다.

통합

파트너는 컨트롤 플레인 API의 전체 세트를 통합할 수 있습니다. 자세한 내용은 API 참고 자료를 참조하세요.

API 및 UI 패리티

Meta는 게이트웨이 UI에서 사용된 것과 동일한 API 엔드포인트를 노출하여 API 및 UI 패리티를 적용하고 있습니다. 그러나 API 참고 자료에서 다루지 않는 API 엔드포인트는 향후 개발에서 변경될 수 있습니다. 예상치 못한 영향을 최소화하기 위해 API 참고 자료에서 다루지 않는 API 엔드포인트는 오류 코드: 418을 반환합니다. API는 여전히 사용할 수 있지만 위험 부담은 스스로 감수해야 합니다.