메인 콘텐츠로 건너뛰기

​
Conversion API 설정

​
사전 준비 사항

​
Ads API Access - New Applications

Step 1: Developer Account
  • Developer Account를 신청할 때, 즉시 승인을 받으려면 구독 plans 중 하나를 함께 신청하세요. 
  • Note: 모범 사례로, 공식 회사 X 핸들을 사용해 개발자 계정을 생성하고 Ads API 접근 권한을 신청할 것을 강력히 권장합니다. 개발자 계정이 개인 개발자 핸들과 연계되어 있으면, 필요 시에도 해당 자격 증명을 이전할 방법이 없습니다. 지속적인 관리를 위해 회사 계정으로 운영하고, 필요에 따라 Multi-user login을 활용하는 것이 가장 좋습니다. 그렇지 않은 경우에도 최소한 계정은 기본값이 아닌 설정(헤더 이미지, 아바타, 프로필 설명, 프로필 URL)으로 구성되어야 하며, 2단계 인증을 사용해야 합니다.
Step 2: Ads API Application
  • Ads API Application을 위해 올바른 App ID를 준비했는지 확인하세요. App ID는 Developer Console의 Projects & Apps 섹션에서 확인할 수 있습니다. 예시: 16489123
  • X 담당자에게 연락하여 Ads API 접근 권한을 요청하세요.

​
Ads API Access - Existing Applications

  • 이미 현재 사용 중인 Ads API App이 있는 경우, 해당 App과 기존 액세스 토큰을 모두 Conversion API에 사용할 수 있습니다.

​
액세스 토큰

  • Ads API 애플리케이션을 소유한 사용자 핸들의 User Access Token은 개발자 콘솔에서 바로 생성하고 조회할 수 있습니다. 이는 본인의 X 핸들에 사용하도록 되어 있기 때문에 “personal access token”이라고 부릅니다. 인증 및 개발자 콘솔에 대한 전반적인 정보는 여기에서 확인할 수 있습니다.
  • Ads API 애플리케이션을 소유한 핸들이 아닌 다른 사용자 핸들의 User Access Token은 3-legged OAuth 플로우로 생성해야 합니다. 3-legged OAuth를 사용해 Access Token을 생성하는 방법은 다음과 같습니다.
  • Conversion API에서 사용되는 모든 사용자 토큰은 AD_MANAGER 또는 ACCOUNT_ADMIN 액세스 레벨을 가진 사용자에 대한 것이어야 하며, 이는 authenticated_user_access 엔드포인트를 통해 확인할 수 있습니다.
  • 참고: 위와 같이 생성된 토큰 자체는 사용 목적으로 AD_MANAGER 또는 ACCOUNT_ADMIN 액세스 레벨이 없는 사용자와도 공유할 수 있습니다.

​
단계

​
Conversion API 이벤트 생성

Conversion API를 사용하려면 Ads Manager에서 새 전환 이벤트를 생성하거나, 이미 생성되어 X Pixel과 함께 사용 중인 기존 전환 이벤트를 사용해야 합니다. Pixel 이벤트와 Conversion API 이벤트 간에 중복 제거(deduplication)를 하려는 경우, Pixel용으로 이미 생성해 둔 기존 전환 이벤트를 사용해야 합니다. 
옵션 1: Ads Manager에서 기존 전환 이벤트 사용
이미 X 픽셀과 함께 사용 중인 기존 이벤트를 사용하려면, 해당 이벤트에서 Event ID를 가져오면 됩니다. 동일한 이벤트에 대해 픽셀과 Conversion API를 모두 사용하는 경우, 같은 이벤트에 대해 Pixel과 Conversion API 간 이벤트를 중복 제거할 수 있도록 Pixel 코드 스니펫과 Conversion API 요청 모두에서 conversion_id를 중복 제거 키로 사용해야 합니다. 자세한 내용은 d. 이벤트 테스트 및 중복 제거 섹션을 참조하세요. 
옵션 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로 설치(Install with Conversion API)를 선택합니다.
  3. 이 이벤트에 대해 API에서 사용될 Pixel ID와 Event ID를 확인할 수 있습니다.
    1. 이 이벤트의 ID가 Event ID입니다.
  4. Save를 클릭하면 전환 이벤트가 생성되며 사용할 준비가 완료됩니다.

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

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

