타겟 오디언스

맞춤 고객

개요

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

Audience API (CRM)
Web
Mobile
Flexible

유사 타겟(Custom Audience Lookalike)은 타기팅에서 제외할 수 없습니다. 또한 동일한 광고 라인 아이템(광고 그룹)에서 커스텀 오디언스와 커스텀 오디언스 유사 타겟을 동시에 타기팅할 수 없습니다. 오디언스 관리 오디언스는 오디언스 파트너와 Ads API 파트너를 통해 관리할 수 있습니다. API에서 커스텀 오디언스에 접근하고 유지 관리할 수 있는 여러 엔드포인트를 제공합니다. 커스텀 오디언스 정보용으로 다음 2개의 엔드포인트를 제공합니다:

오디언스를 업로드하고 관리하는 방법은 Audience API 가이드와 Audience API 가이드를 참고하세요. 처리 시간 일반적으로 오디언스 변경 사항은 6~8시간 주기로 실행되는 배치로 처리됩니다. 변경 사항이 처리되는 동안 업데이트 대상인 기존 오디언스는 영향을 받지 않습니다. 이 시간 내에는 오디언스별로 추가 업데이트 1회, 제거 업데이트 1회를 넘기지 않는 것을 권장합니다. 타기팅 오디언스는 X가 소유·운영하는 클라이언트에서 지난 90일 내 활성 사용자 최소 100명과 일치하는 경우에만 타기팅할 수 있습니다. GET accounts/:account_id/custom_audiences/:custom_audience_id는 일치 사용자가 너무 적어 해당 오디언스를 타기팅할 수 없는지 여부를 표시합니다. Audience API (CRM)

오디언스 또는 API 파트너가 해시된 식별자 목록을 제공하면 X가 매칭을 수행하고, X 내 미디어 집행에 사용할 수 있는 세그먼트를 생성합니다. 파트너는 Audience API로 이러한 오디언스를 생성할 수 있습니다. 동작 방식

Web 우리는 MPP 오디언스 파트너와 협력하여 X 내 미디어 집행 타기팅에 사용할 세그먼트를 식별하기 위한 표준 쿠키 매칭 프로세스를 제공합니다. 또한 광고주는 웹사이트 사용자 데이터를 수집하고 해당 Custom Audience를 생성하기 위해 X Web Event Tag를 설정할 수 있습니다. 설정 단계

동작 방식

Mobile 자세한 내용은 Custom Audiences from Mobile Apps 블로그 게시물을 참조하세요. Flexible Flexible audiences는 광고주가 기존 커스텀 오디언스 또는 그 하위 집합을 기반으로 오디언스 조합을 구성하고 저장할 수 있도록 합니다. 커스텀 오디언스 구성원의 하위 집합은 상호작용의 최신성과 빈도에 따라 타기팅할 수 있습니다. Custom Audiences의 제한된 사용 사례 제한 사항 자세히 보기

오디언스 FAQ

Q: 대량의 데이터를 전송했는데, 오디언스 크기가 왜 TOO_SMALL로 표시되나요? A: 현재 데이터는 실시간으로 오디언스에 추가되지만, 오디언스 크기를 계산하는 처리는 일정 시간이 지난 후에만 실행됩니다. 정확한 오디언스 크기는 몇 시간 후 UI에 표시됩니다. Q: 오디언스 데이터를 전송하고 24시간 이상 기다렸지만 여전히 해당 오디언스를 타게팅할 수 없습니다. 다음 단계로 무엇을 해야 하나요? A: 다음 항목을 확인해 주세요:

전달되는 사용자 ID가 올바르고 형식 오류가 없는지
전달되는 오디언스 이름이 올바르며 이전 멤버십 업데이트와 일치하는지
POST 명령의 응답을 확인했는지
ID Sync 픽셀이 올바르게 구현되었는지, 그리고 ID Sync 프로세스에 따라 해당 사이트에 충분한 사용자가 방문해 매핑이 이뤄졌는지. 멤버십 업데이트에 포함된 미매핑 사용자는 타게팅 가능한 사용자로 전환되지 않습니다.

