잠재고객 - X

맞춤 잠재고객

Overview

파트너가 Custom Audiences를 생성하는 방법은 여러 가지가 있습니다.

Audience API (CRM)
Web
Mobile
Flexible

룩얼라이크 Custom Audience는 타기팅에서 제외할 수 없습니다. 또한 동일한 광고 라인 아이템(광고 그룹)에서 하나의 custom audience와 그 custom audience의 룩얼라이크를 동시에 타기팅할 수 없습니다. Audience management 잠재고객은 audience 파트너 및 Ads API 파트너를 통해 관리할 수 있습니다. API에서는 custom audiences에 액세스하고 이를 유지 관리하기 위한 여러 엔드포인트를 제공합니다. custom audience 정보에 대해서는 다음 2개의 엔드포인트를 제공합니다.

잠재고객 업로드 및 관리 방법에 대한 자세한 내용은 Audience API guide를 참조하세요. Processing Times 일반적으로 잠재고객 변경 사항은 6~8시간마다 실행되는 배치로 처리됩니다. 잠재고객 변경 사항이 처리되는 동안 업데이트 대상이 되는 기존 잠재고객에는 영향을 주지 않습니다. 이 기간 내에 잠재고객별로 추가는 한 번, 제거는 한 번만 업데이트할 것을 권장합니다. Targeting 잠재고객은 X가 소유 및 운영하는 클라이언트에서 지난 90일 동안 활성 상태였던 사용자 최소 100명과 일치하는 경우에만 타기팅할 수 있습니다. GET accounts/:account_id/custom_audiences/:custom_audience_id는 잠재고객이 일치하는 사용자가 너무 적어 타기팅할 수 없는 경우 이를 표시합니다. Audience API (CRM)

Audience 또는 API 파트너가 해시된 식별자 목록을 제공하면, X가 이를 매칭하여 X에서 미디어 구매에 사용할 수 있는 세그먼트를 생성합니다. 파트너는 Audience API를 사용해 이러한 잠재고객을 생성할 수 있습니다. How it works?

Web X에서의 미디어 구매를 위해 타기팅할 세그먼트를 식별하기 위해 MPP audience 파트너와 협력할 때 표준 쿠키 매칭 프로세스를 제공합니다. 추가로, 광고주는 웹사이트 사용자 데이터를 수집하고 해당 Custom Audience를 생성하기 위해 X Web Event Tag를 설정할 수 있습니다. Setup Steps

How it works?

Mobile 자세한 내용은 the Custom Audiences from Mobile Apps blog post를 참조하세요. Flexible Flexible audiences는 기존 custom audiences 또는 기존 custom audiences의 하위 집합을 기반으로 잠재고객 조합을 생성하고 저장할 수 있는 기능을 광고주에게 제공합니다. custom audience 구성원의 하위 집합은 상호작용의 최신성(recency)과 빈도(frequency)에 따라 타기팅할 수 있습니다. Restricted Use Cases for Custome Audiences 제한 사항에 대해 자세히 알아보기

Audiences FAQ

Q: 많은 양의 데이터를 전송했는데, 왜 audience 크기가 TOO_SMALL로 표시되나요? A: 현재 데이터는 실시간으로 audience에 추가되고 있지만, audience 크기를 계산하는 작업은 일정 시간이 지난 후에만 실행됩니다. 몇 시간 후 UI에 올바른 audience 크기가 표시되어야 합니다. Q: audience 데이터를 모두 전송하고 24시간 이상 기다렸는데도 여전히 해당 audience를 타겟팅할 수 없습니다. 다음 단계로 무엇을 해야 하나요? A: 다음 사항을 확인해 주세요.

전달되는 user ID가 올바르며 형식 오류가 없는지 확인합니다.
전달되는 audience 이름이 올바르며, 이전 membership 업데이트와 일치하는지 확인합니다.
POST 명령에 대한 response를 확인합니다.
ID Sync 픽셀이 올바르게 구현되었는지, 그리고 ID Sync 프로세스에서 설명한 대로 충분한 수의 사용자가 해당 사이트를 방문하여 사용자를 매핑할 수 있었는지 확인합니다. membership 업데이트에 포함된 매핑되지 않은 사용자는 타겟팅 사용자로 전환되지 않습니다.

위의 모든 사항이 올바르게 동작하는 것이 확인되면, 가능한 한 자세한 정보와 함께 X 제품 담당자에게 문의해 주세요(선호하는 정보 예시는 Guide to Partner Inbounds를 참고하세요). Q: 이 endpoint는 얼마나 자주 호출할 수 있고, 어떤 알고리즘을 사용해야 하나요? A: 전체 audience membership을 다시 보내지 말고, 증분(delta) 데이터만 시스템으로 전송할 것을 강력히 권장합니다. 이 시스템은 전 세계에서 가장 큰 웹사이트 중 일부의 증분 데이터 업데이트를 처리할 수 있을 정도의 처리량으로 테스트되어 있습니다. 초기 audience 업로드는 신중하게 속도를 조절해야 하며, 첫 업로드는 완료까지 상당한 시간이 걸릴 것으로 예상됩니다. Q: 타겟팅에 사용할 수 있는 audience의 최소 크기는 얼마인가요?

audience의 최소 크기는 100명의 사용자(매칭 후 기준)입니다. 500명 미만의 사용자가 매칭된 audience는 X Ads UI에서 타겟팅에 사용할 수 없습니다.

Q: audience 파일을 처리하는 데 얼마나 시간이 걸리나요? 그리고 audience 파일이 X User Interface에서 사용 가능해지기까지는 얼마나 걸리나요?

일반적으로 audience 파일을 처리하는 데 4~6시간이 소요되지만, 파일 크기에 따라 달라질 수 있습니다. 파일이 처리되면 해당 audiences는 X Ads UI에서 사용할 수 있게 됩니다.

Q: 매치율(match rate)은 어떻게 계산되나요?

Match Rate = 최근 90일 이내 활성 X 사용자 수 / 제공된 사용자 수

Q: audience 파일이 제대로 동작하는지 어떻게 테스트하나요?

테스트용 audience 파일을 제공하고, 광고주 handle로 “keltonlynn”을 사용할 수 있습니다. 그러면 해당 파일이 X UI에 정상적으로 수집되고 로드되는지 우리가 검증할 수 있습니다.

Q: partner user identifier (p_user_id)란 무엇인가요?

귀사가 각 고객을 고유하게 식별하기 위해 사용하는 식별자입니다.

Q: standard ID란 무엇인가요?

이는 이메일 주소, device ID, X @handle 또는 ID가 될 수 있습니다.

Q: HMAC Key는 어떻게 받을 수 있나요?

암호화된 이메일로 제공됩니다. mpp-inquiry@x.com 주소로 귀하의 공개 PGP 키를 보내주시면, 모든 것이 정상적으로 작동하는지 확인하기 위한 테스트 이메일을 보내 드립니다. 검증이 완료되면, HMAC Key를 발송해 드립니다.

Q: 제공된 HMAC Key를 사용해 해싱 프로세스가 제대로 작동했는지 어떻게 검증하나요?

X가 테스트 파일(샘플 이메일 주소, device ID 등 포함)과 그에 대한 결과 해시 파일을 제공하며, 이를 사용해 귀하의 결과를 대조하여 검증할 수 있습니다.

Q: full data match 파일에 대한 파일 크기 제한이 있나요?

아닙니다. full data match 파일에는 크기 제한이 없습니다.

Q: full data match 파일을 처리하는 데 얼마나 걸리나요?

파일을 X가 수신한 후, 파일을 처리하는 데 대략 1일 정도 소요됩니다.

CRM

이 문서는 파일 형식 및 데이터 교환 프로세스를 포함하여 Custom Audiences CRM 파트너를 위한 통합 세부 사항을 설명합니다. 요약 Company는 고객을 대신하여 공통 사용자 식별자(예: 이메일 주소) 또는 파트너 사용자 ID를 해시한 목록을 X에 제공하여 블라인드 매칭을 수행하고, 타기팅을 위한 X 사용자 ID 목록을 생성합니다. 타기팅용 세그먼트는 ads.x.com 캠페인 설정 시 파일 이름으로 지정된 광고주의 특정 @handle에서 사용할 수 있게 됩니다. Company에서 보내는 모든 파일은 X가 Company에 부여한 특정 계정을 통해 IronBox(www.golockbox.com)의 보안 패키지(secure package)를 사용하여 X에 제공됩니다. X는 IronBox에 대한 접근 권한을 제공합니다. IronBox API에 대한 문서는 https://secure.goironcloud.com/Docs/Help/에서 확인할 수 있습니다.

파트너 ID 매칭 요구 사항

회사가 자체 표준 ID 시스템을 사용해 사용자를 추적하는 경우(예: 이메일 주소, device ids, X user ID 등의 일반적인 사용자 식별자를 사용하지 않는 경우) 아래 프로세스를 따르는 것을 권장합니다. 1. 전체 데이터 매치 먼저 회사는 X와의 공통 사용자 식별자(고유한 common user identifier)를 포함한 모든 사용자 레코드의 전체 리스트를 단일 파일로 제공하여, 전체 데이터 매치를 수행하고 파트너 ID(p_user_id)를 X ID(tw_id)에 매핑한 결과를 X가 보관할 수 있도록 합니다. 이 작업은 적절한 최신 상태 유지를 위해 정기적으로, 2~3개월 간격으로 수행됩니다. 매치가 완료되면 X는 이 파일을 기반으로 한 기준 매치율을 이메일을 통해 회사에 공유합니다. 이 파일의 형식은 다음과 같아야 합니다. Name Convention: FullDataMatch.[CompanyName].txt Hashing Algorithm: HMAC_SHA-256 Format: Column 1: 공통 사용자 식별자의 HMAC 해시 값 Column 2: 파트너 사용자 ID(사용자당 고유, 파일 내에서는 중복 가능) Column Delimiter (CSV): 해시된 공통 사용자 식별자와 파트너 ID를 구분하기 위해 쉼표 사용 줄바꿈으로 구분된 값(Line separated values)

예: 사용자 레코드 A에 파트너 사용자 ID 1과 공통 사용자 식별자 1, 2, 3이 있는 경우:


common user identifier 1	p_user_1
common user identifier 2	p_user_1
common user identifier 3	p_user_1

*아래의 Hashing Directions 섹션에서 공통 사용자 식별자에 대한 설명을 확인하십시오. 2. 커스텀 세그먼트 리스트 회사는 p_user_id 형태의 사용자 리스트를 제공하여, 고객을 위한 커스텀 오디언스를 생성하고 이를 X에서 타기팅에 사용할 수 있도록 합니다.

줄바꿈으로 구분된 값(Line separated values)
p_user_id
- (위의 1. 전체 데이터 매치 섹션에서 제공한 값과 동일합니다. 전체 데이터 매치에서 제공된 값이 해시된 값이면, 회사는 오디언스 파일에도 동일한 해시 값을 제공합니다. 제공된 값이 해시되지 않은 값이면, 회사는 해시되지 않은 값을 제공합니다.)

표준 매칭 요구 사항

회사가 모든 고객 사용자 식별자를 매핑하는 데 표준 ID를 사용하지 않는 경우, 다음 프로세스를 권장합니다. 맞춤 세그먼트 리스트 회사는 고객을 대신해 해시된 공통 사용자 식별자 리스트를 X에 직접 제공하여 커스텀 오디언스를 생성합니다. 이 파일의 형식은 다음과 같아야 합니다.

