전환 API
한국어 버전으로 돌아가기
문서가 업데이트되었습니다.
한국어로 번역이 아직 완료되지 않았습니다.
영어 업데이트됨: 4월 22일

3: 개발자 구현

이 페이지에서는 수동 통합과 관련하여 다음과 같은 내용을 다룹니다.

이 섹션은 수동 통합과 개발자 리소스를 사용하여 이 통합을 완료하기로 결정한 경우에만 적용됩니다. 대신 파트너를 사용하여 이 통합을 완료하기로 결정한 경우에는 각 파트너의 통합 지침을 따르세요. 파트너 통합이 완료되면 이 가이드의 4: 데이터 인증 섹션으로 건너뛸 수 있습니다.

이러한 통합 단계를 완료하려면 비즈니스 관리자의 관리자 액세스 권한이 필요합니다. 개발자로 초대된 경우에는 자신에게 전송된 이메일에서 액세스 권한을 얻을 수 있습니다. 그렇지 않은 경우 비즈니스 관리자의 관리자에게 액세스 권한을 요청하세요.

1단계: 페이로드 빌드

이 단계에서는 전환 잠재 고객 통합을 위한 페이로드 사양을 설명하고 서버에서 페이로드를 보내는 방법에 대한 몇 가지 권장 사항을 제공합니다.

  1. CRM 픽셀의 설정 탭에서 CRM 통합 가이드를 열어서 시작합니다.

  2. 전환 API 개발자 가이드를 검토하여 전환 API가 어떻게 작동하는지 파악합니다.

  3. 페이로드를 빌드하려면 페이로드 도우미를 사용하는 것이 좋습니다. 페이로드 도우미는 페이로드의 형식을 지정하고 오류를 확인합니다. 모든 페이로드 오류가 해결되고 나면 페이로드 도우미 내에서 코드 가져오기 버튼을 클릭하여 프로그래밍 언어에 맞는 코드 템플릿을 생성합니다.

  4. 필수 매개변수의 리스트는 다음과 같습니다. 각 매개변수에 대한 전체 설명을 확인하려면 전환 잠재 고객 통합 - 페이로드 사양 가이드를 참조하세요. 이 페이로드 사양은 전환 잠재 고객 최적화 이벤트에만 사용해야 합니다. 즉, 이벤트는 Meta 잠재 고객용 광고와만 관련되고 유효한 잠재 고객 ID가 있어야 합니다. 다른 이벤트 유형(예: 웹사이트 잠재 고객)에 이 페이로드 사양을 사용하지 마세요.

    매개변수
    이름설명

    event_name

    문자열

    CRM 내에서 사용하는 잠재 고객 단계를 캡처하기 위한 자유 양식 필드입니다.

    event_name 매개변수는 CRM의 판매 퍼널을 통해 이동하는 잠재 고객을 나타내야 합니다. 원본 잠재 고객을 포함하여 모든 단계를 업데이트 즉시 전송하세요.

    event_time

    정수

    CRM이 잠재 고객 단계 업데이트 이벤트를 업데이트하는 시점을 나타내는 Unix 타임스탬프(초)입니다.
    타임스탬프는 잠재 고객 확보 시간 이후여야 하며 그렇지 않으면 이벤트가 취소될 수 있습니다.

    action_source

    문자열

    값:system_generated


    (전환 API를 사용하면 자신이 아는 한도 내에서 action_source 매개변수가 정확하다는 데 동의하는 것으로 간주됩니다.)

    lead_id

    정수

    다운로드된 잠재 고객에서 얻은 15~16자리 leadgen_id입니다.

    lead_event_source

    문자열

    이벤트가 발생한 CRM의 이름입니다.

    event_source

    문자열

    값:crm



    예
    예시 페이로드는 다음과 같습니다. 참고: 유효한 lead_id를 사용해야 하며, 그러지 않으면 시스템이 이벤트를 거부합니다. 
    {
    "data": [
        {
            "event_name": "initial_lead",
            "event_time": 1629424350,
            "action_source": "system_generated",
            "user_data": {
                "lead_id": 525645896321548
            },
            "custom_data": {
                "event_source": "crm",
                "lead_event_source": "salesforce"
            }
        }
    ]
}

  5. 이벤트가 페이로드 사양을 준수하지 않거나 Meta 잠재 고객용 광고와 일치하지 않는 경우, 해당 통합에 대해 인식되지 않고 모델을 훈련하는 데 사용되지 않습니다.
    예를 들어, 웹 페이로드는 전환 API에 의해 수락되고 이벤트 관리자에 표시되겠지만 이 통합에 대해서는 인식되지 않습니다. 또한 유효한 lead_id를 사용해야 하며, 그러지 않으면 시스템이 이벤트를 거부합니다.
    전환 잠재 고객 페이로드만 해당 통합에 대해 인식되고 훈련에 사용됩니다.

2단계: 액세스 토큰 및 API 호출 생성

