Pixel & Conversion API한국어 구현 가이드

01 — 왜 시그널이 중요한가

성과 광고는 전환 시그널로 학습합니다.

Pixel이 놓친 전환은 리포트만 빠지는 것이 아닙니다. 입찰 알고리즘이 잘못된 사용자에게 예산을 쓰게 만들고, 실제로는 수익이 나던 캠페인을 끄게 만듭니다.

세 흐름은 모두 구조적이고 더 심해지는 추세입니다. 해결책은 브라우저를 거치지 않는 퍼스트파티 측정, 즉 광고주 서버에서 플랫폼으로 직접 보내는 데이터입니다.

시그널이 깨지면 일어나는 일

1. 1. 브라우저 Pixel이 전환을 전송 → iOS / 광고 차단 / ITP가 시그널을 가로챕니다.
2. 2. 플랫폼이 불완전한 데이터를 수신 → 알고리즘이 왜곡된 시그널로 학습합니다.
3. 3. 잘못된 오디언스에 입찰 → CPA가 오르고 ROAS가 떨어집니다.
4. 4. 캠페인을 멈추거나 이탈 → 실제로는 잘 되던 세트를 끄게 됩니다.

02 — 동작 방식

같은 전환, 전혀 다른 두 개의 파이프라인.

Pixel은 고객의 브라우저가 심부름을 보냅니다. CAPI는 광고주 서버가 플랫폼 서버에 직접 전화를 겁니다.

CAPI는 이메일·전화번호 같은 개인정보를 SHA-256으로 해시한 뒤 보냅니다. 플랫폼은 원문을 보지 않고도 사용자를 매칭할 수 있습니다. 설계상 프라이버시 친화적입니다.

다른 플랫폼에서의 같은 개념

03 — 항목별 비교

성과 광고주에게 중요한 차원만 나란히 봅니다.

CAPI가 대부분의 핵심 지표에서 앞섭니다. 다만 Pixel의 실시간 행동 시그널은 서버만으로는 대체하기 어렵습니다. 그래서 정답은 보통 둘 다입니다.

04 — 의사결정

대부분은 둘 다 운영해야 합니다.

우선순위와 긴급도는 트래픽 구성, 개발 리소스, 프라이버시 정책에 따라 달라집니다. 아래 세 가지 중 어디에 해당하는지 먼저 고르면 됩니다.

05 — 전환 이벤트

위는 볼륨, 아래는 가치. 퍼널을 그대로 매핑합니다.

표준 이벤트를 쓰세요. 플랫폼 알고리즘은 표준 이벤트 데이터로 학습합니다. 커스텀 이벤트는 최적화 지능이 약합니다. 핵심 이벤트는 5–10개면 충분합니다.

* Ads Manager에 없는 항목은 Custom 이벤트로 대체할 수 있습니다. 가능하면 표준 이벤트를 우선하세요.

06 — Direct 구현

Ads Manager에서 토큰을 발급하고, 서버에서 POST 합니다.

자체 웹 서버에 Conversion API를 직접 붙이는 경로입니다. 개발자 포털 승인이나 OAuth 1.0이 더 이상 필요하지 않습니다.

이 경로는 커스텀 테크 스택, 데이터 통제가 중요한 계정, 사내 엔지니어링 팀이 있는 경우, 매장 구매·CRM 이벤트 같은 오프라인 전환이 많은 경우에 맞습니다.

1. 01

   ads.x.com에 광고 계정으로 로그인합니다.

   측정 도구는 광고 계정 단위로 동작합니다. 올바른 계정을 선택했는지 확인하세요.
2. 02

   Tools(도구)에서 Events Manager를 엽니다.

   Tools 탭이 보이지 않으면 계정에 결제 수단이 없는 경우가 많습니다. 결제 수단을 추가한 뒤 다시 확인하세요.
3. 03

   Install Pixel에서 Conversion API를 선택합니다.

   화면 구성에 따라 Install Pixel → Conversion API, 또는 Install Pixel → Manual → Conversion API 경로로 들어갑니다. 여기서 Pixel ID와 Event ID를 확인할 수 있습니다.
4. 04

   액세스 토큰을 생성합니다.

   Generate Access Token으로 토큰을 발급하고 바로 복사하세요. 이후 모든 API 호출의 X-Pixel-Token HTTP 헤더에 이 값을 넣습니다. 토큰은 서버에만 보관하고 브라우저나 공개 저장소에 두지 마세요.
5. 05

   엔드포인트로 이벤트를 POST 합니다.

   POST https://ads-api.x.com/12/measurement/conversions/:pixel_id로 JSON 바디를 보냅니다. HTTP 200과 conversions_processed를 확인한 뒤, Conversion Diagnostics에서 수신 여부를 검증하세요.

07 — 요청 스펙

한 번의 POST로 전환을 전달합니다.

