> ## Documentation Index > Fetch the complete documentation index at: https://docs.x.com/llms.txt > Use this file to discover all available pages before exploring further. # Audiences > Custom Audiences, CRM, 웹, 모바일, lookalike 세그먼트를 포함해 광고 캠페인에서 사용자에게 도달하기 위한 X Ads의 오디언스 타깃팅 개요. export const Button = ({href, children}) => { return
; }; export const BlueprintMark = ({name, height = 150}) =>
; **퍼스트파티 데이터와 X 참여 신호를 활용해 X 광고 캠페인을 위한 정밀 타깃팅된 오디언스를 구축하세요.** ## 빠른 링크 * [전체 API 참조](/x-ads-api/audiences/reference) — 모든 Audience 엔드포인트와 객체 * [가이드](#guides) — CRM, Web, Mobile, ID Sync, User Data 업로드, FAQ ## Custom Audiences ### 개요 파트너가 [Custom Audiences](https://business.x.com/en/targeting/tailored-audiences.html)를 만들 수 있는 방법은 여러 가지가 있습니다. * [Audience API (CRM)](#crm) * [Web](#web) * [Mobile](#mobile) * [Flexible](#flexible) lookalike custom audiences는 타깃팅에서 제외할 수 없다는 점에 유의하세요. 또한 동일한 광고 라인 아이템(ad group)에서 custom audience와 custom audience lookalike를 동시에 타깃팅할 수 없습니다. **오디언스 관리** 오디언스는 audience 파트너와 Ads API 파트너를 통해 관리할 수 있습니다. custom audiences에 액세스하고 유지 관리할 수 있는 일련의 엔드포인트가 API에 제공됩니다. custom audience 정보를 위해 2가지 엔드포인트를 제공합니다: * [GET accounts/:account\_id/custom\_audiences](/x-ads-api/audiences) * [GET accounts/:account\_id/custom\_audiences/:custom\_audience\_id](/x-ads-api/audiences) 오디언스 업로드 및 관리 방법에 대한 자세한 내용은 [Audience API 가이드](/x-ads-api/audiences)를 참고하세요. **처리 시간** 일반적으로 audience 변경사항은 6-8시간마다 실행되는 배치로 처리됩니다. audience 변경이 처리되는 동안 업데이트 대상 기존 audience는 영향을 받지 않습니다. 이 시간 범위 내에서 audience당 추가 1건, 삭제 1건 이상의 업데이트는 권장하지 않습니다. **타깃팅** audience는 X 소유 및 운영 클라이언트에서 지난 90일 이내에 활성화된 사용자 100명 이상과 일치하는 경우에만 타깃팅할 수 있습니다. [GET accounts/:account\_id/custom\_audiences/:custom\_audience\_id](/x-ads-api/audiences)는 audience가 일치하는 사용자가 너무 적어 타깃팅할 수 없는 경우 이를 표시합니다. **Audience API (CRM)** image2 Audience 또는 API 파트너는 해시된 식별자 목록을 제공하고 X는 매칭을 수행하여 X에서의 미디어 구매에 사용할 수 있는 세그먼트를 생성합니다. 파트너는 [Audience API](/x-ads-api/audiences)를 사용해 이러한 audience를 만들 수 있습니다. **작동 방식은?** image3 **Web** MPP audience 파트너와 협력하여 X에서의 미디어 구매를 위해 타깃팅할 세그먼트를 식별할 때 표준 쿠키 매칭 프로세스를 제공합니다. 또한 광고주는 [X Web Event Tag](/x-ads-api/measurement/web-conversions#web-event-tags)를 설정하여 웹사이트 사용자 데이터를 수집하고 해당 Custom Audience를 생성할 수 있습니다. **설정 단계** image0 **작동 방식은?** image1 **Mobile** 자세한 내용은 [모바일 앱의 Custom Audiences 블로그 게시물](https://blog.x.com/2014/introducing-tailored-audiences-from-mobile-apps)을 참고하세요. **Flexible** [Flexible audiences](/x-ads-api/audiences)는 광고주가 기존 custom audiences 또는 기존 custom audiences의 하위 집합을 기반으로 audience 조합을 구축하고 저장할 수 있는 기능을 제공합니다. custom audience 멤버의 하위 집합은 상호작용의 최신성과 빈도를 기반으로 타깃팅할 수 있습니다. **Custom Audiences에 대한 제한 사용 사례** [제한 사항에 대해 자세히 보기](https://developer.x.com/en/developer-terms/more-on-restricted-use-cases "제한 사항에 대해 자세히 보기") ### Audiences FAQ[](#real-time-tailored-audiences "이 헤드라인으로 가는 퍼머링크") **Q: 대량의 데이터를 보냈는데, 왜 audience 크기가 TOO\_SMALL로 표시되나요?** A: 현재 데이터는 실시간으로 audience에 추가되지만, audience 크기를 제공하기 위해 데이터를 처리하는 작업은 일정 기간이 지난 후에만 실행됩니다. 몇 시간 후에 UI에 올바른 audience 크기가 표시되어야 합니다. **Q: audience 데이터를 보내고 24시간 이상 기다렸는데, 여전히 audience를 타깃팅할 수 없습니다. 다음 단계로 무엇을 해야 하나요?** A: 다음 사항을 확인하세요: * 전달된 사용자 ID가 정확하고 잘못된 형식이 아닌지 확인합니다. * 전달된 audience 이름이 정확하고 이전 멤버십 업데이트와 일치하는지 확인합니다. * POST 명령의 응답을 확인합니다. * ID Sync 픽셀이 올바르게 구현되었는지, 그리고 ID Sync 프로세스에서 설명한 대로 해당 사이트를 방문한 사용자가 충분히 많아 사용자 매핑이 이루어졌는지 확인합니다. 멤버십 업데이트에서 매핑되지 않은 사용자는 타깃팅된 사용자로 변환되지 않습니다. 위 항목이 모두 올바르게 확인되었다면 가능한 한 자세한 정보와 함께 X 제품 담당자에게 문의하세요(선호되는 정보 예시는 [Guide to Partner Inbounds](/x-ads-api/introduction) 참고). **Q: 엔드포인트를 몇 번, 어떤 알고리즘으로 호출할 수 있나요?** A: 시스템에 증분(델타)으로 호출할 것을 강력히 권장하며, 전체 audience 멤버십을 다시 보내지 마세요. 시스템은 세계 최대 규모 웹사이트의 증분 데이터 업데이트를 처리하기에 충분한 처리량을 갖도록 테스트되었습니다. audience의 초기 업로드는 신중히 조절해야 하며 첫 업로드에는 상당한 시간이 소요될 수 있습니다. **Q: 타깃팅에 사용할 audience의 최소 크기는 얼마인가요?** * audience의 최소 크기는 사용자 100명(매칭 후)입니다. 매칭된 사용자가 500명 미만인 audience는 X Ads UI에서 타깃팅에 사용할 수 없습니다. **Q: audience 파일을 처리하는 데 얼마나 걸리나요? 그리고 X User Interface에서 audience 파일이 준비되는 데는 얼마나 걸리나요?** * audience 파일 처리에는 일반적으로 4-6시간이 소요되지만, 파일 크기에 따라 다릅니다. 파일이 처리되면 X Ads UI에서 audience를 사용할 수 있습니다. **Q: match rate는 어떻게 계산되나요?** * Match Rate = 90일 활성 X 사용자 / 제공된 사용자 수 **Q: audience 파일이 제대로 작동하는지 어떻게 테스트하나요?** * 테스트 audience 파일을 제공하고 광고주 핸들로 "keltonlynn"을 사용할 수 있습니다. 그러면 파일이 제대로 수집되고 X UI에 로드될 수 있는지 확인할 수 있습니다. **Q: 파트너 사용자 식별자(`p_user_id`)란 무엇인가요?** * 이는 회사에서 각 고객을 고유하게 식별하기 위해 사용되는 식별자입니다. **Q: 표준 ID란 무엇인가요?** * 이는 이메일 주소, 디바이스 ID, X @핸들 또는 ID가 될 수 있습니다. **Q: HMAC Key는 어떻게 받나요?** * 암호화된 이메일로 제공됩니다. [mpp-inquiry@x.com](mailto:mpp-inquiry%x.com)로 공개 PGP 키를 제공해 주시면 모든 것이 작동하는지 확인하기 위해 테스트 이메일을 보내드립니다. 확인이 완료되면 HMAC Key를 보내드립니다. **Q: 제공된 HMAC Key를 사용해 해싱 프로세스가 제대로 작동했는지 어떻게 확인하나요?** * X는 테스트 파일(샘플 이메일 주소, 디바이스 ID 등 포함)과 결과 해시 파일을 제공하여 결과를 검증할 수 있게 합니다. **Q: 전체 데이터 매칭 파일에 파일 크기 제한이 있나요?** * 아니요, 전체 데이터 매칭 파일에는 크기 제한이 없습니다. **Q: 전체 데이터 매칭 파일을 처리하는 데 얼마나 걸리나요?** * X가 파일을 수신하면 파일을 처리하는 데 약 1일이 소요됩니다. ### CRM image0 이 문서는 파일 형식 및 데이터 교환 프로세스를 포함해 Custom Audiences CRM 파트너의 통합 세부 정보를 설명합니다. **요약** Company는 고객을 대신하여 X에게 해시된 공통 사용자 식별자(예: 이메일 주소) 또는 파트너 사용자 ID 목록을 제공하여 블라인드 매칭을 수행하고 타깃팅을 위한 X User ID 목록을 생성합니다. 타깃팅을 위한 세그먼트는 ads.x.com 캠페인 설정 파일 이름으로 지정된 광고주의 특정 @핸들에서 사용할 수 있게 됩니다. Company의 모든 파일은 X가 Company에 부여한 특정 계정을 통해 IronBox([www.golockbox.com)의](http://www.golockbox.com\)의) 안전한 패키지로 X에 제공됩니다. X는 IronBox 액세스를 제공합니다. IronBox API에 대한 문서는 [https://secure.goironcloud.com/Docs/Help/](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는 이 파일의 baseline match rate를 이메일로 Company와 공유합니다. 이 파일의 형식은 다음과 같아야 합니다: 파일 이름 규칙: FullDataMatch.\[CompanyName].txt 해싱 알고리즘: HMAC\_SHA-256 형식: Column 1: 공통 식별자의 HMAC 해시 값 Column 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에서 타깃팅할 커스텀 audience를 만들기 위해 `p_user_id` 형태로 사용자 목록을 제공합니다. * 줄 구분 값 * `p_user_id` * * (위 1. 전체 데이터 매칭 섹션에서 제공된 것과 동일합니다. 전체 데이터 매칭에서 제공된 값이 해시된 경우, Company는 audience 파일에서도 동일한 해시 값을 제공합니다. 제공된 값이 해시되지 않은 경우, Company는 해시되지 않은 값을 제공합니다.) #### 표준 매칭 요구 사항 회사에서 모든 고객 사용자 식별자 매핑을 위해 표준 ID를 사용하지 않는다면, 이것이 권장 프로세스입니다. **커스텀 세그먼트 목록** Company는 커스텀 audience를 만들기 위해 고객을 대신하여 해시된 공통 사용자 식별자 목록을 X에 직접 제공합니다. 이 파일의 형식은 다음과 같아야 합니다: * 줄 구분 값 * 해시된 공통 사용자 식별자 (예: 이메일 주소) * 아래에 설명된 파일 이름 규칙을 따르세요 * 아래(해싱 지침 부분)의 이메일 주소 해싱 지침을 따르세요 #### 커스텀 세그먼트 목록 파일 이름 규칙 및 작업 파일 작업은 다음 사용 가능한 작업 및 일반적인 파일 이름 규칙(audiencename\_partnername.handle.operation.filetype)에 의해 파일 이름으로 결정됩니다: * audiencename: Custom Audience의 이름. 이 필드는 ads.x.com 캠페인 설정 UI에서 audience를 선택할 때 표시되는 이름입니다. 예: brand\_loyalty\_card\_holders. * partnername: 광고주를 대신하여 데이터를 제공하는 회사 이름. 예: company\_name. * handle: Custom Audiences에 접근할 수 있는 X Account (@핸들). 예: @pepsi, @dietpepsi * operation: new, add, remove, removeall, replace (자세한 내용은 아래 참조) * : 업로드되는 각 audience 파일이 고유함을 보장하기 위해 사용되는 초 단위의 표준 Unix epoch time * filetype: 파일은 \*.txt 형식이어야 합니다. #### Audience 생성 및 업데이트 단일 파일로 새 audience 생성. 예: loyalty\_card\_holders\_partnername.pepsi.new\.txt Add - 기존 audience에 목록의 매칭 결과를 추가. 예: loyalty\_card\_holders\_partnername.pepsi.add.txt Remove - 기존 audience에서 목록의 매칭 결과를 제거. 예: loyalty\_card\_holders\_partnername.pepsi.remove.txt Remove All - 정기적으로 업데이트되는 누적 목록에서 생성된 매칭 결과를 해당 고객의 모든 audience에서 제거(즉, 고객의 옵트아웃 목록). 예: partnername.pepsi.removeall.txt * 광고주로부터 옵트아웃한 사용자의 종합 목록에 사용할 수 있습니다. * X는 이 파일에서 가장 최근에 제공된 목록만 반영하며, 매칭된 기존 및 미래의 모든 audience에 걸쳐 반영됩니다. 이 파일이 제공되고 처리된 시점의 X 사용자. Replace - 기존 audience를 제거하고 새 audience 목록으로 교체. 예: loyalty\_card\_holders\_partnername.pepsi.replace.txt Overall Company Opt-Out - Company는 회사의 옵트아웃 정책에 따라 옵트아웃한 사용자를 제거하기 위해 누적 옵트아웃 파일을 제공합니다. X는 이 Company Opt-Out 파일에서 가장 최근 제공된 목록만 반영하며, 이 파일이 제공되고 처리된 시점의 매칭된 X 사용자에 대해 모든 기존 및 미래 audience에 걸쳐 반영합니다. Company Opt-Out 파일 형식은 다음과 같습니다. 예: partnername.removeall.txt Delete - 현재 audience 목록에서 기존 audience를 제거. 예: loyalty\_card\_holders\_partnername.pepsi.delete.txt #### 해싱 지침 X는 공통 사용자 식별자(예: 이메일 주소)를 해싱하기 위해 base64로 인코딩된 프로덕션 키를 PGP를 통해 안전하게 공유합니다. Company는 해싱을 수행하는 데 사용할 32바이트 키를 얻기 위해 base64로 키를 디코딩합니다. base64 인코딩된 예시 키: BrQvOg+dACBUmKjRiNxZgJLh6zydjS0ZOv80FelTNzM= Base64 디코딩된 예시 키: /:� TшY 정규화: Company는 해싱 전에 공통 사용자 식별자에 대해 기본 정규화를 수행해야 합니다(디바이스 ID의 경우 예외, Device ID Normalization 섹션 참조). #### 이메일 정규화 즉, 이메일 주소의 앞뒤 공백을 제거하고 소문자로 변환합니다. 예: 원시 이메일 주소: 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 User ID 정규화 X ID는 PII가 아니지만 데이터 그룹화(즉, @핸들의 고객 목록)가 광고주에게 비공개이므로 여전히 해싱됩니다. SHA-256 해싱 알고리즘과 데이터 파트너에게 제공하는 공통 솔트를 사용해 X ID를 해싱하는 데 동일한 요구 사항이 적용됩니다. X ID/`@`username 모두에서 공백을 제거해야 하지만, User ID는 정규화가 필요하지 않습니다. @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`로 설정해야 합니다. * **웹 전용**: 아래에 설명된 것처럼 광고주의 사이트에 픽셀을 배치하여 수행할 수 있습니다. * **List**: [CRM](/x-ads-api/audiences/reference#crm) 페이지에 설명된 방법 중 하나를 사용해 수행할 수 있습니다. #### 픽셀 URL | | | :----------------------------------------------------------------- | | **Base URL** | | [https://analytics.x.com/i/adsct](https://analytics.x.com/i/adsct) | #### 픽셀 파라미터 | | | | :---------- | :---------------- | | **파라미터** | **설명** | | `p_id` | X가 할당한 파트너 id | | `p_user_id` | 파트너 시스템에서의 사용자 id | #### ID Sync 픽셀: 예시 파트너 id 111과 예시 `p_user_id` abc를 사용하여 구성된 픽셀은 다음과 같습니다: ```json theme={null}
``` **옵트아웃 파일 구성 및 옵트아웃 파일 전송** 파트너는 파트너가 최대한 파악한 대로 타깃 광고 게재를 옵트아웃한 사용자 목록을 X에게 제공해야 합니다. 파일 형식은 다음과 같이 전송해야 합니다: | | | | | | :-------- | :---------------- | :-------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **컬럼 번호** | **컬럼 이름** | **컬럼 타입** | **설명** | | 1 | Partner ID | string | "partner id"는 각 파트너를 고유하게 식별하기 위해 X가 파트너에게 제공하는 ID입니다. | | 2 | 파트너 시스템에서의 사용자 id | string | `p_user_id`는 파트너가 사용자를 식별하기 위해 사용하는 고유 ID입니다. 옵트아웃 사용자를 포함하는 이 파일은 [TON upload](/x-ads-api/audiences) 엔드포인트를 사용해 업로드해야 하며, 업로드된 데이터의 경로는 다음 Global Opt Out 엔드포인트로 전송해야 합니다: [PUT accounts/:account\_id/custom\_audiences/global\_opt\_out](/x-ads-api/audiences). | **멤버십 업데이트 전송** 엔드포인트 문서에서 지정된 대로, [POST custom\_audience\_memberships](/x-ads-api/audiences) 엔드포인트를 통해 사용자를 전달할 때 쿠키 기반 매칭을 가능하게 하기 위해 고객 ID를 전달해야 합니다. `p_id`와 함께 데이터를 보내는 파트너는 **반드시** `user_identifier_type`을 `TALIST_PARTNER_USER_ID` 또는 `TAWEB_PARTNER_USER_ID`로 설정해야 합니다. 다른 모든 단계는 [Real-Time Audience API Integration Guide](/x-ads-api/audiences)에 나열된 것과 동일합니다. ### Custom Audiences User Data 이 문서는 \[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)에서 확인할 수 있습니다. ### Custom Audiences: Web info.png **정보** 파트너는 광고주를 대신하여 타깃팅할 ID 목록(`p_user_ids`)을 전송합니다. 이는 `p_user_ids`와 X 사용자 ID 간의 매핑을 구축하는 ID Sync 프로세스를 통해 이루어집니다. 이 매핑은 이후 타깃팅에 사용될 수 있는 X User ID 목록을 생성하는 데 사용됩니다. 이러한 custom audience는 ads.x.com Custom Audiences Web 캠페인 설정의 라벨로 지정된 광고주의 특정 @핸들에서 사용할 수 있게 됩니다. X는 파트너 태그와 사이트에 배치하여 ID(`p_user_ids`)와 X 사용자 ID를 매칭할 수 있는 보안 픽셀을 제공합니다. ID Sync 프로세스가 완료되면 파트너가 타깃팅 파일을 만들고 HTTPS 엔드포인트를 통해 X에 제공합니다. 이러한 타깃팅 파일은 정기적으로 X에서 수집되어 X UI에서 사용할 수 있게 됩니다. **X Secure 픽셀** X secure 픽셀은 다음과 같이 표시됩니다: [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 엔드포인트 및 자격 증명(username/password)을 X에 제공해야 합니다. 샘플 HTTPS 엔드포인트는 다음과 같습니다: ``` https:///twitter/partner_targeting_%Y-%M-%D.tsv.gz ``` %Y - 연도 형식 코드 (YYYY) %M - 월 형식 코드 (MM) %D - 일 형식 코드 (DD) 전송되는 데이터는 다음과 같은 파일로 구성됩니다: 1. 파트너 타깃팅 사용자 파일 2. 타깃팅 전환 파일 모든 파일은 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"는 광고주의 @핸들입니다. | | 3 | p\_user\_id | string | "p\_user\_id"는 파트너가 사용자를 식별하기 위해 사용하는 고유 ID입니다. | | 3 | confidence score | integer | "confidence score"는 선택 사항입니다. confidence score의 권장 사항은 0-100을 사용하는 것입니다. 사용 사례가 리타깃팅인 경우, "100"의 confidence score는 직접 리타깃팅된 사용자입니다. 0-99의 점수는 look-alike의 신뢰 수준에 해당합니다. | | 4 | segment label | string | "segment label"은 선택 사항입니다. 파트너는 "segment label"을 사용하여 예를 들어 제품 카테고리를 지정할 수 있습니다. 이 "segment label"은 ads.x.com UI의 Custom Audiences에서 사람이 읽을 수 있는 이름이므로 사용하는 것을 권장합니다. | **참고:** 새 파트너 타깃팅 파일을 받을 때마다 파트너가 타깃팅을 권장하는 전체 사용자 목록이어야 합니다(별도 합의가 없는 한 증분이 아님). 각 파트너와 파트너 타깃팅 파일의 배송 빈도를 합의합니다. 예상대로 파트너 타깃팅 파일을 받지 못한 경우, 일부 사전 정의된 만료 시간 동안 이전 버전을 사용합니다. ## Audience API 통합 ### 개요 Audience API는 Ads API [v4](/x-ads-api/introduction)의 일부로 출시되었으며, 이와 함께 레거시 Audiences 엔드포인트에 여러 개선 사항을 제공합니다. 이 새로운 엔드포인트는 새로운 audience 처리 백엔드에 의해 지원되며, 안정성, 견고성, 신뢰성 측면에서 여러 개선 사항을 제공합니다. 이 가이드의 목적은 Audience API와 레거시 audience 업로드 및 관리 프로세스 간의 차이점을 강조하는 것입니다. 참조 문서는 [Audience API](/x-ads-api/audiences) 참조 문서 페이지에서 확인할 수 있습니다. **참고**: 모든 Audience 사용자 데이터는 업로드 전에 SHA-256으로 해시되어야 합니다. 자세한 내용과 허용되는 사용자 식별자 유형 및 데이터 정규화는 [user data](/x-ads-api/audiences) 페이지에서 확인할 수 있습니다. **Audience 기능 변경 사항** Custom Audiences에 대한 다음 변경 사항이 v4부터 도입되었으며, 사용 중단된 엔드포인트는 Ads API v3가 완전히 폐기되면 더 이상 사용할 수 없게 됩니다: * **사용 중단** TON Upload: * 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 * **사용 중단** Real Time Audiences: * POST custom\_audience\_memberships * Custom Audience: * `list_type` 파라미터는 모든 [Custom Audience](/x-ads-api/audiences) 엔드포인트의 요청 및 응답에서 제거됩니다. 이 파라미터는 이전에 Audience의 사용자 식별자 유형(예: 이메일, X User ID 등)을 식별하기 위해 사용되었으나, 이제 Audience는 동일한 Audience에 대해 여러 사용자 식별자를 허용할 수 있어 이 값의 의미가 없어졌습니다. * 일반: * Audience lookback 기간이 지난 90일 동안 활성 사용자와 매칭되도록 업데이트되었습니다(기존 30일에서 변경) * audience가 타깃팅 가능하기 위해 필요한 최소 매칭 사용자 수가 100명으로 감소했습니다(기존 500명에서 변경) **사전 요건** * Ads API 액세스 * Audience 엔드포인트 액세스를 위해 허용 목록에 추가되어야 합니다. 이 양식을 작성하고 2018-08-01 이전에 처음 수락한 경우 새로운 [X Ads Products and Services Agreement](/x-ads-api/introduction)를 수락하세요. **Audience 업로드 프로세스** 다음 표는 이전 및 새로운 Audience 생성 흐름의 주요 차이점을 나열하며, 아래에 더 자세한 내용이 제공됩니다: | 프로세스 단계 | Audience API | (사용 중단) TON Upload | | :---------------- | :---------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------- | | shell Audience 생성 | \[POST custom\_audience 엔드포인트]/x-ads-api/audiences를 통해 생성할 수 있습니다 | \[POST custom\_audience 엔드포인트]/x-ads-api/audiences를 통해 생성할 수 있습니다 | | 새 사용자 추가 | [Audience 엔드포인트](/x-ads-api/audiences)에서 `operation_type` `Update`를 사용합니다 | [POST custom\_audience\_changes](/x-ads-api/audiences) 엔드포인트에서 `operation` `ADD`를 사용합니다 | | 사용자 제거 | [Audience 엔드포인트](/x-ads-api/audiences)에서 `operation_type` `Delete`를 사용합니다 | [POST custom\_audience\_changes](/x-ads-api/audiences) 엔드포인트에서 `operation` `REMOVE`를 사용합니다 | | 사용자 옵트아웃 | [Audience 엔드포인트](/x-ads-api/audiences)에서 `operation_type` `Delete`와 사용자가 속한 해당 `custom_audience_id`들을 사용합니다 | [Global opt-out 엔드포인트](/x-ads-api/audiences)를 사용합니다 | **참고** TON Upload 경로를 통해 업데이트되거나 옵트아웃되는 audience는 [TON Upload](/x-ads-api/audiences) 엔드포인트를 통해 해당 목록이 업로드되어야 하며, [custom\_audience\_changes](/x-ads-api/audiences) 엔드포인트를 사용해 Audience와 연결되어야 합니다. **Rate Limit** Audience API 엔드포인트의 계정당 rate limit은 1500/1분입니다. 단일 페이로드에서 전송할 수 있는 사용자 수에 대한 제한은 없습니다. 페이로드에 대한 유일한 제약 조건은 다음과 같습니다: 1\. 총 작업 수: 2500개 작업 2\. 최대 페이로드 크기: 5,000,000 바이트 **Audience 사용자 관리** 새 Audience를 생성하려면 다음 단계가 필요합니다. ### 새 Custom Audience 생성 \[POST custom\_audience]/x-ads-api/audiences 엔드포인트를 사용해 새 Custom Audience "shell"을 생성하고 해당 Custom Audience `id`를 조회합니다. 이 단계는 처음부터 Audience를 생성하는 경우 필요합니다. 기존 Audience를 업데이트하는 경우 다음 섹션으로 건너뛰세요. ### Audience에 사용자 추가 Custom Audience `id`와 다음과 같은 샘플 페이로드로 [POST accounts/:account\_id/custom\_audiences/:custom\_audience\_id/users](/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) ``` # All values must be hashed, unhashed values are used in this example for illustrative purposes [ { "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`를 사용합니다. #### Audience에서 사용자 제거 사용자 추가에서 설명한 프로세스와 유사하게, 사용자를 다음과 같이 audience에서 제거할 수 있습니다: 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) ``` # All values must be hashed, unhashed values are used in this example for illustrative purposes [ { "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`로 설정되어야 하며 사용자는 Audience에 추가할 때 존재했던 키로 매칭됩니다. 예를 들어, 사용자가 `email`과 `twitter_id`로 audience에 추가된 경우, 이 키 중 어느 하나(즉, `email` 또는 `twitter_id` 또는 둘 다)를 사용하여 동일한 사용자를 제거할 수 있습니다. 또한 동일한 요청 내에서 Audience에 사용자를 추가하고 제거할 수도 있습니다. 엔드포인트는 요청당 여러 `operation_type`을 지원합니다. #### 사용자 옵트아웃 global opt-out 엔드포인트가 사용 중단됨에 따라, 파트너는 모든 Audience에서 옵트아웃한 사용자를 `Delete`해야 합니다. 이를 달성하기 위한 몇 가지 방법이 있습니다: 1. 어떤 사용자가 어떤 Audience에 속해 있는지 추적하고 각 Audience에서 이러한 사용자를 개별적으로 제거합니다. 2. Ads 계정과 연결된 **모든** Audience에서 사용자를 제거합니다. **일반적인 모범 사례** * 처리하는 데 더 오랜 시간이 걸리고 시스템에 불필요한 부하를 주는 급증 큐를 피하기 위해 준실시간 배치로 이 엔드포인트를 호출할 것을 강력히 권장합니다. 이렇게 하면 사용자가 캠페인 타깃팅에 더 빨리 사용 가능해집니다. * 성공적인 API 호출은 요청에서 수신된 `user` 객체 수에 해당하는 `success_count`와 `total_count`를 반환합니다. * 이 엔드포인트는 원자성을 가지며, 즉 전체 요청이 성공하거나 어떤 오류가 있을 경우 전체 요청이 실패합니다. 오류 응답의 경우, API 소비자는 오류를 수정하고 전체 페이로드로 요청을 재시도할 것을 권장합니다. * 실패 시 파트너는 재시도와 함께 [지수 백오프](https://en.wikipedia.org/wiki/Exponential_backoff) 접근 방식을 사용할 것을 권장합니다. 예를 들어 첫 번째 실패 시 즉시 재시도하고, 두 번째 실패 후 1분 후 재시도하고, 세 번째 연속 실패 후 5분 후 재시도하는 방식입니다. *** ## 전체 API 참조 전체 참조(Tailored Audience Permissions, Custom Audiences, Custom Audiences Users, Keyword Insights, Do Not Reach Lists 등)는 **[Audiences API Reference](/x-ads-api/audiences/reference)** 페이지를 참조하세요.