무엇을 보낼지 구성하고 난 후에는 데이터를 보낼 곳을 구성해야 합니다.

이 단계에서는 Meta 픽셀용 액세스 토큰을 생성하는 데 도움을 드립니다. 그런 다음, 이 액세스 토큰을 사용하여 서버와 전환 API를 연결할 수 있습니다.

  1. CRM 픽셀의 설정 탭에서 CRM 통합 가이드로 돌아올 수 있습니다.

  2. 아래로 스크롤하여 엔드포인트 만들기 섹션으로 이동하고 액세스 토큰 생성 버튼을 클릭합니다. 액세스 토큰은 API 호출을 빌드하는 데 사용됩니다.
    새로운 액세스 토큰을 생성하려면 통합 가이드로 돌아가거나, 이벤트 관리자의 설정 탭에서 전환 API 섹션으로 이동하고 액세스 토큰 생성 링크를 클릭하면 됩니다.

  3. 이 가이드의 나머지 내용은 회원님이 Meta SDK를 사용하는지에 따라 달라집니다. 더 나은 오류 및 진단 메시지를 제공하는 Meta Business SDK를 사용하는 것이 좋습니다. Meta Business SDK를 통해 API 호출을 보내려면 픽셀 ID와 액세스 토큰이 필요합니다. CRM 통합 가이드에서 액세스 토큰 복사를 클릭하고 저장하면 액세스 토큰을 받을 수 있습니다. SDK API 호출의 예시는 전환 API 개발자 가이드 또는 Meta 페이로드 도우미의 코드 가져오기 기능에서 확인할 수 있습니다.

  4. 이는 SDK 없이 전환 API에 POST 요청을 보내기 위한 엔드포인트 형식입니다. CRM 통합 가이드에서 엔드포인트 복사를 클릭하고 저장하면 엔드포인트 전체를 가져올 수 있습니다. 
    https://graph.facebook.com/API_VERSION/PIXEL_ID/events?access_token=ACCESS_TOKEN
    • API_VERSION: 현재 마케팅 API 버전
    • PIXEL_ID: 픽셀 ID는 각 픽셀에 대해 이벤트 관리자로부터 얻을 수 있음
    • ACCESS_TOKEN: 위에서 생성한 액세스 토큰
  5. 마케팅 API 릴리스 및 만료 날짜는 API 버전 문서에서 확인할 수 있습니다. 마케팅 API 만료 날짜 전에 코드에서 API 버전 또는 Meta Business SDK를 업데이트하세요. 코드에서 사용 중단된 버전을 사용하면 오류가 발생하고 시스템이 이벤트를 취소할 수 있습니다.

3단계: 페이로드 테스트(선택 사항)

이 시점에서는 서버에서 코드를 구현하기 전에 테스트 페이로드를 픽셀로 전송하는 것이 좋습니다. 이때 이벤트 관리자의 테스트 이벤트 탭을 사용하면 됩니다.

  1. 테스트 서버 이벤트 섹션에서 그래프 API 탐색기 링크를 클릭합니다. 이 고유 링크를 사용하면 픽셀에서 일부 정보를 가져와 미리 입력합니다. (원한다면 그래프 API 탐색기에 직접 액세스할 수도 있습니다.) test_event_code 값은 시간이 지나면서 변경될 수 있으므로 메모해 두세요.

  2. 그래프 API 탐색기 도구에서 다음을 완료하세요.
    1. POST 모드인지 확인합니다.
    2. API 버전과 픽셀 ID가 올바른지 확인합니다.
    3. JSON 보기로 전환합니다.
    4. 페이로드를 입력합니다. 페이로드는 수동으로 만들거나 페이로드 도우미를 사용하여 생성할 수 있습니다. 이전 단계의 test_event_code 매개변수와 유효한 lead_id를 포함하세요.
  3. 픽셀 액세스 토큰을 입력하고 제출 버튼을 클릭합니다.

  4. 페이로드에 구문 또는 API 오류가 포함되지 않은 경우 fbtrace_id가 포함된 성공 메시지를 수신하게 됩니다.

  5. 약간의 시간이 지난 후 테스트 이벤트가 이벤트 관리자의 테스트 이벤트 탭에 표시될 것입니다.

4단계: 프로덕션 데이터 보내기