​
1. X 클릭 ID 식별자 준비

전환 요청에 항상 Click ID를 포함하는 것을 권장합니다. 사용자가 목적지 웹사이트로 이동한 후, 사용할 수 있는 경우 쿼리 문자열 파라미터 twclid에서 Click ID를 파싱해야 합니다.  기본 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. 이메일 식별자 준비

지원되는 고객 매칭 필드는 전송할 수 있으나, 정규화해야 하며 필요할 경우 개인정보 보호를 위해 해시 처리해야 합니다. 해당 정보는 솔트 없이 SHA256으로 해시되어야 합니다.  예를 들어, 이메일 주소 test@x.com의 경우 다음과 같은 해시 형식으로 전송해야 합니다: d360d510a224510f373931ce2d6215a799f5a9c1cef221b0149b6b6b50cced62.

​
3. 전화번호 식별자 준비

전화번호는 E164 표준 형식으로 전달해야 하며, 해당 정보는 솔트 없이 SHA256으로 해시해야 합니다.  예를 들어 미국 전화번호 +11234567890의 경우, 다음과 같이 해시된 형식으로 X에 전송되어야 합니다: 1fa6b8d986d9b9cd01bf36951815158bbde9f520c0567c835dfe34783d0a4231.

​
4. IP 주소 식별자 준비

IP 주소는 다른 식별자(twclid, 이메일 주소, 전화번호 또는 user agent)와 함께 전송해야 합니다. 이 식별자에는 해싱이 필요하지 않습니다. 이 값은 마침표로 구분된 네 개의 숫자로 이루어진 점 구분 10진 표기(dotted-decimal notation)로 작성됩니다. 예를 들어, 사용자의 IP 주소는 8.25.197.25일 수 있습니다.

​
5. User Agent 식별자 준비

User Agent는 다른 식별자(twclid, 이메일 주소, 전화번호 또는 IP 주소)와 함께 전달해야 합니다. 이 식별자에는 해싱이 필요하지 않습니다. 이 식별자는 서버가 요청을 보내는 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와 같이 전달할 수 있습니다.

​
전환 이벤트 요청 구성

POST: version/measurement/conversions/:pixel_id 특정 광고 계정에 대한 전환 이벤트를 전송합니다. 응답 코드를 확인하여 요청이 성공했는지(HTTP 200 OK) 반드시 확인해야 합니다. 오류 코드가 반환되는 경우를 대비해 재시도 메커니즘과 기본 로깅을 구현하는 것이 권장됩니다. 엔드포인트의 URL 및 POST 본문 매개변수에 대한 자세한 내용은 API 참조 문서 섹션을 참조하세요. 

​
예시 요청(가독성을 위해 서식을 정리함)


    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":"Pet supply purchases",
            "contents":[
               {
                  "content_id":"1",
                  "content_name":"Blankets",
                  "content_type":"Pet supplies",
                  "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"}
}

​
Rate Limit

레이트 리밋은 계정당 15분 간격마다 이벤트 60,000개입니다. 이 요청 호출 외부에서 다음과 같은 로직을 서버 코드에 구현해야 할 수도 있습니다:
  1. 각 이벤트마다 올바른 전환 데이터를 전송할 수 있도록 사용자 행동을 계측(로그 기록)하는 작업
  2. 관련 프라이버시 선택권을 행사한 사용자의 전환 이벤트를 필터링하기 위한 모든 필요한 로직 — 예를 들어, 광고주의 웹사이트에서 추적 또는 개인 정보 판매를 거부(opt-out)한 경우
  3. 이벤트를 포착하고 전환을 전송하기 위한 이벤트 트리거 및 페이지와의 통합

