POST /events는 픽셀이 브라우저에서 보내는 것과 같은 이벤트를 받으므로, 픽셀이 실행되지 않는 곳에서 발생한 전환을 보고할 수 있습니다. CRM에서 성사된 판매, 자체 백엔드에서의 결제, 양식이나 예약 도구의 웹훅, 담당자가 예약 완료로 표시한 통화 등이 여기에 해당합니다.
시작하기 전에 세 가지가 필요합니다:
- 퍼널의 모든 페이지에 설치된 Whop Pixel. 이 가이드에서 전달하는 방문자 ID를 생성합니다.
event:create권한이 있는 API 키. Account API Keys에서 키를 생성하고 서버에 보관하세요. 절대 브라우저 코드에 넣지 마세요.- 계정 ID. 대시보드 URL에서
dashboard/뒤에 오는biz_로 시작하는 부분입니다.
Events API를 사용해야 하는 경우
대부분의 통합에는 필요하지 않습니다. 픽셀은 이미 브라우저에서 발생하는 모든 것을 보고하며, 방문자 ID, IP 주소, 사용자 에이전트를 자동으로 채웁니다. 전환이 발생했다는 사실을 서버만 알고 있는 경우에만 Events API를 사용하세요. 액션이 발생하는 곳에서whop.track 호출을 실행할 수 있다면 그것을 대신 사용하세요.
서버 이벤트 보내기
브라우저에서 방문자 ID 읽기
픽셀은 각 방문자의 ID를 도메인의 각 서브도메인은 자체
_wuid라는 퍼스트 파티 쿠키에 저장하고, 같은 키로 localStorage에도 복제합니다. 값은 wuid_k3j9x2m1p8q4r7s0t5u6과 같은 형태입니다. 페이지 로드 시점이 아니라 나중에 보고할 액션을 방문자가 수행하는 순간에 읽으세요. 쿠키는 페이지에서 픽셀 스니펫이 실행된 후에만 존재합니다.Read the visitor ID
_wuid를 가집니다. 픽셀이 이를 한 사람으로 연결하므로, 전달이 일어나는 페이지에 있는 쿠키를 읽으세요.액션과 함께 서버로 보내기
액션을 백엔드로 전달하는 기존 요청(양식 제출, 결제 호출, 가입 요청)에 방문자 ID를 첨부하세요. 동시에 페이지 URL도 캡처하세요. 페이지 URL에는 서버가 달리 볼 수 없는 UTM과 클릭 ID가 포함되어 있습니다.백엔드가 페이지와 같은 호스트에서 응답한다면
_wuid 쿠키가 요청과 함께 자동으로 도착합니다. 브라우저에서 보내는 대신 거기서 읽으세요. 쿠키는 해당 호스트에만 설정되므로 example.com에서 api.example.com으로 보내는 요청에는 포함되지 않습니다.서버는 이미 해당 요청에서 방문자의 IP 주소와 사용자 에이전트를 볼 수 있습니다. 둘 다 보관하세요.고객 레코드에 저장
방문자 ID, 페이지 URL, IP 주소, 사용자 에이전트를 리드, 고객 또는 주문에 저장하세요. 보고하는 전환은 방문 후 며칠이 지나서 발생할 수 있습니다. 영업팀이 다음 주에 성사시키는 거래도 귀속을 위해 원래 방문의 방문자 ID가 필요합니다. Whop은 최대 28일 전의 이벤트까지 받습니다.
이벤트 보내기
API 키를 사용하여 서버에서 이벤트를 보내세요. 이 예시는 광고를 통해 도착하여 견적 양식을 작성한 후 CRM에서 적격 판정을 받은 방문자의 리드를 보고합니다.예시의
url은 방문자가 Meta에서 Whop 광고를 탭한 후 도착하는 페이지입니다. utm_meta_ad_id, utm_meta_adset_id, utm_meta_campaign_id는 네트워크의 ID입니다. wacid, wasid, waid는 Whop 캠페인, 광고 그룹, 광고 ID입니다. utm_source는 노출 영역(fb, ig, msg 또는 an)을, utm_placement는 게재 위치를, utm_content와 utm_adset은 광고 및 광고 그룹 이름을 나타내며, fbclid는 네트워크가 직접 추가하는 태그입니다. Whop은 이 값들로 어떤 광고가 방문을 유도했는지 판단하므로, 매개변수를 골라내지 말고 URL 전체를 저장하세요.응답은 저장된 이벤트 ID를 반환합니다. Whop은 서로 다른 계정의 ID가 충돌하지 않도록 event_id 앞에 계정을 접두사로 붙입니다:올바른 사람에게 기록되었는지 확인
이벤트 목록 조회는 방문자 ID를 서버 이벤트는 같은
identifier로 받으므로, 이벤트가 합류한 전체 여정을 읽을 수 있습니다. 요청에는 company:basic:read와 같은 읽기 권한이 있는 키가 필요합니다.cURL
person_id로 픽셀의 페이지 조회 옆에 표시됩니다. 페이지 조회는 있는데 이벤트가 없다면 방문자 ID가 일치하지 않은 것입니다. 문제 해결을 참조하세요. 이벤트는 대시보드의 Events 페이지에도 표시됩니다.귀속을 결정하는 매개변수
account_id와 event_name만 필수입니다. 나머지 페이로드가 이벤트를 귀속 가능하게 만들므로, 이것들도 필수로 취급하세요.
전체 요청 스키마는 이벤트 생성 레퍼런스 페이지에 있습니다.
이벤트 이름 지정
픽셀과 같은 이름을 사용하세요. 서버에서 보고한lead는 픽셀이 보고한 lead와 같은 이벤트로 기록되므로, 리드를 기준으로 평가되는 캠페인의 결과에 반영됩니다.
그 외의
event_name은 해당 이름의 커스텀 이벤트가 됩니다. 이름은 짧고 일관되게 유지하고, 소수의 이름을 재사용하세요.
Custom event
중복 이벤트 방지
같은 전환이 브라우저와 서버 양쪽에서 Whop에 도달할 수 있다면, 같은event_name과 같은 event_id로 양쪽에서 보내세요. Whop은 하나의 사본만 유지합니다. 양식이 제출 시 whop.track("lead", { event_id })를 실행하고 백엔드가 검증 후 같은 리드를 다시 보고하는 경우 가장 안전한 설정입니다.
event_id는 액션의 유형이 아니라 하나의 액션을 식별합니다. 모든 리드에는 고유한 ID가 필요합니다. 전송 시점에 만들어낸 값은 매번 새로운 값이므로 아무것도 막지 못합니다. 시스템에 이미 있는 해당 액션의 ID를 사용하세요.
문제 해결
이벤트는 저장되었지만 광고에 귀속되지 않습니다. 이벤트에user.anonymous_id가 없거나, 픽셀이 사용한 적 없는 값이 포함되었습니다. 일반적인 원인은 픽셀 스니펫이 실행되기 전에 쿠키를 읽었거나, 픽셀이 없는 도메인에서 읽었거나, 잘못된 레코드에 방문자 ID를 저장한 경우입니다. 해당 방문자 ID의 이벤트를 나열하여 수정을 확인하세요. 픽셀의 페이지 조회가 이벤트와 같은 identifier 아래에 표시되어야 합니다.
event_time에 대한 메시지와 함께 400. 타임스탬프가 28일보다 오래되었습니다. 이벤트가 발생한 시점에 더 가깝게 보내거나 버리세요.
purchase 이벤트에서 400. value가 없거나 0보다 크지 않습니다. 광고 네트워크는 금액이 없는 판매를 기준으로 최적화할 수 없으므로 Whop이 거부합니다.
401 또는 403. 키가 없거나, event:create 권한이 없거나, account_id와 다른 계정에 속합니다. 프로덕션 키는 https://api.whop.com/api/v1을 사용합니다.