인증은 액세스 토큰 한 개입니다. 본문에는 conversions 배열을 넣습니다.

conversions[] 필드

curl -X POST "https://ads-api.x.com/12/measurement/conversions/PIXEL_ID" \
  -H "X-Pixel-Token: YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "conversions": [
    {
      "conversion_time": "2026-06-01T12:34:56.000Z",
      "event_id": "tw-yyyyy-xxxxx",
      "event_source_url": "https://www.example.com/checkout",
      "conversion_id": "order-9f8b7c6d",
      "value": "89000",
      "number_items": 1,
      "identifiers": [
        {
          "twclid": "23opevjt88psuo13lu8d020qkn",
          "hashed_email": "64hexchars_sha256",
          "hashed_phone_number": "64hexchars_sha256",
          "ip_address": "192.0.2.1",
          "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)"
        }
      ]
    }
  ]
}'

{
  "request": {
    "params": { "account_id": "18ce552mlaq" },
    "data": {
      "conversions_processed": 1,
      "debug_id": "ff02e052-36e4-47d6-bdf0-6d8986446562"
    }
  }
}

08 — 식별자

매칭 품질은 식별자 품질입니다.

식별자가 하나도 없으면 이벤트는 사용자에게 붙지 않습니다. twclid와 해시된 이메일을 함께 보내는 것이 가장 안정적입니다.

twclid 저장

사용자가 X 광고를 클릭하면 랜딩 URL에 twclid가 붙습니다. 결제 완료 페이지까지 쿼리가 유지되지 않는 경우가 많으므로, 도착 즉시 저장해 두었다가 전환 시 CAPI에 실어 보내세요.

const params = new URLSearchParams(window.location.search);
const twclid = params.get("twclid");
if (twclid) {
  localStorage.setItem("twclid", twclid);
}

import { createHash } from "node:crypto";

function sha256(value) {
  return createHash("sha256").update(value).digest("hex");
}

// 이메일: 앞뒤 공백만 제거 후 해시 (솔트 없음)
const hashedEmail = sha256("[email protected]".trim());
// d360d510a224510f373931ce2d6215a799f5a9c1cef221b0149b6b6b50cced62

// 전화번호: E.164 형식(+국가번호, 국내 0 제거) 후 해시
const hashedPhone = sha256("+821012345678");

공식 예시: [email protected] → d360d510a224510f373931ce2d6215a799f5a9c1cef221b0149b6b6b50cced62 / +11234567890 → 1fa6b8d986d9b9cd01bf36951815158bbde9f520c0567c835dfe34783d0a4231

09 — 중복 제거

Pixel과 CAPI를 같이 쓰면, 같은 전환을 두 번 세지 않아야 합니다.

두 파이프라인을 켜는 것 자체가 업계 표준입니다. 중복 키가 없으면 전환이 부풀어 오르고, 성과처럼 보이는 인플레이션이 생깁니다.

같은 전환에 대해 Pixel 스니펫과 CAPI 요청에 동일한 conversion_id를 넣으세요. 주문번호, 예약번호처럼 한 건을 유일하게 가리키는 값을 쓰는 것이 가장 안전합니다.

twq('event', 'tw-PIXEL_ID-EVENT_ID', {
  value: 89000,
  currency: 'KRW',
  conversion_id: 'order-9f8b7c6d'
});

10 — 체크리스트

좋은 구현의 기준입니다.

브라우저에 진행 상태가 저장됩니다. 구현 리뷰나 핸드오프 때 그대로 쓰세요.

0 / 14 완료

11 — 검증

보낸 다음, 한 화면에서 Pixel과 CAPI를 같이 봅니다.

Conversion Diagnostics는 Pixel과 CAPI의 실시간 이벤트 볼륨을 한곳에서 보여 줍니다. 구현이 끝났다면 이 화면으로 건강도를 확인하세요.

1. 01

   Ads Manager 왼쪽 메뉴에서 Tools를 엽니다.

   Events Manager 아래에 Conversion Diagnostics가 있습니다.
2. 02

   실시간 그래프와 이벤트 테이블을 확인합니다.

   이벤트 유형, 태그 ID, 마지막 활동 시각이 보입니다. 누락된 파라미터, 중복 제거 문제, 볼륨 급감을 여기서 먼저 찾으세요.
3. 03

   테스트 전환을 한 건 발생시킨 뒤 raw 이벤트를 대조합니다.

   conversion_id, 식별자, value가 기대한 값으로 들어왔는지 확인합니다.

12 — FAQ

구현 전에 자주 나오는 질문입니다.

참고: X Ads Events Manager, Conversion API Direct Implementation Guide (2026년 6월), X Ads API Web Conversions 문서. 이 가이드는 광고주 공유용 구현 설명서이며, 캠페인 어트리뷰션 정책을 변경하지 않습니다.