​
이벤트 테스트 및 중복 방지

​
이벤트 테스트

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

​
Pixel과 Conversion API 간 중복 처리

Pixel과 Conversion API 요청 간 전환을 중복 제거(deduplicate)하려는 경우, conversion\_id를 중복 제거 키로 사용할 수 있습니다. 중복 제거는 이벤트 수준에서만 수행됩니다. 다시 말해, Pixel과 CAPI 요청 간 중복 제거를 하려면 광고주는 동일한 conversion\_id를 사용하는 것뿐 아니라 Pixel과 CAPI 요청 모두에서 동일한 이벤트를 사용해야 합니다. 중복 제거는 48시간 이내에 수신된 이벤트에만 적용될 수 있습니다.

​
전환 추적(개요)

​
요약

전환 추적을 사용하면 X에서 광고를 노출·상호작용한 이후에 원하는 행동을 수행한 X 사용자의 수를 측정할 수 있습니다. 이를 통해 어떤 캠페인이 사이트 방문, 가입, 구매와 같은 행동을 유도하는지 측정할 수 있습니다. 이는 광고주가 X 외부에서 다이렉트 리스폰스 광고의 성과를 파악해 비용 효율적으로 고객을 확보할 수 있도록 해 줍니다. 전환 태그를 사용하면 광고주는 사용자 전환을 추적하고 이를 X 상의 광고 캠페인과 연계할 수 있습니다. 이를 통해 캠페인을 최적화하여 CPA(획득당 비용) 목표를 달성할 수 있는 가시성을 확보할 수 있습니다. 광고주는 전환 추적을 통해 다양한 웹사이트 행동을 측정할 수 있습니다. 광고 캠페인을 통해 유도하고자 하는 행동에 따라 다음 중 하나 이상을 선택할 수 있습니다.
  • 사이트 방문: 사용자가 광고주의 사이트 내 랜딩 페이지를 방문
  • 구매: 사용자가 광고주의 사이트에서 상품 또는 서비스를 구매 완료
  • 다운로드: 사용자가 광고주의 사이트에서 백서나 소프트웨어 패키지와 같은 파일을 다운로드
  • 가입: 사용자가 광고주의 서비스, 뉴스레터 또는 이메일 수신에 가입
  • 사용자 정의: 위 범주에 속하지 않는 사용자 정의 행동을 위한 포괄적인 범주
X의 전환 추적은 광고주가 전환 기여도를 전체적으로 파악할 수 있도록 해 줍니다. 고유 클릭 URL과 서드 파티 추적 태그를 조합하는 방식과 같이, 기존에 X의 자체 전환 추적 기능 대신 사용되었을 수 있는 서드 파티 측정 시스템과 비교했을 때, X의 전환 태그는 광고주가 Tweet 확장, 리트윗, 좋아요, 답글, 팔로우뿐만 아니라 노출(impression)과 같이 퍼널 중·상단의 참여에 기여된 전환까지 추적할 수 있는 기능을 제공합니다.

​
FAQ

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

​
Conversion API 문제 해결 및 지원

API 호출 후 오류 코드 관련 문의가 있으시면 아래 섹션을 참고하세요. 그 외 모든 문의에 대해서는 언제든지 Twitter 담당자에게 연락해 주세요. 가능한 한 신속히 해결할 수 있도록 지원하겠습니다. 

​
오류 처리 및 설명

단일 요청은 그 안에 포함된 모든 전환에 대해 errors가 하나도 없을 때에만 성공합니다. 개별 전환에 어떤 오류라도 발생하면, 엔드포인트는 해당 전환에 대해 적용 가능한 모든 errors 목록을 반환합니다.