줄바꿈으로 구분된 값
해시된 공통 사용자 식별자(예: 이메일 주소)
아래에 설명된 파일 명명 규칙을 따를 것
아래의 이메일 주소 해싱 지침(Hashing Directions)을 따를 것

커스텀 세그먼트 리스트 파일 이름 지정 및 작업

파일의 작업 유형은 파일 이름에 의해 결정되며, 사용 가능한 작업과 일반적인 파일 이름 규칙은 다음과 같습니다: audiencename_partnername.handle.operation.filetype

audiencename: 커스텀 오디언스의 이름입니다. 이 필드는 ads.x.com 캠페인 설정 UI에서 오디언스를 선택할 때 표시되는 이름입니다. 예: brand_loyalty_card_holders.
partnername: 광고주를 대신하여 데이터를 제공하는 회사의 이름입니다. 예: company_name.
handle: 커스텀 오디언스에 액세스할 수 있는 X 계정(@handle)입니다. 예: @pepsi, @dietpepsi
operation: new, add, remove, removeall, replace (자세한 내용은 아래 참조)
: 각 업로드된 오디언스 파일이 고유하도록 하기 위해 사용되는, 초 단위의 표준 Unix epoch 시간
filetype: 파일은 *.txt 형식이어야 합니다.

오디언스 생성 및 업데이트

단일 파일로 새 오디언스를 생성합니다. 예: loyalty_card_holders_partnername.pepsi.new.txt Add - 목록의 매칭된 사용자를 기존 오디언스에 추가합니다. 예: loyalty_card_holders_partnername.pepsi.add..txt Remove - 목록의 매칭된 사용자를 기존 오디언스에서 제거합니다. 예: loyalty_card_holders_partnername.pepsi.remove..txt Remove All - 정기적으로 업데이트되는 누적 목록에서 생성된 매칭된 사용자를 해당 Client의 모든 오디언스에서 제거합니다(예: Client의 옵트아웃 목록). 예: partnername.pepsi.removeall.txt

광고주로부터 옵트아웃한 사용자의 포괄적인 목록에 사용할 수 있습니다.
X는 이 파일에 제공된 최신 목록만을 사용하며, 제공 및 처리 시점에 매칭된 모든 기존 및 향후 오디언스에 이를 적용합니다.

이 파일이 제공되고 처리된 시점의 X 사용자 기준입니다. Replace - 기존 오디언스를 제거하고 새로운 오디언스 목록으로 교체합니다. 예: loyalty_card_holders_partnername.pepsi.replace..txt 회사 전체 옵트아웃 - 회사는 회사의 옵트아웃 정책에 따라 옵트아웃한 사용자를 제거하기 위한 누적 옵트아웃 파일을 제공합니다. X는 이 회사 옵트아웃 파일에 제공된 최신 목록만을 사용하며, 이 파일이 제공되고 처리된 시점에 매칭된 X 사용자에 대해 모든 기존 및 향후 오디언스에 이를 적용합니다. 회사 옵트아웃 파일의 형식은 다음과 같습니다. 예: partnername.removeall.txt Delete - 기존 오디언스를 현재 오디언스 목록에서 제거합니다. 예: loyalty_card_holders_partnername.pepsi.delete.txt

해싱 방법

X는 일반 사용자 식별자(예: 이메일 주소)를 해싱하기 위한 Base64 인코딩된 프로덕션 키를 PGP를 통해 안전하게 공유합니다. 회사는 키를 Base64 디코딩하여 해싱에 사용할 32바이트 키를 생성합니다. 예시 Base64 인코딩된 키: BrQvOg+dACBUmKjRiNxZgJLh6zydjS0ZOv80FelTNzM= 예시 Base64 디코딩된 키: /:� TшY 정규화: 회사는 해싱 전에 일반 사용자 식별자에 대해 기본적인 정규화를 수행합니다(단, Device ID는 예외이며 Device ID 정규화 섹션을 참조하십시오).

E-mail 정규화

즉, 앞뒤 공백을 제거하고 이메일 주소를 모두 소문자로 변환합니다. 예: 원본 e-mail 주소: testemail_Organisational_baseball+884@It92I6Ev2B.Com 정규화 후: testemail_organisational_baseball+884@it92i6ev2b.com 해시 값: 74d9584eded0ad1e5572a1c1849f3716751d371d6117a6155dad5363f4b4fbec 참고: 인코딩된 HMAC 값과 키의 길이는 입력값과 인코딩 방식에 따라 달라질 수 있으므로, 길이가 고정되어 있지는 않습니다.

Device ID 정규화

데이터 파트너에게 제공하는 공통 salt와 SHA-256 해시 알고리즘을 사용해 device ID를 해싱하는 데 동일한 요구 사항이 적용됩니다. 이메일 주소와 마찬가지로 공백은 제거하지만, IDFA/Android ID에 대해서는 소문자 정규화를 수행하지 않으며, IDFA/Android ID의 정확한 형식을 그대로 사용해야 합니다. 다음은 해싱 이전 iOS 및 Android용 Device ID의 원본 형식 예시입니다. iOS IDFA: DD99CFF7-6186-4602-9DF2-ED3FD0B2D431 Android ID: b5bf2122961b3595 해싱된 iOS IDFA: 134fb8cd95c7fd42e2793f469a447198ca5f990968db2dbadad70e723ed9750b 해싱된 Android ID: 130dddff1939f229476f50bc8adab8fcb7e3525b0e9604fe8effc15e68cee4a4

X 사용자 ID 정규화

X ID는 데이터의 그룹화(예: @handle로 구성된 고객 리스트)가 개인 식별 정보(PII)는 아니더라도 광고주에게 비공개이기 때문에 계속 해시된 상태로 유지됩니다. X ID를 해시할 때는 SHA-256 해싱 알고리즘과 우리가 데이터 파트너에게 제공하는 공통 salt를 사용하는 동일한 요구사항이 적용됩니다. X ID와 @username 모두에 대해 공백은 제거해야 하지만, User ID는 정규화가 필요하지 않습니다. 정규화를 위해 @username은 소문자로 변환해야 합니다. 또한 @ 기호는 username의 일부로 포함되면 안 됩니다. 원본 ID 형식은 다음과 같습니다:

User ID: 27674040
@username: testusername

해시된 User ID: bf6b57d4e861e83bea8bbed2b800b251a64c95468ee6e8cb07c3368c9ed45e85 해시된 @username: 12201ae78ad1afa907c7112d17f498154ffb0bf9ea523f5390e072a06d7d9812

ID Sync Integration

p_id로 데이터를 전송하는 파트너는 광고주 또는 파트너의 사용자 id를 X 사용자 id에 매핑하기 위한 ID Sync 프로세스를 반드시 거쳐야 합니다. 이를 통해 광고주는 X에서 자체 사용자 세그먼트를 직접 타게팅할 수 있습니다. 또한 파트너는 멤버십 업데이트를 전송할 때 user_identifier_type 파라미터 값을 TALIST_PARTNER_USER_ID 또는 TAWEB_PARTNER_USER_ID로 설정해야 합니다.

웹 전용: 아래에 설명된 대로 광고주의 사이트에 픽셀을 설치하여 설정할 수 있습니다.
리스트: CRM 페이지에 설명된 방법 중 하나를 사용하여 진행할 수 있습니다.

픽셀 URL


기본 URL
https://analytics.x.com/i/adsct

픽셀 매개변수


매개변수	설명
`p_id`	X에서 부여한 파트너 id
`p_user_id`	파트너 시스템에서의 사용자 id

ID 동기화 픽셀:

예시 파트너 id 값이 111이고, 예시 p_user_id 값이 abc인 경우, 구성되는 픽셀은 다음과 같습니다:

    <pre class="brush: xml">
    <img height="1" width="1" src="https://analytics.x.com/i/adsct?p_id=111&p_user_id=abc" style="display:none" />
    </pre>

옵트아웃 파일 구성 및 옵트아웃 파일 전송 파트너는 타기팅 광고 제공을 받지 않도록 옵트아웃을 선택한 사용자에 대해, 파트너가 파악하고 있는 한도 내에서의 사용자 목록을 X에 제공해야 합니다. 전송되는 파일의 형식은 다음과 같습니다.


Column Number	Column Name	Column Type	Description
1	Partner ID	string	“partner id”는 각 파트너를 고유하게 식별하기 위해 X가 파트너에게 제공하는 ID입니다.
2	The user’s id in the partner system	string	`p_user_id`는 파트너가 사용자를 식별하기 위해 사용하는 고유 ID입니다. 이 옵트아웃 사용자를 포함하는 파일은 TON upload 엔드포인트를 사용해 업로드해야 하며, 업로드된 데이터의 경로는 여기의 Global Opt Out 엔드포인트로 전송해야 합니다: PUT accounts/:account_id/custom_audiences/global_opt_out.

멤버십 업데이트 전송 엔드포인트 문서에 명시된 대로, POST custom_audience_memberships 엔드포인트를 통해 사용자를 전달할 때는 쿠키 기반 매칭을 활성화하기 위해 customer ID를 전달해야 합니다. p_id로 데이터를 전송하는 파트너는 반드시 user_identifier_type을 TALIST_PARTNER_USER_ID 또는 TAWEB_PARTNER_USER_ID로 설정해야 합니다. 그 외 모든 단계는 Real-Time Audience API Integration Guide에 나열된 내용과 동일하게 유지됩니다.

맞춤 잠재고객 사용자 데이터

이 문서는 [Custom Audience]/x-ads-api/audiences 사용자 데이터 형식을 설명합니다. 데이터 정규화 디바이스 ID:

IDFA - 소문자로, 대시는 포함; 예: 4b61639e-47cc-4056-a16a-c8217e029462
AdID - 기기에서의 원래 형식이 필요하며, 대문자로 변환하지 않고 대시를 포함해야 함; 예: 2f5f5391-3e45-4d02-b645-4575a08f86e
Android id - 기기에서의 원래 형식이 필요하며, 대문자로 변환하지 않고 대시나 공백 없이 사용; 예: af3802a465767e36

이메일 주소:

모두 소문자로 변환하고, 앞뒤 공백 제거; 예: support@x.com

X 사용자 이름:

@ 기호 없이, 소문자로 변환하고 앞뒤 공백 제거; 예: jack

X 사용자 ID:

표준 정수; 예: 143567

데이터 해싱 각 행의 데이터는 SHA256을 사용하여 솔트 없이 해시해야 합니다. 또한 최종 출력 해시는 소문자여야 합니다. 예: 49e0be2aeccfb51a8dee4c945c8a70a9ac500cf6f5cb08112575f74db9b1470d 와 같아야 하며, 다음과 같이 쓰면 안 됩니다: 49E0BE2AECCFB51A8DEE4C945C8A70A9AC500CF6F5CB08112575F74DB9B1470D

# hasing user @AdsAPI using python
import hashlib
hashlib.sha256("adsapi".encode()).hexdigest()

#output
49e0be2aeccfb51a8dee4c945c8a70a9ac500cf6f5cb08112575f74db9b1470d

해싱용 추가 코드 예제는 github.com/xdevplatform/ads-platform-tools에서 확인할 수 있습니다.

커스텀 오디언스: 웹

