전환 API 엔드투엔드 구현

전환 API는 소비자에게 적절한 데이터 투명성 및 관리 기능과 지속적으로 개인화된 경험을 제공하고자 하는 광고주의 노력을 지원합니다. 이 API를 통해 브라우저 대신 서버에서 직접 데이터를 공유할 수 있습니다.

통합의 이점

• 퍼널 하단 가시성: 전환 API를 사용하면 Meta 픽셀에 비해 더 광범위한 데이터 배열을 공유할 수 있습니다. 이 API를 통해 CRM 데이터, 하위 퍼널 이벤트(가치 높은 잠재 고객 포함), 웹사이트 및 오프라인 매장에 걸친 여러 사이트 전환 경로 등 더 많은 정보를 고려하며 결정을 내릴 수 있습니다.

• 데이터 관리: 서버 전용 구현을 통해 사용하면(예: Meta 픽셀 없이) 전환 API를 통해 공유하는 데이터를 더 세부적으로 관리할 수 있습니다. 이벤트에 인사이트를 추가하여 제품 수익이나 과거 정보(예: 고객 가치 점수)와 같은 데이터를 제공할 수도 있습니다.

• 시그널 신뢰성 및 회복성: 전환 API를 통해 데이터를 공유하면 Meta 픽셀과 같은 브라우저 기반 방법을 단독으로 사용할 때보다 신뢰성이 더 높아질 수 있습니다. 이 API는 브라우저 충돌이나 연결 문제 등과 같은 문제에 덜 취약하도록 설계되었습니다. 새로운 업계 데이터 전송 제약으로 인해 쿠키 및 픽셀 추적의 효과가 제한될 수 있는 상황에서 전환 API를 사용하면 더 이상 픽셀로 감지하지 못할 수 있는 시그널을 공유할 때 더 세부적인 관리가 가능합니다.

개요

전환 API 통합은 다음과 같은 두 가지 주요 단계로 구성되어 있습니다.

• 준비 — 본인에게 적합한 통합 유형을 선택하고 보낼 이벤트를 정의하고 사용 가능한 최적화 옵션을 검토합니다.

• 실행 — API 구현 방법을 알아봅니다. 이 단계에서 파트너 통합을 사용할 수도 있습니다.

다음은 전체 통합 절차에 대한 간단한 설명입니다.

기존의 픽셀 사용자

기존의 Meta 픽셀 통합 기능이 있는 경우 전환 API 통합 기능을 완전히 다른 연결이 아니라 기존 픽셀 통합의 확장 기능으로 만들어야 합니다.

일반적인 동의

픽셀 데이터 공유와 관련하여 동의를 관리하기 위한 로직이 있다면 전환 API를 통해 데이터를 공유할 때도 동일한 로직을 사용하면 됩니다.

대안

• 광고를 앱 이벤트에 맞게 최적화하고 싶다면 앱 이벤트 API를 사용하세요.

준비

통합 유형 선택

시작하려면 구현하려는 통합 옵션을 선택하세요.

보낼 이벤트 정의하기

통합 접근 방식을 선택한 후 보내려는 이벤트를 정의할 수 있습니다. Meta 사용자 ID에 매칭될 경우 시그널이 가장 유용하므로 이벤트와 함께 Meta에 보내는 매개변수와 전송 빈도에 대해 충분히 생각해 보는 것이 중요합니다.

이벤트 옵션

비즈니스와의 관련성이 가장 높은 이벤트를 보냅니다. 지원되는 표준 및 맞춤 Meta 이벤트의 전체 리스트를 확인하세요.

이벤트 매개변수

각 이벤트 안에 여러 매개변수를 보낼 수 있습니다. 이러한 필드에 대해 자세히 알아보려면 전환 API에 사용되는 매개변수를 참조하세요.

event_id, external_id, order_id 등 다양한 유형의 ID를 이벤트에 추가할 수 있습니다. 이러한 매개변수의 차이점을 아는 것이 중요합니다.

데이터 새로 고침

전환 API를 통해 특정 일정에 따라 일괄적으로 또는 실시간으로 이벤트를 보내는 것이 좋습니다. 실시간이나 1시간 내에 이벤트를 보내면 해당 이벤트를 성과 기여에 활용하고 광고 게재에 최적화할 수 있습니다.

발생한 지 2시간 이후에 이벤트를 보내면 해당 이벤트에 최적화된 광고의 성과가 크게 저하될 수 있습니다. 24시간 이상 이후에 이벤트를 보내면 성과 기여 및 최적화된 광고 게재에 상당한 문제가 발생할 수 있습니다.

전환 기간이 긴 이벤트를 보내는 경우 완전한 전환이 이루어지는 시점으로부터 가능한 한 실시간에 가깝게 이벤트를 보내세요.

아래를 완료한 후 다음 단계를 진행하세요.

• 보낼 이벤트 리스트 정의
• 각 이벤트와 함께 보내려는 특정 필드 확인
• 이벤트 전송 빈도 정의

사용 가능한 최적화 유형

전환 API는 다음과 같은 최적화 유형을 제공합니다.

실행