위 모든 항목이 정상임이 확인되면, 가능한 한 자세한 정보를 포함해 X 제품 담당자에게 문의해 주세요(선호 정보 예시는 Guide to Partner Inbounds를 참고). Q: 엔드포인트는 얼마나 자주 호출할 수 있으며, 어떤 알고리즘을 사용해야 하나요? A: 전체 오디언스 멤버십을 재전송하지 말고, 증분 델타 방식으로 시스템을 호출할 것을 강력히 권장합니다. 이 시스템은 세계 최대 규모 웹사이트의 증분 데이터 업데이트를 처리할 수 있도록 충분한 처리량으로 검증되었습니다. 초기 오디언스 업로드는 신중하게 스로틀링해야 하며, 최초 업로드 완료까지 상당한 시간이 걸릴 수 있습니다. Q: 타게팅에 사용할 수 있는 오디언스의 최소 크기는 얼마인가요?

오디언스의 최소 크기는 100명(매칭 후)입니다. 500명 미만으로 매칭된 오디언스는 X Ads UI에서 타게팅에 사용할 수 없습니다.

Q: 오디언스 파일 처리에는 얼마나 걸리며, X 사용자 인터페이스에서 사용 가능해지기까지 얼마나 걸리나요?

일반적으로 오디언스 파일 처리에는 4–6시간이 소요되지만 파일 크기에 따라 달라질 수 있습니다. 파일 처리 후 오디언스는 X Ads UI에서 사용 가능합니다.

Q: 매칭률은 어떻게 계산되나요?

매칭률 = 최근 90일 활성 X 사용자 수 / 제공된 사용자 수

Q: 오디언스 파일이 정상적으로 작동하는지 어떻게 테스트하나요?

테스트 오디언스 파일을 제공하고 광고주 핸들로 “keltonlynn”을 사용할 수 있습니다. 그러면 파일이 X UI에 정상적으로 수집·로드되는지 확인할 수 있습니다.

Q: 파트너 사용자 식별자(p_user_id)란 무엇인가요?

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

Q: 표준 ID란 무엇인가요?

이메일 주소, 디바이스 ID, X @handle 또는 ID일 수 있습니다.

Q: HMAC 키는 어떻게 받나요?

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

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

X에서 테스트 파일(샘플 이메일 주소, 디바이스 ID 등)과 결과 해시 파일을 제공하므로, 이를 기준으로 결과를 검증할 수 있습니다.

Q: 전체 데이터 매칭 파일에 파일 크기 제한이 있나요?

아니요, 전체 데이터 매칭 파일에는 크기 제한이 없습니다.

Q: 전체 데이터 매칭 파일은 처리하는 데 얼마나 걸리나요?

X가 파일을 수신한 시점부터 처리까지 대략 1일이 소요됩니다.

CRM

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

파트너 ID 매칭 요건

회사가 자체 표준 ID 시스템(즉, 이메일 주소, 디바이스 id, X 사용자 ID 등과 같은 일반 사용자 식별자가 아닌 방식)으로 사용자를 추적하는 경우, 아래 프로세스를 권장합니다. 1. 전체 데이터 매칭 초기에 Company는 X와 공통 사용자 식별자 중 하나의 고유 값을 포함한 모든 사용자 레코드의 포괄적 목록을 단일 파일로 제공하여 전체 데이터 매칭을 수행하고, 파트너 ID(p_user_id)를 X ID(tw_id)에 매핑한 결과를 X가 보관합니다. 이는 적절한 유지 관리를 위해 2~3개월 주기로 정기적으로 수행됩니다. 매칭이 완료되면 X는 해당 파일 기준의 초기 매칭율을 이메일로 Company에 공유합니다. 이 파일의 형식은 다음과 같습니다: 명명 규칙: FullDataMatch.[CompanyName].txt 해싱 알고리즘: HMAC_SHA-256 형식: 열 1: 공통 식별자의 HMAC 해시 값 열 2: 파트너 사용자 ID(사용자별 고유, 파일 내에서는 비고유) 열 구분자(CSV): 쉼표를 사용해 해시된 공통 사용자 식별자와 파트너 ID를 구분 줄 단위 값