정보 파트너는 광고주를 대신해 타게팅할 ID(p_user_ids) 리스트를 전송합니다. 이는 p_user_ids와 X 사용자 ID 간의 매핑을 구축하는 ID 동기화(ID Sync) 프로세스를 통해 수행됩니다. 이 매핑은 타게팅에 사용할 수 있는 X 사용자 ID 리스트를 생성하는 데 사용됩니다. 이러한 커스텀 오디언스는 ads.x.com의 Custom Audiences Web 캠페인 설정에서, 라벨에 지정된 광고주의 특정 @handle에 사용할 수 있도록 제공됩니다. X는 파트너 태그 및 사이트에 삽입할 수 있는 보안 픽셀을 제공하여 ID(p_user_ids)를 X 사용자 ID와 매칭할 수 있도록 합니다. ID 동기화 프로세스가 완료되면 파트너가 타게팅 파일을 생성하고, HTTPS 엔드포인트를 통해 X가 사용할 수 있도록 제공합니다. 이 타게팅 파일은 X에서 정기적으로 가져와 처리하며, 이후 X UI에서 사용할 수 있게 됩니다. X 보안 픽셀 X 보안 픽셀은 다음과 같은 형태입니다: https://analytics.x.com/i/adsct?p_user_id=xyz&p_id=123 p_user_id - xyz는 파트너가 제공하는 파트너 사용자 ID를 의미합니다. p_id - 123은 파트너에 대한 고유 ID를 의미합니다(X에서 제공). 파트너 HTTPS 엔드포인트 & 타게팅 사용자 파일 파트너는 타게팅 파일을 정기적으로 가져오기 위해 사용할 수 있는 HTTPS 엔드포인트와 인증 정보(사용자 이름/비밀번호)를 X에 제공해야 합니다. 예시 HTTPS 엔드포인트는 다음과 같은 형태입니다:

https://<partnerdomain>/twitter/partner_targeting_%Y-%M-%D.tsv.gz

%Y - 연도 형식 코드 (YYYY) %M - 월 형식 코드 (MM) %D - 일 형식 코드 (DD) 전송되는 데이터는 다음 파일들로 구성됩니다.

Partner Targeting User File
Targeting Conversion File

모든 파일은 TSV 형식이며, 각 행의 개별 필드는 탭 문자로 구분됩니다. 각 필드 값 자체에는 탭 문자가 포함되지 않습니다. 허용되는 X IP 범위: Partner Endpoint에 대한 액세스를 허용할 수 있는 IP 범위는 다음과 같습니다.

199.16.156.0/22
199.59.148.0/22

Partner Targeting User File:

Column Number	Column Name	Column Type	Description
1	partner id	string	“partner id”는 각 파트너를 고유하게 식별할 수 있도록 X가 파트너에게 제공하는 ID입니다.
2	advertiser id	string	“advertiser id”는 광고주의 @handle입니다.
3	p_user_id	string	“p_user_id”는 파트너가 사용자를 식별하는 데 사용하는 고유 ID입니다.
3	confidence score	integer	“confidence score”는 선택 사항입니다. “confidence score”는 0~~100 범위를 사용할 것을 권장합니다. 리타게팅이 사용 사례인 경우, “confidence score”가 100인 사용자는 직접 리타게팅된 사용자입니다. 0~~99 점수는 유사 고객에 대한 신뢰도 수준을 나타냅니다.
4	segment label	string	“segment label”은 선택 사항입니다. 파트너는 예를 들어 상품 카테고리를 지정하기 위해 “segment label”을 사용할 수 있습니다. 이 “segment label”은 ads.x.com UI에서 Custom Audiences에 대한 사람이 읽을 수 있는 이름이므로, 이를 사용할 것을 권장합니다.

참고: 새 Partner Targeting File을 받을 때마다, 별도의 합의가 없는 한 이는 증분 데이터가 아니라 파트너가 타겟팅을 권장하는 사용자 전체 목록이라고 예상합니다. 이 Partner Targeting File의 전송 주기는 각 파트너와 사전에 합의합니다. 예상된 시점에 Partner Targeting File을 받지 못한 경우, 미리 정의된 만료 시간이 적용되는 이전 버전을 계속 사용합니다.

Audience API 연동

개요

Audience API는 Ads API의 v4 의 일부로 출시되었으며, 이를 통해 기존 Audiences 엔드포인트에 여러 가지 개선 사항을 제공합니다. 이 새로운 엔드포인트는 새로운 Audience 처리 백엔드에 의해 지원되며, 안정성, 견고성, 신뢰성 측면에서 여러 개선을 제공합니다. 이 가이드의 목적은 Audience API와 기존 Audience 업로드 및 관리 프로세스 간의 차이점을 설명하는 것입니다. 참고 문서는 Audience API 레퍼런스 문서 페이지에서 확인할 수 있습니다. Note: 업로드 전에 모든 Audience 사용자 데이터는 SHA-256으로 해시 처리되어야 합니다. 허용되는 사용자 식별자 type 및 데이터 정규화에 대한 자세한 내용은 user data 페이지에서 확인할 수 있습니다. Audience 기능 변경 사항 다음 Custom Audience 변경 사항은 v4부터 도입되었으며, 사용 중단(deprecated)된 엔드포인트는 Ads API v3의 지원이 종료(sunset)된 이후 더 이상 사용할 수 없습니다:

Deprecated TON 업로드:
- GET accounts/:account_id/custom_audience_changes
- GET accounts/:account_id/custom_audience_changes/:custom_audience_change_id
- POST accounts/:account_id/custom_audience_changes
- PUT accounts/:account_id/custom_audiences/global_opt_out
Deprecated Real Time Audiences:
- POST custom_audience_memberships
Custom Audience:
- 모든 Custom Audience 엔드포인트의 요청과 응답에서 list_type 파라미터가 제거됩니다. 이 파라미터는 이전에 Audience의 사용자 식별자 type(예: 이메일, X User ID 등)을 식별하는 데 사용되었지만, 이제는 동일한 Audience에 대해 여러 사용자 식별자를 수용할 수 있게 되었으므로 이 값은 더 이상 의미가 없습니다.
일반:
- Audience 조회 기간(lookback window)은 최근 30일에서 최근 90일 이내에 활성 상태였던 사용자와 매칭되도록 업데이트되었습니다.
- 타겟팅 가능한 Audience에 필요한 최소 매칭 사용자 수는 500명에서 100명으로 감소했습니다.

사전 준비 사항

Ads API 액세스
Audience 엔드포인트에 대한 액세스를 위해서는 allowlist(허용 목록)에 추가되어야 합니다. 2018-08-01 이전에 최초로 승인을 받은 경우, 이 양식을 작성하고 새로운 X Ads Products and Services Agreement를 수락해야 합니다.

Audience 업로드 프로세스 다음 표는 기존과 새로운 Audience 생성 흐름 간의 주요 차이점을 나열한 것이며, 보다 자세한 내용은 아래에서 확인할 수 있습니다:

프로세스 단계	Audience API	(Deprecated) TON 업로드
셸 Audience 생성	[POST custom_audience endpoint]/x-ads-api/audiences 를 통해 생성 가능	[POST custom_audience endpoint]/x-ads-api/audiences 를 통해 생성 가능
신규 사용자 추가	Audience endpoint에서 `operation_type` `Update` 사용	POST custom_audience_changes 엔드포인트에서 `operation` `ADD` 사용
사용자 제거	Audience endpoint에서 `operation_type` `Delete` 사용	POST custom_audience_changes 엔드포인트에서 `operation` `REMOVE` 사용
사용자 옵트아웃 처리	Audience endpoint에서 `operation_type` `Delete`와 사용자가 속해 있는 해당 `custom_audience_id` 사용	Global opt-out endpoint 사용

Note TON 업로드 경로를 통해 업데이트되거나 옵트아웃 처리되는 모든 Audience는 TON Upload 엔드포인트를 통해 업로드된 해당 리스트가 있어야 하며, custom_audience_changes 엔드포인트를 사용해 Audience와 연계되어야 합니다. Rate Limiting Audience API 엔드포인트의 rate limit은 계정당 1분에 1500회입니다. 단일 페이로드에 포함할 수 있는 사용자 수에는 제한이 없습니다. 페이로드에 대한 제약은 다음과 같습니다:

전체 작업 수: 최대 2,500개
최대 페이로드 크기: 5,000,000바이트

Audience 사용자 관리 새로운 Audience를 생성하려면 다음 단계가 필요합니다.

새로운 Custom Audience 생성

[POST custom_audience]/x-ads-api/audiences 엔드포인트를 사용해 새로운 Custom Audience “셸”을 생성하고 해당 Custom Audience의 id를 가져옵니다. 이 단계는 Audience를 처음부터 생성하는 경우 필수입니다. 기존 Audience를 업데이트하는 경우에는 다음 섹션으로 건너뛰세요.

오디언스에 사용자 추가

Custom Audience id와 아래와 같은 예시 페이로드를 사용해 POST accounts/:account_id/custom_audiences/:custom_audience_id/users 엔드포인트를 호출합니다. POST https://ads-api.x.com/11/accounts/18ce54d4x5t/custom_audiences/1nmth/users

    # 모든 값은 해시 처리되어야 하며, 이 예제에서는 설명 목적으로 해시되지 않은 값을 사용합니다
    [
      {
        "operation_type": "Update",
        "params": {
          "effective_at": "2018-05-15T00:00:00Z",
          "expires_at": "2019-01-01T07:00:00Z",
          "users": [
            {
              "email": [
                "abc@x.com"
              ],
              "handle": [
                "x",
                "adsapi"
              ]
            },
            {
              "email": [
                "edf@x.com"
              ],
              "twitter_id": [
                "121291606",
                "17874544"
              ]
            }
          ]
        }
      }
    ]

사용자를 Audience에 추가하려면 operation_type으로 Update를 사용하세요. 새로운 Audience 인터페이스를 사용하면 단일 사용자에 대해 여러 사용자 키를 전달할 수 있습니다. JSON 객체 배열의 각 객체는 하나의 사용자에 해당합니다. 위의 예시 페이로드를 사용하면 이 요청은 두 명의 사용자를 Audience에 추가하며, 한 사용자는 email과 handle을, 다른 한 사용자는 email과 twitter_id를 사용합니다.

잠재고객에서 사용자 제거

위에서 설명한 사용자 추가 과정과 마찬가지로, 다음과 같이 요청을 보내 잠재고객에서 사용자를 제거할 수 있습니다: POST https://ads-api.x.com/11/accounts/18ce54d4x5t/custom_audiences/1nmth/users

    # 모든 값은 해시 처리되어야 하며, 이 예제에서는 설명 목적으로 해시되지 않은 값을 사용합니다
    [
      {
        "operation_type": "Delete",
        "params": {
          "effective_at": "2018-05-15T00:00:00Z",
          "expires_at": "2019-01-01T07:00:00Z",
          "users": [
            {
              "email": [
                "abc@x.com"
              ],
              "twitter_id": [
                "783214",
                "1225933934"
              ]
            },
            {
              "email": [
                "edf@x.com"
              ],
              "twitter_id": [
                "121291606",
                "17874544"
              ]
            }
          ]
        }
      }
    ]