통합을 구현하는 방법은 두 가지가 있습니다.

• 직접 통합 - 광고주가 직접 전환 API를 구현합니다.
• 플랫폼으로 통합 - 마케팅 파트너가 클라이언트에게 전환 API를 서비스로 제공합니다.

직접 통합

1단계: 요구 사항 설정하기

전환 API를 사용하기 전에 다음 자산을 설정하세요.

자산을 준비한 후 API 구현하기를 진행하세요. API 호출 시 사용하므로 자산 ID를 저장해야 합니다.

2단계: API 구현하기

요구 사항을 다 설정한 후 구현 절차를 시작하세요. 전환 API를 만드는 동안 항상 개발자 문서를 확인해야 합니다.

테스트 호출(선택 사항)

처음으로 API를 사용하는 경우 먼저 테스트 호출을 진행하세요. 이렇게 하려면 페이로드와 API 호출을 위한 메서드가 필요합니다. 호출이 완료된 후 이벤트 관리자에서 호출이 예상대로 작동했는지 확인하세요.

{
  "data": [
   {
    "event_name": "Purchase",
    "event_time": 1601673450,
    "user_data": {
      "em": "7b17fb0bd173f625b58636fb796407c22b3d16fc78302d79f0fd30c2fc2fc068",
      "ph": null
     },
    "custom_data": {
      "currency": "USD",
      "value": "142.52"
    }
   }
  ]
}

{
  "events_received": 1,
  "messages": [],
  "fbtrace_id": <FB-TRACE-ID>
}

첫 번째 호출을 완료한 후 이벤트 관리자 > 내 픽셀 > 개요에서 이벤트를 확인합니다.

이벤트 관리자에서 테스트 이벤트를 확인한 후 이벤트 전송 및 확인하기를 진행하세요.

이벤트 전송 및 확인하기

이벤트 전송을 시작하려면 API의 /events 에지에 POST 요청을 보내세요. 그리고 호출에 페이로드를 첨부합니다. 페이로드를 생성하는 데 도움이 필요하다면 페이로드 도우미를 방문하세요. 자세한 내용과 코드 샘플은 다음 리소스를 참조하세요.

• API 사용하기 > 요청 보내기
• 삭제된 이벤트
• 업로드 시간과 이벤트 거래 시간 비교
• 일괄 요청
• 해시 처리

이벤트 전송을 시작한 후에 이벤트 관리자로 이동하여 Facebook이 해당 이벤트를 받았는지 확인합니다. 이벤트 확인 방법을 알아보세요.

구현이 브라우저 픽셀과 상호 보완적인 작업이라면 중복 제거 설정을 진행하세요. 그렇지 않다면 준비가 끝났습니다! 여전히 궁금한 점이 있다면 지원을 확인하세요.

3단계: 중복 제거를 위한 매개변수 추가하기

픽셀과 전환 API를 통해 동일한 이벤트를 보내는 경우 두 채널을 통해 보내는 이벤트에 대해 중복 제거를 설정해야 합니다. 먼저 개발자 문서를 읽어 중복 제거 로직을 이해합니다.

이벤트 기반 중복 제거

48시간 이내에 동일한 서버 키 조합(event_id, event_name) 및 브라우저 키 조합(eventID, event)이 동일한 픽셀 ID로 전송된 것이 확인되면 Facebook에서 나중에 전송된 중복 이벤트를 삭제합니다.

이벤트의 중복을 제거하려면 다음과 같이 하세요.

• 해당하는 이벤트에 대해 다음 매개변수를 동일한 값으로 설정합니다.

  • 서버 이벤트의 event_id와 브라우저 이벤트의 eventID
  • 서버 및 브라우저 이벤트의 event_name
• 중복 이벤트를 보낸 후 이벤트 관리자에서 올바른 이벤트가 삭제되었는지 확인합니다.
• 픽셀과 전환 API 둘 다를 통해 전송된 각 고유한 이벤트에 자체 event_id가 있는지 확인합니다. 이 ID를 다른 이벤트와 공유해서는 안 됩니다.

이벤트 기반 중복 제거의 대안

이벤트 ID가 항상 이벤트의 중복을 제거하는 최선의 방법이지만 구현이 상당히 복잡합니다. external_id 또는 fbp 매개변수를 사용하여 대체 솔루션을 활용할 수 있습니다. external_id 또는 fbp 매개변수를 브라우저와 서버 모두를 통해 전달되도록 구성했다면 48시간 이내에 동일한 external_id 또는 fbp 매개변수가 지정된 동일한 이벤트가 발견될 경우 해당 이벤트의 중복이 자동으로 제거됩니다.

선택 사항 4단계: 비즈니스 SDK 기능 둘러보기

Meta 비즈니스 SDK에는 전환 API 사용자를 위해 특별히 설계된 다음과 같은 고급 기능이 있습니다.