프로덕션 데이터는 3단계에서 생성된 페이로드와 동일한 형식이지만 서버에서 데이터를 직접 전송한다는 점이 다릅니다. 이 단계는 통합마다 다르기 때문에 이 섹션에서는 단계별 설명보다는 가이드라인을 제공하게 될 것입니다.

  1. 매칭을 위해 PII가 아닌 lead_id를 전송합니다.

  2. Meta에서 생성되고 CRM에 다운로드된 모든 잠재 고객을 나타내는 원시 잠재 고객 이벤트를 포함하여 모든 잠재 고객 단계가 업데이트되는 대로 전송해야 합니다. 퍼널 예시는 아래와 같습니다. 이벤트 이름과 단계는 광고주가 정의하므로 이 예시를 따르지 않아도 됩니다.


    캠페인이 잠재 고객을 100명 확보하는 경우 첫 번째 잠재 고객 단계를 나타내기 위해 '원시 잠재 고객' 이벤트 100개가 업로드될 것입니다. 첫 번째 잠재 고객 단계를 전송하면 해당 잠재 고객이 수신되고 처리되었음을 시스템에 알리게 됩니다. 잠재 고객이 판매 퍼널을 따라 내려가는 동안, '마케팅 자격을 갖춘 잠재 고객' 70명, '판매 기회' 30개, '전환됨' 단계 15개가 업로드될 것입니다.

    요컨대 이 예시 캠페인에서는 잠재 고객 100명이 확보되지만 이벤트 215개가 업로드될 것입니다.

  3. 잠재 고객 상태가 업데이트될 때마다 CRM의 API 또는 데이터베이스에서 업데이트를 가져오는 함수를 만듭니다. 그런 다음에는 맞춤 함수 또는 Meta의 Business SDK를 사용하여 Meta의 전환 API로 페이로드를 전송합니다. 통합에 가장 적합한 것이 무엇인지는 CRM 및 데이터베이스 구성에 따라 달라집니다.

    변수는 다음에 대해 권장됩니다.
    • lead_id
    • event_name
    • event_time
    예를 들어 매개변수 값을 명시적으로 진술하는 페이로드는 다음과 같습니다. 
    {
  "event_name": "initial_lead",
  "event_time": 1628294742,
  "user_data": {
    "lead_id": 1234567890123456
  },
  "action_source": "system_generated",
  "custom_data:" {
    "lead_event_source": "Salesforce",
    "event_source": "crm"
  }
}
    변수를 사용하여 데이터베이스의 값을 전달하는 페이로드는 다음과 같습니다. 
    {
  "event_name": lead_stage // "initial_lead"
  "event_time": unix_time // 1628294742
  "user_data": {
    "lead_id": fb_lead_id // 1234567890123456
  },
  "action_source": "system_generated",
  "custom_data:" {
    "lead_event_source": "Salesforce",
    "event_source": "crm"
  }
}

  4. 데이터를 하루에 한 번 이상 업로드합니다. 이상적으로는 실시간으로 CRM에 호출을 보내야 하지만 실시간 통합이 불가능한 경우에는 시간당 또는 일일 단위로 일괄 처리하는 방법을 사용할 수 있습니다.
    일괄 처리 방법을 선택하는 경우 일괄 처리 시점의 잠재 고객 스냅샷이 아니라 잠재 고객 상태 변경 기록을 캡처해야 합니다. 예를 들어 잠재 고객 상태가 일괄 처리 사이에 3번 업데이트되는 경우 이 잠재 고객에 대해 최종 업데이트만이 아니라 3개의 이벤트가 존재해야 합니다.
    참고: 각 배치는 최대 1,000개의 이벤트를 포함할 수 있습니다. 일괄 처리에 오류가 있을 경우, 전체 일괄 처리가 취소되므로 일괄 처리 규모를 줄이고 재시도를 위한 로직을 추가할 것을 적극 권장합니다.

  5. 선택 사항. CAPI 호출에서 발생하는 오류 메시지를 로깅하고 문제가 있는 경우 알림을 만드는 것이 좋습니다. 이러한 오류에 대한 예외 처리도 도움이 됩니다.

  6. 과거 7일까지의 데이터를 백필링할 수 있습니다. event_time과 upload_time 사이의 시간 차이가 계산됩니다. 일부 데이터를 백필링하면 훈련 과정에 걸리는 시간이 단축될 수 있습니다.

    경고: event_time 값을 수정하여 8일분 이상의 데이터를 백필링하려고 하지 마세요. 이 모델은 정확한 타임스탬프를 사용해야 최적화됩니다. 이렇게 하면 모든 백필링된 데이터가 삭제될 수 있습니다.

  7. event_time 값이 잠재 고객 확보 타임스탬프 이후인지 확인합니다. 그렇지 않으면 이벤트가 취소될 수 있습니다.

  8. 통합에서 이벤트를 Meta에 업로드 중인 경우, 1시간 이내에 픽셀의 이벤트 관리자에 이벤트가 표시되기 시작할 것입니다. 이벤트가 표시되려면 페이로드에서 유효한 lead_id를 사용해야 합니다. 이벤트 관리자에서 전환 잠재 고객 CRM 통합에 대해 전송된 각 이벤트를 열고 맞춤 매개변수인 lead_event_source와 event_source가 입력되어 있는지 확인하세요. 이벤트에 이러한 매개변수가 없을 경우 전환 잠재 고객 이벤트로 등록되지 않습니다.
  9. 시스템에서 이벤트가 유효한 전환 잠재 고객 이벤트인지 인증합니다. 유효한 이벤트가 감지되면 1일 후에 통합의 CRM 이벤트 보내기 단계 옆에 녹색 체크 표시가 나타납니다.