개요
소개
사용 사례
- 크리에이티브
- 타기팅
- 입찰 유형
- 입찰 단위
A/B Testing
사용 사례
- 크리에이티브
- 타기팅
- 입찰 유형
- 입찰 단위
속성
- 테스트 기간: start_time 및 end_time 필드로 표시됨
- 분할이 이루어지는 수준: entity_type 필드로 표시됨
- 최소 두 개(최대 30개)의 사용자 그룹: 각 그룹은 user_groups 배열의 객체로 표시됨
- 해당 사용자 그룹에 할당할 사용자 비율: size 필드로 표시됨
- 해당 사용자 그룹의 사용자 풀을 구성할 캠페인 ID/라인 아이템 ID: entity_ids 배열로 표시됨
사용
생성
- start_time 및 end_time 값은 다음을 만족해야 합니다
- (A/B 테스트 생성 시점을 기준으로) 미래여야 합니다
- 캠페인/라인 아이템의 플라이트 날짜와 겹쳐야 합니다
- 테스트는 앱 비기반 캠페인의 경우 최소 1일, 앱 기반 캠페인의 경우 최소 5일 동안 지속되어야 합니다
- entity_type은 CAMPAIGN 또는 LINE_ITEM으로 설정할 수 있습니다
- 각 사용자 그룹은 user_groups 배열의 객체로 표현됩니다
- 최소 두 개의 사용자 그룹이 필요합니다
- 최대 30개의 사용자 그룹이 허용됩니다
- 각 사용자 그룹의 크기는 1.00과 99.00 사이의 숫자 값을 문자열로 설정합니다
- 참고: 객체 전체의 크기 값 합은 반드시 100.00이어야 합니다
- 캠페인 ID는 각 사용자 그룹의 entity_ids 배열에 지정해야 합니다
- A/B 테스트 캠페인의 모든 라인 아이템이 분할 테스트에 포함되어야 합니다.
- 라인 아이템 수준에서는 균등 분할만 허용됩니다.
- 하나의 분할 테스트에서 허용되는 사용자 그룹 라인 아이템 수는 5개 이하이어야 합니다.
- 사용자 그룹당 라인 아이템은 1개만 허용됩니다.
업데이트
- 객체나 요소를 추가·제거하려면 전체 배열(및 하위 구조)을 전달합니다. 이는 교체 작업입니다.
-
그 외에는 키 이름 또는 ID를 참조하여 기존 필드(변경, 추가, 제거)를 수정합니다.
- 필드를 제거하려면 값을 null로 설정합니다.
- 전달되지 않은 필드는 변경되지 않습니다.
요청 예시
- 이름이나 설명 없이 세 번째 사용자 그룹을 추가합니다
- 각 사용자 그룹의 사용자 비율을 변경합니다
- A/B 테스트 설명을 제거합니다.
- 첫 번째 사용자 그룹에 설명을 추가합니다.
- 두 번째 사용자 그룹에 엔터티 ID(f2syz)를 추가합니다.
- 두 번째 사용자 그룹을 제거합니다
- 각 사용자 그룹의 사용자 비율을 변경합니다
API 레퍼런스
A/B 테스트
GET accounts/:account_id/ab_tests
일부 또는 모든 A/B 테스트의 세부 정보를 조회합니다.리소스 URL
https://ads-api.x.com/12/accounts/:account_id/ab_tests
매개변수
| Name | Description |
|---|---|
| account_id required | 사용 중인 계정의 식별자입니다. 리소스 경로에 표시되며, GET accounts를 제외한 모든 Advertiser API 요청에 일반적으로 필요한 매개변수입니다. 지정한 계정은 인증된 사용자와 연동되어 있어야 합니다. Type: string Example: 18ce54d4x5t |
| ab_test_ids optional | 쉼표로 구분된 식별자 목록을 지정하여 원하는 A/B 테스트만 응답에 포함합니다. 최대 200개의 ID를 제공할 수 있습니다. Type: string Example: hr7l0 |
| count optional | 각 요청당 조회할 레코드 수를 지정합니다. Type: int Default: 200 Min, Max: 1, 1000 |
| cursor optional | 다음 결과 페이지를 가져오기 위한 커서를 지정합니다. 자세한 내용은 Pagination을 참조하세요. Type: string Example: 8x7v00oow |
| live_during optional | 지정한 날짜 범위 동안 진행 중이었거나 진행될 A/B 테스트로 응답을 제한합니다. 시작 및 종료 시간이 해당 날짜 범위와 부분적으로 또는 완전히 겹치는 A/B 테스트를 반환합니다. 값은 ISO 8601 형식의 쉼표로 구분된 날짜로 지정하세요. 이른 날짜를 먼저 지정해야 합니다. Type: string Example: 2020-11-01T08:00:00Z,2020-12-01T08:00:00Z |
| q optional | name으로 리소스를 필터링하는 선택적 쿼리입니다. 모두 가져오려면 이 매개변수를 생략하세요.Type: string Min, Max length: 1, 80 |
| sort_by optional | 지원되는 속성을 기준으로 오름차순 또는 내림차순 정렬합니다. 자세한 내용은 Sorting을 참조하세요. Type: string Example: created_at-asc |
| status optional | 지정한 상태의 A/B 테스트만 응답에 포함합니다. Type: enum Possible values: COMPLETED, LIVE, SCHEDULED |
| user_id optional | 지정한 사용자 ID가 생성한 A/B 테스트만 응답에 포함합니다. Note: username과 동시에 지정할 수 없습니다.Type: long Example: 756201191646691328 |
| username optional | 지정한 사용자 이름이 생성한 A/B 테스트만 응답에 포함합니다. 앞의 ”@” 기호는 포함하지 마세요. Note: user_id와 동시에 지정할 수 없습니다.Type: string Example: apimctestface |
| with_deleted optional | 삭제된 결과를 포함합니다. Type: boolean Default: false Possible values: true, false |
예제 요청
GET https://ads-api.x.com/12/accounts/18ce54d4x5t/ab_tests
예시 응답
POST accounts/:account_id/ab_tests
새 A/B 테스트를 생성합니다. 모든 매개변수는 요청 본문으로 전송되며Content-Type은 application/json이어야 합니다.
리소스 URL
https://ads-api.x.com/12/accounts/:account_id/ab_tests
매개변수
| Name | Description |
|---|---|
| account_id required | 사용 중인 계정의 식별자입니다. 리소스 경로에 포함되며, GET accounts를 제외한 모든 Advertiser API 요청에 일반적으로 필요한 매개변수입니다. 지정된 계정은 인증된 사용자와 연결되어 있어야 합니다. Type: string Example: 18ce54d4x5t |
| end_time required | A/B 테스트가 종료되는 시간(ISO 8601). Type: string Example: 2020-10-02T00:00:00Z |
| entity_type required | 사용자 그룹 분할에 사용할 엔터티 유형입니다. Type: enum Possible values: CAMPAIGN, LINE_ITEM |
| start_time required | A/B 테스트가 시작되는 시간(ISO 8601). Type: string Example: 2022-05-30T00:00:00Z |
| user_groups required | 사용자 그룹을 설명합니다. 자세한 내용은 아래 표를 참조하세요. 사용자 그룹은 2개에서 30개까지 지정할 수 있습니다. Type: array of objects |
| description optional | A/B 테스트에 대한 설명입니다. 최대 길이: 1,024자. Type: string Example: documentation example |
| name optional | A/B 테스트 이름입니다. 최대 길이: 255자. Type: string Example: first AB test |
사용자 그룹
| Name | Description |
|---|---|
| entity_ids required | 엔터티 ID 배열입니다. 참고: 각 엔터티는 하나의 A/B 테스트에만 연결될 수 있습니다. Type: array Example: ["dxi0l", "e66bl"] |
| size required | 이 사용자 그룹에 배정할 사용자 비율입니다. 소수점 이하 최대 두 자리까지의 숫자 값을 문자열로 표기합니다. 예를 들어 40%는 40, 40.0 또는 40.00으로 표기합니다. 참고: 각 객체의 size 값 합계는 반드시 100.00이 되어야 합니다. Type: array Min, Max: 1.00, 99.00 |
| description optional | 사용자 그룹 설명입니다. 최대 길이: 1,024자. Type: string Example: second AB test group |
| name optional | 사용자 그룹 이름입니다. 최대 길이: 255자. Type: string Example: first group |
예시 요청
POST https://ads-api.x.com/12/accounts/18ce54d4x5t/ab_tests -d '{"end_time": "2022-05-30T01:00:00Z", "entity_type" : "CAMPAIGN", "start_time": "2022-05-25T01:00:00Z", "user_groups": [{"entity_ids": ["f2qcw", "f2tht"], "size": "50.00", "name": "first group"},{"entity_ids": ["f2rqi", "f2tws"], "size": "50.00", "name": "second group", "description": "second AB test group"}], "name": "first AB test", "description": "documentation example"}'
예시 응답
PUT accounts/:account_id/ab_tests/:ab_test_id
지정된 A/B 테스트를 업데이트합니다. 모든 매개변수는 요청 본문으로 전송되며Content-Type은 application/json이어야 합니다.
이 엔드포인트는 객체 ID가 포함된 부분 JSON을 지원합니다. 다음 원칙이 적용됩니다.
- 객체나 요소를 추가하거나 제거하려면 전체 배열(및 하위 구조 전체)을 전달하세요. 이는 대체 작업입니다.
- 배열을 다시 생성한다고 생각하면 됩니다.
- 그 외의 경우에는 키 이름이나 ID를 참조하여 기존 필드를 수정(변경, 추가, 제거)하세요.
- 필드를 제거하려면 해당 값을
null로 설정하세요. - 전달되지 않은 필드는 변경되지 않습니다.
- 필드를 제거하려면 해당 값을
status가 SCHEDULED일 때만 업데이트할 수 있습니다. 한 가지 예외로, LIVE 상태일 때도 A/B 테스트의 end_time은 업데이트할 수 있습니다.
리소스 URL
https://ads-api.x.com/12/accounts/18ce54d4x5t/:ab_test_id
매개변수
| 이름 | 설명 |
|---|---|
| account_id required | 레버리지드 계정의 식별자입니다. 리소스 경로에 포함되며, GET accounts를 제외한 모든 Advertiser API 요청에서 일반적으로 필수 매개변수입니다. 지정된 계정은 인증된 사용자와 연결되어 있어야 합니다. 유형: string 예시: 18ce54d4x5t |
| ab_test_id required | 요청에서 사용 중인 A/B 테스트에 대한 참조입니다. 유형: string 예시: hr7l0 |
| description optional | A/B 테스트의 설명입니다. 최대 길이: 1,024자. 참고: A/B 테스트의 status가 SCHEDULED일 때에만 업데이트할 수 있습니다.유형: string 예시: documentation example |
| end_time optional | A/B 테스트가 종료되는 시간(ISO 8601 형식)입니다. 참고: A/B 테스트의 status가 SCHEDULED 또는 LIVE일 때에만 업데이트할 수 있습니다.유형: string 예시: 2020-10-02T00:00:00Z |
| name optional | A/B 테스트의 이름입니다. 최대 길이: 255자. 참고: A/B 테스트의 status가 SCHEDULED일 때에만 업데이트할 수 있습니다.유형: string 예시: first AB test |
| start_time optional | A/B 테스트가 시작되는 시간(ISO 8601 형식)입니다. 참고: A/B 테스트의 status가 SCHEDULED일 때에만 업데이트할 수 있습니다.유형: string 예시: 2022-05-30T00:00:00Z |
| user_groups required | 사용자 그룹을 설명합니다. 아래 표에서 자세한 정보를 확인하세요. 참고: A/B 테스트의 status가 SCHEDULED일 때에만 업데이트할 수 있습니다.유형: 객체 배열 |
사용자 그룹
| 이름 | 설명 |
|---|---|
| id 때때로 필요 | 요청에서 작업 중인 사용자 그룹 객체를 참조합니다. 참고: 사용자 그룹 객체의 필드를 수정(변경, 추가, 제거)할 때 필요합니다. 참고: 전체 사용자 그룹 객체를 추가하거나 제거할 때는 ID를 지정하지 마세요. 유형: string 예시: p1bcx |
| description 선택 사항 | 사용자 그룹의 설명입니다. 최대 길이: 1,024자. 참고: 해당 필드를 null 값으로 지정하면 설정이 해제(제거)됩니다.유형: string 예시: second AB test group |
| entity_ids 선택 사항 | 엔터티 ID 배열입니다. 참고: 이 작업은 대체입니다. 이전에 설정된 값은 모두 덮어씁니다. 참고: 엔터티는 하나의 A/B 테스트에만 연결될 수 있습니다. 유형: array 예시: ["dxi0l", "e66bl"] |
| name 선택 사항 | 사용자 그룹의 이름입니다. 최대 길이: 255자. 참고: 해당 필드를 null 값으로 지정하면 설정이 해제(제거)됩니다.유형: string 예시: first group |
| size 선택 사항 | 이 사용자 그룹에 할당할 사용자 비율입니다. 소수점 이하 최대 두 자리의 숫자 값을 문자열로 표현합니다. 예: 40% → 40, 40.0, 40.00. 참고: 객체 간 크기 값의 합은 반드시 100.00이어야 합니다. 유형: string 최솟값, 최댓값: 1.00, 99.00 |
예시 요청
이 요청은 다음과 같은 변경을 수행합니다.- A/B 테스트 설명을 제거합니다.
- 종료 시간을 변경합니다.
- 첫 번째 사용자 그룹에 설명을 추가합니다.
- 각 사용자 그룹의 사용자 비율을 변경합니다.
- 두 번째 사용자 그룹에 엔터티 ID(
f2syz)를 추가합니다.
PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/ab_tests/hr7l0 -d '{"description": null, "end_time": "2022-06-01T01:00:00Z", "user_groups": [{"id": "p1bcx", "description": "first AB test group", "size": "60.00"},{"id": "p1bcy", "size": "40.00", "entity_ids": ["f2rqi", "f2tws", "f2syz"]}]}'
응답 예시
DELETE accounts/:account_id/ab_tests/:ab_test_id
지정된 A/B 테스트를 삭제합니다. 참고: A/B 테스트 삭제는 되돌릴 수 없으며, 이후 이 리소스를 다시 삭제하려는 시도는 HTTP 404를 반환합니다.리소스 URL
https://ads-api.x.com/12/accounts/:account_id/ab_tests/:ab_test_id
매개변수
| 이름 | 설명 |
|---|---|
| ab_test_id required | 이 요청에서 사용 중인 A/B 테스트에 대한 참조입니다. 유형: string 예시: hr7l0 |
예시 요청
DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/ab_tests/hr7l0