예: 사용자 레코드 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

*아래 ‘해싱 지침’ 섹션에서 공통 사용자 식별자를 참고하세요. 2. 커스텀 세그먼트 목록 Company는 X에서 타깃팅을 위한 고객 커스텀 오디언스를 생성하기 위해 p_user_id 형태의 사용자 목록을 제공합니다.

줄 단위 값
p_user_id
- (위의 1. 전체 데이터 매칭 섹션과 동일합니다. 전체 데이터 매칭에서 제공한 값이 해시된 값이라면, 오디언스 파일에도 동일한 해시 값을 제공합니다. 해시되지 않은 값을 제공했다면, 오디언스 파일에도 해시되지 않은 값을 제공합니다.)

표준 매칭 요건

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

줄바꿈으로 구분된 값
해시된 공통 사용자 식별자(예: 이메일 주소)
아래에 제시된 파일 명명 규칙 준수
아래의 이메일 주소 해싱 지침(해싱 지침) 준수

커스텀 세그먼트 목록 파일 명명 규칙 및 작업

파일의 동작은 파일 이름에 의해 결정되며, 사용 가능한 작업과 일반적인 파일 명명 규칙은 다음과 같습니다: 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 추가 - 목록에서 일치 항목을 기존 오디언스에 추가합니다. 예: loyalty_card_holders_partnername.pepsi.add..txt 제거 - 목록에서 일치 항목을 기존 오디언스에서 제거합니다. 예: loyalty_card_holders_partnername.pepsi.remove..txt 전체 제거 - 정기적으로 업데이트되는 누적 목록에서 생성된 일치 항목을 해당 클라이언트의 모든 오디언스에서 제거합니다(즉, 클라이언트의 옵트아웃 목록). 예: partnername.pepsi.removeall.txt

이는 광고주로부터 옵트아웃한 사용자들의 포괄적 목록에 사용할 수 있습니다.
X는 이 파일에 제공된 최신 목록만을 반영하며, 해당 목록과 일치하는 기존 및 향후 모든 오디언스에 적용합니다.

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

해싱 지침

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

이메일 정규화

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

디바이스 ID 정규화

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

X 사용자 ID 정규화

X ID는 데이터 그룹화(예: 광고주의 고객 목록에 있는 @handles)가 PII는 아니더라도 광고주 전용의 비공개 데이터이므로 계속 해시 처리합니다. 데이터 파트너에게 제공하는 공통 솔트와 SHA-256 해싱 알고리즘을 사용하여 X ID를 해시해야 한다는 요구 사항은 동일합니다. X ID와 @username 모두에서 공백은 제거해야 하지만, User ID는 별도의 정규화가 필요하지 않습니다. @username은 정규화를 위해 소문자로 변환해야 하며, @ 기호는 username에 포함하지 않습니다. 원시 ID 형식은 다음과 같습니다:

User ID: 27674040
@username: testusername

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

ID Sync 통합

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">
    style="display:none"
    </pre>

옵트아웃 파일 구성 및 옵트아웃 파일 전송 파트너는 타깃 광고 제공에서 옵트아웃을 선택한 사용자 목록을, 파트너가 아는 한 최선의 판단에 따라 X에 제공해야 합니다. 파일 형식은 다음과 같습니다:


열 번호	열 이름	열 유형	설명
1	Partner ID	string	“partner id”는 각 파트너를 고유하게 식별하기 위해 X가 파트너에게 제공하는 ID입니다.
2	파트너 시스템에서 사용자의 id	string	`p_user_id`는 파트너가 사용자를 식별하는 데 사용하는 고유 ID입니다. 이 옵트아웃 사용자를 포함한 파일은 TON upload 엔드포인트를 사용해 업로드해야 하며, 업로드된 데이터의 경로는 다음의 Global Opt Out 엔드포인트로 전송해야 합니다: PUT accounts/:account_id/custom_audiences/global_opt_out.