operation_type은 Delete로 설정해야 하며, 사용자 매칭에는 오디언스에 사용자를 추가할 때 사용했던 키들 중 어느 것이든 사용할 수 있습니다. 예를 들어, 사용자가 email과 twitter_id를 사용해 오디언스에 추가되었다면, 동일한 사용자는 이 키들 중 하나, 즉 email 또는 twitter_id 또는 그 둘 다를 사용해 제거할 수 있습니다. 또한, 단일 요청 내에서 Audience에 사용자를 추가하고 제거하는 것도 가능합니다. 이 엔드포인트는 요청당 여러 개의 operation_type을 지원합니다.

옵트아웃(Opt-Out) 사용자

글로벌 옵트아웃 엔드포인트가 더 이상 지원되지(deprecated) 않음에 따라, 파트너는 어느 Audience에서든 옵트아웃한 사용자를 반드시 Delete 해야 합니다. 이를 수행하는 방법은 다음과 같습니다:

어떤 사용자가 어떤 Audience에 속해 있는지 추적하고, 각 Audience에서 해당 사용자를 개별적으로 제거합니다.
Ads 계정과 연결된 모든 Audience에서 해당 사용자를 제거합니다.

일반적인 모범 사례

큐가 짧은 시간에 급격히 증가해 처리 시간이 길어지고 전반적으로 시스템에 불필요한 부하가 걸리는 것을 피하기 위해, 이 엔드포인트는 실시간에 가까운 배치(near real-time batches)로 호출할 것을 강력히 권장합니다. 이렇게 하면 사용자를 캠페인 타기팅에 더 빨리 활용할 수 있습니다.
성공적인 API 호출은 요청에서 전달된 user 객체 수에 해당하는 success_count 와 total_count 를 반환합니다.
이 엔드포인트는 원자적(atomic)입니다. 즉, 전체 요청이 성공하거나, 어떤 오류가 발생할 경우 전체 요청이 실패합니다. 오류 응답이 발생한 경우, 이 API의 사용자는 오류를 수정한 뒤 전체 페이로드로 요청을 다시 시도할 것을 권장합니다.
요청이 실패한 경우, 파트너는 재시도 시 지수 백오프(exponential backoff) 방식을 사용할 것을 권장합니다. 예를 들어, 첫 번째 실패 시에는 즉시 재시도하고, 두 번째 실패 후에는 1분 뒤에, 세 번째 연속 실패 후에는 5분 뒤에 재시도하는 식으로 진행합니다.

API 참조 문서

키워드 인사이트

GET insights/keywords/search

키워드 그룹을 기준으로 관련된 Tweet 수와 함께 30개의 연관 키워드 집합을 가져옵니다. Tweet 수는 연관 키워드가 아니라 입력한 키워드에만 해당합니다. 최대 7일(end_time - start_time)의 기간만 허용됩니다. 결과는 단일 geo(국가) 기준으로 제한된다는 점에 유의하세요. Resource URL https://ads-api.x.com/12/insights/keywords/search Parameters

Name	Description
granularity required	`start_time`과 `end_time`으로 지정된 기간에 대해 반환되는 데이터의 세분성을 지정합니다. 예를 들어 `HOUR`로 설정한 경우, `start_time`과 `end_time` 사이의 각 시간마다 데이터 포인트가 제공됩니다. Type: enum Possible values: `DAY`, `HOUR`
keywords required	검색 범위를 좁히기 위한, 쉼표로 구분된 키워드 문자열입니다. 모든 키워드는 서로 OR 조건으로 결합됩니다. Note: 최대 10개의 키워드(`keywords`와 `negative_keywords` 합산)를 사용할 수 있습니다. Type: string Example: `developers`
start_time required	가져온 데이터를 `start_time`과 `end_time` 사이의 시간 구간으로 제한합니다. ISO 8601 형식으로 표현됩니다. Type: string Example: `2017-07-10T00:00:00Z`
end_time optional	가져온 데이터를 `start_time`과 `end_time` 사이의 시간 구간으로 제한합니다. ISO 8601 형식으로 표현됩니다. Note: 지정하지 않으면 현재 시간이 기본값으로 사용됩니다. Type: string Example: `2017-07-11T00:00:00Z`
location optional	계정 사용자의 위치 기준으로 결과를 제한하기 위해, GET targeting_criteria/locations 엔드포인트에서 얻을 수 있는 타기팅 값입니다. 현재는 국가 단계(location)만 지원됩니다. Type: string Example: `0ce8b9a7b2742f7e`
negative_keywords optional	제외할 키워드를 쉼표로 구분한 문자열입니다. 모든 제외 키워드는 서로 OR 조건으로 결합됩니다. Note: 최대 10개의 키워드(`keywords`와 `negative_keywords` 합산)를 사용할 수 있습니다. Type: string Example: `rain`

Example Request

GET https://ads-api.x.com/12/insights/keywords/search?end_time=2018-02-02&granularity=DAY&keywords=developers&start_time=2018-02-01

예시 응답*

    {
      "request": {
        "params": {
          "start_time": "2018-02-01T00:00:00Z",
          "end_time": "2018-02-02T00:00:00Z",
          "granularity": "DAY",
          "keywords": [
            "developers"
          ]
        }
      },
      "data": {
        "related_keywords": [
          "dev",
          "developer",
          "coders",
          "mysql",
          "devs",
          "#technology",
          "#developers",
          "security",
          "programmers",
          "#tech",
          "javascript",
          "#iot",
          "#bigdata",
          "cloud",
          "devops",
          "php",
          "developer",
          "programmer",
          "engineer",
          "big data",
          "agile",
          "app",
          "programming",
          "ios",
          "maker",
          "startups",
          "developer's",
          "java",
          "#devops",
          "startup"
        ],
        "tweet_volume": [
          15707
        ]
      }
    }

맞춤 잠재고객 권한

GET accounts/:account_id/tailored_audiences/:tailored_audience_id/permissions

지정된 맞춤 잠재 고객과 연관된 일부 또는 전체 권한에 대한 세부 정보를 조회합니다. Resource URL https://ads-api.x.com/5/accounts/:account_id/tailored_audiences/:tailored_audience_id/permissions Parameters

Name	Description
account_id required	활용 중인 계정의 식별자입니다. 리소스 경로 내에 나타나며, GET accounts를 제외한 모든 Advertiser API 요청에 일반적으로 필요한 매개변수입니다. 지정된 계정은 인증된 사용자와 연관되어 있어야 합니다. Type: string Example: `18ce54d4x5t`
tailored_audience_id required	요청에서 작업 중인 맞춤 잠재 고객에 대한 참조입니다. Type: string Example: `1nmth`
count optional	요청당 조회할 레코드 수를 지정합니다. Type: int Default: `200` Min, Max: `1`, `1000`
cursor optional	다음 페이지의 결과를 가져오기 위한 커서를 지정합니다. 자세한 내용은 Pagination을 참고하세요. Type: string Example: `8x7v00oow`
granted_account_ids optional	쉼표로 구분된 식별자 목록을 지정하여 응답을 원하는 계정으로만 한정합니다. 최대 200개의 ID를 제공할 수 있습니다. Type: string Example: `18ce54aymz3`
sort_by optional	지원되는 속성을 기준으로 오름차순 또는 내림차순으로 정렬합니다. 자세한 내용은 Sorting을 참고하세요. Type: string Example: `created_at-asc`
tailored_audience_permission_ids optional	쉼표로 구분된 식별자 목록을 지정하여 응답을 원하는 맞춤 잠재 고객 권한으로만 한정합니다. 최대 200개의 ID를 제공할 수 있습니다. Type: string Example: `ri`
with_total_count optional	`total_count` 응답 속성을 포함합니다. Note: 이 매개변수와 `cursor`는 함께 사용할 수 없습니다. Note: `total_count`를 포함하는 요청에는 더 낮은 요청 한도가 적용되며, 현재 15분당 200건으로 설정되어 있습니다. Type: boolean Default: `false` Possible values: `true`, `false`

Example Request GET https://ads-api.x.com/5/accounts/18ce54d4x5t/tailored_audiences/1nmth/permissions Example Response

    {
      "request": {
        "params": {
          "account_id": "18ce54d4x5t",
          "tailored_audience_id": "1nmth"
        }
      },
      "next_cursor": null,
      "data": [
        {
          "tailored_audience_id": "1nmth",
          "permission_level": "READ_ONLY",
          "id": "ri",
          "created_at": "2017-06-08T23:17:59Z",
          "granted_account_id": "18ce54aymz3",
          "updated_at": "2017-06-08T23:17:59Z",
          "deleted": false
        }
      ]
    }

POST accounts/:account_id/tailored_audiences/:tailored_audience_id/permissions

지정된 오디언스를 특정 계정과 공유할 수 있도록 하는 새로운 권한(permission) 객체를 생성합니다. 참고: 맞춤형 오디언스의 권한을 생성하거나 수정하려면, 해당 오디언스는 권한 수정을 시도하는 계정이 소유하고 있어야 합니다. 특정 오디언스에 대한 응답에서 is_owner 응답 속성을 확인하여 맞춤형 오디언스의 소유 여부를 확인할 수 있습니다. 참고: 오디언스는 동일한 비즈니스에 속한 광고 계정 간에만 공유할 수 있으며, 또는 오디언스를 소유한 광고 계정에 SHARE_AUDIENCE_OUTSIDE_BUSINESS 계정 기능이 있는 경우에만 공유할 수 있습니다. Resource URL https://ads-api.x.com/5/accounts/:account_id/tailored_audiences/:tailored_audience_id/permissions Parameters

Name	Description
account_id required	활용되는 계정의 식별자입니다. 리소스 경로 내에 나타나며, GET accounts를 제외한 모든 Advertiser API 요청에서 일반적으로 필수 매개변수입니다. 지정된 계정은 인증된 사용자와 연결되어 있어야 합니다. Type: string Example: `18ce54d4x5t`
granted_account_id required	맞춤형 오디언스에 대한 권한을 부여하려는 계정입니다. Type: string Example: `18ce54aymz3`
permission_level required	`granted_account_id`가 맞춤형 오디언스에 대해 가져야 하는 접근 권한 유형입니다. Type: enum Possible values: `READ_ONLY`, `READ_WRITE`
tailored_audience_id required	이 요청에서 사용 중인 맞춤형 오디언스를 참조합니다. Type: string Example: `2906h`

Example Request

POST https://ads-api.x.com/5/accounts/18ce54d4x5t/tailored_audiences/2906h/permissions?granted_account_id=18ce54aymz3&permission_level=READ_ONLY

Example Response

    {
      "request": {
        "params": {
          "account_id": "18ce54d4x5t",
          "granted_account_id": "18ce54aymz3",
          "permission_level": "READ_ONLY",
          "tailored_audience_id": "2906h"
        }
      },
      "data": {
        "tailored_audience_id": "2906h",
        "permission_level": "READ_ONLY",
        "id": "14m",
        "created_at": "2017-09-12T23:49:34Z",
        "granted_account_id": "18ce54aymz3",
        "updated_at": "2017-09-12T23:49:34Z",
        "deleted": false
      }
    }

DELETE accounts/:account_id/tailored_audiences/:tailored_audience_id/permissions/:tailored_audience_permission_id

