메인 콘텐츠로 건너뛰기

​
Conversion API 설정

​
사전 준비 사항 

​
Ads API 액세스 - 신규 애플리케이션

1단계: 개발자 계정
  • 개발자 계정을 신청할 때는 즉시 승인을 위해 구독 요금제 중 하나를 신청하세요.
  • 참고: 모범 사례로, 공식 회사 X 핸들로 개발자 계정을 만들고 Ads API 액세스를 신청할 것을 강력히 권장합니다. 개발자 계정이 개발자 핸들과 연결되어 있으면 필요 시 자격 증명을 이전할 수 없습니다. 지속적인 관리를 위해 회사 계정으로 운영하고 필요에 따라 다중 사용자 로그인을 사용하는 것이 가장 좋습니다. 그렇지 않다면 최소한 계정은 기본값이 아닌 설정(헤더 이미지, 아바타, 소개, 소개 URL)으로 구성하고 2단계 인증을 사용해야 합니다.
2단계: Ads API 애플리케이션
  • Ads API 애플리케이션에 사용할 올바른 App ID를 준비하세요. App ID는 Developer Portal의 Projects & Apps에서 확인할 수 있습니다. 예: 16489123
  • X 담당자에게 연락해 Ads API 액세스를 요청하세요.

​
Ads API 액세스 - 기존 애플리케이션

  • 이미 활발히 사용 중인 Ads API 애플리케이션이 있다면, 해당 애플리케이션과 기존 액세스 토큰을 Conversion API에도 사용할 수 있습니다.

​
액세스 토큰

  • Ads API 애플리케이션을 소유한 사용자 핸들의 사용자 액세스 토큰은 개발자 포털에서 직접 생성하고 조회할 수 있습니다. 이는 본인의 X 핸들에 사용하도록 설계되었기 때문에 “개인 액세스 토큰”이라고 합니다. 인증 및 개발자 포털 전반에 대한 정보는 여기에서 확인할 수 있습니다.
  • Ads API 애플리케이션을 소유한 핸들이 아닌 다른 사용자 핸들의 사용자 액세스 토큰은 3-legged OAuth 플로우로 생성해야 합니다. 3-legged OAuth로 액세스 토큰을 생성하는 옵션은 다음과 같습니다:
  • Conversion API에서 사용되는 모든 사용자 토큰은 AD_MANAGER 또는 ACCOUNT_ADMIN 액세스 레벨을 가진 사용자여야 하며, 이는 authenticated_user_access 엔드포인트에서 확인할 수 있습니다.
  • 참고: 위와 같이 생성된 토큰 자체는 사용을 위해 AD_MANAGER 또는 ACCOUNT_ADMIN 액세스 레벨이 없는 사용자에게도 공유할 수 있습니다.

​
절차

​
Conversion API 이벤트 생성

Conversion API를 사용하려면 Ads Manager에서 새 전환 이벤트를 생성하거나, 이미 생성되어 X Pixel과 함께 사용 중인 기존 이벤트를 사용할 수 있습니다. 픽셀 이벤트와 Conversion API 이벤트 간에 중복 제거를 하려면 Pixel용으로 생성한 기존 이벤트를 사용해야 합니다. 
옵션 1: Ads Manager에서 기존 전환 이벤트 사용
이미 X 픽셀과 함께 사용 중인 기존 이벤트를 계속 사용하려면, 해당 이벤트의 Event ID를 가져오면 됩니다. 동일한 이벤트에 픽셀과 Conversion API를 모두 사용하는 경우, 같은 이벤트에 대해 픽셀과 Conversion API 사이에서 중복을 제거할 수 있도록 Pixel 코드 스니펫과 Conversion API 요청 모두에서 중복 제거 키(즉, conversion_id)를 사용했는지 확인하세요. 자세한 내용은 d. Testing Events and Deduplication 섹션을 참고하세요. 
옵션 2: Ads Manager에서 새 전환 이벤트 만들기:
이벤트를 만들기 전에 Events Manager에서 Event Source를 먼저 생성해야 합니다. 계정에 Event Source(X Pixel)가 추가되어 있는지 확인하려면 Events Manager로 이동해 왼쪽 메뉴에 X Pixel이 있는지 확인하세요. 아직 Event Source가 없다면, 아래 단계를 따라 Event Source를 생성하세요.
  1. ads.x.com으로 이동
  2. 왼쪽 상단의 Tools 섹션으로 이동하여 Events Manager 클릭
  3. 왼쪽 사이드바에 X Pixel Event Source가 아직 없다면, 오른쪽 상단의 Add event source를 선택해 Add an event source 실행
    1. X Pixel Event Source의 ID가 Pixel ID입니다
이제 Event Source와 Pixel ID가 준비되었습니다. 추적하려는 전환 이벤트를 위해 해당 Event Source 내에 이벤트를 생성해야 합니다:
  1. X Pixel Event Source에서 오른쪽의 Add events 선택
  2. Conversion API로 설치 선택
  3. API에서 사용될 이 이벤트의 Pixel ID와 Event ID를 확인
    1. 이벤트의 ID가 Event ID입니다
  4. Save를 클릭하면 전환 이벤트가 생성되어 사용할 준비가 완료됩니다

​
전환 이벤트용 식별자 준비 

현재 Click ID(twclid), 이메일 주소, 또는 전화번호 등 식별자 중 최소 하나를 전달해야 합니다. IP 주소 또는 User-Agent를 사용하는 경우, 정확한 전환 매칭을 위해 두 번째 식별자를 함께 전송해야 합니다. 식별자를 더 많이 전달할수록 전환 매칭률이 높아집니다.
고객 매칭 필드형식해시 필요 여부
X Click IDX에서 생성됨 (자세히 알아보기)아니요
이메일 주소앞뒤 공백 제거필요(SHA‑256)
전화번호E.164 표준필요(SHA‑256)
IP 주소앞뒤 공백 제거아니요
User-Agent앞뒤 공백 제거아니요

​
1. X Click ID 식별자 준비 