• 비동기 요청 - 요청이 완료될 때까지 기다리기 위해 프로그램의 실행을 차단하고 싶지 않다면 이 기능을 사용합니다. 이 접근 방식에서는 요청을 보내고 요청 완료 후 서버로부터 다시 시그널을 받습니다. 응답을 기다리는 동안 프로그램을 계속 실행할 수 있습니다.
• 동시 일괄 처리 - 비동기 요청을 활용하여 더 효율적으로 리소스를 활용하는 방식으로 처리량을 늘립니다. 이벤트 요청 작업자, cron 작업 등과 같은 사용 사례를 지원하려면 일괄 처리된 요청을 만드세요.
• HTTP 서비스 인터페이스 - 비즈니스 SDK의 기본 HTTP 서비스를 재정의하고 원하는 메서드 또는 라이브러리를 사용하여 자체 맞춤 서비스를 구현합니다.

플랫폼으로 통합

다음은 광고주에게 전환 API를 서비스로 제공하는 파트너를 위한 안내입니다.

1단계: 요구 사항 설정하기

앱에서 다음과 같은 기능과 권한을 얻어야 합니다.

• 액세스 레벨: Advanced Access
• 기능: 광고 관리 표준 액세스
• 권한: ads_management, pages_read_engagement 및 ads_read.

2단계: 클라이언트 대신 이벤트 보내기

먼저 직접 통합 단계를 따르고 통합을 테스트합니다. 그런 다음 클라이언트 대신 이벤트를 보내기 위한 승인을 요청할 수 있습니다. 사용 가능한 인증 옵션은 다음과 같습니다.

Meta Business 확장 도구 접근 방식(권장)

Meta Business 확장 도구는 다음 절차를 통해 클라이언트 대신 이벤트를 보내는 데 필요한 모든 정보를 반환합니다. Meta Business 확장 도구는 클라이언트의 비즈니스 관리자에서 생성된 시스템 사용자 액세스 토큰을 가져오기 위해 엔드포인트를 제공합니다. 이 절차는 서버 이벤트를 보내기 위한 권한을 포함하며 안전하게 자동으로 처리됩니다.

엔드포인트에는 입력 매개변수로 사용자 액세스 토큰이 필요합니다. 새로운 Meta Business 확장 도구 사용자의 경우 Meta Business 확장 도구 설정을 완료한 후 이 엔드포인트를 호출하여 시스템 사용자 액세스 토큰을 가져오면 됩니다. 기존 사용자는 새로운 API 엔드포인트를 호출하기 전에 재인증을 요청해야 합니다.

클라이언트 시스템 사용자 액세스 토큰

클라이언트가 픽셀 설정 내에서 전환 API를 통해 시스템 사용자 액세스 토큰을 수동으로 만들도록 합니다. 그런 다음 해당 토큰으로 광고주의 픽셀에 이벤트를 보냅니다.

시스템 사용자 또는 관리자 시스템 사용자는 액세스 토큰 생성에 사용될 앱을 설치해야 합니다. 이 설정을 통해 앱이 이 시스템 사용자 또는 관리자 시스템 사용자 대신 API를 호출할 수 있게 됩니다.

클라이언트가 파트너의 비즈니스 관리자에 픽셀 공유

이 옵션에서는 클라이언트가 비즈니스 관리자 설정이나 API를 통해 파트너에게 자신의 픽셀을 공유합니다. 그러면 파트너가 파트너 시스템 사용자를 클라이언트 픽셀에 할당하고 서버 이벤트를 보내기 위한 액세스 토큰을 생성할 수 있습니다.

3단계: 이벤트를 파트너 플랫폼으로 인해 발생한 것으로 설정하기

전환 API 이벤트를 파트너 플랫폼으로 인해 발생한 것으로 설정하려면 partner_agent 필드를 사용합니다. 이렇게 하면 클라이언트 대신 이벤트를 보낼 때 자체 플랫폼 식별자를 설정할 수 있습니다. Meta 담당자가 지정되어 있는 파트너의 경우 해당 Meta 담당자와 함께 플랫폼을 위한 식별자를 정하면 됩니다. 이 값은 23자 미만 형식이어야 하며, 영문자를 두 개 이상 포함해야 합니다. 그런 다음 각 서버 이벤트와 함께 보냅니다.

지원

모든 파트너

디버깅에 관한 정보와 비즈니스 고객 센터 도움말을 참조하세요.

Meta 담당자가 지정되어 있는 파트너

Meta 담당자에게 비즈니스 관리자 ID, 앱 ID, 픽셀 ID를 제공하세요. 그러면 담당자가 통합 테스트 및 문제 해결에 도움을 줄 수 있습니다.

API 문서

• 시작하기 - 자체 비즈니스 관리자에서 API 테스트하기
• API 사용하기
• 모범 사례 - 전환 API
• 플랫폼으로 전환 API 설정하기
• 표준 Meta 이벤트
• 맞춤 Meta 이벤트
• 매개변수
• 페이로드 도우미
• 전환 API 및 오프라인 전환 API를 위한 데이터 처리 옵션
• 앱 이벤트에 맞게 최적화하려는 경우 앱 이벤트 API 사용
• 이벤트가 매장 판매인 경우 오프라인 전환 API 사용 - 매장 판매가 아닌 오프라인 이벤트의 경우 전환 API를 사용할 수 있음