매달 X Ads API에 변경 사항을 적용하고 여러 가지 신규 기능을 출시합니다. 이러한 변경 사항은 거의 항상 하위 호환성을 유지하지만, 매년 소수의 브레이킹 체인지가 발생하곤 합니다. Ads API에서 빠른 변경 주기가 새로운 기능 구현, 사용 중단 처리, 변경 사항 테스트와 같은 개발 주기에 미치는 영향에 대해 개발자들로부터 피드백을 받아왔습니다. 우리는 Ads 플랫폼을 사용하는 개발자들의 경험을 개선하고자 하며, 그 일환으로 엔드포인트에 버전 개념을 도입했습니다.
아래는 우리가 논의하는 몇 가지 개념에 대한 정의입니다.
버전(Version): 모든 Ads API 요청의 URL 경로에서 찾을 수 있는 버전 번호를 의미합니다. 예: GET //accounts. 이러한 방식의 버전 관리는 URI 버전 관리(URI versioning)라고 합니다.
기존 기능을 깨는 변경 사항(Breaking Changes): 기존 기능을 유지하기 위해 개발자 리소스가 필요한 모든 변경 사항을 의미합니다. 여기에는 어떤 변경을 해야 하는지 조사하는 데 사용되는 리소스, 사용 중단(deprecation)되는 기능/엔드포인트를 파악하는 작업, 그리고 이러한 모든 변경 사항을 최종적으로 구현하는 작업이 포함됩니다. 브레이킹 체인지의 예시는 다음과 같습니다.
- API 요청/응답에서 파라미터를 제거하는 것
- 파라미터나 엔드포인트의 이름을 변경하는 것
- 값 표현 방식 변경 (preview_url → card_uri)
- 엔드포인트 동작 방식 변경 (예: 비동기(async) vs 동기(sync) 통계)
- 선택적 또는 필수 파라미터를 추가/변경하는 것 (예: 요청에서 name을 필수 필드로 만드는 경우)
- 모든 하위 호환성을 깨는 변경 사항은 새 버전에 묶어서 제공됩니다.
- 새 버전이 발표될 때 기존 버전에 대한 사용 중단(deprecation) 유예 기간은 6개월입니다.
- 언제든지 API는 두 개의 버전에서 오는 요청을 동시에 허용하지만, 이 둘 중 오래된 버전은 지원되지 않습니다.
- 새로운 제품을 더 빠르게 도입할 수 있도록, 이러한 제품은 버전 관리 주기와는 별도로 지속적으로 출시됩니다.
-
모든 API 응답에는
x-current-api-version이 포함되며, 이 값은 현재 API 버전으로 설정됩니다. 또한 사용 중단된(deprecated) API endpoint를 호출하는 경우x-api-warn헤더가 추가로 포함됩니다.
Note: 이번 릴리스 시점부터 Ads API 버전 7(v7)은 지원이 종료되어 더 이상 사용할 수 없습니다.
accounts/:account_id/account_media endpoint는 사용 중단(deprecated)되었습니다.
이전 버전과 마찬가지로, v5로 마이그레이션하기 위한 6개월 전환 기간이 제공됩니다. 2019-08-28 이후로는 Ads API 버전 4를 더 이상 사용할 수 없습니다. 모든 파트너가 서비스 중단을 방지하기 위해 가능한 한 빨리 최신 버전의 API로 마이그레이션할 것을 권장합니다. Ads API 버전 3은 수명이 종료(end of life)되어 더 이상 제공되지 않습니다.
어떤 엔티티가 활성 상태였는지 판별하기
Active Entities 엔드포인트는 광고 엔티티에 대한 애널리틱스 메트릭이 변경되었는지를 나타냅니다. 애널리틱스 엔드포인트와 함께 사용하도록 설계되었으며, Active Entities는 엔티티 type과 최대 90일의 날짜 범위를 지정하면, 귀하의 플랫폼이 애널리틱스를 요청해야 하는 엔티티 ID 배열을 반환합니다. 반환된 ID 이외의 값은 이후 애널리틱스 요청에서 조회하지 않아야 합니다.
이 엔드포인트는 다음과 같은 엔티티 type을 지원합니다: CAMPAIGN, FUNDING_INSTRUMENT, LINE_ITEM, MEDIA_CREATIVE, PROMOTED_TWEET.
MEDIA_CREATIVE 통계
Ads API의 애널리틱스 엔드포인트는 이제 Media Creative 엔티티에 대한 메트릭을 제공합니다. Media Creative는 X Audience Platform에서 인스트림 광고 또는 이미지를 프로모션하는 방식입니다. X Ads UI에서는 “In-stream videos” 및 “Display creatives” 탭에서 Media Creative 메트릭을 표시합니다. 동기식과 비동기식 애널리틱스 엔드포인트 모두 이제 MEDIA_CREATIVE 엔티티 enum을 지원합니다.
여러 카드 가져오기
카드 URI 값으로 단일 카드를 조회하도록 설계된 엔드포인트의 v3 릴리스를 개선하여, 이제 GET accounts/:account_id/cards/all 엔드포인트를 사용해 여러 카드를 가져올 수 있습니다. 이제 각 카드마다 요청을 보내는 대신, 한 번의 요청으로 최대 200개의 카드를 조회할 수 있습니다.
다음 두 가지를 유의하십시오.
- URL 경로는 이제
accounts/:account_id/cards/all입니다. (이전 경로는 더 이상 사용할 수 없습니다.) 이는 ID로 카드를 조회하도록 설계된 엔드포인트와의 일관성을 유지하기 위함입니다. - 필수 요청 파라미터 이름은 이제 card_uris(복수형)입니다.
- GET accounts/:account_id/line_item_apps
- GET accounts/:account_id/media_creatives
- GET accounts/:account_id/promoted_accounts
- GET accounts/:account_id/preroll_call_to_actions
draft_only | with_draft | |
Network Activation Duration 타게팅
Ads API에서는 Network Activation Duration 타게팅을 추가한 이후, 응답의 타게팅 type에 _IN_SEC 접미사가 포함되던 표시 문제를 해결했습니다. Network Activation Duration은 항상 개월 단위로 표현되므로, 초(second)에 대한 참조는 혼란을 줄 수 있었습니다. 이번 수정으로 표현 방식이 일관되게 되어 혼동이 줄어듭니다.
| v4 | v5 |
| :--- | :--- | :--- |
| NETWORK_ACTIVATION_DURATION_IN_SEC | NETWORK_ACTIVATION_DURATION | |
전체 개수 및 커서
v5에서는 with_total_count와 cursor가 상호 배타적입니다. 요청에 둘 다 지정하면 EXCLUSIVE_PARAMETERS 오류 코드를 반환합니다. v5 이전에는 cursor가 지정된 경우 with_total_count는 무시되었습니다. 이번 변경으로 둘 사이의 관계가 명시적으로 정의됩니다.
preview_url, account_id, parent_ids 등 세 가지 필드가 Ads API 응답에서 제거됩니다. 이 세 항목에 대한 엔지니어링 작업량은 최소 수준입니다.
- v4에서 카드에 대한 preview_url 응답 매개변수가 항상 null이라고 이미 공지되었습니다. 이 마이그레이션의 마지막 단계는 모든 카드 응답에서 preview_url을 제거하는 것입니다.
- 다음 리소스의 경우 ads 계정 ID가 이미 URL 및 request.params에 포함되어 있으므로 account_id 응답 속성이 제거됩니다. (펀딩 인스트루먼트는 의도적으로 이 목록에서 제외됩니다. 가능한 경우 parent ID는 응답 객체에 포함되어야 하며, account ID는 펀딩 인스트루먼트의 상위 엔티티이기 때문입니다.)
- 계정 미디어
- App 이벤트 공급자
- App 이벤트 태그
- 캠페인
- 카드
- 라인 아이템
- 프로모션 대상 사용자
- 타기팅 기준
- GET accounts/:account_id/targeting_criteria 요청의 경우, parent_ids 필드는 항상 빈 배열이었기 때문에 더 이상 반환되지 않습니다.
- 참고: 이는 이미지 및 동영상 app 다운로드 카드에는 영향을 미치지 않습니다.
- Media Library에 추가된
AMPLIFY_VIDEO애셋은PREROLL크리에이티브 타입으로 자동으로 Account Media 애셋으로 추가됩니다. - 특정 규격의 이미지를 Media Library에 추가하면 자동으로 Account Media 애셋으로 추가됩니다. 크리에이티브 타입(예:
INTERSTITIAL)은 이미지 규격에 따라 달라집니다. (규격에 대한 자세한 내용은 Enumerations 페이지를 참조하세요.)
- TON 업로드:
- GET accounts/:account_id/tailored_audience_changes
- GET accounts/:account_id/tailored_audience_changes/:tailored_audience_change_id
- POST accounts/:account_id/tailored_audience_changes
- PUT accounts/:accounti_d/tailored_audiences/global_opt_out
- 실시간 오디언스:
- POST tailored_audience_memberships
list_type 파라미터가 제거됩니다.
Settings 엔드포인트
이제 계정 관리자가 사용자, 계정, 세금 설정을 설정하고 업데이트할 수 있습니다. User settings는 특정 광고 계정에 대한 사용자별 연락 설정 선호도를 의미합니다. PUT accounts/:account_id 엔드포인트를 사용하여 광고주는 이제 계정 이름과 산업 유형을 업데이트할 수 있습니다. 마지막으로, tax settings 엔드포인트를 통해 부가가치세(VAT)가 부과되는 국가의 광고주는 회사명, 주소, VAT ID, 계정이 광고주가 직접 소유한 것인지 또는 대행사가 광고주를 대신해 계정을 소유하는지와 같은 정보를 업데이트할 수 있습니다.
Universal Lookalike 이름 변경
POST accounts/:account_id/line_items 및 PUT accounts/:accountit/line_items/:line_item_id 엔드포인트에서 lookalike_expansion 매개변수의 enum 값을 변경했습니다.
모든 곳에서
country_code 사용
Ads API 전반의 일관성을 높이기 위한 작업의 일환으로, 다음 엔드포인트들의 매개변수 이름을 app_country_code에서 country_code로 변경했습니다.
- POST accounts/:account_id/cards/image_app_download
- PUT accounts/:account_id/cards/image_app_download/:card_id
- POST accounts/:account_id/cards/video_app_download
- PUT accounts/:account_id/cards/video_app_download/:card_id
preview_url은 항상 null
v3 공지에서 약속한 대로, 이제 모든 기존 카드에는 card_uri가 있습니다. 그 결과 preview_url 값은 항상 null입니다.
참고로, card_uri 값을 사용해 카드를 Tweet에 연결할 수 있습니다. 다음 예시 요청을 참고하세요.
$ twurl -X POST -H ads-api.x.com “/4/accounts/18ce54d4x5t/tweet?text=Version 4&card_uri=card://958225772740714496”
Video 엔드포인트
accounts/:account_id/videos 엔드포인트는 v4에서는 더 이상 사용할 수 없습니다. 이 엔드포인트는 Media Library 엔드포인트의 도입으로 사용 중단되었습니다. 아래의 사용 예 비교를 참고하세요.
-
v3 videos 엔드포인트:
twurl -H ads-api.x.com "/3/accounts/18ce54d4x5t/videos" -
v4 동영상용 Media Library 엔드포인트:
twurl -H ads-api.x.com "/4/accounts/18ce54d4x5t/media_library?media_type=VIDEO"
as_user_id
GET accounts/:account_id/tweet/preview/:tweet_id 엔드포인트에서 사용 가능하던 as_user_id 파라미터는 더 이상 허용되지 않습니다. 미리보기는 항상 Tweet 작성자 기준으로 렌더링됩니다.
Ads API 버전 3는 2018년 2월 1일에 출시되었습니다. Ads API 버전 2는 2018년 8월 1일에 지원이 종료(EOL)됩니다.
이번 릴리스에는 새로운 Audience Intelligence 제품, Media Library에 대한 액세스, 그리고 개선된 카드 워크플로우가 포함됩니다. 또한 PUT accounts/:account_id/targeting_criteria 엔드포인트 사용 중단도 함께 공지합니다. 마지막으로, 버전 3에는 일부 매개변수 및 응답의 소규모 변경 사항과 더 낮은 배치 크기 한도가 포함됩니다.
버전 2와 마찬가지로, 파트너에게 전환을 위한 6개월을 제공합니다. 2018-08-01에 Ads API v2는 완전히 중단됩니다. 모든 파트너 및 개발자에게 가능한 한 빨리 v3로 마이그레이션할 것을 권장합니다.
Audience Intelligence
Audience Intelligence는 특정 X 오디언스와 가장 관련성이 높은 상위 해시태그, @핸들, 이벤트에 대한 실시간 인사이트를 제공합니다. 예를 들어, 미국의 남성 18–34를 입력하면, 이 오디언스에서 트렌드 중인 #nintendoswitch, #cardinal, @ricegum 등을 확인할 수 있습니다.
Audience Intelligence 엔드포인트는 다음 기능을 제공합니다.
- 입력 오디언스를 기준으로 상위 관련 해시태그, @핸들, 이벤트를 조회합니다.
- 입력 오디언스를 기준으로 핵심 인구통계 정보(예: 나이, 성별, 가구 소득)를 조회합니다.
- 키워드를 기준으로 Tweet 볼륨 시계열 데이터를 조회합니다.
- 이제 GET insights/keywords/search 엔드포인트의 응답에 입력 키워드와 관련된 30개의 용어를 포함하는
related_keywords속성이 추가되었습니다.
- 타기팅 기준 배치의 최대 크기가 이제 500으로 증가했습니다.
card_uri와preview_url응답 속성은 이제 상호 배타적입니다. 카드에card_uri가 있는 경우preview_url은null이 됩니다. 카드에card_uri가 없는 경우에는preview_url만 반환됩니다.- 2018-01-29 이후에 생성된 모든 카드는
card_uri를 갖습니다. - 버전 4까지는 기존의 모든 카드가
card_uri를 갖게 됩니다.
- 2018-01-29 이후에 생성된 모든 카드는
- 5:2 이미지가 있는 카드를 새로 생성하는 것은 더 이상 불가능합니다. 기존의 5:2 이미지 기반 카드는 계속 동작하지만, 파트너 여러분께는 (지원되는 경우) 성과가 더 좋은 1.91:1 또는 1:1 종횡비로 전환하실 것을 권장합니다.
- PUT accounts/:account_id/targeting_criteria 엔드포인트는 더 이상 사용할 수 없습니다. 이 엔드포인트의 replace 동작이 광고주에게 혼란을 주었고, 한 번에 하나의 리소스만 업데이트하는 다른 PUT 엔드포인트와 일관되지 않았기 때문에 이 변경을 적용하기로 결정했습니다. 대신 파트너 여러분은 POST batch/accounts/:account_id/targeting_criteria 엔드포인트를 사용해야 하며, 이 엔드포인트는 하나의 요청에서 타기팅을 추가 및 제거를 모두 할 수 있는 등 더 큰 유연성을 제공합니다.
paused응답 속성은 더 이상 자금 수단(funding instruments)에 대해 반환되지 않습니다. 대신 자금 수단이 일시 중지되었는지 여부를 확인하려면entity_status응답 속성을 참조하십시오. 또한paused와cancelled가 동일한 값을 가리키므로,cancelled역시 응답에서 더 이상 반환되지 않습니다.- GET accounts/:account_id/tweet/preview 엔드포인트에서
card_id파라미터를 제거했습니다. - 삭제된 예약 Tweet은 조회할 수 없기 때문에
with_deleted파라미터는 더 이상 지원되지 않습니다. - 다음 엔드포인트에서
draft_only파라미터가 제거되었습니다. 이 엔티티는 초안 상태가 될 수 없기 때문입니다.
-
total_count는 이제 선택적 응답 속성입니다.with_total_count가true로 설정된 경우에만 제공됩니다. -
line_items및campaigns요청 및 응답 객체의paused및draft_only필드는 단일entity_status파라미터로 대체되었습니다. -
POST accounts/:account_id/tweet 및 GET accounts/:account_id/tweet/preview 엔드포인트에서
status파라미터 이름이text로 변경되었습니다. -
GET targeting_criteria/locations 엔드포인트의
location_typeenum 값이 복수형으로 변경되었습니다.COUNTRY는 이제COUNTRIES,REGION은 이제REGIONS이며, 기타 값도 동일한 규칙이 적용됩니다. 단, v2에서는CITY가METROS로 변경되어, 위치 타입이 Designated Marker Areas(DMA) 또는 “metros”를 가리킨다는 점을 정확히 반영합니다. -
PUT accounts/:account_id/promoted_tweets 엔드포인트에서
display_properties속성이 제거되었습니다. 이 값은 응답의 일부로도 더 이상 반환되지 않습니다. - 위 변경으로 인해, 더 이상 promoted_tweets 엔티티를 업데이트(PUT)할 수 없습니다.
-
GET accounts/:account_id/promoted_tweets 엔드포인트의
line_item_id파라미터가 제거되었습니다. - v2 엔드포인트에서는 더 이상 5:2 Website Card를 생성할 수 없습니다.
-
data_type응답 속성은 더 이상 반환되지 않습니다.
- Cards v2
- 초안 캠페인/라인 아이템 생성 및 활성화
- 예약 Tweet
- 비동기 작업 요약
- Tweet과 카드를 연결할 때 Tweet 텍스트에
preview_url을 추가하는 방식 대신card_uri요청 파라미터를 사용해야 합니다. - (카드 생성 단계에서) 응답에
card_uri파라미터가 반환되지 않는 경우preview_url을 사용하십시오. - 모든 신규 카드 포맷은
card_uri파라미터를 활용하는 네이티브 형식으로 API에서 제공됩니다.
- Video Website Cards:
- POST accounts/:account_id/line_items 및 POST accounts/:account_id/campaigns 엔드포인트의
entity_status파라미터 값을DRAFT로 설정하면 새로운 초안 캠페인이나 라인 아이템을 생성할 수 있습니다. - 새로 생성하는 초안에 필요한 필수 파라미터:
Notes¶
- 초안 라인 아이템 또는 캠페인은
entity_status가DRAFT인 상태에서만PAUSED또는ACTIVE로 전환할 수 있습니다. - 여러 라인 아이템이 있는 전체 캠페인을 활성화하려면, 캠페인에 속한 각 라인 아이템과 캠페인 자체 모두의
entity_status를ACTIVE로 설정해야 합니다. - 캠페인 또는 라인 아이템의
entity_status를 변경하려면, 해당하는 PUT 엔드포인트를 사용하십시오.
- Scheduled Tweets는 다음과 같은 새로운 엔드포인트로 구성됩니다.
- Scheduled Tweets:
- Campaign Management:
- 새로 예약된 Tweets는 미래의 임의의 날짜로 예약할 수 있습니다.
- 현재로서는 예약된 Tweet을 미리 볼 수 있는 기능이 없습니다.
-
SCHEDULED상태의 Scheduled Tweets만 편집/삭제할 수 있습니다. -
Scheduled Tweets는
scheduled_at날짜/시간까지 엔터프라이즈 Firehose 또는 다른 어떤 데이터 API로도 전파되지 않습니다.
- 버전 관리 지원
CUSTOM목표는 더 이상 지원되지 않습니다- 배치 엔드포인트는 이제 정식 출시되었습니다
- 도달수 추정치 변경 사항:
- 더 정확한 도달 범위 추정을 위해 이 엔드포인트는 이제 예산을 고려합니다. 이제 다음 매개변수가 필수입니다:
- [신규]
campaign_daily_budget_amount_local_micro currencybidobjective
- [신규]
- 응답 객체의 구조가 변경되어 이제 응답 값에 대한 범위를 반환합니다.
infinite_count는 역할에 대한 혼동을 피하기 위해infinite_bid_count로 이름이 변경되었습니다.count및infinite_bid_count외에 이제 다음과 같은 새로운 데이터 포인트가 반환됩니다:impressionsengagementsestimated_daily_spend_local_micro
- Tailored Audiences 데이터 type 변경
- 모든 응답에서 Tailored Audiences의
data_type값이tailored_audiences에서tailored_audience로 변경되었습니다. - Shared Tailored Audiences 기능이 이제 API 전용 베타로 제공됩니다. Shared Tailored Audiences를 사용하면 하나의 오디언스를 여러 광고 계정에서 함께 사용할 수 있습니다. 여러 광고 계정에서 공유하려는 맞춤형 오디언스의 권한을 관리하려면 POST accounts/:account_id/tailored_audiences/:tailored_audience_id/permissions 및 관련 엔드포인트를 사용하세요.
- 광고주 계정의 성과 analytics를 수집하는 방식이 크게 개선되었습니다:
- 모범 사례에 맞추기 위해, 이제 동기식 통계 엔드포인트에 대해서는 최대 7일분의 데이터만 조회할 수 있습니다.
- 메트릭 조회를 간소화하기 위해
metrics파라미터를 새로운metric_groups파라미터로 대체했습니다. 이제 개발자는 특정 요청에 대해 어떤 메트릭 그룹을 반환받을지 반드시 명시해서 요청해야 합니다.- 특정 엔티티에 적합하지 않은 메트릭을 요청하면, 해당 메트릭은 응답에서 제외되고
null값으로 표시됩니다. 이러한 메트릭은 분석 비용 한도에 산정되지 않습니다.
- 특정 엔티티에 적합하지 않은 메트릭을 요청하면, 해당 메트릭은 응답에서 제외되고
- 응답이 대폭 단순화되어 이제 UI에서 메트릭이 노출되는 방식과 보다 가깝게 일치합니다.
- 이전에는 각 게재 위치(검색에서의 Promoted Tweets, 타임라인에서의 Promoted Tweets, 프로필 및 Tweet 상세에서의 Promoted Tweets, X Audience Platform)에 대해 별도의 지표를 제공했습니다. 이제는 각 위치에 대해 표준화된 지표 세트를 반환합니다. 즉, 더 이상
promoted_tweet_timeline_impressions,promoted_tweet_search_impressions,promoted_tweets_profile_impressions,promoted_tweets_tpn_impressions를 사용하지 않고, 다음 카테고리 중 하나로 요청할 때 단일 지표인impressions로 제공되며, 이는 모든 지표에 적용됩니다: ALL_ON_TWITTERPUBLISHER_NETWORK- 요청을 보내면 UI의 값과 일치시키기 쉽도록 단일
impressions지표만 받게 됩니다. ALL_ON_TWITTER와PUBLISHER_NETWORK데이터를 모두 얻으려면, 이 둘은 결합할 수 없으므로 두 개의 쿼리를 수행해야 합니다.
- 이전에는 각 게재 위치(검색에서의 Promoted Tweets, 타임라인에서의 Promoted Tweets, 프로필 및 Tweet 상세에서의 Promoted Tweets, X Audience Platform)에 대해 별도의 지표를 제공했습니다. 이제는 각 위치에 대해 표준화된 지표 세트를 반환합니다. 즉, 더 이상
- 비동기 통계 엔드포인트를 이제 개발자 여러분의 피드백을 반영해 사용할 수 있습니다!
- 통계를 비동기적으로 요청할 수 있는 새 엔드포인트 세트로, 즉시 필요하지 않은 데이터나 과거 데이터 조회에 사용할 수 있습니다.
- 새로운 단일 엔드포인트를 통해 통계 job을 큐에 등록합니다. 사용 가능한 리소스 범위 내에서 요청하신 데이터를 수집합니다.
- 데이터 사용 가능 여부를 확인하기 위해 job status 엔드포인트를 조회할 수 있습니다.
- 데이터가 준비되면, 동기식 엔드포인트의 응답을 그대로 반영한 JSON 응답을 다운로드할 수 있도록 pick-up ID를 제공합니다.
- 하나의 job에서 최대 90일치 데이터와 최대 20개 엔티티에 대한 데이터를 조회할 수 있습니다.
- v0 지표를 v1 지표에 매핑한 내용을 포함한 analytics v1 마이그레이션 가이드를 확인하세요
- Sandbox 개선 사항 * 이제 Sandbox 환경에서 여러 개의 테스트용 광고 계정을 생성할 수 있습니다. * 이제 Sandbox 환경에서 테스트용 광고 계정에 대해 여러 개의 결제 수단을 생성할 수 있습니다. 이를 통해 모든 결제 수단 type을 테스트할 수 있습니다. 이전에는 테스트에 사용할 수 있는 결제 수단이
CREDIT_CARD하나뿐이었습니다. * 베타 기능을 테스트해 보고 싶으신가요? 이제 Sandbox 환경에서 계정별로 기능을 켜거나 끌 수 있으므로, 테스트 요구 사항에 맞게 설정할 수 있습니다.