멤버십 업데이트 전송 엔드포인트 문서에 명시된 대로, POST custom_audience_memberships 엔드포인트로 사용자를 전송할 때는 쿠키 기반 매칭을 활성화하기 위해 고객 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

# Python에서 @AdsAPI 사용자 해싱
import hashlib
hashlib.sha256("adsapi".encode()).hexdigest()

# 출력
49e0be2aeccfb51a8dee4c945c8a70a9ac500cf6f5cb08112575f74db9b1470d

해싱 추가 코드 샘플은 github.com/xdevplatform/ads-platform-tools에서 확인할 수 있습니다.

커스텀 오디언스: 웹

정보 파트너는 광고주를 대신해 타기팅을 위한 ID 목록(p_user_ids)을 전송합니다. 이는 p_user_ids와 X 사용자 ID 간의 매핑을 구축하는 ID 동기화 프로세스를 통해 이뤄집니다. 이 매핑을 바탕으로 타기팅에 사용할 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 엔드포인트 및 타기팅 사용자 파일 파트너는 타기팅 파일을 정기적으로 수집할 수 있도록 X에 HTTPS 엔드포인트와 자격 증명(사용자 이름/비밀번호)을 제공해야 합니다. 예시 HTTPS 엔드포인트는 다음과 같습니다:

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

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

파트너 타기팅 사용자 파일
타기팅 전환 파일

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

199.16.156.0/22
199.59.148.0/22

파트너 타기팅 사용자 파일:

열 번호	열 이름	열 유형	설명
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”는 선택 사항입니다. 권장 범위는 0–100입니다. 리타기팅 사용 사례의 경우 “100”은 직접 리타기팅된 사용자를 의미합니다. 0–99 점수는 유사 타기팅 대상에 대한 신뢰 수준을 나타냅니다.
4	segment label	string	“segment label”은 선택 사항입니다. 파트너는 예를 들어 제품 카테고리를 지정하기 위해 “segment label”을 사용할 수 있습니다. 이는 ads.x.com UI에서 커스텀 오디언스의 사람이 읽을 수 있는 이름이므로 해당 “segment label” 사용을 권장합니다.

참고: 새 파트너 타기팅 파일을 받을 때마다, 별도 합의가 없는 한, 이는 증분이 아닌 파트너가 타기팅을 권장하는 사용자 전체 목록이어야 합니다. 이 파트너 타기팅 파일의 제공 빈도는 각 파트너와 합의합니다. 예상된 파트너 타기팅 파일을 받지 못한 경우, 사전에 정의된 만료 시간과 함께 이전 버전을 사용합니다.

오디언스 API 통합

개요

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

사용 중단 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
사용 중단 실시간 Audiences:
- POST custom_audience_memberships
Custom Audience:
- 모든 Custom Audience 엔드포인트의 요청 및 응답에서 list_type 매개변수가 제거됩니다. 이 매개변수는 이전에 Audience의 사용자 식별자 유형(예: 이메일, X 사용자 ID 등)을 식별하는 데 사용되었으나, 이제 Audiences는 동일한 Audience에 대해 여러 사용자 식별자를 수용할 수 있어 이 값이 불필요합니다.
일반:
- Audience 조회 기간(lookback window)은 과거 30일에서 90일 이내에 활동한 사용자와 매칭되도록 업데이트되었습니다.
- 타기팅 가능하도록 요구되는 일치 사용자 최소 수는 500명에서 100명으로 감소했습니다。

사전 준비 사항

Ads API 액세스
Audience 엔드포인트에 액세스하려면 allowlist에 추가되어야 합니다. 이 양식을 작성하고, 2018-08-01 이전에 최초 승인을 받은 경우 새로운 X Ads Products and Services Agreement에 동의해 주세요.