전환 요청에는 항상 Click ID를 포함하는 것이 좋습니다. 사용자가 대상 웹사이트로 이동한 뒤 사용할 수 있을 때, Click ID는 쿼리 문자열 매개변수인 twclid에서 파싱해야 합니다.  기본 JavaScript 코드 예시: 
var queryString = document.location.search;
if (queryString.has('twclid') {
  twitterClickID = getParam(queryString, 'twclid');
  // 권장되는 다음 단계: 로깅, 로컬 스토리지에 저장
}
다음을 권장합니다: 
  1. URL 쿼리 매개변수에 twclid 값이 포함되어 있으면 항상 이를 파싱하세요.
  2. 관련 양식 필드 또는 전환 이벤트 정보와 함께 해당 데이터를 저장하세요.
Click ID를 전환 이벤트 및 워크플로 정보와 연결하면 배치 처리, 여러 웹사이트 탐색 흐름을 기반으로 전환 이벤트를 분석·생성하는 알고리즘, 대량 업로드 등의 시나리오를 구현할 수 있습니다. Event Source URL은 URL 인코딩을 적용해야 하며, 이벤트를 트리거한 웹페이지를 나타냅니다.

​
2. 이메일 식별자 준비

지원되는 고객 매칭 필드는 전송할 수 있지만, 표준화한 뒤 필요 시 개인정보 보호를 위해 해시 처리해야 합니다. 해시는 솔트를 사용하지 않고 SHA‑256으로 수행해야 합니다. 예를 들어 이메일 주소 test@x.com은 다음과 같은 해시 값으로 전송해야 합니다: d360d510a224510f373931ce2d6215a799f5a9c1cef221b0149b6b6b50cced62.

​
3. 전화 식별자 준비 

전화번호는 E164 표준을 사용해 전달하고, 해당 정보는 솔트 없이 SHA‑256으로 해시해야 합니다.  예를 들어, 미국 전화번호 +11234567890의 경우, 우리에게 전송될 때 다음과 같은 해시 값이어야 합니다: 1fa6b8d986d9b9cd01bf36951815158bbde9f520c0567c835dfe34783d0a4231.

​
4. IP 주소 식별자 준비

IP 주소는 다른 식별자(twclid, 이메일 주소, 전화번호 또는 사용자 에이전트)와 함께 전달해야 합니다. 이 식별자에는 해시 처리가 필요하지 않습니다. 이 값은 점으로 구분하는 10진 표기법으로 표기하며, 마침표로 구분된 네 개의 숫자로 구성됩니다. 예를 들어, 사용자의 IP 주소는 8.25.197.25일 수 있습니다.

​
5. 사용자 에이전트 식별자 준비

User Agent는 다른 식별자(twclid, 이메일 주소, 전화번호 또는 IP 주소)와 함께 전달해야 합니다. 이 식별자에는 해시가 필요하지 않습니다. 이 식별자는 서버가 요청을 보낸 사용자 에이전트의 애플리케이션, 운영체제, 공급업체 및/또는 버전을 식별할 수 있게 합니다. 예를 들어, 이 값은 Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/127.0.0.0 Safari/537.36로 전달할 수 있습니다.

​
전환 이벤트 요청 구성

POST: version/measurement/conversions/:pixel_id 특정 광고 계정의 전환 이벤트를 전송합니다. 응답 코드(HTTP 200 OK)를 확인해 성공 여부를 판단해야 합니다. 오류 코드가 반환될 수 있으므로 재시도 메커니즘과 기본 로깅을 마련해 두는 것을 권장합니다. 엔드포인트의 URL과 POST 본문 매개변수에 대한 자세한 내용은 API Reference 섹션을 참고하세요. 

​
예시 요청(가독성을 위해 보기 좋게 정렬)


    twurl -H 'ads-api.x.com' -X POST '/12/measurement/conversions/oka17' --data '
    {
      "conversions":[
         {
            "conversion_time":"2022-02-18T01:14:00.603Z",
            "event_id":"ol288",
            "identifiers":[
               {
                  "twclid":"23opevjt88psuo13lu8d020qkn"
               },
               {
                  "hashed_email":"d360d510a224510f373931ce2d6215a799f5a9c1cef221b0149b6b6b50cced62"
               },
               {
                  "hashed_phone_number":"1fa6b8d986d9b9cd01bf36951815158bbde9f520c0567c835dfe34783d0a4231"
               },
               {
                  "ip_address":"1.0.0.0",
                  "user_agent":"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/127.0.0.0 Safari/537.36"
               }
            ],
            "value":"20.00",
            "number_items":3,
            "conversion_id":"23294827",
            "description":"반려동물 용품 구매",
            "contents":[
               {
                  "content_id":"1",
                  "content_name":"담요",
                  "content_type":"반려동물 용품",
                  "content_price":100.99,
                  "num_items":1,
                  "content_group_id":"123"
               }
            ]
         }
      ]
    }' --header 'Content-Type: application/json'

​
예시 응답

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

​
요청 한도

요청 한도는 계정당 15분마다 이벤트 60,000개입니다. 다음과 같이, 이 요청 호출 외부에서 로직을 구현해야 할 수도 있습니다.
  1. 이벤트별로 정확한 전환 데이터를 전송할 수 있도록 사용자 동작을 계측(로그 수집)하는 작업
  2. 관련 프라이버시 선택을 행사한 사용자의 전환 이벤트를 걸러내기 위한 필요한 로직 — 예: 광고주 웹사이트에서 추적 또는 개인 정보 판매를 거부(옵트아웃)한 경우
  3. 이벤트를 포착하고 전환을 전송하기 위한 이벤트 트리거 및 페이지와의 통합

​
이벤트 테스트 및 중복 제거

​
이벤트 테스트

이벤트가 전환 이벤트를 성공적으로 수신한 경우, 12~24시간 내에 Ads Manager의 전환 추적 페이지에서 ‘Single event web tag’의 상태가 TRACKING으로 표시됩니다. Conversion API를 통해 전환을 전송하더라도 진행 중인 캠페인에는 영향을 주지 않습니다. 또한 태그 ID별 전환 이벤트 분석 결과는 다음 방법으로 확인할 수 있습니다.

​
Pixel과 Conversion API 간 중복 제거

Pixel과 Conversion API 요청 간 전환을 중복 제거하려면 디듀플리케이션 키로 conversion_id를 사용합니다. 디듀플리케이션은 이벤트 단위로만 이뤄집니다. 즉, 픽셀과 CAPI 요청 간 중복 제거를 위해서는 동일한 conversion_id를 사용할 뿐 아니라 픽셀과 CAPI 요청 모두에서 동일한 이벤트를 사용해야 합니다. 디듀플리케이션은 48시간 이내에 수신된 이벤트에만 적용됩니다

​
전환 추적(개요)

​
요약

전환 추적은 X에서 광고를 본 뒤 상호작용한 사용자가 원하는 행동을 수행한 수를 측정할 수 있게 해줍니다. 이를 통해 캠페인이 사이트 방문, 가입, 구매 등 어떤 행동을 얼마나 유도하는지 측정할 수 있습니다. 이는 광고주가 X 외부에서도 직접 반응형 광고의 성과를 파악해 비용 효율적으로 고객을 확보할 수 있도록 돕습니다. 전환 태그를 사용하면 광고주는 사용자 전환을 추적하고 이를 X의 광고 캠페인과 연결할 수 있습니다. 이를 통해 캠페인을 최적화하여 획득당 비용(CPA) 목표를 달성하는 데 필요한 가시성을 확보할 수 있습니다. 전환 추적으로 측정할 수 있는 웹사이트 내 행동은 다양합니다. 광고 캠페인을 통해 유도하려는 목표에 따라 하나 이상을 선택할 수 있습니다.
  • 사이트 방문: 사용자가 광고주의 사이트 내 랜딩 페이지를 방문
  • 구매: 사용자가 광고주의 사이트에서 제품 또는 서비스를 구매 완료
  • 다운로드: 사용자가 광고주의 사이트에서 백서나 소프트웨어 패키지 등의 파일을 다운로드
  • 가입: 사용자가 광고주의 서비스, 뉴스레터 또는 이메일 구독에 가입
  • 사용자 지정: 위 범주에 속하지 않는 사용자 지정 행동을 위한 포괄적 범주
X의 전환 추적은 광고주에게 전환 기여도에 대한 총체적인 관점을 제공합니다. 고유 클릭 URL과 타사 추적 태그 조합 등, X의 자체 전환 추적 기능 대신 사용되었을 수 있는 타사 측정 시스템과 비교하면, X의 전환 태그는 노출은 물론 트윗 확장, 리트윗, 즐겨찾기, 답글, 팔로우와 같은 미드 및 어퍼 퍼널 상호작용에 기인한 전환까지 추적할 수 있습니다.

​
자주 묻는 질문

먼저 광고주는 X에서 제공하는 코드 스니펫인 전환 태그를 생성해 자사 웹사이트에 설치합니다. 이제 사용자가 지정된 행동을 완료하면 전환을 측정할 준비가 된 것입니다.그다음 사용자는 X 클라이언트에서 광고주의 광고를 보고, 광고주의 웹사이트로 이동해 태그로 지정한 행동을 수행합니다. 사용자가 태그 설정 시 광고주가 지정한 어트리뷰션 윈도우 내에 그 행동을 완료하면, 태그는 사용자가 이전에 X 광고와 상호작용했음을 인식합니다. 그러면 태그가 “발화(fire)”하여 X 서버로 알림을 보내고, 해당 전환을 이를 유도한 광고에 귀속시킬 수 있게 됩니다.
아니요. 현재 제품은 특정 전환 태그를 특정 캠페인에 개별적으로 연결하도록 설계되어 있지 않습니다. 대신 태그를 한 번 설정하면, 시스템이 자동으로 어떤 광고가 해당 태그에서 전환을 발생시켰는지 추적합니다.
기본 조회 후 어트리뷰션 윈도우: 1일기본 참여 후 어트리뷰션: 14일이 기본값은 전환 태그 설정 중 또는 태그 생성 후 언제든 변경할 수 있습니다. 참여 후 어트리뷰션 윈도우 옵션은 1, 7, 14, 30, 60, 90일입니다. 조회 후 어트리뷰션 윈도우 옵션은 없음, 1, 7, 14, 30, 60, 90일입니다.
각 클라이언트의 목표, 상황, 전략은 다르지만, 전환 추적 알파/베타에 참여한 클라이언트에게 효과적이었던 아이디어는 다음과 같습니다.크리에이티브:
  • 오퍼: 프로모티드 트윗과 함께 할인, 프로모션, 무료 배송과 같은 오퍼를 제공해 행동 유도를 강화
  • 경품 및 콘테스트: 특히 인지도가 높은 브랜드에서 전환 유도에 효과적이었음
  • 트윗 문구 실험: 대문자 vs 소문자 테스트(FREE vs free, NOW vs now)
  • 마감 기한: 즉각적 행동을 유도하는 마감 표현 제시(Offer Expires December 12!)
  • 매력적인 이미지 추가: 시각적으로 강렬한 이미지를 트윗 크리에이티브에 추가하는 테스트를 권장하며, 효과는 제공 상품/서비스에 따라 달라질 수 있음
타기팅:
  • @handle 타기팅 및 관심사 카테고리 타기팅: 트윗 문구와 @handle을 의도한 대상과 긴밀히 맞출수록 전환이 향상됨
  • 틈새이지만 검색량이 높은 키워드 활용: 공연 분야에서는 아티스트/뮤지션(예: 이름) 관련 키워드가 효과적이었음
  • 테일러드 오디언스: TA 웹과 전환 추적을 함께 사용한 경우, 다른 타기팅을 사용한 대조군 대비 더 낮은 CPA 달성
캠페인을 더 세분화할수록 전환 리포트 결과를 더 실질적으로 활용할 수 있습니다. 예를 들어 50개 키워드를 쓰는 캠페인보다 4개 키워드를 쓰는 캠페인이 최적화가 훨씬 쉽습니다.

​
Conversion API에 대한 문제 해결 및 지원

API 호출 후 오류 코드 관련 질문은 아래 섹션을 참고해 주세요. 그 외 다른 문의 사항은 주저하지 말고 Twitter 담당자에게 연락해 주시면 최대한 신속히 해결해 드리겠습니다. 

​
오류 처리 및 설명

단일 요청은 그 안에 포함된 모든 전환에서 오류가 전혀 없을 때에만 성공합니다. 특정 전환에서 오류가 하나라도 발생하면, 엔드포인트는 해당되는 모든 오류의 목록을 반환합니다.

​
X Ads API 오류 코드 개요

다음은 Ads API의 오류 코드를 포괄적으로 정리한 전체 목록입니다: https://developer.x.com/en/docs/twitter-ads-api/response-codes Conversion API에서의 성공적인 응답은 200번대 HTTP 상태 코드와 요청한 객체를 포함한 JSON 기반 페이로드로 표시됩니다.

​
500대 HTTP 코드가 발생하는 경우, 이는 요청이나 계정 설정 문제가 아니라 서버 문제와 관련이 있습니다. 다른 사용자들도 비슷한 문제를 겪고 있는지 X API status page나 developer community forum을 확인하세요.

​
400대 HTTP 코드가 발생하는 경우 일반적인 사례는 다음과 같습니다

  • 400 Bad Request (요청이 규격에 맞지 않음)
  • 401 Unauthorized (인증 문제)
  • 403 Forbidden (해당 개발자 계정과 연관된 API 접근 문제)
  • 404 Not Found (해당 엔드포인트에 맞는 URL 또는 매개변수가 아닐 수 있음)

​
전환 API 오류 코드

​
400 Bad Request 시나리오

ReasonTypeError Message
식별자 누락 오류(현재 해시된 이메일 또는 X 클릭 ID - twclid)400 Bad Request사용자 식별자를 최소 하나 이상 제공해야 합니다
잘못된 해시된 이메일400 Bad RequestHashed_email은(는) 올바른 SHA-256 해시가 아닙니다
event_id의 유형이 단일 이벤트 태그(SET)가 아님400 Bad RequestEvent_id (<event_id>) is not a single event tag (SET)
요청된 전환 이벤트가 제한을 초과함(현재 요청당 500건의 이벤트)400 Bad Request전환 이벤트 개수 제한은 500입니다
이벤트 ID 누락400 Bad Request이벤트 ID를 찾을 수 없습니다

​
JSON 오류 코드 예제

요청:
POST '/11/measurement/conversions/o6dkt' --data '{"conversions":[{"conversion_time": "2022-06-16T01:14:00.603Z", "event_id":"o6dkt", "identifiers": [{"twclid": "23opevjt88psuo13lu8d020qkn"}]}]}' --header 'Content-Type: application/json

​
오류 메시지:

{"errors":[{"code":"INVALID_PARAMETER","message":"event&#95;id (o6dkt)는 단일 이벤트 태그(SET)가 아닙니다","parameter":"event&#95;id"}],"request":{"params":{"account&#95;id":"18ce552mlaq"}}}

​
요청:

twurl_ads -X POST '/11/measurement/conversions/o6dkt' --data '{"conversions":[{"conversion_time": "2022-06-16T01:14:00.603Z", "event_id":"o6dl3", "identifiers": [{"twclid": ""}]}]}' --header 'Content-Type: application/json'

​
오류 메시지:

{"errors":[{"code":"INVALID_PARAMETER","message":"최소 한 개 이상의 사용자 식별자를 제공해야 합니다","parameter":""}],"request":{"params":{"account_id":"18ce552mlaq"}}}

​
요청:

twurl_ads -X POST '/11/measurement/conversions/o6dkt' --data '{"conversions":[{"conversion&#95;time": "2022-06-16T01:14:00.603Z", "event&#95;id":"o6dl3", "identifiers": [{"hashed&#95;email": "abc"}]}]}' --header 'Content-Type: application/json'

​
오류 메시지:

{"errors":[{"code":"INVALID_PARAMETER","message":"hashed_email (abc)은 유효한 SHA-256 해시가 아닙니다","parameter":"hashed_email"}],"request":{"params":{"account_id":"18ce552mlaq"}}}

​
요청:

twurl_ads -X POST '/11/measurement/conversions/o6dkt' --data '{"conversions":[{"conversion&#95;time": "2022-06-16T01:14:00.603", "event&#95;id":"o6dl3", "identifiers": [{"twclid": "23opevjt88psuo13lu8d020qkn"}]}]}' --header 'Content-Type: application/json'

​
오류 메시지:

{"errors":[{"code":"INVALID_PARAMETER","message":"기대되는 시간 형식은 yyyy-MM-ddTHH:mm:ss.SSSZ이며, conversion&#95;time 값으로 \"2022-06-16T01:14:00.603\"이(가) 전달되었습니다","parameter":"conversion_time"}],"request":{"params":{"account_id":"18ce552mlaq"}}}

​
401 인증되지 않음

이유: 인증 자격 증명이 없거나 올바르지 않음 해결 방법: 다음 3가지 인증 방법 중 하나를 사용하여 설정 문서에 있는 인증 절차를 따르세요. Ads API 애플리케이션 소유자가 아닌 다른 사용자 핸들의 사용자 액세스 토큰은 3-legged OAuth 플로우로 발급해야 합니다. 3-legged OAuth로 액세스 토큰을 발급하는 방법은 다음과 같습니다. Conversion API에서 사용하는 모든 사용자 토큰은 액세스 수준이 AD_MANAGER 또는 ACCOUNT_ADMIN인 사용자에 한하며, 이는 authenticated_user_access 엔드포인트로 확인할 수 있습니다.

​
403 액세스 금지 

이유유형오류 메시지
사용 중인 개발자 계정에는 Ads API 액세스 권한이 없습니다. 여기에서 액세스를 신청하세요.403 Unauthorized Client이 요청을 수행하는 id <>의 클라이언트 애플리케이션에는 X Ads API에 대한 액세스 권한이 없습니다. 애플리케이션에 advertiser-api 액세스 권한이 있는지 확인하세요. 사용 중인 애플리케이션을 변경하려면 ‘twurl accounts’와 ‘twurl set default <username> <key>‘를 사용하세요.

​
404 찾을 수 없음 

이유유형오류 메시지
요청 URL 또는 매개변수가 엔드포인트에 적합하지 않습니다404 Route Not Found요청한 리소스를 찾을 수 없습니다
pixel_id/Universal website tag을 소유한 계정에 대한 접근 권한이 없습니다404 Not FoundUser <user_id>에는 account <account_id>에 대한 접근 권한이 없습니다. 사용자 핸들을 확인하려면 ‘sn <user_id>‘를 입력하세요. 사용하는 사용자를 변경하려면 ‘twurl accounts’와 ‘twurl set default \u003Cusername\u003E’를 사용하세요.
이벤트 id가 픽셀 ID(UWT ID)와 연관된 제공된 계정에 속하지 않습니다404 Not Foundevent_id <event_id>는 제공된 계정에 속하지 않습니다

​
JSON 오류 코드 예제

​
요청:

twurl_ads -X POST '/11/measurement/conversions/o8z6j' --data '{"conversions":[{"conversion_time": "2022-06-16T01:14:00.603Z", "event_id":"abc", "identifiers": [{"twclid": "23opevjt88psuo13lu8d020qkn"}]}]}' --header 'Content-Type: application/json' 오류 메시지: {"errors":[{"code":"NOT_FOUND","message":"event_id (abc)이(가) 제공된 계정에 속하지 않습니다","parameter":"event_id"},{"code":"INVALID_PARAMETER","message":"event_id (abc)은(는) 단일 이벤트 태그(SET)가 아닙니다","parameter":"event_id"}],"request":{"params":{"account_id":"18ce55gze09"}}}

​
API 참조 색인

전체 API 참조를 보려면 목록에서 엔드포인트를 선택하세요:

​
웹 전환

전환 APImeasurement/conversions/:pixel_id
웹 이벤트 태그accounts/:account_id/web_event_tags

​
웹 전환

POST version/measurement/conversions/:pixel_id 단일 이벤트 태그 ID에 대한 웹사이트 전환 이벤트를 전송합니다. 응답 코드(HTTP 200 OK)를 확인해 성공 여부를 판단하세요. 오류 코드가 반환될 경우를 대비해 재시도 메커니즘과 기본 로깅을 갖추는 것을 권장합니다. 레이트 리밋은 계정당 15분마다 100,000건의 요청입니다(요청 1건당 이벤트 500개 전송 가능).
리소스 URL
https://ads-api.x.com/12/measurement/conversions/:pixel_id
요청 URL 매개변수
NameDescription
pixel_id
required		광고 계정의 Base Tag ID입니다. 광고 계정의 Base Tag ID를 base36으로 인코딩한 값입니다.

Type: string

Example: o8z6j
conversions
required		API 요청의 POST 본문에 포함되는 객체입니다. 전환 이벤트 목록으로, 최대 500개까지 제공할 수 있습니다. 지원되는 필드는 아래 표를 참조하세요.

Type: array

Example: "conversions":[{"conversion_time": "2022-02-18T01:14:00.603Z", "event_id":"o87ne", "identifiers": [{"twclid": "23opevjt88psuo13lu8d020qkn"}], "conversion&#95;id": "23294827"}]
conversions 객체
NameDescription
conversion_time
required		ISO 8601 형식의 시간입니다.

Type: string

Example: 2017-10-05T00:00:00Z
event_id
required		특정 이벤트의 base-36 ID입니다. 이 광고 계정에 미리 설정된 이벤트와 일치합니다. Events Manager의 해당 이벤트에서는 이를 ID라고 합니다.

Type: string

Example: o87ne 또는 tw-o8z6j-o87ne (tw-pixel_id-event-id) 모두 허용됨
identifiers
required		전환 이벤트와 매칭할 식별자 객체 목록입니다. 지원되는 필드는 아래 표에 나와 있습니다. 식별자 객체는 최소 하나가 필요합니다.

IP 주소 또는 사용자 에이전트를 사용하는 경우, 정확한 전환 매칭을 위해 두 번째 식별자를 함께 전송해야 합니다.

Type: array

Example: "identifiers": [{"twclid": "23opevjt88psuo13lu8d020qkn"},{"hashed_email": "e586883b2b4faf78d48300a79e0e15138d664cdf796ffb86e533170a9893eda8"}]
number_items
optional		이벤트에서 구매되는 항목 수입니다. 0보다 큰 양수여야 합니다.

Type: integer

Example: 4
price_currency
optional		이벤트에서 구매되는 항목의 통화를 ISO-4217 형식으로 표현합니다. 자세한 내용은 Currency를 참조하세요.

Type: string

Default: USD

Example: JPY
value
optional		이벤트에서 구매되는 항목의 가격으로, price_currency 통화로 표시됩니다.

Type: double

Example: 100.00
conversion_id
optional		픽셀과 Conversion API 간 전환의 중복 제거를 위한 값입니다. 동일한 이벤트 태그 내에서 Web Pixel과 Conversion API 전환 간 중복 제거에 사용할 수 있는 전환 이벤트 식별자입니다. 자세한 내용은 Conversions Guide의 Testing Events and Deduplication 섹션을 참고하세요.

Type: string

Example: 23294827
description
optional		전환에 대한 추가 정보를 포함한 설명입니다.

Type: string

Example: test conversion
contents
optional		세분화된 정보를 제공하기 위한 특정 제품/콘텐츠 관련 상세 목록입니다. 지원되는 필드는 아래 표를 참조하세요.

Type: array

Example: contents": [{"content_id": "1", "content_name": "Blankets", "content_type": "home improvement", "content_price": 100.99, "num_items": 1, "content_group_id": "123"}, {"content_id": "2"}]
identifiers 객체
NameDescription
twclid
때때로 필수		클릭 유입 URL에서 파싱된 Click ID입니다. 다른 식별자가 추가되지 않은 경우 필수입니다.

Type: string

Example: 26l6412g5p4iyj65a2oic2ayg2
hashed_email
때때로 필수		SHA256으로 해시한 이메일 주소입니다. 해시 전에 모든 앞뒤 공백을 제거하고 소문자로 변환해야 합니다. 다른 식별자가 추가되지 않은 경우 필수입니다.

Type: string

Example: test-email@test.com의 경우 = e586883b2b4faf78d48300a79e0e15138d664cdf796ffb86e533170a9893eda8
hashed_phone_number
때때로 필수		E164 형식의 전화번호를 SHA256으로 해시한 값입니다. 해시 전에 전화번호는 반드시 E164 형식이어야 합니다. 다른 식별자가 추가되지 않은 경우 필수입니다.

Type: string

Example: +11234567890의 경우 = 1fa6b8d986d9b9cd01bf36951815158bbde9f520c0567c835dfe34783d0a4231 
ip_address
때때로 필수		점-10진 표기법으로 작성되며, 마침표로 구분된 네 개의 숫자로 구성됩니다.

IP 주소는 다른 식별자(twclid, 이메일 주소, 전화번호 또는 user agent)와 함께 전달되어야 합니다.

Type: string

Example: 8.25.197.25
**user_agent **
때때로 필수		이 식별자는 서버가 요청을 보낸 user agent의 애플리케이션, 운영체제, 공급업체 및/또는 버전을 식별할 수 있도록 합니다.

User Agent는 다른 식별자(twclid, 이메일 주소, 전화번호 또는 IP 주소)와 함께 전달되어야 합니다.

Type: string

Example: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/127.0.0.0 Safari/537.36.
contents object
NameDescription
content_id
optional		SKU 또는 GTIN; 콘텐츠를 나타내는 식별자입니다.

Type: string

Example: jhp
content_group_id
optional		제품 변형 그룹과 연결된 ID입니다.

Type: integer

Example: group 1
content_name
optional		제품 또는 서비스의 이름입니다.

Type: string

Example: radio flyer
content_price
optional		제품 또는 서비스의 가격입니다.

Type: double

Example: 5.00
content_type
optional		구매된 제품의 범주입니다.

Type: string

Example: clothes
num_items
optional		구매한 제품 수입니다.

Type: integer

Example: 1
응답 매개변수
이름설명
conversions_processed성공적으로 처리된 전환 수

유형: integer

예시: 1
debug_id후속 조사에 사용할 수 있는 디버그 UUID

유형: string

예시: ff02e052-36e4-47d6-bdf0-6d8986446562
예시 요청
    twurl -H 'ads-api.x.com' -X POST '/12/measurement/conversions/oka17' --data '
    {
      "conversions":[
         {
            "conversion_time":"2022-02-18T01:14:00.603Z",
            "event_id":"ol288",
            "identifiers":[
               {
                  "twclid":"23opevjt88psuo13lu8d020qkn"
               },
               {
                  "hashed&#95;email":"d360d510a224510f373931ce2d6215a799f5a9c1cef221b0149b6b6b50cced62"
               },
               {
                  "hashed&#95;phone&#95;number":"1fa6b8d986d9b9cd01bf36951815158bbde9f520c0567c835dfe34783d0a4231"
               },
               {
                  "ip&#95;address":"1.0.0.0",
                  "user&#95;agent":"Mozilla/5.0 (Macintosh; Intel Mac OS X 10&#95;15&#95;7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/127.0.0.0 Safari/537.36"
               }
            ],
            "value":"20.00",
            "number&#95;items":3,
            "conversion&#95;id":"23294827",
            "description":"반려동물용품 구매",
            "contents":[
               {
                  "content&#95;id":"1",
                  "content&#95;name":"담요",
                  "content&#95;type":"반려동물용품",
                  "content&#95;price":100.99,
                  "num&#95;items":1,
                  "content&#95;group&#95;id":"123"
               }
            ]
         }
      ]
    }' --header 'Content-Type: application/json'
예시 요청
    {
       "request":{
          "params":{
             "account_id":"18ce552mlaq"
          }
       },
       "data":{
          "conversions_processed":1,
          "debug_id":"ff02e052-36e4-47d6-bdf0-6d8986446562"
       }
    }

​
웹 이벤트 태그

GET accounts/:account_id/web_event_tags 현재 계정에 연결된 웹 이벤트 태그의 세부 정보를 일부 또는 전체 조회합니다.

​
리소스 URL

https://ads-api.x.com/12/accounts/:account_id/web_event_tags

​
매개변수

이름설명
account_id
required		활용 중인 계정의 식별자입니다. 리소스 경로에 포함되며, GET accounts를 제외한 대부분의 Advertiser API 요청에서 일반적으로 필요한 매개변수입니다. 지정된 계정은 인증된 사용자와 연결되어 있어야 합니다.

유형: string

예시: 18ce54d4x5t
count
optional		개별 요청마다 가져올 레코드 수를 지정합니다.

유형: int

기본값: 200
최소, 최대: 1, 1000
cursor
optional		다음 결과 페이지를 가져오기 위한 커서를 지정합니다. 자세한 내용은 Pagination을 참조하세요.

유형: string

예시: 8x7v00oow
sort_by
optional		지원되는 속성을 기준으로 오름차순 또는 내림차순으로 정렬합니다. 자세한 내용은 Sorting을 참조하세요.

유형: string

예시: created_at-asc
web_event_tag_ids
optional		쉼표로 구분된 식별자 목록을 지정하여 원하는 웹 이벤트 태그만 응답에 포함하도록 범위를 제한합니다. 최대 200개의 ID를 제공할 수 있습니다.

유형: string

예시: o3bk1
with_deleted
optional		삭제된 결과를 응답에 포함합니다.

유형: boolean

기본값: false
가능한 값: true, false
with_total_count
optional		total_count 응답 속성을 포함합니다.

참고: 이 매개변수와 cursor는 상호 배타적입니다.

참고: total_count를 포함한 요청은 더 낮은 요청 한도가 적용되며, 현재 15분당 200으로 설정되어 있습니다.

유형: boolean

기본값: false
가능한 값: true, false

​
예시 요청

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/web_event_tags?web_event_tag_ids=o3bk1

​
응답 예시

    {
      "request": {
        "params": {
          "web_event_tag_ids": [
            "o3bk1"
          ],
          "account_id": "18ce54d4x5t"
        }
      },
      "next_cursor": null,
      "data": [
        {
          "name": "웹 이벤트 태그",
          "view_through_window": 7,
          "click_window": 7,
          "embed_code": "<script src="//platform.x.com/oct.js" type="text/javascript"></script><script type="text/javascript">twttr.conversion.trackPid('ny3od',  { tw_sale_amount: 0, tw_order_quantity: 0 });</script><noscript><img height="1" width="1" style="display:none;" alt=""  src="https://analytics.x.com/i/adsct?txn_id=ny3od&amp;p_id=Twitter&amp;tw_sale_amount=0&amp;tw_order_quantity=0" /><img height="1" width="1" style="display:none;" alt=""  src="//t.co/i/adsct?txn_id=ny3od&amp;p_id=Twitter&amp;tw_sale_amount=0&amp;tw_order_quantity=0" /></noscript>",
          "id": "o3bk1",
          "retargeting_enabled": false,
          "last_tracked_at": "2021-05-22T17:00:04Z",
          "status": "TRACKING",
          "type": "DOWNLOAD"
          "website_tag_id": "ny3od",
          "deleted": false
        }
      ]
    }

​
GET accounts/:account_id/web_event_tags/:web_event_tag_id

현재 계정에 연결된 특정 웹 이벤트 태그를 조회합니다.
리소스 URL
https://ads-api.x.com/12/accounts/:account_id/web_event_tags/:web_event_tag_id
매개변수
이름설명
account_id
필수		활용 중인 계정의 식별자입니다. 리소스 경로에 포함되며, GET accounts를 제외한 대부분의 Advertiser API 요청에서 일반적으로 요구됩니다. 지정된 계정은 인증된 사용자와 연결되어 있어야 합니다.

유형: string

예시: 18ce54d4x5t
web_event_tag_id
필수		요청에서 사용 중인 웹 이벤트 태그에 대한 참조입니다.

유형: string

예시: o3bk1
with_deleted
선택		삭제된 결과를 포함합니다.

유형: boolean

기본값: false
가능한 값: true, false
예시 요청
GET https://ads-api.x.com/12/accounts/18ce54d4x5t/web_event_tags/o3bk1
예시 응답
    {
      "request": {
        "params": {
          "web_event_tag_id": "o3bk1",
          "account_id": "18ce54d4x5t"
        }
      },
      "data": {
        "name": "웹 이벤트 태그",
        "view_through_window": 7,
        "click_window": 7,
        "embed_code": "<script src="//platform.x.com/oct.js" type="text/javascript"></script><script type="text/javascript">twttr.conversion.trackPid('ny3od',  { tw_sale_amount: 0, tw_order_quantity: 0 });</script><noscript><img height="1" width="1" style="display:none;" alt=""  src="https://analytics.x.com/i/adsct?txn_id=ny3od&amp;p_id=Twitter&amp;tw_sale_amount=0&amp;tw_order_quantity=0" /><img height="1" width="1" style="display:none;" alt=""  src="//t.co/i/adsct?txn_id=ny3od&amp;p_id=Twitter&amp;tw_sale_amount=0&amp;tw_order_quantity=0" /></noscript>",
        "id": "o3bk1",
        "retargeting_enabled": false,
        "last_tracked_at": "2021-05-22T17:00:04Z",
        "status": "TRACKING",
        "type": "DOWNLOAD"
        "website_tag_id": "ny3od",
        "deleted": false
      }
    }

​
POST accounts/:account_id/web_event_tags

현재 계정에 연결된 새 웹 이벤트 태그를 생성합니다.

​
리소스 URL

https://ads-api.x.com/12/accounts/:account_id/web_event_tags

​
매개변수

이름설명
account_id
필수		사용 중인 계정의 식별자입니다. 리소스 경로에 포함되며, GET accounts를 제외한 모든 Advertiser API 요청에서 일반적으로 필수 매개변수입니다. 지정한 계정은 인증된 사용자와 연동되어 있어야 합니다.

유형: string

예시: 18ce54d4x5t
click_window
필수		이 웹 태그의 클릭 윈도우입니다.

참고: 아래에 나열된 값만 허용됩니다.

유형: int

가능한 값: 1, 7, 14, 30
name
필수		웹 태그의 이름입니다.

유형: string

예시: Sample single conversion event
retargeting_enabled
필수		이 웹 태그에 대해 리타게팅을 활성화할지 여부를 나타냅니다.

유형: boolean

가능한 값: true, false
type
필수		웹 태그의 유형입니다.

유형: enum

가능한 값: ADDED_PAYMENT_INFO, ADD_TO_CART, ADD_TO_WISHLIST, CHECKOUT_INITIATED, CONTENT_VIEW, CUSTOM, DOWNLOAD, PRODUCT_CUSTOMIZATION,PURCHASE, SEARCH, SIGN_UP, SITE_VISIT, START_TRIAL, SUBSCRIBE

(UI에서는 SITE_VISIT이(가) “Page view”, SIGN_UP이(가) “Lead”로 표시됩니다)
view_through_window
필수		이 웹 태그의 뷰스루 윈도우입니다. 이 값은 항상 click_window 값 이하여야 합니다.

참고: 아래에 나열된 값만 허용됩니다.

유형: int

가능한 값: 0, 1, 7, 14, 30
예시 요청
POST https://ads-api.x.com/12/accounts/18ce54d4x5t/web_event_tags?click_window=7&name=web event tag&retargeting_enabled=false&type=SITE_VISIT&view_through_window=7

​
응답 예시

    {
      "data": {
        "name": "웹 이벤트 태그",
        "view_through_window": 7,
        "click_window": 7,
        "embed_code": "<script src='"//platform.x.com/oct.js"' type='"text/javascript"'></script><script type='"text/javascript"'>twttr.conversion.trackPid('ny3od',  { tw_sale_amount: 0, tw_order_quantity: 0 });</script><noscript><img alt='""' height='"1"' src='"https://analytics.x.com/i/adsct?txn_id=ny3od&p_id=Twitter&tw_sale_amount=0&tw_order_quantity=0"' style='"display:none;"' width='"1"'/><img alt='""' height='"1"' src='"//t.co/i/adsct?txn_id=ny3od&p_id=Twitter&tw_sale_amount=0&tw_order_quantity=0"' style='"display:none;"' width='"1"'/></noscript>",
        "id": "o3bk1",
        "retargeting_enabled": false,
        "last_tracked_at": null,
        "status": "UNVERIFIED",
        "type": "SITE_VISIT",
        "website_tag_id": "ny3od",
        "deleted": false
      },
      "request": {
        "params": {
          "name": "웹 이벤트 태그",
          "view_through_window": 7,
          "click_window": 7,
          "retargeting_enabled": false,
          "account_id": "18ce54d4x5t",
          "type": "SITE_VISIT"
        }
      }
    }

​
PUT accounts/:account_id/web_event_tags/:web_event_tag_id

현재 계정에 연결된 웹 이벤트 태그를 업데이트합니다.
리소스 URL
https://ads-api.x.com/12/accounts/:account_id/web_event_tags/:web_event_tag_id

​
매개변수

NameDescription
account_id
required		레버리지된 계정의 식별자입니다. 리소스 경로에 포함되며, GET accounts를 제외한 모든 Advertiser API 요청에서 일반적으로 필수 매개변수입니다. 지정한 계정은 인증된 사용자와 연결되어 있어야 합니다.

Type: string

Example: 18ce54d4x5t
web_event_tag_id
required		현재 계정의 웹 태그 식별자입니다.

Type: string

Example: o3bk1
click_window
optional		이 웹 태그의 클릭 윈도입니다.

Note: 아래에 나열된 값만 허용됩니다.

Type: int

Possible values: 1, 7, 14, 30
name
optional		웹 태그의 이름입니다.

Type: string

Example: Sample single conversion event
retargeting_enabled
optional		이 웹 태그에 대해 리타게팅을 활성화할지 여부입니다.

Type: boolean

Possible values: true, false
type
optional		웹 태그의 유형입니다.

Type: enum

Possible values: ADDED_PAYMENT_INFO, ADD_TO_CART, ADD_TO_WISHLIST, CHECKOUT_INITIATED, CONTENT_VIEW, CUSTOM, DOWNLOAD, PRODUCT_CUSTOMIZATION, PURCHASE, SEARCH, SIGN_UP, SITE_VISIT, START_TRIAL, SUBSCRIBE

(UI에서는 SITE_VISIT은 “Page view”, SIGN_UP은 “Lead”로 표시됩니다)
view_through_window
optional		이 웹 태그의 뷰스루 윈도입니다. 이 값은 항상 click_window 값보다 작거나 같아야 합니다.

Note: 아래에 나열된 값만 허용됩니다.

Type: int

Possible values: 0, 1, 7, 14, 30

​
예제 요청

PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/web_event_tags/o3bk1?type=DOWNLOAD

​
응답 예시

    {
      "data": {
        "name": "웹 이벤트 태그",
        "view_through_window": 7,
        "click_window": 7,
        "embed_code": "<script src='"//platform.x.com/oct.js"' type='"text/javascript"'></script><script type='"text/javascript"'>twttr.conversion.trackPid('ny3od',  { tw_sale_amount: 0, tw_order_quantity: 0 });</script><noscript><img alt='""' height='"1"' src='"https://analytics.x.com/i/adsct?txn_id=ny3od&p_id=Twitter&tw_sale_amount=0&tw_order_quantity=0"' style='"display:none;"' width='"1"'/><img alt='""' height='"1"' src='"//t.co/i/adsct?txn_id=ny3od&p_id=Twitter&tw_sale_amount=0&tw_order_quantity=0"' style='"display:none;"' width='"1"'/></noscript>",
        "id": "o3bk1",
        "retargeting_enabled": false,
        "last_tracked_at": "2021-05-22T17:00:04Z",
        "status": "UNVERIFIED",
        "type": "DOWNLOAD",
        "website_tag_id": "ny3od",
        "deleted": false
      },
      "request": {
        "params": {
          "web_event_tag_id": "o3bk1",
          "type": "DOWNLOAD",
          "account_id": "18ce54d4x5t"
        }
      }
    }

​
DELETE accounts/:account_id/web_event_tags/:web_event_tag_id

현재 계정에 연결된 특정 웹 이벤트 태그를 삭제합니다.

​
리소스 URL

https://ads-api.x.com/12/accounts/:account_id/web_event_tags/:web_event_tag_id
매개변수
이름설명
account_id
필수		활용 계정의 식별자입니다. 리소스 경로에 포함되며 GET accounts를 제외한 모든 Advertiser API 요청에서 일반적으로 필수 매개변수입니다. 지정된 계정은 인증된 사용자와 연결되어 있어야 합니다.

유형: string

예: 18ce54d4x5t
web_event_tag_id
필수		현재 계정의 웹 태그 식별자입니다.

유형: string

예: o3bk1
예시 요청
DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/web_event_tags/o3bk1
예시 응답
    {
      "data": {
        "name": "웹 이벤트 태그",
        "view_through_window": 7,
        "click_window": 7,
        "embed_code": "<script src='"//platform.x.com/oct.js"' type='"text/javascript"'></script><script type='"text/javascript"'>twttr.conversion.trackPid('ny3od',  { tw_sale_amount: 0, tw_order_quantity: 0 });</script><noscript><img alt='""' height='"1"' src='"https://analytics.x.com/i/adsct?txn_id=ny3od&p_id=Twitter&tw_sale_amount=0&tw_order_quantity=0"' style='"display:none;"' width='"1"'/><img alt='""' height='"1"' src='"//t.co/i/adsct?txn_id=ny3od&p_id=Twitter&tw_sale_amount=0&tw_order_quantity=0"' style='"display:none;"' width='"1"'/></noscript>",
        "id": "o3bk1",
        "retargeting_enabled": false,
        "last_tracked_at": "2021-05-22T17:00:04Z",
        "status": "UNVERIFIED",
        "type": "DOWNLOAD",
        "website_tag_id": "ny3od",
        "deleted": true
      },
      "request": {
        "params": {
          "web_event_tag_id": "o3bk1",
          "account_id": "18ce54d4x5t"
        }
      }
    }