지정된 Tailored Audience 공유 권한을 철회합니다. 참고: Tailored Audience의 권한을 생성하거나 수정하려면, 해당 Audience는 권한을 수정하려는 계정이 소유하고 있어야 합니다. 특정 Audience에 대한 응답에서 is_owner 응답 속성을 확인하여 Tailored Audience의 소유 여부를 확인할 수 있습니다. 권한이 철회되면, 권한이 부여된 계정(granted_account_id)은 향후 캠페인에서 더 이상 해당 Audience를 타게팅할 수 없음을 보장합니다. 기존 캠페인은 공유된 Audience와 함께 계속 실행됩니다. 캠페인은 중지되지 않으며 Audience가 캠페인에서 제거되지도 않습니다. Audience 공유 권한이 철회된 후에는 이 캠페인을 복사할 수 없습니다. 리소스 URL

https://ads-api.x.com/5/accounts/:account_id/tailored_audiences/:tailored_audience_id/permissions/:tailored_audience_permission_id

매개변수

Name	Description
account_id required	활용 중인 계정의 식별자입니다. 리소스 경로 내에 나타나며, GET accounts를 제외한 모든 Advertiser API 요청에 대해 일반적으로 필수 매개변수입니다. 지정된 계정은 인증된 사용자와 연관되어 있어야 합니다. Type: string Example: `18ce54d4x5t`
tailored_audience_id required	요청에서 대상으로 하는 Tailored Audience에 대한 참조입니다. Type: string Example: `1nmth`
tailored_audience_permission_id required	요청에서 대상으로 하는 Tailored Audience 권한에 대한 참조입니다. Type: string Example: `ri`

요청 예시 DELETE https://ads-api.x.com/5/accounts/18ce54d4x5t/tailored_audiences/1nmth/permissions/ri 응답 예시

    {
      "request": {
        "params": {
          "account_id": "18ce54d4x5t",
          "tailored_audience_permission_id": "ri",
          "tailored_audience_id": "1nmth"
        }
      },
      "data": {
        "tailored_audience_id": "1nmth",
        "permission_level": "READ_ONLY",
        "id": "ri",
        "created_at": "2017-06-08T23:17:59Z",
        "granted_account_id": "18ce54aymz3",
        "updated_at": "2017-08-30T18:29:35Z",
        "deleted": true
      }
    }

타겟팅된 오디언스

GET accounts/:account_id/custom_audiences/:custom_audience_id/targeted

지정된 custom_audience_id를 타게팅하는 활성 또는 전체 라인 아이템 및 캠페인 목록을 조회합니다.

Name	Description
account_id required	사용되는 계정의 식별자입니다. 리소스 경로에 나타나며, GET accounts를 제외한 모든 Advertiser API 요청에서 일반적으로 필수 매개변수입니다. 지정한 계정은 인증된 사용자와 연계되어 있어야 합니다. Type: string Example: `18ce54d4x5t`
custom_audience_id required	요청에서 사용 중인 커스텀 오디언스를 참조합니다. Type: string Example: `2906h`
with_active optional	`false`일 경우, `servable=false` 상태의 라인 아이템도 포함합니다. Type: boolean Default: `true` Possible values: `true`, `false`
cursor optional	결과의 다음 페이지를 가져오기 위한 커서를 지정합니다. 자세한 내용은 Pagination을 참조하세요. Type: string Example: `8x7v00oow`

Example Request GET https://ads-api.x.com/12/accounts/18ce54d4x5t/custom_audiences/2906h/targeted Example Response

    {
      "request": {
        "params": {
          "account_id": "18ce54d4x5t",
          "custom_audience_id": "2906h",
        }
      },
      "next_cursor": null,
      "data": [
        {
          "campaign_id": "59hod",
          "campaign_name": "test-campaign",
          "line_items": [
            {
              "id": "5gzog",
              "name": "test-line-item",
              "servable": true
            }
          ]
        },
        {
          "campaign_id": "arja7",
          "campaign_name": "Untitled campaign",
          "line_items": [
            {
              "id": "bjw1q",
              "name": null,
              "servable": true
            }
          ]
        }
      ]
    }

Custom Audiences의 사용자

POST accounts/:account_id/custom_audiences/:custom_audience_id/users

이 엔드포인트를 사용하면 파트너가 지정된 custom_audience_id에 대해 사용자를 추가, 업데이트 및 제거할 수 있습니다. 또한 이 엔드포인트는 각 사용자에 대해 여러 종류의 사용자 식별자를 함께 전달받을 수 있습니다. 요청의 users 필드에 제공되는 모든 데이터는 partner_user_id를 제외하고 SHA256으로 해시한 뒤 정규화해야 합니다. 배치 요청

현재 이 엔드포인트에 대한 최대 배치 크기는 2500입니다. 배치 크기는 요청당 작업(Update/Delete)의 수로 결정됩니다. 예를 들어, 하나의 배열에 2500개를 초과하는 작업 객체({"operation_type": "Update/Delete", [..] })가 있으면 오류가 발생합니다.
이 엔드포인트가 수락할 수 있는 요청 POST 본문의 최대 크기는 5,000,000바이트입니다.
이 엔드포인트에 대한 요청 한도는 1분당 1500건입니다.
모든 매개변수는 요청 본문에 전송되며, Content-Type이 application/json이어야 합니다.
배치 요청은 하나의 그룹으로 함께 실패하거나 성공하며, 오류와 성공 모두에 대한 모든 API 응답은 최초 요청의 항목 순서를 그대로 유지합니다.

배치 응답 Ads API가 반환하는 응답에는 success_count와 total_count라는 두 필드가 포함됩니다. 이 값들은 항상 같아야 하며, 백엔드에서 처리된 요청 내 레코드 수를 나타냅니다. 요청 본문에 전송된 레코드 수가 success_count 및 total_count와 같지 않은 상황은 오류 상태로 간주해야 하며, 재시도가 필요합니다. 배치 오류

요청 수준 오류(예: 최대 배치 크기 초과)는 응답의 errors 객체 아래에 표시됩니다.
항목 수준 오류(예: 필수 매개변수 누락)는 응답의 operation_errors 객체 아래에 표시됩니다.
operation_errors 내 오류의 인덱스는 입력 항목의 인덱스를 가리키며, 해당 오류 메시지가 함께 제공됩니다.

리소스 URL

https://ads-api.x.com/12/accounts/:account_id/custom_audiences/:custom_audience_id/users

매개변수

Name	Description
operation_type required	`users` 그룹별로 수행되는 작업 유형입니다. Type: enum Possible values: `Update`, `Delete`
params required	`users` 배열과 `effective_at`, `expires_at` 타임스탬프를 포함하는 JSON 객체입니다. Type: JSON
users required	개별 사용자에 대한 모든 params를 포함하는 JSON 객체 배열입니다. Type: JSON
effective_at optional	커스텀 오디언스 연관 관계가 적용되기 시작해야 하는 UTC 시간입니다. ISO 8601 형식으로 표현됩니다. 기본값은 현재 날짜와 시간입니다. Type: string Example: `2017-07-05T07:00:00Z`
expires_at optional	커스텀 오디언스 연관 관계가 만료되어야 하는 UTC 시간입니다. 지정된 시간은 `effective_at` 값 이후여야 합니다. ISO 8601 형식으로 표현됩니다. 기본값은 요청 타임스탬프 기준 13개월 후입니다. Type: string Example: `2017-07-05T07:00:00Z`

users 객체에 대한 멀티 키 방식으로 인해, 이 객체의 각 요소는 아래와 같이 문서화되어 있습니다:

Name	Description
email optional	사용자의 이메일 주소입니다. Type: Array[String]
device_id optional	IDFA/AdID/Android ID입니다. Type: Array[String]
handle optional	사용자에게 속한 @handle입니다. Type: Array[String]
twitter_id optional	사용자에게 속한 X ID입니다. Type: Array[String]
phone_number optional	사용자의 전화번호입니다. Type: Array[String]
partner_user_id optional	파트너 시스템에서의 사용자의 ID입니다. Type: Array[String]

예시 요청

POST https://ads-api.x.com/12/accounts/18ce54d4x5t/custom_audiences/1nmth/users

    [
      {
        "operation_type": "Update",
        "params": {
          "effective_at": "2018-05-15T00:00:00Z",
          "expires_at": "2019-01-01T07:00:00Z",
          "users": [
            {
              "email": [
                "4798b8bbdcf6f2a52e527f46a3d7a7c9aefb541afda03af79c74809ecc6376f3"
              ],
              "handle": [
                "7352f353c460e74c7ae226952d04f8aa307b12329c5512ec8cb6f1a0f8f9b2cb",
                "49e0be2aeccfb51a8dee4c945c8a70a9ac500cf6f5cb08112575f74db9b1470d"
              ]
            },
            {
              "email": [
                "5bf13d5ad4200407c5bc8b9bb578e425d05ef936fd488e3799a9d0806669223c"
              ],
              "twitter_id": [
                "34d56c7159a7eea941f359653029410f813f65a1d2d13ecc5ccbdd5a8cb755cf",
                "00e7b76c9739dec57f4c4a20ec021a20ffcf26bd00f519b17ea00f0ed6048f85"
              ]
            }
          ]
        }
      },
      {
        "operation_type": "Delete",
        "params": {
          "effective_at": "2018-05-15T00:00:00Z",
          "expires_at": "2019-01-01T07:00:00Z",
          "users": [
            {
              "device_id": [
                "8d969eef6ecad3c29a3a629280e686cf0c3f5d5a86aff3ca12020c923adc6c92"
              ],
              "email": [
                "4798b8bbdcf6f2a52e527f46a3d7a7c9aefb541afda03af79c74809ecc6376f3"
              ],
              "handle": [
                "461222f5dd690a20651c3d19848015cb0369db3f8e937571ffb775de70750847"
              ],
              "twitter_id": [
                "c623c7e163984493b46c547088542e95d0aaa529bc52bbecce3ff91eb6b7843b"
              ]
            },
            {
              "email": [
                "5bf13d5ad4200407c5bc8b9bb578e425d05ef936fd488e3799a9d0806669223c"
              ],
              "twitter_id": [
                "858cdc7f313f84a3f3c48e9a6323307c1ef1bb7439b8e3623e140454b0fd8fa5",
                "bb074e154657b91d99bd1bb3757409149670e8ae7a0fe9136fae29a26a7881c8"
              ]
            }
          ]
        }
      }
    ]

응답 예시

    {
      "request": {
        "params": {
          "account_id": "18ce54d4x5t",
          "custom_audience_id": "1nmth"
        }
      },
      "data": {
        "success_count": 4,
        "total_count": 4
      }
    }

맞춤 오디언스 권한

GET accounts/:account_id/custom_audiences/:custom_audience_id/permissions

지정한 커스텀 오디언스에 연결된 일부 또는 전체 권한의 세부 정보를 조회합니다. 리소스 URL https://ads-api.x.com/12/accounts/:account_id/custom_audiences/:custom_audience_id/permissions 매개변수