Audience 업로드 프로세스 다음 표는 이전 및 새로운 Audience 생성 흐름 간의 주요 차이점을 나열하며, 아래에 추가 세부 정보를 제공합니다:

프로세스 단계	Audience API	(사용 중단) TON 업로드
셸 Audience 생성	POST custom_audience endpoint 를 통해 생성 가능	POST custom_audience endpoint 를 통해 생성 가능
새 사용자 추가	Audience endpoint에서 `operation_type` `Update` 사용	POST custom_audience_changes 엔드포인트에서 `operation` `ADD` 사용
사용자 제거	Audience endpoint에서 `operation_type` `Delete` 사용	POST custom_audience_changes 엔드포인트에서 `operation` `REMOVE` 사용
사용자 옵트아웃	사용자가 속한 해당 `custom_audience_id`들과 함께 Audience endpoint에서 `operation_type` `Delete` 사용	Global opt-out endpoint 사용

참고 TON 업로드 경로를 통해 업데이트되거나 옵트아웃되는 모든 audience는 TON Upload 엔드포인트를 통해 해당 목록이 업로드되어야 하며, custom_audience_changes 엔드포인트를 사용해 Audience와 연결되어야 합니다. Rate Limiting Audience API 엔드포인트의 레이트 리밋은 계정당 1분에 1500건입니다. 단일 페이로드에 보낼 수 있는 사용자 수에는 제한이 없습니다. 페이로드 제약은 다음과 같습니다:

총 작업 수: 2,500건
최대 페이로드 크기: 5,000,000바이트

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

새로운 커스텀 오디언스 생성

[POST custom_audience]/x-ads-api/audiences 엔드포인트를 사용해 새 커스텀 오디언스 “셸”을 만들고, 해당 커스텀 오디언스 id를 조회하세요. 오디언스를 처음부터 생성하는 경우 이 단계가 필요합니다. 기존 오디언스를 업데이트하는 경우 다음 섹션으로 넘어가세요.

오디언스에 사용자 추가

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 또는 둘 다로 제거할 수 있습니다. 또한 동일한 요청에서 오디언스에 사용자를 추가하고 제거하는 것도 가능합니다. 이 엔드포인트는 요청당 여러 개의 operation_type를 지원합니다.

옵트아웃 사용자

글로벌 옵트아웃 엔드포인트가 사용 중단됨에 따라 파트너는 어떤 Audiences에서든 옵트아웃한 사용자를 Delete해야 합니다. 이를 수행하는 방법은 다음과 같습니다:

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

일반 모범 사례

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

API 참고서

키워드 인사이트

GET insights/keywords/search

키워드 그룹이 주어지면 해당 키워드의 트윗량과 함께 관련 키워드 30개 세트를 반환합니다. 트윗량은 입력된 키워드에만 해당하며, 관련 키워드에는 적용되지 않습니다. 허용되는 최대 시간 범위(end_time - start_time)는 7일입니다. 결과는 단일 지역(국가) 범위로 제한됩니다. 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 엔드포인트에서 가져오는 타기팅 값입니다. 현재는 국가 수준 위치만 지원됩니다. 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

지정한 오디언스를 특정 계정과 공유할 수 있도록 하는 새 권한 객체를 생성합니다. 참고: 맞춤형 오디언스의 권한을 생성하거나 수정하려면 해당 오디언스가 권한을 수정하려는 계정 소유여야 합니다. 특정 오디언스 응답의 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의 권한을 생성하거나 수정하려면 해당 오디언스가 권한을 변경하려는 계정의 소유여야 합니다. 특정 오디언스의 응답에서 is_owner 속성을 확인해 Tailored Audience의 소유 여부를 확인할 수 있습니다. 권한이 해제되면 부여된 계정(granted_account_id)은 향후 캠페인에서 해당 오디언스를 타깃팅할 수 없도록 보장됩니다. 기존 캠페인은 공유된 오디언스로 계속 진행되며, 캠페인이 중단되거나 캠페인에서 오디언스가 제거되지 않습니다. 오디언스 공유 권한이 해제된 후에는 이 캠페인을 복사할 수 없습니다. Resource URL

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

