Audiences

​

빠른 링크

• 전체 API 참조 — 모든 Audience 엔드포인트와 객체
• 가이드 — CRM, Web, Mobile, ID Sync, User Data 업로드, FAQ

​

Custom Audiences

​

개요

• Audience API (CRM)
• Web
• Mobile
• Flexible

• GET accounts/:account_id/custom_audiences
• GET accounts/:account_id/custom_audiences/:custom_audience_id

​

Audiences FAQ

• 전달된 사용자 ID가 정확하고 잘못된 형식이 아닌지 확인합니다.
• 전달된 audience 이름이 정확하고 이전 멤버십 업데이트와 일치하는지 확인합니다.
• POST 명령의 응답을 확인합니다.
• ID Sync 픽셀이 올바르게 구현되었는지, 그리고 ID Sync 프로세스에서 설명한 대로 해당 사이트를 방문한 사용자가 충분히 많아 사용자 매핑이 이루어졌는지 확인합니다. 멤버십 업데이트에서 매핑되지 않은 사용자는 타깃팅된 사용자로 변환되지 않습니다.

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

• audience 파일 처리에는 일반적으로 4-6시간이 소요되지만, 파일 크기에 따라 다릅니다. 파일이 처리되면 X Ads UI에서 audience를 사용할 수 있습니다.

• Match Rate = 90일 활성 X 사용자 / 제공된 사용자 수

• 테스트 audience 파일을 제공하고 광고주 핸들로 “keltonlynn”을 사용할 수 있습니다. 그러면 파일이 제대로 수집되고 X UI에 로드될 수 있는지 확인할 수 있습니다.

• 이는 회사에서 각 고객을 고유하게 식별하기 위해 사용되는 식별자입니다.

• 이는 이메일 주소, 디바이스 ID, X @핸들 또는 ID가 될 수 있습니다.

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

• X는 테스트 파일(샘플 이메일 주소, 디바이스 ID 등 포함)과 결과 해시 파일을 제공하여 결과를 검증할 수 있게 합니다.

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

• X가 파일을 수신하면 파일을 처리하는 데 약 1일이 소요됩니다.

​

CRM

​

파트너 ID 매칭 요구 사항

• 예: 사용자 레코드 A가 파트너 사용자 ID 1과 공통 식별자 1, 2, 3을 가진 경우:

• 줄 구분 값
• p_user_id
• • (위 1. 전체 데이터 매칭 섹션에서 제공된 것과 동일합니다. 전체 데이터 매칭에서 제공된 값이 해시된 경우, Company는 audience 파일에서도 동일한 해시 값을 제공합니다. 제공된 값이 해시되지 않은 경우, Company는 해시되지 않은 값을 제공합니다.)

​

표준 매칭 요구 사항

• 줄 구분 값
• 해시된 공통 사용자 식별자 (예: 이메일 주소)
• 아래에 설명된 파일 이름 규칙을 따르세요
• 아래(해싱 지침 부분)의 이메일 주소 해싱 지침을 따르세요

​

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

• 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 생성 및 업데이트

• 광고주로부터 옵트아웃한 사용자의 종합 목록에 사용할 수 있습니다.
• X는 이 파일에서 가장 최근에 제공된 목록만 반영하며, 매칭된 기존 및 미래의 모든 audience에 걸쳐 반영됩니다.

​

해싱 지침

​

이메일 정규화

​

디바이스 ID 정규화

​

X User ID 정규화

• User ID: 27674040
• @username: testusername

​

ID Sync 통합

• 웹 전용: 아래에 설명된 것처럼 광고주의 사이트에 픽셀을 배치하여 수행할 수 있습니다.
• List: CRM 페이지에 설명된 방법 중 하나를 사용해 수행할 수 있습니다.

​

픽셀 URL

​

픽셀 파라미터

​

ID Sync 픽셀:

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

​

Custom Audiences User Data

• IDFA - 대시가 포함된 소문자; 예: 4b61639e-47cc-4056-a16a-c8217e029462
• AdID - 디바이스의 원본 형식이 필요하며, 대시가 포함된 대문자로 변환하지 않음; 예: 2f5f5391-3e45-4d02-b645-4575a08f86e
• Android id - 디바이스의 원본 형식이 필요하며, 대시나 공백 없이 대문자로 변환하지 않음; 예: af3802a465767e36

• 소문자, 앞뒤 공백 제거; 예: support@x.com

• @ 없이, 소문자와 앞뒤 공백 제거; 예: jack

• 표준 정수; 예: 143567

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

#output
49e0be2aeccfb51a8dee4c945c8a70a9ac500cf6f5cb08112575f74db9b1470d

​

Custom Audiences: Web

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

1. 파트너 타깃팅 사용자 파일
2. 타깃팅 전환 파일

• 199.16.156.0/22
• 199.59.148.0/22

​

Audience API 통합

​

개요

• 사용 중단 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 엔드포인트의 요청 및 응답에서 제거됩니다. 이 파라미터는 이전에 Audience의 사용자 식별자 유형(예: 이메일, X User ID 등)을 식별하기 위해 사용되었으나, 이제 Audience는 동일한 Audience에 대해 여러 사용자 식별자를 허용할 수 있어 이 값의 의미가 없어졌습니다.
• 일반:
  • Audience lookback 기간이 지난 90일 동안 활성 사용자와 매칭되도록 업데이트되었습니다(기존 30일에서 변경)
  • audience가 타깃팅 가능하기 위해 필요한 최소 매칭 사용자 수가 100명으로 감소했습니다(기존 500명에서 변경)

​

새 Custom Audience 생성

​

Audience에 사용자 추가

    # 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에서 사용자 제거

    # 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"
              ]
            }
          ]
        }
      }
    ]

​

사용자 옵트아웃

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

• 처리하는 데 더 오랜 시간이 걸리고 시스템에 불필요한 부하를 주는 급증 큐를 피하기 위해 준실시간 배치로 이 엔드포인트를 호출할 것을 강력히 권장합니다. 이렇게 하면 사용자가 캠페인 타깃팅에 더 빨리 사용 가능해집니다.
• 성공적인 API 호출은 요청에서 수신된 user 객체 수에 해당하는 success_count와 total_count를 반환합니다.
• 이 엔드포인트는 원자성을 가지며, 즉 전체 요청이 성공하거나 어떤 오류가 있을 경우 전체 요청이 실패합니다. 오류 응답의 경우, API 소비자는 오류를 수정하고 전체 페이로드로 요청을 재시도할 것을 권장합니다.
• 실패 시 파트너는 재시도와 함께 지수 백오프 접근 방식을 사용할 것을 권장합니다. 예를 들어 첫 번째 실패 시 즉시 재시도하고, 두 번째 실패 후 1분 후 재시도하고, 세 번째 연속 실패 후 5분 후 재시도하는 방식입니다.

​

전체 API 참조