소개
애널리틱스 지표는 파트너와 광고주가 X에서 프로모션하는 콘텐츠의 성과를 이해하는 데 도움을 줍니다. 여기에는 노출 수(impressions), 클릭 수(clicks), 동영상 조회수(video views), 집행 금액(spend)과 같은 정보가 포함됩니다. 또한 파트너와 광고주는 도달한 오디언스의 다양한 세그먼트별로 상세 지표를 조회할 수 있습니다. Ads API는 캠페인 성과 지표를 상세하게 조회하는 두 가지 방식을 지원합니다. 동기(synchronous) 방식과 비동기(asynchronous) 방식입니다. 동기 애널리틱스 호출에서는 요청한 지표가 응답에 바로 반환됩니다. 비동기 애널리틱스 엔드포인트에서는 관련 “job” 처리가 완료된 후, 요청한 지표를 다운로드 가능한 결과 파일에서 확인할 수 있습니다. 동기 엔드포인트는 짧은 기간 범위를 지원하며 실시간 캠페인 최적화에 적합합니다. 비동기 엔드포인트는 훨씬 긴 기간 범위를 지원하며, 훨씬 더 많은 데이터를 조회하는 용도로 설계되어 있어 리포트 생성이나 과거 데이터 백필에 이상적입니다.상세 정보
동기식 vs. 비동기식
| Feature | Synchronous | Asynchronous |
|---|---|---|
| Rate limiting | 사용자 수준: 15분당 요청 250건 | 계정 수준: 동시에 처리 중일 수 있는* 작업 최대 100건 |
| Time range | 7일 | 90일(세분화 없음 기준) 45일(세분화 기준) |
| Segmentation | 없음 | 있음 |
| Response returns | 메트릭 데이터 | 작업의 처리 상태** |
| Recommended use case | 실시간 최적화 사용자 인터페이스 요청 | 정기적인 동기화 작업 과거 데이터 백필(backfill) |
- 이는 어떤 시점에서든 처리 상태에 있을 수 있는 최대 작업 수를 의미합니다.
사용 사례
- 실시간 최적화: 성과 지표를 사용해 진행 중인 캠페인을 업데이트
- 동기화: 정기적으로 실행되는 백그라운드 동기화
- 새 계정 온보딩: 과거 데이터 백필(backfilling)
요청 옵션
- 엔터티: 엔터티
type과 애널리틱스를 조회하려는 최대 20개의 엔터티id - 기간: ISO 8601 형식으로 표현된 시작 및 종료 시각
- 참고: 반드시 정각(1시간 단위)으로 표현해야 합니다
- 메트릭 그룹: 하나 이상의 관련 메트릭 집합(각 메트릭 그룹에 포함된 메트릭 목록은 Metrics and Segmentation을 참조)
- 세분성(granularity): 메트릭이 반환되어야 하는 집계 수준을 지정
- 노출 위치(placement): X 온플랫폼 또는 오프플랫폼에서 게재된 광고의 메트릭을 가져올지 여부를 결정
- 참고: 요청당 하나의 placement 값만 지정할 수 있습니다
start_time 및 end_time 요청 매개변수를 사용하여 기간을 지정합니다. 이 값들은 아래와 같이 지정한 granularity와 일치해야 합니다.
TOTAL: 임의의 기간을 지정할 수 있음(엔드포인트 제한 범위 내)DAY: 시작 시각과 종료 시각 모두 계정 시간대 기준 자정에 맞춰야 함HOUR: 임의의 기간을 지정할 수 있음(엔드포인트 제한 범위 내)
end_time)은 포함되지 않습니다(exclusive). 예를 들어, start_time=2019-01-01T00:00:00Z 및 end_time=2019-01-02T00:00:00Z로 요청하면, 이 기간은 정확히 24시간만 포함하므로 하루치 애널리틱스 메트릭만(이틀 분이 아닌) 반환됩니다.
세그멘테이션
비동기 애널리틱스 엔드포인트에서만 제공되는 세그멘테이션 기능을 사용하면, 파트너와 광고주는 특정 타게팅 값별로 분리된 메트릭을 조회할 수 있습니다. 세그먼트된 메트릭을 요청하려면 segmentation_type 요청 매개변수를 사용하세요. 세그멘테이션 옵션에 대한 자세한 내용은 Metrics and Segmentation을 참조하세요.
FAQs
ALL_ON_TWITTER,PUBLISHER_NETWORK,SPOTLIGHT,TREND모든 게재 위치에 대한 데이터를 요청했는지 확인하세요.- Ads API에서 종료 시간은 배타적이지만, Ads UI에서는 포함된다는 점을 기억하세요.
- 집계 지표가 사용 가능해지는 즉시 조회할 수 있으며, 거의 실시간으로 제공됩니다. 다만 이러한 초기 결과는 추정치이므로 이후 변경될 수 있습니다. 지표는 지출 데이터를 제외하고 24시간 후에 확정됩니다.
- 지출(spend) 지표는 일반적으로 이벤트 발생 후 3일 이내에 확정됩니다. 하지만 청구 데이터는 (예: 스팸 필터링을 위해) 이벤트 발생일로부터 최대 14일까지 처리됩니다.
- Active Entities endpoint를 사용하세요.
null인 이유는 무엇인가요?
- 요청한 기간 동안 캠페인이 집행되지 않았을 가능성이 큽니다.
- 어떤 기간에 어떤 엔티티에 대해 애널리틱스를 조회해야 할지 결정하기 위해 Active Entities endpoint를 사용하세요.
null 값을 표시하는데 UI는 0으로 표시하나요?
- UI는 이러한 값을 0으로 표시하도록 선택했을 뿐이며, 실제로는 동일한 값을 나타냅니다.
- 애널리틱스에서는
ALL_ON_TWITTER,PUBLISHER_NETWORK,SPOTLIGHT,TREND(즉, X Audience Platform)에 대한 게재 위치 값을 지원합니다.
- 네. 엔티티의 상태는 애널리틱스 지표의 가용성에 영향을 주지 않습니다.
- 이 정보가 산출되는 방식 때문에, 세그먼트된 데이터가 비세그먼트 데이터와 100% 합산되어 일치할 것으로 기대해서는 안 됩니다.
- 다중 세그먼트 요청은 지원하지 않습니다.
모범 사례
속도 제한 및 재시도
- 속도 제한이 적용된 쿼리(HTTP 429 상태 코드를 반환하는 경우)에서는
x-rate-limit-reset헤더를 확인하고, 해당 헤더에 표시된 시각에 도달했거나 그 이후에만 다시 시도해야 합니다. - HTTP 503 Service Unavailable 상태 코드를 반환하는 쿼리에서는
retry-after헤더를 확인하고, 해당 헤더에 표시된 시간이 지난 이후에만 다시 시도해야 합니다. - 재시도와 관련하여 표시된 시간을 준수하지 않는 애플리케이션은 사전 통지 없이 Ads API에 대한 접근 권한이 취소되거나 제한될 수 있습니다.
애널리틱스 메트릭 요약
billed_charge_local_micro를 제외한 모든 애널리틱스 메트릭은 24시간이 지나면 확정되며 이후에는 변경되지 않습니다.billed_charge_local_micro메트릭은 데이터가 반환된 시점부터 최대 3일 동안은 추정값입니다.- 24시간 이후에는 초과 집행(지정된
end_time이후에 노출된 광고) 및 무효로 판정된 과금 가능 이벤트에 대한 크레딧으로 인해 이 메트릭이 감소할 수 있습니다. 이 메트릭은 24시간 이후에는 거의 변경되지 않습니다. - 자세한 내용은 Analytics 문서를 참고하세요.
실시간 비세그먼트 데이터 가져오기
- 항상
start_time과end_time을 모두 제공하세요. - 7일보다 오래된 엔티티의 데이터는 조회하지 마세요.
- 가능하면
HOUR세분성으로 데이터를 요청하세요. 언제든지 집계하여DAY및TOTAL세분성으로 롤업할 수 있습니다. - 가능하면
line_items및promoted_tweets수준에서 데이터를 요청하세요. 언제든지 이러한 메트릭을 집계하여 전체 광고 엔티티 계층(예: 캠페인, 자금 조달 수단 또는 계정 수준)에 대한 총합으로 롤업할 수 있습니다. - 분석 메트릭 값을 로컬에서 저장·보관하세요.
- 30일보다 오래된 데이터는 반복해서 쿼리하지 마세요. 이 데이터는 변경되지 않으므로 로컬에 저장해 두어야 합니다.
- 모든 비세그먼트 데이터는 실시간이며, 이벤트가 발생한 후 몇 초 이내에 데이터를 조회할 수 있습니다.
- 전환(conversion) 메트릭과 비전환 메트릭은 별도의 요청으로 분리하세요.
세분화된 데이터 가져오기
- 위의 “실시간 비세분화 데이터 가져오기”에 제공된 가이드라인을 참조하세요. 추가적인 안내는 아래 내용을 참고하세요.
- 대부분의 세분화된 데이터 유형의 경우, 데이터가 최대 1시간 동안 완전히 수집되지 않을 수 있습니다.
INTERESTS기준으로 세분화된 데이터는 최대 12시간까지 지연될 수 있습니다. - 이 정보가 생성되는 방식 때문에, 세분화된 데이터를 모두 합산하더라도 비세분화 데이터와 100% 일치하지 않을 수 있습니다.
과거 데이터 가져오기
- 데이터를 보충할 때(예: 새 광고주 계정을 추가하는 경우),
start_time과end_time을 더 작은 구간으로 나눠 여러 번 요청해야 할 수 있습니다. - 조회 범위를 최대 30일 이내의 기간 단위로 제한하세요.
- 이러한 요청으로 인해 요청 한도가 소진되지 않도록, 시간을 두고 분산시키고 요청 속도를 조절하세요.
예시
fetch_stats)는 ads-platform-tools GitHub 리포지토리에서 확인할 수 있습니다.
목표별 지표
ENGAGEMENTS
관련 메트릭 그룹: ENGAGEMENT 및 BILLING. 크리에이티브에 미디어가 사용된 경우 MEDIA도 적용됩니다.
| 파생 지표 | 노출 지표 계산식 |
| 참여율 | engagements/impressions |
| CPE | billed_charge_local_micro/engagements |
| 미디어 조회율 | media_views/impressions |
WEBSITE_CLICKS 및 WEBSITE_CONVERSIONS
ENGAGEMENT, BILLING, WEB_CONVERSION. 크리에이티브에 미디어가 사용된 경우 MEDIA도 적용됩니다.
| 파생 메트릭 | 노출 메트릭 계산식 |
| CPM | billed_charge_local_micro/impressions/1000 |
| 클릭률 | clicks/impressions |
| CPLC | billed_charge_local_micro/clicks |
| 총 전환 수 | conversion_custom + conversion_site_visits + conversion_sign_ups + conversion_downloads + conversion_purchases |
| 전환율 | 총 전환 수 / impressions |
| CPA | billed_charge_local_micro / 총 전환 수 |
APP_INSTALLS 및 APP_ENGAGEMENTS
ENGAGEMENT, BILLING, MOBILE_CONVERSION, LIFE_TIME_VALUE_MOBILE_CONVERSION. 크리에이티브에서 미디어 또는 비디오 앱 카드가 사용된 경우 MEDIA 및 VIDEO도 적용됩니다.
| 파생 지표 | 노출 지표의 계산식 |
| CPM | billed_charge_local_micro/impressions/1000 |
| App 클릭률 | app_clicks/impressions |
| CPAC | billed_charge_local_micro/app_clicks |
| CPI | billed_charge_local_micro/mobile_conversion_installs |
FOLLOWERS
ENGAGEMENT 및 BILLING. 크리에이티브에 미디어가 사용된 경우 MEDIA도 적용됩니다.
| 파생 메트릭 | 표시 메트릭 계산식 |
| CPM | billed_charge_local_micro/impressions/1000 |
| 팔로우율 | follows/impressions |
| CPF | billed_charge_local_micro/follows |
| 미디어 조회율 | media_views/impressions |
LEAD_GENERATION
ENGAGEMENT 및 BILLING. 크리에이티브에 미디어가 사용되는 경우 MEDIA도 적용됩니다.
| 파생 지표 | 제공 지표 계산식 |
| CPM | billed_charge_local_micro/impressions/1000 |
| 리드(Leads) | card_engagements |
| 리드율(Lead Rate) | card_engagements/impressions |
| 리드당 비용(Cost Per Lead) | billed_charge_local_micro/card_engagements |
VIDEO_VIEWS
ENGAGEMENT, BILLING, VIDEO.
| 파생 메트릭 | 표시 메트릭 계산식 |
| CPM | billed_charge_local_micro/impressions/1000 |
| 동영상 재생 비율 | video_total_views/impressions |
| 조회당 비용 | billed_charge_local_micro/video_total_views |
VIDEO_VIEWS_PREROLL
ENGAGEMENT, BILLING, VIDEO.
| 파생 메트릭 | 표시 메트릭 계산식 |
| CPM | billed_charge_local_micro/impressions/1000 |
| 동영상 재생률 | video_total_views/impressions |
| 조회당 비용 | billed_charge_local_micro/video_total_views |
지표 및 세분화
| 지표 그룹 | |||||||
| 엔터티 | ENGAGEMENT | BILLING | VIDEO | MEDIA | WEB_CONVERSION | MOBILE_CONVERSION | LIFE_TIME_VALUE_MOBILE_CONVERSION |
ACCOUNT | ✔* | ||||||
FUNDING_INSTRUMENT | ✔* | ✔ | |||||
CAMPAIGN | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ |
LINE_ITEM | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ |
PROMOTED_TWEET | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ |
MEDIA_CREATIVE | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ |
ORGANIC_TWEET | ✔ | ✔ |
ENGAGEMENT 지표 그룹의 일부 지표는 account 및 funding instrument 수준에서는 사용할 수 없습니다. 자세한 내용은 ENGAGEMENT 섹션을 참고하세요.
메트릭 그룹별 제공 메트릭
ENGAGEMENT
| Metric | Description | Segmentation Available | Data Type | Available for Account / Funding Instrument |
engagements | 총 참여 횟수 | ✔ | 정수 배열 | ✔ |
impressions | 총 노출 수 | ✔ | 정수 배열 | ✔ |
retweets | 총 리트윗 수 | ✔ | 정수 배열 | ✔ |
replies | 총 답글 수 | ✔ | 정수 배열 | ✔ |
likes | 총 좋아요 수 | ✔ | 정수 배열 | ✔ |
follows | 총 팔로우 수 | ✔ | 정수 배열 | ✔ |
card_engagements | 총 카드 참여 수 | ✔ | 정수 배열 | |
clicks | 즐겨찾기 및 기타 참여를 포함한 총 클릭 수 | ✔ | 정수 배열 | |
app_clicks | App 설치 또는 실행 시도 횟수 | ✔ | 정수 배열 | |
| url_clicks | 프로모션 내 링크 또는 Website Card에 대한 총 클릭 수(획득 트래픽 포함) | ✔ | 정수 배열 | |
qualified_impressions | 총 유효 노출 수 | ✔ | 정수 배열 | |
carousel_swipes | Carousel 이미지 또는 동영상에 대한 총 스와이프 수 | ✔ | 정수 배열 |
BILLING
| Metric | 설명 | 세분화 가능 여부 | Data Type |
billed_engagements | 청구된 참여의 총 수 | ✔ | 정수 배열 |
billed_charge_local_micro | 마이크로 단위의 총 지출 금액 | ✔ | 정수 배열 |
VIDEO
VIDEO 메트릭 그룹 내의 video_total_views 메트릭은 MRC 표준에 따라, 최소 2초 동안 화면의 50% 이상에 노출된 조회수를 집계합니다.
기존 비디오 조회 정의인 “최소 3초 동안 100% 화면 노출”은 VIDEO 메트릭 그룹의 새로운 video_3s100pct_views 메트릭으로 계속 제공됩니다. 기존 조회 정의를 기준으로 입찰 및 과금하려면 새로 제공되는 VIEW_3S_100PCT bid_unit을 사용하십시오.
| Metric | Description | Segmentation Available | Data Type |
video_total_views | 비디오 조회수 합계 | ✔ | int 배열 |
video_views_25 | 비디오의 최소 25%가 재생된 조회수 합계 | ✔ | int 배열 |
video_views_50 | 비디오의 최소 50%가 재생된 조회수 합계 | ✔ | int 배열 |
video_views_75 | 비디오의 최소 75%가 재생된 조회수 합계 | ✔ | int 배열 |
video_views_100 | 비디오 전체가 재생된 조회수 합계 | ✔ | int 배열 |
video_cta_clicks | 콜투액션에 대한 클릭 수 합계 | ✔ | int 배열 |
video_content_starts | 비디오 재생 시작 횟수 합계 | ✔ | int 배열 |
video_3s100pct_views | 100% 화면 노출 상태에서 최소 3초 이상 재생된 조회수 합계 (레거시 video_total_views) | ✔ | int 배열 |
video_6s_views | 비디오의 최소 6초가 재생된 조회수 합계 | ✔ | int 배열 |
video_15s_views | 비디오의 최소 15초 또는 전체 재생 시간의 95%가 재생된 조회수 합계 | ✔ | int 배열 |
MEDIA
| 지표 | 설명 | 세분화 가능 여부 | 데이터 유형 |
media_views | 동영상, Vine, GIF, 이미지 전반에 걸친 미디어 조회 수 합계(자동 재생 및 클릭 포함). | ✔ | 정수 배열 |
media_engagements | 동영상, Vine, GIF, 이미지 전반에 걸친 미디어 클릭 수 합계. | ✔ | 정수 배열 |
WEB_CONVERSION
| Metric | Description | Segmentation Available | Data Type |
conversion_purchases | PURCHASE type의 전환 수 및 해당 매출액과 주문 수량 | PLATFORMS만 해당 | JSON object |
conversion_sign_ups | SIGN_UP type의 전환 수 및 해당 매출액과 주문 수량 | PLATFORMS만 해당 | JSON object |
conversion_site_visits | SITE_VISIT type의 전환 수 및 해당 매출액과 주문 수량 | PLATFORMS만 해당 | JSON object |
conversion_downloads | DOWNLOAD type의 전환 수 및 해당 매출액과 주문 수량 | PLATFORMS만 해당 | JSON object |
conversion_custom | CUSTOM type의 전환 수 및 해당 매출액과 주문 수량 | PLATFORMS만 해당 | JSON object |
MOBILE_CONVERSION
| 지표 | 설명 | 세분화 가능 여부 | 데이터 유형 |
mobile_conversion_spent_credits | SPENT_CREDIT type 모바일 전환을 post_view, post_engagement, assisted, order_quantity, sale_amount별로 세분화한 값 | ✔ | JSON 객체 |
mobile_conversion_installs | INSTALL type 모바일 전환을 post_view, post_engagement, assisted, order_quantity, sale_amount별로 세분화한 값 | ✔ | JSON 객체 |
mobile_conversion_content_views | CONTENT_VIEW type 모바일 전환을 post_view, post_engagement, assisted, order_quantity, sale_amount별로 세분화한 값 | ✔ | JSON 객체 |
mobile_conversion_add_to_wishlists | ADD_TO_WISHLIST type 모바일 전환을 post_view, post_engagement, assisted, order_quantity, sale_amount별로 세분화한 값 | ✔ | JSON 객체 |
mobile_conversion_checkouts_initiated | CHECKOUT_INITIATED type 모바일 전환을 post_view, post_engagement, assisted, order_quantity, sale_amount별로 세분화한 값 | ✔ | JSON 객체 |
mobile_conversion_reservations | RESERVATION type 모바일 전환을 post_view, post_engagement, assisted, order_quantity, sale_amount별로 세분화한 값 | ✔ | JSON 객체 |
mobile_conversion_tutorials_completed | TUTORIAL_COMPLETED type 모바일 전환을 post_view, post_engagement, assisted, order_quantity, sale_amount별로 세분화한 값 | ✔ | JSON 객체 |
mobile_conversion_achievements_unlocked | ACHIEVEMENT_UNLOCKED type 모바일 전환을 post_view, post_engagement, assisted, order_quantity, sale_amount별로 세분화한 값 | ✔ | JSON 객체 |
mobile_conversion_searches | 모바일 전환 중 type이 SEARCH인 항목을 post_view, post_engagement, assisted, order_quantity, sale_amount별로 세분화한 값 | ✔ | JSON 객체 |
mobile_conversion_add_to_carts | 모바일 전환 중 type이 ADD_TO_CART인 항목을 post_view, post_engagement, assisted, order_quantity, sale_amount별로 세분화한 값 | ✔ | JSON 객체 |
mobile_conversion_payment_info_additions | 모바일 전환 중 type이 PAYMENT_INFO_ADDITION인 항목을 post_view, post_engagement, assisted, order_quantity, sale_amount별로 세분화한 값 | ✔ | JSON 객체 |
mobile_conversion_re_engages | 모바일 전환 중 type이 RE_ENGAGE인 항목을 post_view, post_engagement, assisted, order_quantity, sale_amount별로 세분화한 값 | ✔ | JSON 객체 |
mobile_conversion_shares | 모바일 전환 중 type이 SHARE인 항목을 post_view, post_engagement, assisted, order_quantity, sale_amount별로 세분화한 값 | ✔ | JSON 객체 |
mobile_conversion_rates | 모바일 전환 중 type이 RATE인 항목을 post_view, post_engagement, assisted, order_quantity, sale_amount별로 세분화한 값 | ✔ | JSON 객체 |
mobile_conversion_logins | 모바일 전환 중 type이 LOGIN인 항목을 post_view, post_engagement, assisted, order_quantity, sale_amount별로 세분화한 값 | ✔ | JSON 객체 |
mobile_conversion_updates | 모바일 전환 중 type이 UPDATE인 항목을 post_view, post_engagement, assisted, order_quantity, sale_amount별로 세분화한 값 | ✔ | JSON 객체 |
mobile_conversion_levels_achieved | 모바일 전환 중 type이 LEVEL_ACHIEVED인 항목을 post_view, post_engagement, assisted, order_quantity, sale_amount별로 세분화한 값 | ✔ | JSON 객체 |
mobile_conversion_invites | type가 INVITE인 모바일 전환을 post_view, post_engagement, assisted, order_quantity, sale_amount별로 구분한 값 | ✔ | JSON 객체 |
mobile_conversion_key_page_views | type가 KEY_PAGE_VIEW인 모바일 전환을 post_view 및 post_engagement별로 구분한 값 | ✔ | JSON 객체 |
| mobile_conversion_downloads | type가 DOWNLOAD인 모바일 전환을 post_view, post_engagement, assisted, order_quantity, sale_amount별로 구분한 값 | ✔ | JSON 객체 |
| mobile_conversion_purchases | type가 PURCHASE인 모바일 전환을 post_view, post_engagement, assisted, order_quantity, sale_amount별로 구분한 값 | ✔ | JSON 객체 |
| mobile_conversion_sign_ups | type가 SIGN_UP인 모바일 전환을 post_view, post_engagement, assisted, order_quantity, sale_amount별로 구분한 값 | ✔ | JSON 객체 |
| mobile_conversion_site_visits | type가 SITE_VISIT인 모바일 전환을 post_view, post_engagement, assisted, order_quantity, sale_amount별로 구분한 값 | ✔ | JSON 객체 |
LIFE_TIME_VALUE_MOBILE_CONVERSION
| Metric | Description | Segmentation Available | Data Type |
mobile_conversion_lifetime_value_purchases | PURCHASE type 모바일 전환의 세부 내역 | JSON object | |
mobile_conversion_lifetime_value_sign_ups | SIGN_UP type 모바일 전환의 세부 내역 | JSON object | |
mobile_conversion_lifetime_value_updates | UPDATE type 모바일 전환의 세부 내역 | JSON object | |
mobile_conversion_lifetime_value_tutorials_completed | TUTORIAL_COMPLETED type 모바일 전환의 세부 내역 | JSON object | |
mobile_conversion_lifetime_value_reservations | RESERVATION type 모바일 전환의 세부 내역 | JSON object | |
mobile_conversion_lifetime_value_add_to_carts | ADD_TO_CART type 모바일 전환의 세부 내역 | JSON object | |
mobile_conversion_lifetime_value_add_to_wishlists | ADD_TO_WISHLIST type 모바일 전환의 세부 내역 | JSON object | |
mobile_conversion_lifetime_value_checkouts_initiated | CHECKOUT_INITIATED type 모바일 전환의 세부 내역 | JSON object | |
mobile_conversion_lifetime_value_levels_achieved | LEVEL_ACHIEVED type 모바일 전환의 세부 내역 | JSON object | |
mobile_conversion_lifetime_value_achievements_unlocked | ACHIEVEMENT_UNLOCKED type 모바일 전환의 세부 내역 | JSON object | |
mobile_conversion_lifetime_value_shares | SHARE type 모바일 전환의 세부 내역 | JSON object | |
mobile_conversion_lifetime_value_invites | INVITE type 모바일 전환의 세부 내역 | JSON object | |
mobile_conversion_lifetime_value_payment_info_additions | PAYMENT_INFO_ADDITION type 모바일 전환의 세부 내역 | JSON object | |
mobile_conversion_lifetime_value_spent_credits | SPENT_CREDIT type 모바일 전환의 세부 내역 | JSON object | |
mobile_conversion_lifetime_value_rates | RATE type 모바일 전환의 세부 내역 | JSON object |
세분화
MEDIA_CREATIVE 또는 ORGANIC_TWEET 엔티티에는 지원되지 않습니다.
일부 세분화 type은 추가 파라미터를 함께 전달해야 합니다. 이에 대해서는 아래에서 설명합니다.
CITIES 또는 POSTAL_CODES 기준으로 세분화할 때, API는 타기팅된 위치만을 반환합니다. 지역(region) 및 대도시권(metro) 세분화는 타기팅된 위치와 타기팅되지 않은 위치를 모두 반환합니다.
| 세분화 type | country 파라미터 필요 | platform 파라미터 필요 |
AGE | ||
APP_STORE_CATEGORY | ||
AUDIENCES | ||
CITIES | ✔ | |
CONVERSATIONS | ||
CONVERSION_TAGS | ||
DEVICES | ✔ | |
EVENTS | ||
GENDER | ||
INTERESTS | ||
KEYWORDS | ||
LANGUAGES | ||
LOCATIONS | ||
METROS | ✔ | |
PLATFORMS | ||
PLATFORM_VERSIONS | ✔ | |
POSTAL_CODES | ✔ | |
REGIONS | ✔ | |
SLIDES | ||
SIMILAR_TO_FOLLOWERS_OF_USER | ||
TV_SHOWS |
파생 지표
metric은 Ads API analytics 엔드포인트에서 반환되는 지표입니다. {중괄호}로 둘러싸인 모든 이름은 해당 카테고리의 파생 지표를 나타냅니다.
참여(ENGAGEMENTS)
| 파생 지표 | 공개 지표 계산식 |
promoted_tweet_search_impressions + promoted_tweet_timeline_impressions + promoted_tweet_profile_impressions | |
billed_charge_local_micro / {Impressions} / 1000 | |
| {Total Engagements} | promoted_account_follows + promoted_tweet_search_engagements + promoted_tweet_timeline_engagements + promoted_tweet_profile_engagements or promoted_account_follows + promoted_tweet_search_clicks + promoted_tweet_search_replies + promoted_tweet_search_retweets + promoted_tweet_search_follows + promoted_tweet_timeline_clicks + promoted_tweet_timeline_replies + promoted_tweet_timeline_retweets + promoted_tweet_timeline_follows + promoted_tweet_profile_clicks + promoted_tweet_profile_replies + promoted_tweet_profile_retweets + promoted_tweet_profile_follows |
| {Engagement Rate} | {Total Engagements} / {Impressions} |
billed_charge_local_micro / {Total Engagements} | |
| {Media Views} | promoted_tweet_timeline_media_views + promoted_tweet_search_media_views + promoted_tweet_profile_media_views |
| {Media View Rate} | {Media Views} / {Impressions} |
WEBSITE_CLICKS
| 파생 지표 | 표시 지표 계산식 |
promoted_tweet_search_impressions + promoted_tweet_timeline_impressions + promoted_tweet_profile_impressions | |
billed_charge_local_micro / {Impressions} / 1000 | |
| {Link Clicks} | promoted_tweet_search_url_clicks + promoted_tweet_timeline_url_clicks + promoted_tweet_profile_url_clicks |
| {Click Rate} | {Link Clicks} / {Impressions} |
billed_charge_local_micro / {Link Clicks} | |
conversion_site_visits | |
| {Conversion Rate} | conversion_site_visits / {Impressions} |
billed_charge_local_micro / conversion_site_visits |
APP_INSTALLS 및 APP_ENGAGEMENTS
| 파생 지표 | 공개 지표 계산식 |
promoted_tweet_search_impressions + promoted_tweet_timeline_impressions | |
billed_charge_local_micro / {Impressions} / 1000 | |
| {App Clicks} | promoted_tweet_app_install_attempts + promoted_tweet_app_open_attempts + promoted_tweet_timeline_url_clicks + promoted_tweet_search_url_clicks |
| {App Click Rate} | {App Clicks} / {Impressions} |
billed_charge_local_micro / {App Clicks} | |
billed_charge_local_micro / mobile_conversion_installs |
팔로워
| 파생 지표 | 표시 지표 계산식 |
promoted_account_impressions | |
billed_charge_local_micro / {Impressions} / 1000 | |
promoted_account_follows | |
| {팔로우율} | promoted_account_follow_rate |
billed_charge_local_micro / promoted_account_follows | |
| {미디어 조회수} | promoted_tweet_timeline_media_views + promoted_tweet_search_media_views + promoted_tweet_profile_media_views |
| {미디어 조회율} | {Media Views} / {Impressions} |
LEAD_GENERATION
| 파생 지표 | 노출 지표 산식 |
promoted_tweet_search_impressions + promoted_tweet_timeline_impressions + promoted_tweet_profile_impressions | |
billed_charge_local_micro / {Impressions} / 1000 | |
promoted_tweet_search_card_engagements + promoted_tweet_timeline_card_engagements + promoted_tweet_profile_card_engagements | |
| {리드율} | {Leads} / {Impressions} |
| {리드당 비용} | billed_charge_local_micro / {Leads} |
VIDEO_VIEWS
| 파생 지표 | 노출 지표 기반 계산식 |
promoted_tweet_search_impressions + promoted_tweet_timeline_impressions + promoted_tweet_profile_impressions | |
billed_charge_local_micro / {Impressions} / 1000 | |
| {Video Views} | promoted_video_total_views |
| {Video Rate} | promoted_video_total_views / {Impressions} |
| {Cost Per View} | billed_charge_local_micro / promoted_video_total_views |
QUALIFIED_IMPRESSIONS
| 파생 지표 | 노출 지표 계산 |
promoted_tweet_search_impressions + promoted_tweet_timeline_impressions + promoted_tweet_profile_impressions | |
billed_charge_local_micro / {Impressions} / 1000 | |
| {Qualified Impressions} | promoted_tweet_timeline_qualified_impressions + promoted_tweet_search_qualified_impressions + promoted_tweet_profile_qualified_impressions |
| {Qualified Impression Rate} | {Qualified Impressions} / {Impressions} |
| {Cost Per 1000 Qualified Impressions } | billed_charge_local_micro / {Qualified Impressions} / 1000 |
커스텀
placement_type가 PROMOTED_ACCOUNT인 경우 위의 FOLLOWERS 목표를 참조하세요. 이 목표를 사용하는 그 외 모든 게재 위치의 경우, 해당 파생 지표에 대해서는 ENGAGEMENTS를 참조하세요.
가이드
활동 중인 엔티티
소개
데이터
엔드포인트
Request
entity, start_time, end_time이 필요합니다.
twurl -H ads-api.x.com "/11/stats/accounts/18ce54d4x5t/active_entities?entity=PROMOTED_TWEET&start_time=2019-03-05T00:00:00Z&end_time=2019-03-06T00:00:00Z"
지원되는 entity 값은 다음과 같습니다: CAMPAIGN, FUNDING_INSTRUMENT, LINE_ITEM, MEDIA_CREATIVE, PROMOTED_ACCOUNT, PROMOTED_TWEET. 이는 당사 분석 엔드포인트가 지원하는 엔티티 type을 반영한 것입니다.
start_time과 end_time 값은 ISO 8601 형식으로 지정해야 하며, 조회할 시간 단위 구간(hourly buckets)을 지정합니다. 이 값들은 반드시 정시 단위로만 지정해야 합니다.
이 엔드포인트는 결과를 필터링하는 데 사용할 수 있는 세 가지 선택적 매개변수도 지원합니다: funding_instrument_ids, campaign_ids, line_item_ids. 이 매개변수들은 광고 계층 구조의 모든 레벨에서, 그리고 지정한 어떤 entity type과도 함께 사용할 수 있습니다.
응답
data 배열에는 이후 분석 요청에 포함되어야 하는 각 엔티티마다 하나의 객체가 포함됩니다. 이 집합에 포함되지 않은 ID에 대해서는 분석을 요청해서는 안 됩니다.
각 객체에는 네 개의 필드가 있습니다: entity_id, activity_start_time, activity_end_time, placements. activity 시작 및 종료 시각은 연관된 엔티티의 변경 이벤트가 적용되는 기간을 나타내며, 따라서 이후 분석 요청에서 지정해야 하는 날짜 범위를 결정합니다. placements 배열에는 ALL_ON_TWITTER, PUBLISHER_NETWORK, SPOTLIGHT, TREND 값을 포함할 수 있습니다. 이 값들은 해당 엔티티 ID에 대해 어떤 placement를 요청해야 하는지를 나타냅니다.
사용 방법
- 활성 엔티티 정보를 얼마나 자주 요청할지, 그리고 그에 따라 애널리틱스를 얼마나 자주 가져올지.
- 활동 시작 및 종료 시간을 어떻게 사용하여 애널리틱스 요청의
start_time및end_time값을 결정할지.
요약
- Active Entities 요청을 보냅니다.
- 응답을 placement 기준으로 분리합니다.
ALL_ON_TWITTER,PUBLISHER_NETWORK,SPOTLIGHT,TREND각각에 대해 하나의 그룹을 만듭니다. - 각 placement 그룹에 대해 다음을 수행합니다.
- 엔티티 id를 추출합니다.
- 애널리틱스
start_time및end_time값을 결정합니다.- 최소
activity_start_time을 찾습니다. 이 값을 내림 처리합니다. - 최대
activity_end_time을 찾습니다. 이 값을 올림 처리합니다.
- 최소
- 애널리틱스 요청을 보냅니다.
- 엔티티 id를 20개씩 배치로 그룹화합니다.
- #3b에서 정의한
start_time및end_time값을 사용합니다. - 적절한
placement값을 지정합니다.
- 데이터 저장소에 기록합니다.
빈도
start_time이 이전 요청의 end_time과 같도록 시간 범위를 선택해야 합니다.
Note: 하나의 시간 구간(time window)은 한 번만 요청해야 합니다. 동일한 시간 구간을 두 번 이상 요청하면 불필요한 애널리틱스 요청이 발생합니다. (아래 예외 참고.)
start_time 및 end_time 타임스탬프를 보여줍니다.
| 요청 시각 | start_time 타임스탬프 | end_time 타임스탬프 |
| 00:15:00 | 00:00:00 | 00:15:00 |
| 00:30:00 | 00:15:00 | 00:30:00 |
| 00:45:00 | 00:30:00 | 00:45:00 |
| 01:00:00 | 00:45:00 | 01:00:00 |
활동 시간
activity_start_time과 최대 activity_end_time을 찾습니다. 그런 다음 최소 활동 시작 시간은 내림하고, 최대 활동 종료 시간은 올림합니다. 구체적으로 두 시각 모두 시, 분, 초를 0으로 설정하고 종료 시간에는 하루를 더합니다. 아래 표와 같습니다. 이렇게 도출된 값이 이후 분석 요청에서 지정해야 할 시작 및 종료 시간입니다.
| 최소/최대 활동 시간 | 도출된 시간 |
| 2019-03-04T20:55:20Z 2019-03-05T14:40:59Z | 2019-03-04T00:00:00Z 2019-03-06T00:00:00Z |
DAY 단위를 지정한 경우에는 허용되지 않는다는 점에 유의하세요.)
예제
start_time 및 end_time 값은 각각 2019-02-11T00:00:00Z와 2019-02-12T00:00:00Z로 설정됩니다. 아래의 각 metrics 배열에서 세 번째 요소가 활성 엔티티 정보를 바탕으로 예상했던 대로 0이 아닌 값임을 확인할 수 있습니다.
비동기 처리 가이드
API 참조 문서
비동기 분석
소개
사용 방법
- POST stats/jobs/accounts/:account_id 엔드포인트를 사용해 작업을 생성합니다.
- 작업 처리가 완료되었는지 확인하기 위해, 일정한 간격으로 GET stats/jobs/accounts/:account_id 엔드포인트에 요청을 보냅니다.
- 작업 처리가 완료되면 데이터 파일을 다운로드합니다.
- 데이터 파일의 압축을 해제합니다.
segmentation_type 요청 파라미터를 사용하세요.
예시
이 섹션에서는 비동기 분석 엔드포인트를 사용하는 방법을 보여줍니다. 먼저 POST stats/jobs/accounts/:account_id 엔드포인트를 사용해 작업을 생성합니다. 아래 예시는 특정 라인 아이템에 대해 일주일 동안의 노출 수, 좋아요, 클릭 수 등과 같은 참여 지표를 요청합니다. (요청한 시간 범위의 타임스탬프가 자정으로 설정되어 있기 때문에, 3월 20일은 포함되지 않고 그 직전 시점까지만 포함된다는 점에 유의하세요.)id 및 id_str 속성 모두에 표시됩니다.
다음으로, 이전 응답에서 받은 id_str를 사용해 생성한 작업이 응답에서 "status": "SUCCESS"로 표시된 것처럼 처리가 완료되었는지 확인해야 합니다. 이는 데이터를 다운로드할 준비가 되었다는 의미입니다. url 필드에는 다운로드 링크가 포함되어 있습니다.
job_ids 파라미터를 사용해 최대 200개의 작업 ID를 지정하여 여러 작업의 상태를 한 번에 확인하는 것이 좋습니다.
다음으로, 나열된 url 값을 사용해 데이터 파일을 다운로드합니다.
도달률 및 평균 노출 빈도
https://ads-api.x.com/stats/accounts/:account_id/reach/campaigns
파라미터
| Name | Description |
|---|---|
| account_id required | 레버리지드 계정(leveraged account)의 식별자입니다. 리소스의 경로(path)에 포함되며, GET accounts를 제외한 모든 Advertiser API 요청에서 일반적으로 필수 파라미터입니다. 지정된 계정은 인증된 사용자와 연관(associated)되어 있어야 합니다. Type: string Example: 18ce54d4x5t |
| campaign_ids required | 쉼표로 구분된 식별자 리스트를 지정하여, 응답 범위를 원하는 캠페인으로만 한정합니다. 최대 20개의 ID를 제공할 수 있습니다. Note: 최대 20개의 campaign ID를 제공할 수 있습니다. Type: string Example: 8fgzf |
| end_time required | 조회되는 데이터를 지정된 종료 시각까지의 범위로 한정하며, ISO 8601 형식으로 표현합니다. Note: 반드시 정시(0분 0초) 단위로 표현해야 합니다. Type: string Example: 2017-05-26T07:00:00Z |
| start_time required | 조회되는 데이터를 지정된 시작 시각부터의 범위로 한정하며, ISO 8601 형식으로 표현합니다. Note: 반드시 정시(0분 0초) 단위로 표현해야 합니다. Type: string Example: 2017-05-19T07:00:00Z |
GET https://ads-api.x.com/12/stats/accounts/18ce54d4x5t/reach/campaigns?campaign_ids=8fgzf&start_time=2017-05-19&end_time=2017-05-26
응답 예시
리소스 URL
https://ads-api.x.com/stats/accounts/:account_id/reach/funding_instruments
| Name | Description |
|---|---|
| account_id required | 레버리지 계정의 식별자입니다. 리소스의 경로에 포함되며, GET accounts를 제외한 모든 Advertiser API 요청에서 일반적으로 필수 매개변수입니다. 지정된 계정은 인증된 사용자와 연계되어 있어야 합니다. Type: string Example: 18ce54d4x5t |
| funding_instrument_ids required | 쉼표로 구분된 식별자 목록을 지정하여, 응답을 원하는 펀딩 인스트루먼트로만 제한합니다. 최대 20개의 ID를 제공할 수 있습니다. Note: 최대 20개의 펀딩 인스트루먼트 ID를 제공할 수 있습니다. Type: string Example: lygyi |
| end_time required | ISO 8601 형식으로 표현된 지정된 종료 시각까지로, 조회되는 데이터를 제한합니다. Note: 반드시 정시(0분 0초) 단위로 표현해야 합니다. Type: string Example: 2017-05-26T07:00:00Z |
| start_time required | ISO 8601 형식으로 표현된 지정된 시작 시각부터로, 조회되는 데이터를 제한합니다. Note: 반드시 정시(0분 0초) 단위로 표현해야 합니다. Type: string Example: 2017-05-19T07:00:00Z |
요청 예시
응답 예시
동기식 분석
end_time - start_time)은 7일입니다.
리소스 URL
https://ads-api.x.com/12/stats/accounts/:account_id
매개변수
| Name | Description |
|---|---|
| account_id required | 레버리지 계정의 식별자입니다. 리소스 경로에 포함되며, GET accounts를 제외한 모든 Advertiser API 요청에서 일반적으로 필수 매개변수입니다. 지정된 계정은 인증된 사용자와 연결되어 있어야 합니다. Type: string Example: 18ce54d4x5t |
| end_time required | ISO 8601 형식으로 표현된 지정 종료 시각까지로 조회된 데이터의 범위를 제한합니다. Note: 분과 초가 0인 정시 단위로만 표현해야 합니다. Type: string Example: 2017-05-26T07:00:00Z |
| entity required | 데이터를 조회할 엔티티 유형입니다. Type: enum Possible values: ACCOUNT, CAMPAIGN, FUNDING_INSTRUMENT, LINE_ITEM, ORGANIC_TWEET, PROMOTED_ACCOUNT, PROMOTED_TWEET, MEDIA_CREATIVE |
| entity_ids required | 데이터를 조회할 개별 엔티티입니다. 쉼표로 구분한 엔티티 ID 목록을 지정합니다. Note: 최대 20개의 엔티티 ID를 제공할 수 있습니다. Type: string Example: 8u94t |
| granularity required | 조회된 데이터의 세분화 수준을 지정합니다. Type: enum Possible values: DAY, HOUR, TOTAL |
| metric_groups required | 반환할 메트릭을 지정합니다. 쉼표로 구분한 메트릭 그룹 목록을 지정하세요. 자세한 내용은 Metrics and Segmentation을 참조하세요. Note: MOBILE_CONVERSION 데이터는 별도로 요청해야 합니다.Type: enum Possible values: BILLING, ENGAGEMENT, LIFE_TIME_VALUE_MOBILE_CONVERSION, MEDIA, MOBILE_CONVERSION, VIDEO, WEB_CONVERSION |
| placement required | 조회된 데이터를 특정 placement로 제한합니다. Note: 요청당 하나의 값만 허용됩니다. X와 X Audience Platform 둘 다에 placement가 있는 엔티티의 경우, 각 placement 값마다 별도의 요청이 필요합니다. Type: enum Possible values: ALL_ON_TWITTER, PUBLISHER_NETWORK, SPOTLIGHT, TREND |
| start_time required | ISO 8601 형식으로 표현된 지정 시작 시각부터로 조회된 데이터의 범위를 제한합니다. Note: 분과 초가 0인 정시 단위로만 표현해야 합니다. Type: string Example: 2017-05-19T07:00:00Z |
요청 예시
활성 엔티티
지정된 기간 동안 어떤 엔티티의 분석 지표가 변경되었는지에 대한 세부 정보를 조회합니다. 이 엔드포인트는 애널리틱스 엔드포인트와 함께 사용해야 합니다. 이 엔드포인트의 결과는 어떤 광고 엔티티에 대해 애널리틱스를 요청해야 하는지를 나타냅니다. 사용 방법에 대해서는 Active Entities Guide를 참조하세요. 변경 이벤트는 1시간 단위의 버킷으로 제공됩니다.start_time및end_time값은 조회할 시간별 버킷을 지정합니다.- 반환되는
data배열에는 이후 애널리틱스 요청에 포함해야 하는 각 엔티티에 대한 객체가 포함됩니다. - 중요: 이후 애널리틱스 요청에서 지정해야 하는 날짜는
activity_start_time및activity_end_time값을 기준으로 결정해야 합니다.- 이 값들은 저장된 변경 이벤트가 적용되는 시간 범위를 나타냅니다. 이는 엔티티별로 반환됩니다.
end_time - start_time)는 90일입니다.
https://ads-api.x.com/12/stats/accounts/:account_id/active_entities
매개변수
| 이름 | 설명 |
|---|---|
| account_id 필수 | 레버리지 계정의 식별자입니다. 리소스 경로에 포함되며, GET accounts를 제외한 모든 Advertiser API 요청에 일반적으로 필요한 매개변수입니다. 지정한 계정은 인증된 사용자와 연관되어 있어야 합니다. Type: string Example: 18ce54d4x5t |
| end_time 필수 | 가져오는 데이터를 지정한 종료 시각으로 범위 제한합니다. ISO 8601 형식으로 표현됩니다. 참고: 반드시 정시(0분 0초)로 표현해야 합니다. Type: string Example: 2017-05-26T07:00:00Z |
| entity 필수 | 데이터를 조회할 엔터티 유형입니다. Type: enum 가능한 값: CAMPAIGN, FUNDING_INSTRUMENT, LINE_ITEM, MEDIA_CREATIVE, PROMOTED_ACCOUNT, PROMOTED_TWEET |
| start_time 필수 | 가져오는 데이터를 지정한 시작 시각으로 범위 제한합니다. ISO 8601 형식으로 표현됩니다. 참고: 반드시 정시(0분 0초)로 표현해야 합니다. Type: string Example: 2017-05-19T07:00:00Z |
| campaign_ids 선택 | 쉼표로 구분된 식별자 목록을 지정하여, 원하는 캠페인과 연관된 엔터티만 응답에 포함되도록 범위를 제한합니다. 최대 200개의 ID를 제공할 수 있습니다. 참고: funding_instrument_ids 및 line_item_ids와 상호 배타적입니다.Type: string Example: 8wku2 |
| funding_instrument_ids 선택 | 쉼표로 구분된 식별자 목록을 지정하여, 원하는 펀딩 인스트루먼트와 연관된 엔터티만 응답에 포함되도록 범위를 제한합니다. 최대 200개의 ID를 제공할 수 있습니다. 참고: campaign_ids 및 line_item_ids와 상호 배타적입니다.Type: string Example: lygyi |
| line_item_ids 선택 | 쉼표로 구분된 식별자 목록을 지정하여, 원하는 라인 아이템과 연관된 엔터티만 응답에 포함되도록 범위를 제한합니다. 최대 200개의 ID를 제공할 수 있습니다. 참고: campaign_ids 및 line_item_ids와 상호 배타적입니다.Type: string Example: 8v7jo |
예제 요청
GET https://ads-api.x.com/12/stats/accounts/18ce54d4x5t/active_entities?entity=PROMOTED_TWEET&start_time=2019-02-28&end_time=2019-03-01