Parameters

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`

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

    {
      "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`

예시 요청 GET https://ads-api.x.com/12/accounts/18ce54d4x5t/custom_audiences/2906h/targeted 예시 응답

    {
      "request": {
        "params": {
          "account_id": "18ce54d4x5t",
          "custom_audience_id": "2906h",
        }
      },
      "next_cursor": null,
      "data": [
        {
          "campaign_id": "59hod",
          "campaign_name": "테스트 캠페인",
          "line_items": [
            {
              "id": "5gzog",
              "name": "테스트 라인 아이템",
              "servable": true
            }
          ]
        },
        {
          "campaign_id": "arja7",
          "campaign_name": "제목 없는 캠페인",
          "line_items": [
            {
              "id": "bjw1q",
              "name": null,
              "servable": true
            }
          ]
        }
      ]
    }

커스텀 오디언스 사용자

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이어야 합니다.
배치 요청은 그룹 단위로 함께 성공하거나 함께 실패하며, 성공/오류 응답 모두 초기 요청의 항목 순서를 유지합니다.

배치 응답 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	개별 사용자에 대한 모든 매개변수를 담은 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 필수	활용되는 계정의 식별자입니다. 리소스 경로에 포함되며, 일반적으로 GET accounts를 제외한 모든 Advertiser API 요청에 필요한 매개변수입니다. 지정된 계정은 인증된 사용자와 연결되어 있어야 합니다. 유형: string 예시: `18ce54d4x5t`
custom_audience_id 필수	요청에서 작업 중인 커스텀 오디언스를 참조합니다. 유형: string 예시: `1nmth`
count 선택	각 요청당 조회할 레코드 수를 지정합니다. 유형: int 기본값: `200` 최소, 최대: `1`, `1000`
cursor 선택	다음 페이지 결과를 가져오기 위한 커서를 지정합니다. 자세한 내용은 Pagination을 참조하세요. 유형: string 예시: `8x7v00oow`
granted_account_ids 선택	쉼표로 구분된 식별자 목록을 지정하여 응답을 원하는 계정으로만 제한합니다. 최대 200개의 ID를 제공할 수 있습니다. 유형: string 예시: `18ce54aymz3`
sort_by 선택	지원되는 속성으로 오름차순 또는 내림차순 정렬합니다. 자세한 내용은 Sorting을 참조하세요. 유형: string 예시: `created_at-asc`
custom_audience_permission_ids 선택	쉼표로 구분된 식별자 목록을 지정하여 응답을 원하는 커스텀 오디언스 권한으로만 제한합니다. 최대 200개의 ID를 제공할 수 있습니다. 유형: string 예시: `ri`
with_total_count 선택	`total_count` 응답 속성을 포함합니다. 참고: 이 매개변수와 `cursor`는 상호 배타적입니다. 참고: `total_count`를 포함하는 요청은 더 낮은 요청 한도가 적용되며, 현재 15분당 200건으로 설정되어 있습니다. 유형: boolean 기본값: `false` 가능한 값: `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의 권한을 생성하거나 수정하려면 해당 오디언스가 권한을 수정하려는 계정의 소유여야 합니다. 특정 오디언스의 응답에서 is_owner 응답 속성을 확인하여 Custom Audience의 소유 여부를 확인할 수 있습니다. 권한이 취소되면 부여된 계정(granted_account_id)은 향후 캠페인에서 해당 오디언스를 타깃팅할 수 없도록 보장됩니다. 기존 캠페인은 공유된 오디언스로 계속 진행됩니다. 캠페인은 중단되지 않으며 오디언스가 캠페인에서 제거되지도 않습니다. 오디언스 공유 권한이 취소된 후에는 이 캠페인을 복사할 수 없습니다. Resource URL

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

Parameters

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`