이름	설명
account_id required	활용 중인 계정의 식별자입니다. 리소스 경로에 포함되며, GET accounts를 제외한 모든 Advertiser API 요청에서 일반적으로 필수 매개변수입니다. 지정된 계정은 인증된 사용자와 연결되어 있어야 합니다. Type: string Example: `18ce54d4x5t`
custom_audience_id required	요청에서 작업 중인 커스텀 오디언스를 가리키는 참조입니다. Type: string Example: `1nmth`
count optional	각 요청마다 조회할 레코드 수를 지정합니다. Type: int Default: `200` Min, Max: `1`, `1000`
cursor optional	다음 페이지의 결과를 가져오기 위한 커서를 지정합니다. 자세한 내용은 Pagination을 참조하세요. Type: string Example: `8x7v00oow`
granted_account_ids optional	쉼표로 구분된 식별자 목록을 지정하여 응답을 원하는 계정으로만 한정합니다. 최대 200개의 ID를 제공할 수 있습니다. Type: string Example: `18ce54aymz3`
sort_by optional	지원되는 속성을 기준으로 오름차순 또는 내림차순으로 정렬합니다. 자세한 내용은 Sorting을 참조하세요. Type: string Example: `created_at-asc`
custom_audience_permission_ids optional	쉼표로 구분된 식별자 목록을 지정하여 응답을 원하는 커스텀 오디언스 권한으로만 한정합니다. 최대 200개의 ID를 제공할 수 있습니다. Type: string Example: `ri`
with_total_count optional	`total_count` 응답 속성을 포함할지 여부를 지정합니다. 참고: 이 매개변수와 `cursor`는 상호 배타적입니다. 참고: `total_count`를 포함하는 요청에는 더 낮은 요청 한도가 적용되며, 현재 15분당 200건으로 설정되어 있습니다. Type: boolean Default: `false` Possible values: `true`, `false`

요청 예시 GET https://ads-api.x.com/12/accounts/18ce54d4x5t/custom_audiences/1nmth/permissions 응답 예시

    {
      "request": {
        "params": {
          "account_id": "18ce54d4x5t",
          "custom_audience_id": "1nmth"
        }
      },
      "next_cursor": null,
      "data": [
        {
          "custom_audience_id": "1nmth",
          "permission_level": "READ_ONLY",
          "id": "ri",
          "created_at": "2017-06-08T23:17:59Z",
          "granted_account_id": "18ce54aymz3",
          "updated_at": "2017-06-08T23:17:59Z",
          "deleted": false
        }
      ]
    }

POST accounts/:account_id/custom_audiences/:custom_audience_id/permissions

지정된 맞춤 오디언스를 특정 계정과 공유할 수 있도록 하는 새 권한 객체를 생성합니다. 참고: 맞춤 오디언스의 권한을 생성하거나 수정하려면, 해당 맞춤 오디언스를 소유한 계정이어야 합니다. 특정 맞춤 오디언스에 대한 응답에서 is_owner 응답 속성을 확인하여 소유 여부를 확인할 수 있습니다. 참고: 오디언스는 동일한 비즈니스에 속한 광고 계정 간에만 공유할 수 있습니다. 단, 오디언스를 소유한 광고 계정에 SHARE_AUDIENCE_OUTSIDE_BUSINESS 계정 기능이 있는 경우에는 예외입니다. Resource URL https://ads-api.x.com/12/accounts/:account_id/custom_audiences/:custom_audience_id/permissions Parameters

Name	Description
account_id required	사용되는 계정의 식별자입니다. 리소스 경로에 포함되며, GET accounts를 제외한 모든 Advertiser API 요청에서 일반적으로 필수 매개변수입니다. 지정한 계정은 인증된 사용자와 연결되어 있어야 합니다. Type: string Example: `18ce54d4x5t`
granted_account_id required	맞춤 오디언스에 대한 권한을 부여하려는 계정입니다. Type: string Example: `18ce54aymz3`
permission_level required	`granted_account_id`가 맞춤 오디언스에 대해 가져야 하는 액세스 수준입니다. Type: enum Possible values: `READ_ONLY`, `READ_WRITE`
custom_audience_id required	요청에서 작업 중인 맞춤 오디언스를 가리키는 참조 값입니다. Type: string Example: `2906h`

Example Request

POST https://ads-api.x.com/12/accounts/18ce54d4x5t/custom_audiences/2906h/permissions?granted_account_id=18ce54aymz3&permission_level=READ_ONLY

응답 예시

    {
      "request": {
        "params": {
          "account_id": "18ce54d4x5t",
          "granted_account_id": "18ce54aymz3",
          "permission_level": "READ_ONLY",
          "custom_audience_id": "2906h"
        }
      },
      "data": {
        "custom_audience_id": "2906h",
        "permission_level": "READ_ONLY",
        "id": "14m",
        "created_at": "2017-09-12T23:49:34Z",
        "granted_account_id": "18ce54aymz3",
        "updated_at": "2017-09-12T23:49:34Z",
        "deleted": false
      }
    }

DELETE accounts/:account_id/custom_audiences/:custom_audience_id/permissions/:custom_audience_permission_id

지정된 Custom Audience 공유 권한을 철회합니다. 참고: Custom Audience에 대한 권한을 생성하거나 수정하려면, 해당 Audience가 권한을 수정하려는 계정이 소유하고 있어야 합니다. 특정 Audience에 대한 응답에서 is_owner 응답 속성을 확인하여 Custom Audience의 소유 여부를 확인할 수 있습니다. 권한이 철회되면, 부여된 계정(granted_account_id)은 향후 캠페인에서 해당 Audience를 타기팅할 수 없도록 보장됩니다. 기존 캠페인은 공유된 Audience와 함께 계속 실행됩니다. 캠페인은 중지되지 않으며, Audience도 캠페인에서 제거되지 않습니다. Audience 공유 권한이 철회된 이후에는 이 캠페인을 복사할 수 없습니다. 리소스 URL

https://ads-api.x.com/12/accounts/:account_id/custom_audiences/:custom_audience_id/permissions/:custom_audience_permission_id

매개변수

Name	Description
account_id required	대상 계정의 식별자입니다. 리소스 경로에 나타나며, GET accounts를 제외한 모든 Advertiser API 요청에서 일반적으로 필수 매개변수입니다. 지정된 계정은 인증된 사용자와 연결되어 있어야 합니다. Type: string Example: `18ce54d4x5t`
custom_audience_id required	요청에서 사용 중인 Custom Audience에 대한 참조입니다. Type: string Example: `1nmth`
custom_audience_permission_id required	요청에서 사용 중인 Custom Audience 권한에 대한 참조입니다. Type: string Example: `ri`

요청 예시 DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/custom_audiences/1nmth/permissions/ri 응답 예시

    {
      "request": {
        "params": {
          "account_id": "18ce54d4x5t",
          "custom_audience_permission_id": "ri",
          "custom_audience_id": "1nmth"
        }
      },
      "data": {
        "custom_audience_id": "1nmth",
        "permission_level": "READ_ONLY",
        "id": "ri",
        "created_at": "2017-06-08T23:17:59Z",
        "granted_account_id": "18ce54aymz3",
        "updated_at": "2017-08-30T18:29:35Z",
        "deleted": true
      }
    }

맞춤 잠재 고객

GET accounts/:account_id/custom_audiences

현재 계정과 연결된 일부 또는 모든 Custom Audiences의 세부 정보를 조회합니다. Resource URL https://ads-api.x.com/12/accounts/:account_id/custom_audiences Parameters

