> ## Documentation Index
> Fetch the complete documentation index at: https://generaltranslation.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# 잠재고객
export const Button = ({href, children}) => {
return
;
};
## 맞춤 잠재고객
### Overview
파트너가 [Custom Audiences](https://business.x.com/en/targeting/tailored-audiences.html)를 생성하는 방법은 여러 가지가 있습니다.
* [Audience API (CRM)](#crm)
* [Web](#web)
* [Mobile](#mobile)
* [Flexible](#flexible)
룩얼라이크 Custom Audience는 타기팅에서 제외할 수 없습니다. 또한 동일한 광고 라인 아이템(광고 그룹)에서 하나의 custom audience와 그 custom audience의 룩얼라이크를 동시에 타기팅할 수 없습니다.
**Audience management**
잠재고객은 audience 파트너 및 Ads API 파트너를 통해 관리할 수 있습니다. API에서는 custom audiences에 액세스하고 이를 유지 관리하기 위한 여러 엔드포인트를 제공합니다.
custom audience 정보에 대해서는 다음 2개의 엔드포인트를 제공합니다.
* [GET accounts/:account\_id/custom\_audiences](/ko/x-ads-api/audiences)
* [GET accounts/:account\_id/custom\_audiences/:custom\_audience\_id](/ko/x-ads-api/audiences)
잠재고객 업로드 및 관리 방법에 대한 자세한 내용은 [Audience API guide](/ko/x-ads-api/audiences)를 참조하세요.
**Processing Times**
일반적으로 잠재고객 변경 사항은 6\~8시간마다 실행되는 배치로 처리됩니다. 잠재고객 변경 사항이 처리되는 동안 업데이트 대상이 되는 기존 잠재고객에는 영향을 주지 않습니다. 이 기간 내에 잠재고객별로 추가는 한 번, 제거는 한 번만 업데이트할 것을 권장합니다.
**Targeting**
잠재고객은 X가 소유 및 운영하는 클라이언트에서 지난 90일 동안 활성 상태였던 사용자 최소 100명과 일치하는 경우에만 타기팅할 수 있습니다. [GET accounts/:account\_id/custom\_audiences/:custom\_audience\_id](/ko/x-ads-api/audiences)는 잠재고객이 일치하는 사용자가 너무 적어 타기팅할 수 없는 경우 이를 표시합니다.
**Audience API (CRM)**
Audience 또는 API 파트너가 해시된 식별자 목록을 제공하면, X가 이를 매칭하여 X에서 미디어 구매에 사용할 수 있는 세그먼트를 생성합니다. 파트너는 [Audience API](/ko/x-ads-api/audiences)를 사용해 이러한 잠재고객을 생성할 수 있습니다.
**How it works?**
**Web**
X에서의 미디어 구매를 위해 타기팅할 세그먼트를 식별하기 위해 MPP audience 파트너와 협력할 때 표준 쿠키 매칭 프로세스를 제공합니다. 추가로, 광고주는 웹사이트 사용자 데이터를 수집하고 해당 Custom Audience를 생성하기 위해 [X Web Event Tag](/ko/x-ads-api/measurement/web-conversions#web-event-tags)를 설정할 수 있습니다.
**Setup Steps**
![]()
**How it works?**
**Mobile**
자세한 내용은 [the Custom Audiences from Mobile Apps blog post](https://blog.x.com/2014/introducing-tailored-audiences-from-mobile-apps)를 참조하세요.
**Flexible**
[Flexible audiences](/ko/x-ads-api/audiences)는 기존 custom audiences 또는 기존 custom audiences의 하위 집합을 기반으로 잠재고객 조합을 생성하고 저장할 수 있는 기능을 광고주에게 제공합니다. custom audience 구성원의 하위 집합은 상호작용의 최신성(recency)과 빈도(frequency)에 따라 타기팅할 수 있습니다.
**Restricted Use Cases for Custome Audiences**
[제한 사항에 대해 자세히 알아보기](https://developer.x.com/en/developer-terms/more-on-restricted-use-cases "Read more about restrictions")
### Audiences FAQ[](#real-time-tailored-audiences "이 제목으로 고유 링크")
**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](/ko/x-ads-api/introduction)를 참고하세요).
**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](mailto: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)의](http://www.golockbox.com\)의) 보안 패키지(secure package)를 사용하여 X에 제공됩니다. X는 IronBox에 대한 접근 권한을 제공합니다. IronBox API에 대한 문서는 [https://secure.goironcloud.com/Docs/Help/](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](/ko/x-ads-api/audiences#crm) 페이지에 설명된 방법 중 하나를 사용하여 진행할 수 있습니다.
| | |
| :---------- | :---------------- |
| **매개변수** | **설명** |
| `p_id` | X에서 부여한 파트너 id |
| `p_user_id` | 파트너 시스템에서의 사용자 id |
#### ID 동기화 픽셀:
예시 파트너 id 값이 111이고, 예시 `p_user_id` 값이 abc인 경우, 구성되는 픽셀은 다음과 같습니다:
```json theme={null}
```
**옵트아웃 파일 구성 및 옵트아웃 파일 전송**
파트너는 타기팅 광고 제공을 받지 않도록 옵트아웃을 선택한 사용자에 대해, 파트너가 파악하고 있는 한도 내에서의 사용자 목록을 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](/ko/x-ads-api/audiences) 엔드포인트를 사용해 업로드해야 하며, 업로드된 데이터의 경로는 여기의 Global Opt Out 엔드포인트로 전송해야 합니다: [PUT accounts/:account\_id/custom\_audiences/global\_opt\_out](/ko/x-ads-api/audiences). |
**멤버십 업데이트 전송**
엔드포인트 문서에 명시된 대로, [POST custom\_audience\_memberships](/ko/x-ads-api/audiences) 엔드포인트를 통해 사용자를 전달할 때는 쿠키 기반 매칭을 활성화하기 위해 customer ID를 전달해야 합니다. `p_id`로 데이터를 전송하는 파트너는 반드시 `user_identifier_type`을 `TALIST_PARTNER_USER_ID` 또는 `TAWEB_PARTNER_USER_ID`로 설정해야 합니다.
그 외 모든 단계는 [Real-Time Audience API Integration Guide](/ko/x-ads-api/audiences)에 나열된 내용과 동일하게 유지됩니다.
### 맞춤 잠재고객 사용자 데이터
이 문서는 \[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](https://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](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:///twitter/partner_targeting_%Y-%M-%D.tsv.gz
```
%Y - 연도 형식 코드 (YYYY)
%M - 월 형식 코드 (MM)
%D - 일 형식 코드 (DD)
전송되는 데이터는 다음 파일들로 구성됩니다.
1. Partner Targeting User File
2. 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](/ko/x-ads-api/introduction) 의 일부로 출시되었으며, 이를 통해 기존 Audiences 엔드포인트에 여러 가지 개선 사항을 제공합니다. 이 새로운 엔드포인트는 새로운 Audience 처리 백엔드에 의해 지원되며, 안정성, 견고성, 신뢰성 측면에서 여러 개선을 제공합니다. 이 가이드의 목적은 Audience API와 기존 Audience 업로드 및 관리 프로세스 간의 차이점을 설명하는 것입니다.
참고 문서는 [Audience API](/ko/x-ads-api/audiences) 레퍼런스 문서 페이지에서 확인할 수 있습니다.
**Note**: 업로드 전에 모든 Audience 사용자 데이터는 SHA-256으로 해시 처리되어야 합니다. 허용되는 사용자 식별자 type 및 데이터 정규화에 대한 자세한 내용은 [user data](/ko/x-ads-api/audiences) 페이지에서 확인할 수 있습니다.
**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](/ko/x-ads-api/audiences) 엔드포인트의 요청과 응답에서 `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](/ko/x-ads-api/introduction)를 수락해야 합니다.
**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](/ko/x-ads-api/audiences)에서 `operation_type` `Update` 사용 | [POST custom\_audience\_changes](/ko/x-ads-api/audiences) 엔드포인트에서 `operation` `ADD` 사용 |
| 사용자 제거 | [Audience endpoint](/ko/x-ads-api/audiences)에서 `operation_type` `Delete` 사용 | [POST custom\_audience\_changes](/ko/x-ads-api/audiences) 엔드포인트에서 `operation` `REMOVE` 사용 |
| 사용자 옵트아웃 처리 | [Audience endpoint](/ko/x-ads-api/audiences)에서 `operation_type` `Delete`와 사용자가 속해 있는 해당 `custom_audience_id` 사용 | [Global opt-out endpoint](/ko/x-ads-api/audiences) 사용 |
**Note** TON 업로드 경로를 통해 업데이트되거나 옵트아웃 처리되는 모든 Audience는 [TON Upload](/ko/x-ads-api/audiences) 엔드포인트를 통해 업로드된 해당 리스트가 있어야 하며, [custom\_audience\_changes](/ko/x-ads-api/audiences) 엔드포인트를 사용해 Audience와 연계되어야 합니다.
**Rate Limiting**
Audience API 엔드포인트의 rate limit은 계정당 1분에 1500회입니다. 단일 페이로드에 포함할 수 있는 사용자 수에는 제한이 없습니다. 페이로드에 대한 제약은 다음과 같습니다:
1. 전체 작업 수: 최대 2,500개
2. 최대 페이로드 크기: 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](/ko/x-ads-api/audiences) 엔드포인트를 호출합니다.
POST [https://ads-api.x.com/11/accounts/18ce54d4x5t/custom\_audiences/1nmth/users](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](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` 해야 합니다. 이를 수행하는 방법은 다음과 같습니다:
1. 어떤 사용자가 어떤 Audience에 속해 있는지 추적하고, 각 Audience에서 해당 사용자를 개별적으로 제거합니다.
2. Ads 계정과 연결된 **모든** Audience에서 해당 사용자를 제거합니다.
**일반적인 모범 사례**
* 큐가 짧은 시간에 급격히 증가해 처리 시간이 길어지고 전반적으로 시스템에 불필요한 부하가 걸리는 것을 피하기 위해, 이 엔드포인트는 실시간에 가까운 배치(near real-time batches)로 호출할 것을 강력히 권장합니다. 이렇게 하면 사용자를 캠페인 타기팅에 더 빨리 활용할 수 있습니다.
* 성공적인 API 호출은 요청에서 전달된 `user` 객체 수에 해당하는 `success_count` 와 `total_count` 를 반환합니다.
* 이 엔드포인트는 원자적(atomic)입니다. 즉, 전체 요청이 성공하거나, 어떤 오류가 발생할 경우 전체 요청이 실패합니다. 오류 응답이 발생한 경우, 이 API의 사용자는 오류를 수정한 뒤 전체 페이로드로 요청을 다시 시도할 것을 권장합니다.
* 요청이 실패한 경우, 파트너는 재시도 시 [지수 백오프(exponential backoff)](https://en.wikipedia.org/wiki/Exponential_backoff) 방식을 사용할 것을 권장합니다. 예를 들어, 첫 번째 실패 시에는 즉시 재시도하고, 두 번째 실패 후에는 1분 뒤에, 세 번째 연속 실패 후에는 5분 뒤에 재시도하는 식으로 진행합니다.
## API 참조 문서
### 키워드 인사이트
#### GET insights/keywords/search[](#get-insights-keywords-search "Permalink to this headline")
키워드 그룹을 기준으로 관련된 Tweet 수와 함께 30개의 연관 키워드 집합을 가져옵니다. Tweet 수는 연관 키워드가 아니라 입력한 키워드에만 해당합니다.
최대 7일(`end_time` - `start_time`)의 기간만 허용됩니다.
결과는 단일 geo(국가) 기준으로 제한된다는 점에 유의하세요.
**Resource URL[](#resource-url "Permalink to this headline")**
`https://ads-api.x.com/12/insights/keywords/search`
**Parameters[](#parameters "Permalink to this headline")**
| 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](https://en.wikipedia.org/wiki/ISO_8601) 형식으로 표현됩니다.
Type: string
Example: `2017-07-10T00:00:00Z` |
| end\_time *optional* | 가져온 데이터를 `start_time`과 `end_time` 사이의 시간 구간으로 제한합니다. [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) 형식으로 표현됩니다.
**Note**: 지정하지 않으면 현재 시간이 기본값으로 사용됩니다.
Type: string
Example: `2017-07-11T00:00:00Z` |
| location *optional* | 계정 사용자의 위치 기준으로 결과를 제한하기 위해, [GET targeting\_criteria/locations](/ko/x-ads-api/campaign-management#get-targeting-criteria-locations) 엔드포인트에서 얻을 수 있는 타기팅 값입니다. 현재는 국가 단계(location)만 지원됩니다.
Type: string
Example: `0ce8b9a7b2742f7e` |
| negative\_keywords *optional* | 제외할 키워드를 쉼표로 구분한 문자열입니다. 모든 제외 키워드는 서로 OR 조건으로 결합됩니다.
**Note**: 최대 10개의 키워드(`keywords`와 `negative_keywords` 합산)를 사용할 수 있습니다.
#### GET accounts/:account\_id/tailored\_audiences/:tailored\_audience\_id/permissions[](#get-accounts-account-id-tailored-audiences-tailored-audience-id-permissions "이 표제에 대한 고유 링크")
지정된 맞춤 잠재 고객과 연관된 일부 또는 전체 권한에 대한 세부 정보를 조회합니다.
**Resource URL[](#resource-url "이 표제에 대한 고유 링크")**
`https://ads-api.x.com/5/accounts/:account_id/tailored_audiences/:tailored_audience_id/permissions`
**Parameters[](#parameters "이 표제에 대한 고유 링크")**
| Name | Description |
| :---------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| account\_id *required* | 활용 중인 계정의 식별자입니다. 리소스 경로 내에 나타나며, [GET accounts](/ko/x-ads-api/campaign-management#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](/ko/x-ads-api/introduction)을 참고하세요.
Type: string
Example: `8x7v00oow` |
| granted\_account\_ids *optional* | 쉼표로 구분된 식별자 목록을 지정하여 응답을 원하는 계정으로만 한정합니다. 최대 200개의 ID를 제공할 수 있습니다.
Type: string
Example: `18ce54aymz3` |
| sort\_by *optional* | 지원되는 속성을 기준으로 오름차순 또는 내림차순으로 정렬합니다. 자세한 내용은 [Sorting](/ko/x-ads-api/introduction)을 참고하세요.
Type: string
Example: `created_at-asc` |
| tailored\_audience\_permission\_ids *optional* | 쉼표로 구분된 식별자 목록을 지정하여 응답을 원하는 맞춤 잠재 고객 권한으로만 한정합니다. 최대 200개의 ID를 제공할 수 있습니다.
**Note**: `total_count`를 포함하는 요청에는 더 낮은 요청 한도가 적용되며, 현재 15분당 200건으로 설정되어 있습니다.
Type: boolean
Default: `false` Possible values: `true`, `false` |
**Example Request[](#example-request "이 표제에 대한 고유 링크")**
`GET https://ads-api.x.com/5/accounts/18ce54d4x5t/tailored_audiences/1nmth/permissions`
**Example Response[](#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[](#post-accounts-account-id-tailored-audiences-tailored-audience-id-permissions "Permalink to this headline")
지정된 오디언스를 특정 계정과 공유할 수 있도록 하는 새로운 권한(permission) 객체를 생성합니다.
**참고**: 맞춤형 오디언스의 권한을 생성하거나 수정하려면, 해당 오디언스는 권한 수정을 시도하는 계정이 소유하고 있어야 합니다. 특정 오디언스에 대한 응답에서 `is_owner` 응답 속성을 확인하여 맞춤형 오디언스의 소유 여부를 확인할 수 있습니다.
**참고**: 오디언스는 동일한 비즈니스에 속한 광고 계정 간에만 공유할 수 있으며, 또는 오디언스를 소유한 광고 계정에 `SHARE_AUDIENCE_OUTSIDE_BUSINESS` 계정 기능이 있는 경우에만 공유할 수 있습니다.
**Resource URL[](#resource-url "Permalink to this headline")**
`https://ads-api.x.com/5/accounts/:account_id/tailored_audiences/:tailored_audience_id/permissions`
**Parameters[](#parameters "Permalink to this headline")**
| Name | Description |
| :--------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| account\_id *required* | 활용되는 계정의 식별자입니다. 리소스 경로 내에 나타나며, [GET accounts](/ko/x-ads-api/campaign-management#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* | 이 요청에서 사용 중인 맞춤형 오디언스를 참조합니다.
#### DELETE accounts/:account\_id/tailored\_audiences/:tailored\_audience\_id/permissions/:tailored\_audience\_permission\_id[](#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[](#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](/ko/x-ads-api/campaign-management#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[](#get-accounts-account-id-custom-audiences-custom-audience-id-targeted "이 제목에 대한 퍼머링크")
지정된 `custom_audience_id`를 타게팅하는 활성 또는 전체 라인 아이템 및 캠페인 목록을 조회합니다.
| Name | Description |
| :------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| account\_id *required* | 사용되는 계정의 식별자입니다. 리소스 경로에 나타나며, [GET accounts](/ko/x-ads-api/campaign-management#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](/ko/x-ads-api/introduction)을 참조하세요.
#### POST accounts/:account\_id/custom\_audiences/:custom\_audience\_id/users[](#post-accounts-account-id-custom-audiences-custom-audience-id-users "Permalink to this headline")
이 엔드포인트를 사용하면 파트너가 지정된 `custom_audience_id`에 대해 사용자를 추가, 업데이트 및 제거할 수 있습니다. 또한 이 엔드포인트는 각 사용자에 대해 여러 종류의 사용자 식별자를 함께 전달받을 수 있습니다.
요청의 `users` 필드에 제공되는 모든 데이터는 `partner_user_id`를 **제외하고** `SHA256`으로 해시한 뒤 [정규화](/ko/x-ads-api/audiences#twitter-user-id-normalization)해야 합니다.
**배치 요청**
* 현재 이 엔드포인트에 대한 최대 배치 크기는 `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[](#resource-url "Permalink to this headline")
#### 매개변수[](#parameters "Permalink to this headline")
| 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](https://en.wikipedia.org/wiki/ISO_8601) 형식으로 표현됩니다. 기본값은 현재 날짜와 시간입니다.
Type: string
Example: `2017-07-05T07:00:00Z` |
| expires\_at *optional* | 커스텀 오디언스 연관 관계가 만료되어야 하는 UTC 시간입니다. 지정된 시간은 `effective_at` 값 이후여야 합니다. [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) 형식으로 표현됩니다. 기본값은 요청 타임스탬프 기준 13개월 후입니다.
Type: string
Example: `2017-07-05T07:00:00Z` |
`users` 객체에 대한 멀티 키 방식으로 인해, 이 객체의 각 요소는 아래와 같이 문서화되어 있습니다:
| Name | Description |
| :---------------------------------- | :------------------------------------------------------- |
| email *optional* | 사용자의 이메일 주소입니다.
#### GET accounts/:account\_id/custom\_audiences/:custom\_audience\_id/permissions[](#get-accounts-account-id-custom-audiences-custom-audience-id-permissions "이 제목에 대한 고유 링크")
지정한 커스텀 오디언스에 연결된 일부 또는 전체 권한의 세부 정보를 조회합니다.
**리소스 URL[](#resource-url "이 제목에 대한 고유 링크")**
`https://ads-api.x.com/12/accounts/:account_id/custom_audiences/:custom_audience_id/permissions`
**매개변수[](#parameters "이 제목에 대한 고유 링크")**
| 이름 | 설명 |
| :-------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| account\_id *required* | 활용 중인 계정의 식별자입니다. 리소스 경로에 포함되며, [GET accounts](/ko/x-ads-api/campaign-management#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](/ko/x-ads-api/introduction)을 참조하세요.
Type: string
Example: `8x7v00oow` |
| granted\_account\_ids *optional* | 쉼표로 구분된 식별자 목록을 지정하여 응답을 원하는 계정으로만 한정합니다. 최대 200개의 ID를 제공할 수 있습니다.
Type: string
Example: `18ce54aymz3` |
| sort\_by *optional* | 지원되는 속성을 기준으로 오름차순 또는 내림차순으로 정렬합니다. 자세한 내용은 [Sorting](/ko/x-ads-api/fundamentals/sorting)을 참조하세요.
Type: string
Example: `created_at-asc` |
| custom\_audience\_permission\_ids *optional* | 쉼표로 구분된 식별자 목록을 지정하여 응답을 원하는 커스텀 오디언스 권한으로만 한정합니다. 최대 200개의 ID를 제공할 수 있습니다.
**참고**: `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/1nmth/permissions`
**응답 예시[](#example-response "이 제목에 대한 고유 링크")**
```
{
"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[](#post-accounts-account-id-custom-audiences-custom-audience-id-permissions "이 헤드라인의 퍼머링크")
지정된 맞춤 오디언스를 특정 계정과 공유할 수 있도록 하는 새 권한 객체를 생성합니다.
**참고**: 맞춤 오디언스의 권한을 생성하거나 수정하려면, 해당 맞춤 오디언스를 소유한 계정이어야 합니다. 특정 맞춤 오디언스에 대한 응답에서 `is_owner` 응답 속성을 확인하여 소유 여부를 확인할 수 있습니다.
**참고**: 오디언스는 동일한 비즈니스에 속한 광고 계정 간에만 공유할 수 있습니다. 단, 오디언스를 소유한 광고 계정에 `SHARE_AUDIENCE_OUTSIDE_BUSINESS` 계정 기능이 있는 경우에는 예외입니다.
**Resource URL[](#resource-url "이 헤드라인의 퍼머링크")**
`https://ads-api.x.com/12/accounts/:account_id/custom_audiences/:custom_audience_id/permissions`
**Parameters[](#parameters "이 헤드라인의 퍼머링크")**
| Name | Description |
| :------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| account\_id *required* | 사용되는 계정의 식별자입니다. 리소스 경로에 포함되며, [GET accounts](/ko/x-ads-api/campaign-management#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* | 요청에서 작업 중인 맞춤 오디언스를 가리키는 참조 값입니다.
#### DELETE accounts/:account\_id/custom\_audiences/:custom\_audience\_id/permissions/:custom\_audience\_permission\_id[](#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[](#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](/ko/x-ads-api/campaign-management#accounts)를 제외한 모든 Advertiser API 요청에서 일반적으로 필수 매개변수입니다. 지정된 계정은 인증된 사용자와 연결되어 있어야 합니다.
Type: string
Example: `18ce54d4x5t` |
| custom\_audience\_id *required* | 요청에서 사용 중인 Custom Audience에 대한 참조입니다.
Type: string
Example: `1nmth` |
| custom\_audience\_permission\_id *required* | 요청에서 사용 중인 Custom Audience 권한에 대한 참조입니다.
#### GET accounts/:account\_id/custom\_audiences[](#get-accounts-account-id-custom-audiences "이 헤드라인의 고유 주소")
현재 계정과 연결된 일부 또는 모든 Custom Audiences의 세부 정보를 조회합니다.
**Resource URL[](#resource-url "이 헤드라인의 고유 주소")**
`https://ads-api.x.com/12/accounts/:account_id/custom_audiences`
**Parameters[](#parameters "이 헤드라인의 고유 주소")**
| Name | Description |
| :-------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| account\_id *required* | 사용 중인 계정의 식별자입니다. 리소스 경로에 포함되며, [GET accounts](/ko/x-ads-api/campaign-management#accounts)를 제외한 모든 Advertiser API 요청에서 일반적으로 필수 매개변수입니다. 지정된 계정은 인증된 사용자와 연결되어 있어야 합니다.
Type: string
Example: `18ce54d4x5t` |
| count *optional* | 각 요청당 조회를 시도할 레코드 수를 지정합니다.
Type: int
Default: `200` Min, Max: `1`, `1000` |
| cursor *optional* | 다음 페이지의 결과를 가져오기 위한 cursor를 지정합니다. 자세한 내용은 [Pagination](/ko/x-ads-api/introduction)을 참조하세요.
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](/ko/x-ads-api/fundamentals/sorting)을 참조하세요.
Type: string
Example: `created_at-asc` |
| custom\_audience\_ids *optional* | 쉼표로 구분된 식별자 리스트를 지정하여, 원하는 Custom Audiences만 응답에 포함되도록 범위를 지정합니다. 최대 200개의 ID를 제공할 수 있습니다.
#### GET accounts/:account\_id/custom\_audiences/:custom\_audience\_id[](#get-accounts-account-id-custom-audiences-custom-audience-id "이 제목의 퍼머링크")
현재 계정과 연관된 특정 Custom Audience를 조회합니다.
**Resource URL[](#resource-url "이 제목의 퍼머링크")**
`https://ads-api.x.com/12/accounts/:account_id/custom_audiences/:custom_audience_id`
**Parameters[](#parameters "이 제목의 퍼머링크")**
| Name | Description |
| :------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| account\_id *required* | 사용 중인 계정의 식별자입니다. 리소스 경로에 포함되며, [GET accounts](/ko/x-ads-api/campaign-management#accounts)를 제외한 모든 Advertiser API 요청에서 일반적으로 필수 매개변수입니다. 지정된 계정은 인증된 사용자와 연결되어 있어야 합니다.
Type: string
Example: `18ce54d4x5t` |
| custom\_audience\_id *required* | 요청에서 사용하는 Custom Audience에 대한 참조입니다.
Type: string
Example: `2906h` |
| with\_deleted *optional* | 요청 결과에 삭제된 항목을 포함합니다.
#### POST accounts/:account\_id/custom\_audiences[](#post-accounts-account-id-custom-audiences "이 제목의 퍼마링크")
현재 계정과 연결된 새 플레이스홀더 맞춤 잠재고객(Custom Audience)을 생성합니다.
**리소스 URL[](#resource-url "이 제목의 퍼마링크")**
`https://ads-api.x.com/12/accounts/:account_id/custom_audiences`
**매개변수[](#parameters "이 제목의 퍼마링크")**
| Name | Description |
| :---------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| account\_id *required* | 대상 계정의 식별자입니다. 리소스의 경로에 포함되며, [GET accounts](/ko/x-ads-api/campaign-management#accounts)를 제외한 모든 Advertiser API 요청에서 일반적으로 필수 매개변수입니다. 지정된 계정은 인증된 사용자와 연결되어 있어야 합니다.
Type: string
Example: `18ce54d4x5t` |
| name *required* | 이 잠재고객의 표시 이름입니다. 고유한 이름 값을 사용해야 합니다. 그렇지 않으면 오류가 발생합니다.
Type: string
Example: `ads api users` |
| description *optional* | 이 잠재고객에 대한 설명입니다.
#### PUT accounts/:account\_id/custom\_audiences/:custom\_audience\_id[](#put-accounts-account-id-custom-audiences-custom-audience-id "이 제목의 고유 링크")
현재 계정과 연결된 특정 Custom Audience를 업데이트합니다.
**Resource URL[](#resource-url "이 제목의 고유 링크")**
`https://ads-api.x.com/12/accounts/:account_id/custom_audiences/:custom_audience_id`
**Parameters[](#parameters "이 제목의 고유 링크")**
| Name | Description |
| :------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| account\_id *required* | 사용되는 계정의 식별자입니다. 리소스 경로에 포함되며, [GET accounts](/ko/x-ads-api/campaign-management#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[](#example-request "이 제목의 고유 링크")**
`PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/custom_audiences/2906h?name=developers_changed`
**Example Response[](#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[](#post-batch-accounts-account-id-custom-audiences "이 제목에 대한 퍼머링크")
Custom Audiences를 일괄 생성합니다. Audience에 대한 정보는 [Custom Audiences 개요](/ko/x-ads-api/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[](#resource-url "이 제목에 대한 퍼머링크")**
`https://ads-api.x.com/12/batch/accounts/:account_id/custom_audiences`
**Parameters[](#parameters "이 제목에 대한 퍼머링크")**
| Name | Description |
| :----------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| account\_id *required* | 사용하는 계정을 식별하는 식별자입니다. 리소스 경로에 포함되며, [GET accounts](/ko/x-ads-api/campaign-management#accounts)을(를) 제외한 모든 Advertiser API 요청에서 일반적으로 필수 매개변수입니다. 지정한 계정은 인증된 사용자와 연결되어 있어야 합니다.
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) 등을 의미합니다.
#### DELETE accounts/:account\_id/custom\_audiences/:custom\_audience\_id[](#delete-accounts-account-id-custom-audiences-custom-audience-id "이 제목의 퍼머링크")
현재 계정에 속한 지정된 Custom Audience를 삭제합니다.
**Resource URL[](#resource-url "이 제목의 퍼머링크")**
`https://ads-api.x.com/12/accounts/:account_id/custom_audiences/:custom_audience_id`
**Parameters[](#parameters "이 제목의 퍼머링크")**
| Name | Description |
| :------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| account\_id *required* | 사용 중인 계정의 식별자입니다. 리소스 경로에 포함되며, [GET accounts](/ko/x-ads-api/campaign-management#accounts)를 제외한 모든 Advertiser API 요청에 일반적으로 필요한 매개변수입니다. 지정된 계정은 인증된 사용자와 연결되어 있어야 합니다.
#### GET accounts/:account\_id/do\_not\_reach\_lists[](#get-accounts-account-id-do-not-reach-lists "이 제목의 고유 링크")
현재 계정과 연결된 일부 또는 전체 연락 금지 리스트(Do Not Reach List)의 세부 정보를 조회합니다.
**참고**: 하나의 `account_id`에는 최대 하나의 연락 금지 리스트(Do Not Reach List)만 존재할 수 있습니다.
**리소스 URL[](#resource-url "이 제목의 고유 링크")**
`https://ads-api.x.com/12/accounts/:account_id/do_not_reach_lists`
**매개변수[](#parameters "이 제목의 고유 링크")**
| Name | Description |
| :------------------------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| account\_id *required* | 활용 중인 계정의 식별자입니다. 리소스 경로에 포함되며, [GET accounts](/ko/x-ads-api/campaign-management#accounts)를 제외한 모든 Advertiser API 요청에서 일반적으로 필수 매개변수입니다. 지정된 계정은 인증된 사용자와 연결되어 있어야 합니다.
Type: string
Example: `18ce54d4x5t` |
| with\_deleted *optional* | 삭제된 결과를 요청에 포함할지 여부입니다.
Type: boolean
Default: `false` Possible values: `true`, `false` |
**요청 예시[](#example-request "이 제목의 고유 링크")**
`GET https://ads-api.x.com/12/accounts/18ce54bgxky/do_not_reach_lists`
**응답 예시[](#example-response "이 제목의 고유 링크")**
```
{
"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[](#post-accounts-account-id-do-not-reach-lists "이 제목의 고유 링크")
현재 계정과 연결된 새로운 Do Not Reach 리스트를 생성합니다.
**참고**: 하나의 `account_id`에는 최대 하나의 Do Not Reach 리스트만 존재할 수 있습니다.
**리소스 URL[](#resource-url "이 제목의 고유 링크")**
`https://ads-api.x.com/12/accounts/:account_id/do_not_reach_lists`
**매개변수[](#parameters "이 제목의 고유 링크")**
| Name | Description |
| :---------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| account\_id *required* | 활용 중인 계정의 식별자입니다. 리소스의 경로 내에 나타나며, [GET accounts](/ko/x-ads-api/campaign-management#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": "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[](#post-batch-accounts-account-id-do-not-reach-lists-do-not-reach-list-id-users "Permalink to this headline")
이 엔드포인트는 지정된 `do_not_reach_list_id` 에서 사용자를 추가, 업데이트 및 제거할 수 있도록 합니다. 이 엔드포인트는 유효한 사용자 식별자 type 으로 이메일만 허용합니다.
요청의 `emails` 필드에 제공되는 모든 데이터는 `SHA256` 으로 해시해야 하며, [정규화](/ko/x-ads-api/audiences#e-mail-normalization)되어야 합니다.
**참고**
* 하나의 `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[](#resource-url "Permalink to this headline")**
`https://ads-api.x.com/12/batch/accounts/:account_id/do_not_reach_lists/:do_not_reach_list_id/users`
**파라미터[](#parameters "Permalink to this headline")**
| Name | Description |
| :----------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| account\_id *required* | 대상 계정의 식별자입니다. 리소스 경로에 포함되며, [GET accounts](/ko/x-ads-api/campaign-management#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](https://en.wikipedia.org/wiki/ISO_8601) 형식으로 표현됩니다. 기본값은 현재 타임스탬프 기준 13개월 후입니다.
Type: string
Example: `2017-07-05T07:00:00Z` |
`users` 객체에 여러 키를 사용하는 방식에 따라, 이 객체의 각 요소는 아래에서 개별적으로 설명됩니다:
| 이름 | 설명 |
| :--------------------------- | :------------------------------------------- |
| email *선택 사항* | 사용자의 이메일 주소.
Type: Array\[String] |
| phone\_number *선택 사항* | 사용자의 전화번호.
#### DELETE accounts/:account\_id/do\_not\_reach\_lists/:do\_not\_reach\_list\_id[](#delete-accounts-account-id-do-not-reach-lists-do-not-reach-list-id "Permalink to this headline")
현재 계정에 속한 특정 Do Not Reach 리스트를 삭제합니다.
**리소스 URL[](#resource-url "Permalink to this headline")**
`https://ads-api.x.com/12/accounts/:account_id/do_not_reach_lists/:do_not_reach_list_id`
**매개변수[](#parameters "Permalink to this headline")**
없음
**요청 예시[](#example-request "Permalink to this headline")**
`DELETE https://ads-api.x.com/12/accounts/18ce54bgxky/do_not_reach_lists/4ofrp`
**응답 예시[](#example-response "Permalink to this headline")**
```
{
"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
}
}
```
Audience 또는 API 파트너가 해시된 식별자 목록을 제공하면, X가 이를 매칭하여 X에서 미디어 구매에 사용할 수 있는 세그먼트를 생성합니다. 파트너는 [Audience API](/ko/x-ads-api/audiences)를 사용해 이러한 잠재고객을 생성할 수 있습니다.
**How it works?**
**Web**
X에서의 미디어 구매를 위해 타기팅할 세그먼트를 식별하기 위해 MPP audience 파트너와 협력할 때 표준 쿠키 매칭 프로세스를 제공합니다. 추가로, 광고주는 웹사이트 사용자 데이터를 수집하고 해당 Custom Audience를 생성하기 위해 [X Web Event Tag](/ko/x-ads-api/measurement/web-conversions#web-event-tags)를 설정할 수 있습니다.
**Setup Steps**
![]()
**How it works?**
**Mobile**
자세한 내용은 [the Custom Audiences from Mobile Apps blog post](https://blog.x.com/2014/introducing-tailored-audiences-from-mobile-apps)를 참조하세요.
**Flexible**
[Flexible audiences](/ko/x-ads-api/audiences)는 기존 custom audiences 또는 기존 custom audiences의 하위 집합을 기반으로 잠재고객 조합을 생성하고 저장할 수 있는 기능을 광고주에게 제공합니다. custom audience 구성원의 하위 집합은 상호작용의 최신성(recency)과 빈도(frequency)에 따라 타기팅할 수 있습니다.
**Restricted Use Cases for Custome Audiences**
[제한 사항에 대해 자세히 알아보기](https://developer.x.com/en/developer-terms/more-on-restricted-use-cases "Read more about restrictions")
**정보**
파트너는 광고주를 대신해 타게팅할 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](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://