​
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 상태 페이지나 개발자 커뮤니티 포럼을 확인해 보세요.

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

  • 400 Bad Request (요청이 표준/형식에 맞지 않음)
  • 401 Unauthorized (인증 관련 문제)
  • 403 Forbidden (해당 개발자 계정과 연관된 API 접근 권한 문제)
  • 404 Not Found (해당 엔드포인트에 대해 URL 또는 매개변수가 올바르지 않을 수 있음)

​
Conversion API 오류 코드

​
400 잘못된 요청 시나리오

ReasonTypeError Message
식별자 누락 오류 (현재 해시된 이메일 또는 X 클릭 ID(twclid))400 Bad Request사용자 식별자는 최소 한 개 이상 제공해야 합니다
잘못된 해시된 이메일400 Bad RequestHashed_email이 올바른 SHA-256 해시가 아닙니다
event_id의 type이 단일 이벤트 태그(SET)가 아님400 Bad RequestEvent_id (<event_id>)가 단일 이벤트 태그(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_id (o6dkt) is not a single event tag (SET)","parameter":"event_id"}],"request":{"params":{"account_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":"At least one user identifier must be provided","parameter":""}],"request":{"params":{"account_id":"18ce552mlaq"}}}

​
요청:

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

​
오류 메시지:

{"errors":[{"code":"INVALID_PARAMETER","message":"hashed_email (abc) is not a valid SHA-256 hash","parameter":"hashed_email"}],"request":{"params":{"account_id":"18ce552mlaq"}}}

​
요청:

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

​
오류 메시지:

{"errors":[{"code":"INVALID_PARAMETER","message":"Expected Time in yyyy-MM-ddTHH:mm:ss.SSSZ, got \"2022-06-16T01:14:00.603\" for conversion_time","parameter":"conversion_time"}],"request":{"params":{"account_id":"18ce552mlaq"}}}

​
401 Unauthorized

이유: 인증 자격 증명이 없거나 올바르지 않음  해결 방법: 다음 3가지 인증 방법 중 하나를 사용하여 Set Up 문서에 있는 인증 단계를 따르세요: Ads API 애플리케이션을 소유한 핸들이 아닌 다른 사용자 핸들에 대한 User Access Token은 3-legged OAuth 플로우로 생성해야 합니다. 3-legged OAuth를 사용하여 Access Token을 생성하는 옵션은 다음과 같습니다. 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 Not Found

이유유형오류 메시지
요청 URL 또는 매개변수가 해당 엔드포인트에 대해 올바르지 않습니다404 Route Not FoundThe requested resource could not be found
pixel_id/Universal Website Tag를 소유한 계정에 대한 액세스 권한이 없습니다404 Not FoundUser <user_id> does not have access to account <account_id>. Type ‘sn <user_id>’ to get the handle of the user. Use ‘twurl accounts’ and ‘twurl set default \u003Cusername\u003E’ to change the user you’re using.
event id가 pixel ID(UWT ID)와 연결된 제공된 계정에 속해 있지 않습니다404 Not Foundevent_id <event_id> does not belong to provided account

​
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) does not belong to provided account","parameter":"event_id"},{"code":"INVALID_PARAMETER","message":"event_id (abc) is not a single event tag (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건이며, 각 요청에는 최대 500개의 이벤트를 포함할 수 있습니다.
리소스 URL
https://ads-api.x.com/12/measurement/conversions/:pixel_id
Request URL Parameters
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_id": "23294827"}]
conversions object
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		전환 이벤트를 매칭하기 위한 식별자 객체(identifier object) 목록입니다. 지원되는 필드는 아래 표에 나열되어 있습니다. 식별자 객체 중 최소 하나는 필수입니다.

IP 주소 또는 user agent를 사용하는 경우, 올바른 전환 매칭을 위해 두 번째 식별자를 함께 전송해야 합니다.

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 전환 간 중복 제거를 위한 값입니다. 동일한 event tag 내에서 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 object
NameDescription
twclid
sometimes required		클릭 유입 URL에서 파싱된 Click ID입니다. 다른 식별자가 추가되지 않은 경우 필수입니다.

Type: string

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

Type: string

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

Type: string

Example: +11234567890의 경우 = 1fa6b8d986d9b9cd01bf36951815158bbde9f520c0567c835dfe34783d0a4231 
ip_address
sometimes required		마침표로 구분된 네 개의 숫자로 구성된 점-10진수 표기법으로 작성된 값입니다.

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

Type: string

Example: 8.25.197.25
**user_agent **
sometimes required		이 식별자는 서버가 요청하는 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 객체
NameDescription
content_id
optional		SKU 또는 GTIN; 콘텐츠를 나타내는 식별자입니다.

Type: string

Example: jhp
content_group_id
optional		제품 옵션(variant) 그룹과 연결된 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성공적으로 처리된 전환(conversion) 수

Type: integer

Example: 1
debug_id후속 분석에 사용할 수 있는 디버그용 UUID

Type: string

Example: 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_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":"Pet supply purchases",
            "contents":[
               {
                  "content_id":"1",
                  "content_name":"Blankets",
                  "content_type":"Pet supplies",
                  "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"
       }
    }

​
웹 이벤트 태그

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

​
리소스 URL

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

​
Parameters

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

Type: string

Example: 18ce54d4x5t
count
optional		각 요청마다 가져올 레코드 수를 지정합니다.

Type: int

Default: 200
Min, Max: 1, 1000
cursor
optional		다음 페이지의 결과를 가져오기 위한 커서를 지정합니다. 자세한 내용은 Pagination을 참고하세요.

Type: string

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

Type: string

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

Type: string

Example: o3bk1
with_deleted
optional		삭제된 결과도 응답에 포함합니다.

Type: boolean

Default: false
Possible values: true, false
with_total_count
optional		total_count 응답 속성을 포함합니다.

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

Note: total_count를 포함하는 요청에는 더 낮은 요청 한도가 적용되며, 현재 15분당 200건입니다.

Type: boolean

Default: false
Possible values: 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": "web event tag",
          "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
매개변수
NameDescription
account_id
required		활용 중인 광고 계정의 식별자입니다. 리소스 경로에 포함되며, GET accounts을(를) 제외한 모든 Advertiser API 요청에서 일반적으로 필수 매개변수입니다. 지정한 계정은 인증된 사용자와 연관되어 있어야 합니다.

Type: string

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

Type: string

Example: o3bk1
with_deleted
optional		요청 결과에 삭제된 항목을 포함할지 여부입니다.

Type: boolean

Default: false
Possible values: 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": "web event tag",
        "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

​
매개변수

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

Type: string

Example: 18ce54d4x5t
click_window
required		이 웹 태그의 클릭 윈도우입니다.

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

Type: int

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

Type: string

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

Type: boolean

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

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
required		이 웹 태그의 뷰스루 윈도우입니다. 이 값은 항상 click_window 값보다 작거나 같아야 합니다.

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

Type: int

Possible values: 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": "web event tag",
        "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": "web event tag",
          "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		레버리지 계정(leveraged account)의 식별자입니다. 리소스 경로에 포함되며, GET accounts를 제외한 모든 Advertiser API 요청에서 일반적으로 필수 매개변수입니다. 지정한 계정은 인증된 사용자와 연관되어 있어야 합니다.

Type: string

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

Type: string

Example: o3bk1
click_window
optional		이 웹 태그의 클릭 윈도우(기간)입니다.

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

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 값보다 작거나 같아야 합니다.

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

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": "web event tag",
        "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
Parameters
NameDescription
account_id
required		활용 중인 계정의 식별자입니다. 리소스 경로에 포함되며, GET accounts를 제외한 모든 Advertiser API 요청에서 일반적으로 필수 매개변수입니다. 지정된 계정은 인증된 사용자와 연결되어 있어야 합니다.

Type: string

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

Type: string

Example: o3bk1
예시 요청
DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/web_event_tags/o3bk1
응답 예시
    {
      "data": {
        "name": "web event tag",
        "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"
        }
      }
    }