Name	Description
account_id required	사용 중인 계정의 식별자입니다. 리소스 경로에 포함되며, GET accounts를 제외한 모든 Advertiser API 요청에서 일반적으로 필수 매개변수입니다. 지정된 계정은 인증된 사용자와 연결되어 있어야 합니다. Type: string Example: `18ce54d4x5t`
count optional	각 요청당 조회를 시도할 레코드 수를 지정합니다. Type: int Default: `200` Min, Max: `1`, `1000`
cursor optional	다음 페이지의 결과를 가져오기 위한 cursor를 지정합니다. 자세한 내용은 Pagination을 참조하세요. Type: string Example: `8x7v00oow`
permission_scope optional	응답을 사용자가 소유한 리스트 또는 공유받은 리스트로 필터링할 수 있습니다. 기본적으로 이 매개변수를 지정하지 않으면 사용자가 소유한 audience만 표시됩니다. Type: enum Default: `OWNER` Possible values: `OWNER`, `SHARED`
q optional	`name`으로 리소스를 범위 지정하기 위한 선택적 쿼리입니다. Note: 대소문자를 구분하지 않는 접두어 일치 방식으로 매칭을 수행합니다. Type: string Min, Max length: `1`, `255`
sort_by optional	지원되는 속성을 기준으로 결과를 오름차순 또는 내림차순으로 정렬합니다. 자세한 내용은 Sorting을 참조하세요. Type: string Example: `created_at-asc`
custom_audience_ids optional	쉼표로 구분된 식별자 리스트를 지정하여, 원하는 Custom Audiences만 응답에 포함되도록 범위를 지정합니다. 최대 200개의 ID를 제공할 수 있습니다. Type: string Example: `1nmth`
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`

Example Request GET https://ads-api.x.com/12/accounts/18ce54d4x5t/custom_audiences?custom_audience_ids=1nmth Example Response

    {
      "request": {
        "params": {
          "custom_audience_ids": [
            "1nmth"
          ],
          "account_id": "18ce54d4x5t"
        }
      },
      "next_cursor": null,
      "data": [
        {
          "targetable": true,
          "name": "twurl-using-subshell-for-file",
          "targetable_types": [
            "CRM",
            "EXCLUDED_CRM"
          ],
          "audience_type": "CRM",
          "description": null,
          "permission_level": "READ_WRITE",
          "owner_account_id": "18ce54d4x5t",
          "id": "1nmth",
          "reasons_not_targetable": [],
          "created_at": "2017-01-08T08:19:58Z",
          "updated_at": "2017-01-08T16:21:13Z",
          "partner_source": "OTHER",
          "deleted": false,
          "audience_size": 1470
        }
      ]
    }

GET accounts/:account_id/custom_audiences/:custom_audience_id

현재 계정과 연관된 특정 Custom Audience를 조회합니다. Resource URL https://ads-api.x.com/12/accounts/:account_id/custom_audiences/:custom_audience_id Parameters

Name	Description
account_id required	사용 중인 계정의 식별자입니다. 리소스 경로에 포함되며, GET accounts를 제외한 모든 Advertiser API 요청에서 일반적으로 필수 매개변수입니다. 지정된 계정은 인증된 사용자와 연결되어 있어야 합니다. Type: string Example: `18ce54d4x5t`
custom_audience_id required	요청에서 사용하는 Custom Audience에 대한 참조입니다. Type: string Example: `2906h`
with_deleted optional	요청 결과에 삭제된 항목을 포함합니다. Type: boolean Default: `false` Possible values: `true`, `false`

Example Request GET https://ads-api.x.com/12/accounts/18ce54d4x5t/custom_audiences/2906h Example Response

    {
      "request": {
        "params": {
          "custom_audience_id": "2906h",
          "account_id": "18ce54d4x5t"
        }
      },
      "data": {
        "targetable": false,
        "name": "developers",
        "targetable_types": [
          "CRM",
          "EXCLUDED_CRM"
        ],
        "audience_type": "CRM",
        "description": null,
        "permission_level": "READ_WRITE",
        "owner_account_id": "18ce54d4x5t",
        "id": "2906h",
        "reasons_not_targetable": [],
        "created_at": "2017-08-22T23:34:26Z",
        "updated_at": "2017-08-22T23:34:26Z",
        "partner_source": "OTHER",
        "deleted": false,
        "audience_size": 140321
      }
    }

POST accounts/:account_id/custom_audiences

현재 계정과 연결된 새 플레이스홀더 맞춤 잠재고객(Custom Audience)을 생성합니다. 리소스 URL https://ads-api.x.com/12/accounts/:account_id/custom_audiences 매개변수

Name	Description
account_id required	대상 계정의 식별자입니다. 리소스의 경로에 포함되며, GET accounts를 제외한 모든 Advertiser API 요청에서 일반적으로 필수 매개변수입니다. 지정된 계정은 인증된 사용자와 연결되어 있어야 합니다. Type: string Example: `18ce54d4x5t`
name required	이 잠재고객의 표시 이름입니다. 고유한 이름 값을 사용해야 합니다. 그렇지 않으면 오류가 발생합니다. Type: string Example: `ads api users`
description optional	이 잠재고객에 대한 설명입니다. Type: string Example: `Ads API를 사용하는 모든 사용자 모음`

요청 예시 POST https://ads-api.x.com/12/accounts/18ce54d4x5t/custom_audiences?name=developers 응답 예시

    {
      "data": {
        "targetable": false,
        "name": "developers",
        "targetable_types": [
          "CRM",
          "EXCLUDED_CRM"
        ],
        "audience_type": "CRM",
        "description": null,
        "permission_level": "READ_WRITE",
        "owner_account_id": "18ce54d4x5t",
        "id": "2906h",
        "reasons_not_targetable": [
          "PROCESSING",
          "TOO_SMALL"
        ],
        "created_at": "2017-08-22T23:34:26Z",
        "updated_at": "2017-08-22T23:34:26Z",
        "partner_source": "OTHER",
        "deleted": false,
        "audience_size": null
      },
      "request": {
        "params": {
          "account_id": "18ce54d4x5t",
          "name": "developers"
        }
      }
    }

PUT accounts/:account_id/custom_audiences/:custom_audience_id

현재 계정과 연결된 특정 Custom Audience를 업데이트합니다. Resource URL https://ads-api.x.com/12/accounts/:account_id/custom_audiences/:custom_audience_id Parameters

Name	Description
account_id required	사용되는 계정의 식별자입니다. 리소스 경로에 포함되며, GET accounts를 제외한 모든 Advertiser API 요청에서 일반적으로 필수 매개변수입니다. 지정된 계정은 인증된 사용자와 연결되어 있어야 합니다. Type: string Example: `18ce54d4x5t`
custom_audience_id required	요청에서 사용 중인 Custom Audience에 대한 참조입니다. Type: string Example: `2906h`
name optional	이 Custom Audience의 표시 이름입니다. 고유한 이름 값을 사용해야 합니다. 그렇지 않으면 오류가 발생합니다. Type: string Example: `ads api users`
description optional	이 Custom Audience에 대한 설명입니다. Type: string Example: `Collection of all users of the Ads API`

Example Request PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/custom_audiences/2906h?name=developers_changed Example Response

    {
      "data": {
        "targetable": false,
        "name": "developers_changed",
        "targetable_types": [
          "CRM",
          "EXCLUDED_CRM"
        ],
        "audience_type": "CRM",
        "description": null,
        "permission_level": "READ_WRITE",
        "is_owner": true,
        "id": "2906h",
        "reasons_not_targetable": [
          "PROCESSING",
          "TOO_SMALL"
        ],
        "created_at": "2017-08-22T23:34:26Z",
        "updated_at": "2017-08-22T23:34:26Z",
        "partner_source": "OTHER",
        "deleted": false,
        "audience_size": null
      },
      "request": {
        "params": {
          "account_id": "18ce54d4x5t",
          "name": "developers_changed"
        }
      }
    }

POST batch/accounts/:account_id/custom_audiences

Custom Audiences를 일괄 생성합니다. Audience에 대한 정보는 Custom Audiences 개요 페이지를 참고하세요. 참고: 이 배치 엔드포인트는 현재 비공개 베타 단계이며, 일부 선정된 광고주에게만 제공됩니다. 이 베타 기간 동안에는 모바일 Custom Audiences를 기반으로 한 Flexible Audiences만 생성할 수 있습니다. 배치 요청

현재 최대 배치 크기는 10입니다.
모든 파라미터는 요청 본문에 포함되며, Content-Type 값으로 application/json 이 필요합니다.
배치 요청은 하나의 그룹으로 함께 실패하거나 성공하며, 오류와 성공 응답 모두에서 초기 요청의 항목 순서를 그대로 유지합니다.

배치 응답 배치 API 응답은 순서가 있는 항목 컬렉션을 반환합니다. 그 외에는 해당 단일 항목 엔드포인트와 구조적으로 동일합니다. 배치 오류

요청 수준 오류(예: 최대 배치 크기 초과)는 응답의 errors 객체 아래에 표시됩니다.
항목 수준 오류(예: 필수 파라미터 누락)는 응답의 operation_errors 객체 아래에 표시됩니다.

Flexible Audiences

Flexible Audiences는 한 번 생성되면 변경할 수 없습니다.
Custom Audiences는 Flexible Audiences를 생성하기 위해 불리언 논리 조합을 사용하는 트리 구조로 전달됩니다.
최대 10개의 Custom Audiences 리프 노드를 사용하여 하나의 Flexible Audience를 생성할 수 있습니다.

Resource URL https://ads-api.x.com/12/batch/accounts/:account_id/custom_audiences Parameters

Name	Description
account_id required	사용하는 계정을 식별하는 식별자입니다. 리소스 경로에 포함되며, GET accounts을(를) 제외한 모든 Advertiser API 요청에서 일반적으로 필수 매개변수입니다. 지정한 계정은 인증된 사용자와 연결되어 있어야 합니다. Type: string Example: `18ce54d4x5t`
audience_type required	생성할 오디언스의 type입니다. Type: enum Possible values: `FLEXIBLE`, `MOBILE_AUDIENCE`
child_segments required	타깃팅하려는 Custom Audience 구성원의 하위 집합을 정의하는 객체 배열입니다. 각 객체에는 `custom_audience_id`, `frequency`, `frequency_comparator`, `lookback_window`, `negate`가 포함되어야 하며, 경우에 따라 추가적인 `child_segments`가 포함될 수 있습니다. Type: array
name required	오디언스의 표시 이름입니다. name 값은 고유해야 합니다. 그렇지 않으면 오류가 발생합니다. Type: string Example: `my_flexible_audience_name`
operation_type required	각 항목에 대해 수행되는 작업 type입니다. Type: enum Possible values: `Create`, `Update`, `Delete`
boolean_operator sometimes required	상위(포함하는) 객체 내에서 child segments 간의 논리적 관계입니다. 상위 객체의 child_segments가 비어 있지 않은 경우 필수입니다. Type: enum Possible values: `AND`, `OR`
lookback_window sometimes required	사용자가 특정 작업을 수행하고 해당 custom audience 자격을 갖추게 된 기간(일 수 범위)을 지정하는 정수 값입니다. Type: int Possible values: `1`, `7`, `14`, `30`
segments sometimes required	타깃팅하려는 Custom Audience 구성원의 하위 집합을 정의하는 `boolean_operator` 및 `child_segments`를 포함하는 객체입니다. Type: object
custom_audience_id sometimes required	하위 세그먼트로 사용할 custom audience의 id입니다. Type: string Example: `tyfo`
frequency optional	사용자가 특정 작업을 수행하고 해당 custom audience 자격을 갖추게 된 횟수를, lookback window 내에서 지정하는 정수 값입니다. Type: int Default value: `1`
frequency_comparator optional	요청에 전달된 `frequency`에 대한 비교 연산자입니다. Note: 아래 값들에서 `GTE`는 크거나 같음(greater than or equal), `LT`는 작음(less than) 등을 의미합니다. Type: string Possible values: `NUM_GTE`, `NUM_GT`, `NUM_EQ`, `NUM_LTE`, `NUM_LT` Default value: `NUM_GTE`
negate optional	세그먼트를 부정하여 조합에서 제외합니다. Type: boolean Default value: `true` Possible values: `true`, `false`

예시 요청 POST https://ads-api.x.com/12/batch/accounts/18ce54d4x5t/custom_audiences

    [
      {
        "operation_type":"Create",
        "params":{
          "name":"my_flexible_audience_name",
          "audience_type":"FLEXIBLE",
          "segments":{
            "boolean_operator":"AND",
            "child_segments":[
              {
                "custom_audience_id":"TYIF",
                "frequency":1,
                "frequency_comparator":"NUM_GT",
                "lookback_window":30,
                "negate":true,
                "child_segments":[

                ]
              },
              {
                "boolean_operator":"OR",
                "child_segments":[
                  {
                    "custom_audience_id":"TXR1",
                    "lookback_window":30,
                    "child_segments":[

                    ]
                  },
                  {
                    "custom_audience_id":"TYFO",
                    "frequency":1,
                    "frequency_comparator":"NUM_GT",
                    "lookback_window":30,
                    "negate":true,
                    "child_segments":[

                    ]
                  }
                ]
              }
            ]
          }
        }
      }
    ]

응답 예시

    {
      "data": {
        "targetable": false,
        "name": "my_flexible_audience_name",
        "targetable_types": [
          "FLEXIBLE",
          "EXCLUDED_FLEXIBLE"
        ],
        "audience_type": "FLEXIBLE",
        "id": "13ld7",
        "reasons_not_targetable": [
          "PROCESSING",
          "TOO_SMALL"
        ],
        "metadata": [
          {
            "custom_audience_id": "13ld7",
            "account_id": "qsx3w2",
            "name": "my_flexible_audience_name",
            "audience_source": "FLEXIBLE_AUDIENCE",
            "upload_status": "UPLOADED",
            "segments": {
              "boolean_operator": "AND",
              "frequency": 1,
              "frequency_comparator": "NUM_GTE",
              "negate": false,
              "child_segments": [
                {
                  "custom_audience_id": "tyif",
                  "lookback_window": 30,
                  "frequency": 1,
                  "frequency_comparator": "NUM_GT",
                  "negate": true,
                  "child_segments": [

                  ]
                },
                {
                  "boolean_operator": "OR",
                  "frequency": 1,
                  "frequency_comparator": "NUM_GTE",
                  "negate": false,
                  "child_segments": [
                    {
                      "custom_audience_id": "txr1",
                      "lookback_window": 30,
                      "frequency": 1,
                      "frequency_comparator": "NUM_GTE",
                      "negate": false,
                      "child_segments": [

                      ]
                    },
                    {
                      "custom_audience_id": "tyfo",
                      "lookback_window": 30,
                      "frequency": 1,
                      "frequency_comparator": "NUM_GT",
                      "negate": true,
                      "child_segments": [

                      ]
                    }
                  ]
                }
              ]
            }
          }
        ],
        "created_at": "2015-11-10T21:26:43Z",
        "updated_at": "2015-11-11T01:11:47Z",
        "partner_source": "OTHER",
        "deleted": false,
        "audience_size": null
      },
      "request": [
        {
          "params": {
            "name": "my_flexible_audience_name",
            "audience_type": "FLEXIBLE",
            "segments": {
              "boolean_operator": "AND",
              "child_segments": [
                {
                  "custom_audience_id": "TYIF",
                  "lookback_window": 30,
                  "frequency": 1,
                  "frequency_comparator": "NUM_GT",
                  "negate": true,
                  "child_segments": [

                  ]
                },
                {
                  "boolean_operator": "OR",
                  "child_segments": [
                    {
                      "custom_audience_id": "TXR1",
                      "lookback_window": 30,
                      "child_segments": [

                      ]
                    },
                    {
                      "custom_audience_id": "TYFO",
                      "lookback_window": 30,
                      "frequency": 1,
                      "frequency_comparator": "NUM_GT",
                      "negate": true,
                      "child_segments": [

                      ]
                    }
                  ]
                }
              ]
            },
            "account_id": "qsx3w2"
          },
          "operation_type": "Create"
        }
      ]
    }

DELETE accounts/:account_id/custom_audiences/:custom_audience_id

현재 계정에 속한 지정된 Custom Audience를 삭제합니다. Resource URL https://ads-api.x.com/12/accounts/:account_id/custom_audiences/:custom_audience_id Parameters

Name	Description
account_id required	사용 중인 계정의 식별자입니다. 리소스 경로에 포함되며, GET accounts를 제외한 모든 Advertiser API 요청에 일반적으로 필요한 매개변수입니다. 지정된 계정은 인증된 사용자와 연결되어 있어야 합니다. Type: string Example: `18ce54d4x5t`
custom_audience_id required	요청에서 조작하려는 Custom Audience에 대한 참조입니다. Type: string Example: `2906h`

Example Request DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/custom_audiences/2906h Example Response

    {
      "data": {
        "targetable": false,
        "name": "developers",
        "targetable_types": [
          "CRM",
          "EXCLUDED_CRM"
        ],
        "audience_type": "CRM",
        "description": null,
        "permission_level": "READ_WRITE",
        "owner_account_id": "18ce54d4x5t",
        "id": "2906h",
        "reasons_not_targetable": [
          "TOO_SMALL"
        ],
        "created_at": "2017-08-22T23:34:26Z",
        "updated_at": "2017-08-30T18:09:00Z",
        "partner_source": "OTHER",
        "deleted": true,
        "audience_size": null
      },
      "request": {
        "params": {
          "custom_audience_id": "2906h",
          "account_id": "18ce54d4x5t"
        }
      }
    }

도달 제외 리스트

GET accounts/:account_id/do_not_reach_lists

현재 계정과 연결된 일부 또는 전체 연락 금지 리스트(Do Not Reach List)의 세부 정보를 조회합니다. 참고: 하나의 account_id에는 최대 하나의 연락 금지 리스트(Do Not Reach List)만 존재할 수 있습니다. 리소스 URL https://ads-api.x.com/12/accounts/:account_id/do_not_reach_lists 매개변수

Name	Description
account_id required	활용 중인 계정의 식별자입니다. 리소스 경로에 포함되며, GET accounts를 제외한 모든 Advertiser API 요청에서 일반적으로 필수 매개변수입니다. 지정된 계정은 인증된 사용자와 연결되어 있어야 합니다. Type: string Example: `18ce54d4x5t`
with_deleted optional	삭제된 결과를 요청에 포함할지 여부입니다. Type: boolean Default: `false` Possible values: `true`, `false`

요청 예시 GET https://ads-api.x.com/12/accounts/18ce54bgxky/do_not_reach_lists 응답 예시

    {
      "request": {
        "params": {
          "account_id": "18ce54bgxky"
        }
      },
      "next_cursor": null,
      "data": [
        {
          "targetable": false,
          "name": "Do Not Reach List",
          "description": "test DNRL",
          "id": "4kzrq",
          "reasons_not_targetable": [
            "TOO_SMALL"
          ],
          "created_at": "2021-10-28T22:09:29Z",
          "list_size": null,
          "updated_at": "2021-11-04T03:33:06Z",
          "deleted": false
        }
      ]
    }

POST accounts/:account_id/do_not_reach_lists

현재 계정과 연결된 새로운 Do Not Reach 리스트를 생성합니다. 참고: 하나의 account_id에는 최대 하나의 Do Not Reach 리스트만 존재할 수 있습니다. 리소스 URL https://ads-api.x.com/12/accounts/:account_id/do_not_reach_lists 매개변수

Name	Description
account_id required	활용 중인 계정의 식별자입니다. 리소스의 경로 내에 나타나며, GET accounts를 제외한 모든 Advertiser API 요청에서 일반적으로 필수 매개변수입니다. 지정된 계정은 인증된 사용자와 연결되어 있어야 합니다. Type: string Example: `18ce54d4x5t`
description optional	이 오디언스에 대한 설명입니다. Type: string Example: `A list of users to exclude`

요청 예시 POST https://ads-api.x.com/12/accounts/18ce54bgxky/do_not_reach_lists?description=A list of users to exclude 응답 예시

    {
      "request": {
        "params": {
          "description": "A list of users to exclude",
          "account_id": "18ce54bgxky"
        }
      },
      "data": {
        "targetable": false,
        "name": "Do Not Reach List",
        "description": "A list of users to exclude",
        "id": "4ofrq",
        "reasons_not_targetable": [
          "PROCESSING",
          "TOO_SMALL"
        ],
        "created_at": "2022-02-08T23:02:48Z",
        "list_size": null,
        "updated_at": "2022-02-08T23:02:48Z",
        "deleted": false
      }
    }

POST batch/accounts/:account_id/do_not_reach_lists/:do_not_reach_list_id/users

이 엔드포인트는 지정된 do_not_reach_list_id 에서 사용자를 추가, 업데이트 및 제거할 수 있도록 합니다. 이 엔드포인트는 유효한 사용자 식별자 type 으로 이메일만 허용합니다. 요청의 emails 필드에 제공되는 모든 데이터는 SHA256 으로 해시해야 하며, 정규화되어야 합니다. 참고

하나의 account_id 에는 최대 하나의 Do Not Reach List만 존재할 수 있습니다.
이 리스트에 추가된 사용자는 현재 타임스탬프 기준 13개월 미만이 되도록 expires_at 타임스탬프가 반드시 설정되어 있어야 합니다.
Do Not Reach List API는 effective_at 타임스탬프를 받지 않으며, 기본값으로 현재 타임스탬프를 사용합니다.
Do Not Reach List는 계정의 일부 또는 모든 커스텀 오디언스에서 사용자를 제거하지 않고, 계정에서 집행되는 모든 캠페인에 대해 제외 타기팅으로 작동합니다.

배치 요청

현재 이 엔드포인트에 대한 최대 배치 크기는 2500 입니다. 배치 크기는 요청당 작업(Update/Delete) 개수로 결정됩니다. 예를 들어, 하나의 배열에 2500개가 넘는 작업 객체({"operation_type": "Update/Delete", [..] })가 포함되면 오류가 발생합니다.
이 엔드포인트가 허용하는 최대 요청 POST 본문 크기는 5,000,000 바이트입니다.
이 엔드포인트에 대한 요청 한도는 1분 윈도우당 1500회입니다.
모든 파라미터는 요청 본문으로 전송되며, Content-Type 으로 application/json 이 필요합니다.
배치 요청은 그룹 단위로 함께 실패하거나 성공하며, 오류 및 성공에 대한 모든 API 응답은 초기 요청의 항목 순서를 그대로 유지합니다.

배치 응답 Ads API가 반환하는 응답에는 success_count 와 total_count 두 필드가 포함됩니다. 이 값들은 항상 같아야 하며, 백엔드에서 처리된 요청 내 레코드 수를 의미합니다. 요청 본문에 전송된 레코드 수가 success_count 및 total_count 와 같지 않은 상황은 오류 상태로 간주해야 하며, 재시도가 필요합니다. 배치 오류

요청 수준 오류(예: 최대 배치 크기 초과)는 응답의 errors 객체 아래에 표시됩니다.
항목 수준 오류(예: 필수 파라미터 누락)는 응답의 operation_errors 객체 아래에 표시됩니다.
operation_errors 내 오류의 인덱스는 입력 항목의 인덱스를 가리키며, 해당 오류 메시지와 매핑됩니다.

리소스 URL https://ads-api.x.com/12/batch/accounts/:account_id/do_not_reach_lists/:do_not_reach_list_id/users 파라미터

Name	Description
account_id required	대상 계정의 식별자입니다. 리소스 경로에 포함되며, GET accounts를 제외한 모든 Advertiser API 요청에서 일반적으로 필수 파라미터입니다. 지정된 계정은 인증된 사용자와 연결되어 있어야 합니다. Type: string Example: `18ce54d4x5t`
do_not_reach_list_id required	이 요청에서 작업을 수행하려는 Do Not Reach List에 대한 참조입니다. Type: string Example: `2906h`
operation_type required	각 `users` 그룹에 대해 수행되는 작업 type 입니다. Type: enum Possible values: `Update`, `Delete`
params required	`emails` 배열과 `expires_at` 타임스탬프를 포함하는 JSON 객체입니다. Type: JSON
users required	개별 사용자에 대한 모든 params 를 포함하는 JSON 객체 배열입니다. Type: JSON
expires_at optional	사용자 연결이 만료되어야 하는 UTC 시간입니다. 지정된 시간은 현재 타임스탬프보다 나중이어야 합니다. ISO 8601 형식으로 표현됩니다. 기본값은 현재 타임스탬프 기준 13개월 후입니다. Type: string Example: `2017-07-05T07:00:00Z`

users 객체에 여러 키를 사용하는 방식에 따라, 이 객체의 각 요소는 아래에서 개별적으로 설명됩니다:

이름	설명
email 선택 사항	사용자의 이메일 주소. Type: Array[String]
phone_number 선택 사항	사용자의 전화번호. Type: Array[String]

예시 요청

`POST https://ads-api.x.com/12/batch/accounts/18ce54bgxky/do_not_reach_lists/4kzro/users`

    [
      {
        "operation_type": "Update",
        "params": {
          "expires_at": "2023-01-22T00:00:00Z",
          "users": [
            {
              "email": [
                "FEAD76F6ADF99FFFB997AA4E3C8AD38FF531BC4C956DBD03CD0163F744D8AABC"
              ],
              "phone_number": [
                "CCABF1B62A202E0FE28BC6C014983C89A65451DD4482BD66A0ADB65366F38A9A"
              ]
            },
            {
              "email": [
                "FEAD76F6ADF99FFFB997AA4E3C8AD38FF531BC4C956DBD03CD0163F744D8AABA"
              ],
              "phone_number": [
                "CCABF1B62A202E0FE28BC6C014983C89A65451DD4482BD66A0ADB65366F38A9E"
              ]
            }
          ]
        }
      }
    ]