Example Request DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/custom_audiences/1nmth/permissions/ri Example Response

    {
      "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	다음 페이지 결과를 가져오기 위한 커서를 지정합니다. 자세한 내용은 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",
          "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

현재 계정과 연결된 새 플레이스홀더 커스텀 오디언스를 생성합니다. 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`
name required	이 오디언스의 표시 이름입니다. 고유한 이름 값을 사용해야 하며, 그렇지 않으면 오류가 발생합니다. Type: string Example: `ads api users`
description optional	이 오디언스에 대한 설명입니다. Type: string Example: `Collection of all users of the Ads API`

Example Request POST https://ads-api.x.com/12/accounts/18ce54d4x5t/custom_audiences?name=developers 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": [
          "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	이 오디언스의 표시 이름입니다. 고유한 이름 값을 사용해야 하며, 그렇지 않으면 오류가 발생합니다. Type: string Example: `ads api users`
description optional	이 오디언스의 설명입니다. 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를 일괄 생성할 수 있습니다. 오디언스에 대한 정보는 Custom Audiences 개요 페이지를 참조하세요. 참고: 이 배치 엔드포인트는 현재 클로즈드 베타로, 일부 광고주에게만 제공됩니다. 베타 기간 동안에는 모바일 커스텀 오디언스를 기반으로 한 Flexible Audiences만 생성할 수 있습니다. 배치 요청

현재 최대 배치 크기는 10입니다.
모든 매개변수는 요청 본문으로 전송되며 Content-Type은 application/json이어야 합니다.
배치 요청은 그룹 단위로 함께 실패하거나 함께 성공하며, 오류와 성공을 포함한 모든 API 응답은 초기 요청의 항목 순서를 유지합니다.

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

요청 수준 오류(예: 최대 배치 크기 초과)는 응답의 errors 오브젝트에 표시됩니다.
항목 수준 오류(예: 필수 매개변수 누락)는 응답의 operation_errors 오브젝트에 표시됩니다.

Flexible Audiences

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

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: 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	오디언스의 표시 이름입니다. 고유한 이름을 사용해야 하며, 그렇지 않으면 오류가 발생합니다. Type: string Example: `my_flexible_audience_name`
operation_type required	항목별로 수행되는 작업 유형입니다. Type: enum Possible values: `Create`, `Update`, `Delete`
boolean_operator sometimes required	상위(포함) 객체 내 자식 세그먼트 간의 논리 연산입니다. 상위 객체의 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`는 크거나 같음을, `LT`는 작음을 의미합니다. 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`

Example Request 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": "개발자",
        "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가 최대 1개만 있을 수 있습니다. 리소스 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": "도달 금지 목록",
          "description": "테스트 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 List를 생성합니다. 참고: 하나의 account_id에는 Do Not Reach List가 최대 한 개만 존재할 수 있습니다 Resource URL https://ads-api.x.com/12/accounts/:account_id/do_not_reach_lists Parameters

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

Example Request POST https://ads-api.x.com/12/accounts/18ce54bgxky/do_not_reach_lists?description=A list of users to exclude Example Response

    {
      "request": {
        "params": {
          "description": "제외할 사용자 목록",
          "account_id": "18ce54bgxky"
        }
      },
      "data": {
        "targetable": false,
        "name": "도달 금지 목록",
        "description": "제외할 사용자 목록",
        "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에 사용자 추가, 업데이트, 제거를 수행할 수 있게 해줍니다. 유효한 사용자 식별자 유형으로는 이메일만 허용합니다. 요청의 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: enum Possible values: `Update`, `Delete`
params required	`emails` 배열과 `expires_at` 타임스탬프를 포함하는 JSON 오브젝트입니다. Type: JSON
users required	개별 사용자에 대한 모든 매개변수를 포함하는 JSON 오브젝트의 배열입니다. Type: JSON
expires_at optional	사용자 연관이 만료되어야 하는 UTC 시간입니다. 지정된 시간은 현재 타임스탬프 값보다 이후여야 합니다. ISO 8601로 표현됩니다. 기본값은 현재 타임스탬프로부터 13개월입니다. Type: string Example: `2017-07-05T07:00:00Z`

users 오브젝트의 다중 키 접근 방식에 따라, 이 오브젝트의 각 요소는 아래에 문서화되어 있습니다:

이름	설명
email 선택 사항	사용자 이메일 주소. 유형: Array[String]
phone_number 선택 사항	사용자 전화번호 유형: 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": "도달 금지 목록",
        "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
      }
    }

X Ads API

기본

자료

측정

​맞춤 고객

​개요

​오디언스 FAQ

​CRM

​파트너 ID 매칭 요건

​표준 매칭 요건

​커스텀 세그먼트 목록 파일 명명 규칙 및 작업

​오디언스 생성 및 업데이트

​해싱 지침

​이메일 정규화

​디바이스 ID 정규화

​X 사용자 ID 정규화

​ID Sync 통합

​픽셀 URL

​픽셀 매개변수

​ID 동기화 픽셀:

​커스텀 오디언스 사용자 데이터

​커스텀 오디언스: 웹

​오디언스 API 통합

​개요

​새로운 커스텀 오디언스 생성

​오디언스에 사용자 추가

​오디언스에서 사용자 제거

​옵트아웃 사용자

​API 참고서

​키워드 인사이트

​GET insights/keywords/search

​맞춤 오디언스 권한

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

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

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

​타깃 오디언스

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

​커스텀 오디언스 사용자

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

​리소스 URL

​매개변수

​예시 요청

​예시 응답

​커스텀 오디언스 권한

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

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

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

​맞춤 오디언스

​GET accounts/:account_id/custom_audiences

​GET accounts/:account_id/custom_audiences/:custom_audience_id

​POST accounts/:account_id/custom_audiences

​PUT accounts/:account_id/custom_audiences/:custom_audience_id

​POST batch/accounts/:account_id/custom_audiences

​DELETE accounts/:account_id/custom_audiences/:custom_audience_id

​접촉 금지 목록

​GET accounts/:account_id/do_not_reach_lists

​POST accounts/:account_id/do_not_reach_lists

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

​DELETE accounts/:account_id/do_not_reach_lists/:do_not_reach_list_id

맞춤 고객

개요

오디언스 FAQ

CRM

파트너 ID 매칭 요건

표준 매칭 요건

커스텀 세그먼트 목록 파일 명명 규칙 및 작업

오디언스 생성 및 업데이트

해싱 지침

이메일 정규화

디바이스 ID 정규화

X 사용자 ID 정규화

ID Sync 통합

픽셀 URL

픽셀 매개변수

ID 동기화 픽셀:

커스텀 오디언스 사용자 데이터

커스텀 오디언스: 웹

오디언스 API 통합

개요

새로운 커스텀 오디언스 생성

오디언스에 사용자 추가

오디언스에서 사용자 제거

옵트아웃 사용자

API 참고서

키워드 인사이트

GET insights/keywords/search

맞춤 오디언스 권한

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

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

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

타깃 오디언스

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

커스텀 오디언스 사용자

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

리소스 URL

매개변수

예시 요청

예시 응답

커스텀 오디언스 권한

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

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

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

맞춤 오디언스

GET accounts/:account_id/custom_audiences

GET accounts/:account_id/custom_audiences/:custom_audience_id

POST accounts/:account_id/custom_audiences

PUT accounts/:account_id/custom_audiences/:custom_audience_id

POST batch/accounts/:account_id/custom_audiences

DELETE accounts/:account_id/custom_audiences/:custom_audience_id

접촉 금지 목록

GET accounts/:account_id/do_not_reach_lists

POST accounts/:account_id/do_not_reach_lists

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

DELETE accounts/:account_id/do_not_reach_lists/:do_not_reach_list_id