응답 예시

    {
      "data": [
        {
          "success_count": 2,
          "total_count": 2
        }
      ],
      "request": [
        {
          "params": {
            "do_not_reach_list_id": "4ofrq",
            "expires_at": "2023-01-22T00:00:00Z",
            "account_id": "18ce54bgxky"
          },
          "operation_type": "Update"
        }
      ]
    }

DELETE accounts/:account_id/do_not_reach_lists/:do_not_reach_list_id

현재 계정에 속한 특정 Do Not Reach 리스트를 삭제합니다. 리소스 URL https://ads-api.x.com/12/accounts/:account_id/do_not_reach_lists/:do_not_reach_list_id 매개변수 없음 요청 예시 DELETE https://ads-api.x.com/12/accounts/18ce54bgxky/do_not_reach_lists/4ofrp 응답 예시

    {
      "request": {
        "params": {
          "do_not_reach_list_id": "4ofrp",
          "account_id": "18ce54bgxky"
        }
      },
      "data": {
        "targetable": false,
        "name": "Do Not Reach List",
        "description": null,
        "id": "4ofrp",
        "reasons_not_targetable": [
          "PROCESSING",
          "TOO_SMALL"
        ],
        "created_at": "2022-02-08T23:02:07Z",
        "list_size": null,
        "updated_at": "2022-02-08T23:02:21Z",
        "deleted": true
      }
    }