A/B 테스트

​

개요

​

소개

A/B 테스트를 사용하면 광고주가 X에서 도달하고 있는 사용자를 세분화하여, 캠페인 성과를 어떻게 최적으로 최적화할 수 있는지 파악하고 마케팅 전략 수립에 필요한 인사이트를 수집할 수 있습니다.

이러한 세분화는 사용자 그룹 분할(user group split)이라 부르며, 무작위(randomized)이고 상호 배타적입니다. 무작위화를 통해 결과에 영향을 미치는 요인들이 각 그룹에 고르게 분포하게 됩니다. 즉, 그룹 간이나 각 그룹의 예상 행동 간에 본질적인 차이가 없습니다. 따라서 특정 변형안(variation)을 한 사용자 그룹에만 적용하고 다른 그룹에는 적용하지 않았을 때, 캠페인 성과의 차이는 해당 변형안에 기인한 것이라고 볼 수 있습니다.

한 번에 여러 변형안을 테스트하는 것도 가능하지만, 한 번에 하나의 변형안만 테스트할 것을 강력히 권장합니다. 이렇게 해야 관찰된 캠페인 성과 차이에 대한 인과 요인을 명확히 분리할 수 있습니다.

변형안은 캠페인 수준에서 설정합니다. 예를 들어, 광고주가 새로운 크리에이티브의 효과를 테스트하고자 할 경우, 크리에이티브만 다르고 나머지 설정은 모두 동일한 두 개의 캠페인을 생성해야 합니다. 향후에는 라인 아이템(line item) 수준의 변형안 설정도 지원할 계획입니다.

​

사용 사례

A/B 테스트는 주로 (1) X에서 어떤 방식이 가장 효과적인지 파악해 투자를 최적화하려는 퍼포먼스 광고주의 최적화 관련 사용 사례와, (2) 학습 결과를 마케팅 전략 수립에 반영하려는 브랜드 광고주의 인사이트 도출 관련 사용 사례를 지원하는 데 사용됩니다. 

API는 다음을 포함한 모든 캠페인 변수에 대한 A/B 테스트를 지원합니다.

• 크리에이티브 

• 타기팅 

• 입찰 유형

• 입찰 단위

​

A/B Testing

A/B Testing은 광고주가 X에서 도달하는 사용자를 세분화하여 캠페인 성과를 최적화하는 최적 방안을 파악하고, 마케팅 전략 수립에 활용할 수 있는 인사이트를 수집할 수 있도록 해줍니다.

이러한 세그먼트는 사용자 그룹 분할(user group splits)이라고 하며, 무작위로 배정되고 서로 배타적입니다. 무작위 배정을 통해 결과에 영향을 미치는 요인들이 각 그룹에 고르게 분포하게 됩니다. 즉, 그룹 간이나 예상 행동 간에 본질적인 차이가 없습니다. 따라서 하나의 변형(variation)만 특정 사용자 그룹에 적용하고 다른 그룹에는 적용하지 않은 경우, 캠페인 성과의 차이는 해당 변형에 기인한다고 볼 수 있습니다.

여러 변형을 동시에 테스트하는 것도 가능하지만, 한 번에 하나의 변형만 테스트할 것을 강력히 권장합니다. 이렇게 하면 관찰된 캠페인 성과 차이를 야기한 인과 요인을 명확히 분리해낼 수 있습니다.

변형은 캠페인 수준 또는 광고 그룹(ad group) 수준에서 설정할 수 있습니다. 광고 그룹은 Ads API의 line item을 통해 설정합니다. 광고 그룹 수준 변형의 예로, 광고주가 새로운 크리에이티브의 효과를 테스트하고자 한다면, 크리에이티브만 다른 2개의 동일한 광고 그룹을 포함하는 하나의 캠페인을 생성해야 합니다.

​

사용 사례

A/B 테스트는 주로 (1) X에서 어떤 요소가 가장 효과적인지 파악해 투자 효율을 극대화하려는 성과 중심 광고주의 최적화 사용 사례와, (2) 테스트 결과를 바탕으로 마케팅 전략 수립에 활용하려는 브랜드 광고주의 학습 사용 사례를 지원하는 데 사용됩니다. 

이 API는 다음을 포함한 모든 캠페인 변수에 대해 A/B 테스트를 지원합니다.

• 크리에이티브

• 타게팅

• 입찰 유형

• 입찰 단위

​

속성

A/B 테스트는 중첩 구조로 표현됩니다. A/B 테스트 자체에 대한 최상위 필드와, 각각을 설명하는 필드 집합을 가진 사용자 그룹 객체 배열이 있습니다.

개략적으로, 모든 A/B 테스트에는 다음 정보가 포함되어야 합니다.

• 테스트 기간으로, start_time 및 end_time 필드로 표현됩니다.

• 분할이 이루어지는 수준으로, entity_type 필드로 표현됩니다.

• 최소 2개(최대 30개)의 사용자 그룹으로, 각각 user_groups 배열의 객체로 표현됩니다.

각 사용자 그룹에는 다음 정보가 반드시 포함되어야 합니다.

• 해당 사용자 그룹에 할당되어야 하는 사용자 비율로, size 필드로 표현됩니다.

• 해당 사용자 그룹의 사용자 풀을 구성하는 캠페인 ID/라인 아이템 ID로, entity_ids 배열로 표현됩니다.

선택적으로, A/B 테스트 및 사용자 그룹에 대해 name 및 description 값을 설정할 수 있습니다. 유효성 검사 규칙 및 기타 제약 조건에 대한 정보는 아래에서 확인할 수 있습니다.

ID나 생성 시각과 같은 기타 메타데이터도 포함되지만, 이는 X에서 자동으로 설정합니다.

캠페인 수준에 대한 A/B 테스트 엔티티 예시는 아래에 나와 있습니다.

{
  "created_at": "2020-12-01T00:00:00Z",
  "created_by": {
    "user_id": "756201191646691328",
    "username": "apimctestface"
  },
  "deleted": false,
  "description": "documentation example",
  "end_time": "2020-12-05T01:00:00Z",
  "entity_type": "CAMPAIGN",
  "id": "hr7l0",
  "name": "first AB test",
  "start_time": "2020-12-01T01:00:00Z",
  "status": "SCHEDULED",
  "user_groups": [
    {
      "id": "p1bcx",
      "name": "first group",
      "description": null,
      "size": "50.0",
      "entity_ids": [
        "f2qcw",
        "f2tht"
      ]
    },
    {
      "id": "p1bcy",
      "name": "second group",
      "description": "second AB test group",
      "size": 50,
      "entity_ids": [
        "f2rqi",
        "f2tws"
      ]
    }
  ],
  "updated_at": "2020-12-01T00:00:00Z",
  "updated_by": {
    "user_id": "756201191646691328",
    "username": "apimctestface"
  }
}

다음은 라인 아이템 수준 A/B 테스트 엔티티의 예시입니다.

{
   "created_by":{
      "user_id":"756201191646691328",
      "username":"apimctestface"
   },
   "name":"Test2e",
   "start_time":"2022-08-15T00:00:00Z",
   "updated_by":{
      "user_id":"756201191646691328",
      "username":"apimctestface"
   },
   "description":"My Second AB test",
   "entity_type":"LINE_ITEM",
   "end_time":"2022-08-30T00:00:00Z",
   "id":"1ul",
   "user_groups":[
      {
         "name":"first group",
         "size":"50.0",
         "description":"first group description",
         "entity_ids":[
            "ij9dh"
         ],
         "id":"4xe"
      },
      {
         "name":"second group",
         "size":"50.0",
         "description":"second group description",
         "entity_ids":[
            "ihng8"
         ],
         "id":"4xf"
      }
   ],
   "status":"SCHEDULED",
   "created_at":"2022-08-11T00:10:50Z",
   "updated_at":"2022-08-11T00:10:50Z",
   "deleted":false
}

​

사용 방법

아래 섹션에서는 A/B 테스트를 생성하고 업데이트하는 방법을 설명합니다. 조회와 삭제는 다른 Ads API 엔드포인트와 동일하게 동작합니다.

​

생성

POST accounts/:account_id/ab_tests 엔드포인트를 사용해 A/B 테스트를 생성합니다. 이 엔드포인트는 JSON POST 본문만 허용합니다. Content-Type은 application/json으로 설정해야 합니다.

광고주가 두 개 이상의 캠페인을 설정한 후 A/B 테스트를 생성할 수 있습니다. 위에서 언급했듯이 A/B 테스트에는 반드시 테스트 기간, 분할 수준(split level), 그리고 최소 두 개의 사용자 그룹이 포함되어야 합니다. 각 사용자 그룹은 자신에게 할당할 사용자 비율과 해당 사용자 풀을 구성할 캠페인 ID를 명시해야 합니다. 각 항목에 대해서는 아래에서 더 자세히 설명합니다.

테스트 기간:

• start_time 및 end_time 값은 다음을 만족해야 합니다.

  • (A/B 테스트가 생성되는 시점 기준으로) 미래 시점이어야 합니다.

  • 캠페인/라인 아이템의 집행 기간(flight dates)과 겹쳐야 합니다.

• 테스트는 앱 기반이 아닌 캠페인의 경우 최소 1일, 앱 기반 캠페인의 경우 최소 5일 동안 진행되어야 합니다.

분할 수준:

• entity_type은 CAMPAIGN 또는 LINE_ITEM으로 설정할 수 있습니다.

사용자 그룹:

• 각 사용자 그룹은 user_groups 배열 내의 하나의 객체로 표현됩니다.

  • 최소 두 개의 사용자 그룹이 필요합니다.

  • 최대 30개의 사용자 그룹까지 허용됩니다.

• 각 사용자 그룹의 크기는 1.00 이상 99.00 이하의 숫자 값을 문자열로 표현하여 설정합니다.

  • 참고: 모든 객체에 걸친 size 값의 합은 반드시 100.00이 되어야 합니다.

• 캠페인 ID는 각 사용자 그룹의 entity_ids 배열에 지정해야 합니다.

선택적으로, A/B 테스트 자체나 하나 이상의 사용자 그룹에 대해 name과 description을 설정할 수 있습니다.

다음 요청은 캠페인 수준에서 A/B 테스트를 생성하며, 4일 동안 진행되고 각 그룹에 전체 사용자의 50%가 포함된 두 개의 사용자 그룹을 갖습니다. 첫 번째 사용자 그룹은 캠페인 f2qcw와 f2tht를 기반으로 하고, 두 번째 사용자 그룹은 캠페인 f2rqi와 f2tws를 기반으로 합니다. 이 요청은 또한 엔티티의 일부에 이름과 설명을 추가합니다.

twurl -X POST -H ads-api.x.com “/8/accounts/18ce54d4x5t/ab_tests” -d ’{“end_time”: “2020-12-05T01:00:00Z”, “entity_type” : “CAMPAIGN”, “start_time”: “2020-12-01T01: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”}’

twurl -X POST -H ads-api.x.com "/8/accounts/18ce54d4x5t/ab_tests" -d '{"end_time": "2020-12-05T01:00:00Z", "entity_type" : "CAMPAIGN", "start_time": "2020-12-01T01: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"}'

{
  "request": {
    "params": {
      "account_id": "18ce54d4x5t",
      "end_time": "2020-12-05T01:00:00Z",
      "entity_type": "CAMPAIGN",
      "start_time": "2020-12-01T01:00:00Z",
      "user_groups": [
        {
          "entity_ids": [
            "f2qcw",
            "f2tht"
          ],
          "size": "50.0",
          "name": "first group"
        },
        {
          "entity_ids": [
            "f2rqi",
            "f2tws"
          ],
          "size": "50.0",
          "name": "second group",
          "description": "second AB test group"
        }
      ],
      "name": "first AB test",
      "description": "documentation example"
    }
  },
  "data": {
    "created_at": "2020-12-01T00:00:00Z",
    "created_by": {
      "user_id": "756201191646691328",
      "username": "apimctestface"
    },
    "deleted": false,
    "description": "documentation example",
    "end_time": "2020-12-05T01:00:00Z",
    "entity_type": "CAMPAIGN",
    "id": "hr7l0",
    "name": "first AB test",
    "start_time": "2020-12-01T01:00:00Z",
    "status": "SCHEDULED",
    "user_groups": [
      {
        "id": "p1bcx",
        "name": "first group",
        "description": null,
        "size": "50.0",
        "entity_ids": [
          "f2qcw",
          "f2tht"
        ]
      },
      {
        "id": "p1bcy",
        "name": "second group",
        "description": "second AB test group",
        "size": "50.0",
        "entity_ids": [
          "f2rqi",
          "f2tws"
        ]
      }
    ],
    "updated_at": "2020-12-01T00:00:00Z",
    "updated_by": {
      "user_id": "756201191646691328",
      "username": "apimctestface"
    }
  }
}

라인 아이템 수준의 A/B 테스트용

캠페인 수준과 라인 아이템 수준에서의 A/B 테스트의 주요 차이점은 entity_type입니다. 라인 아이템 수준에서 A/B 테스트를 수행하려면 entity_type = LINE_ITEM으로 설정해야 합니다. 이는 아래에 설명된, 이미 생성된 A/B 테스트에 대해 수행하는 모든 작업에 적용됩니다. 

요구 사항:

1. A/B 테스트 캠페인의 모든 라인 아이템이 스플릿 테스트에 포함되어야 합니다.
2. 라인 아이템 수준에서는 균등 분할만 허용됩니다.
3. 하나의 스플릿 테스트에서 사용자 그룹별로 허용되는 라인 아이템 수는 최대 5개입니다. 
4. 각 사용자 그룹에는 라인 아이템을 1개만 설정할 수 있습니다.

​

업데이트

PUT accounts/:account_id/ab_tests/:ab_test_id 엔드포인트를 사용해 A/B 테스트를 업데이트합니다. 이 엔드포인트를 호출할 때는 요청 본문에 JSON blob을 포함해 전송해야 합니다. Content-Type은 application/json으로 설정해야 합니다.

다른 업데이트 엔드포인트와 마찬가지로, PUT accounts/:account_id/ab_tests/:ab_test_id 엔드포인트를 사용할 때는 URL에 A/B 테스트 ID를 포함해야 합니다. 일반적으로 A/B 테스트는 상태가 SCHEDULED일 때만 업데이트할 수 있습니다. 단, 상태가 LIVE일 때 end_time을 업데이트하는 것은 예외적으로 허용됩니다.

이 엔드포인트는 object ID를 포함하는 부분 JSON을 지원합니다. 다음 원칙이 적용됩니다.

• 객체나 요소를 추가하거나 제거하려면 전체 배열(및 그 하위 구조)을 전달해야 합니다. 이는 대체(replacement) 작업입니다.

• 그 밖의 경우에는 키 이름 또는 ID를 참조해 기존 필드를 수정(변경, 추가, 제거)합니다.

  • 필드를 제거하려면 그 값을 null로 설정합니다.

  • 전달되지 않은 필드는 수정되지 않습니다.

예를 들어, 이전에 생성한 A/B 테스트에 세 번째 사용자 그룹을 추가하려면, 기존 두 개의 사용자 그룹 객체와 새로 추가하려는 사용자 그룹을 모두 포함하는 user_groups 배열을 전송해야 합니다. 이를 user_groups 배열을 재생성하는 것으로 생각하면 됩니다. 처음부터 이렇게 생성하는 것처럼 데이터를 전달해야 하며(사용자 그룹 object ID는 전달하지 마십시오). 업데이트 요청의 user_groups 배열은 다음과 같이 표현할 수 있습니다.

[
  {
    "entity_ids": [
      "f2qcw",
      "f2tht"
    ],
    "size": "30.0",
    "name": "first group"
  },
  {
    "entity_ids": [
      "f2rqi",
      "f2tws"
    ],
    "size": "30.0",
    "name": "second group",
    "description": "second AB test group"
  },
  {
    "entity_ids": [
      "i1vwr",
      "i1xre"
    ],
    "size": "40.0"
  }
]

여러 객체의 size 값 합계가 여전히 100.00이 되는지에 주목하세요. 만약 첫 두 객체(이전에 각각 50.00으로 설정되어 있던 값)를 업데이트하지 않고 그대로 두었다면, 이 요청은 실패했을 것입니다.

반대로, 첫 번째 사용자 그룹에 설명만 추가하려는 경우라면, 업데이트 요청의 user_groups 배열은 다음과 같이 표현됩니다.

[
  {
    "id": "p1bcx",
    "description": "PUT 요청으로 업데이트됨"
  }
]

user group 객체는 id로 참조하고, 수정하려는 필드만 요청에 포함합니다.

​

요청 예시

이 섹션에서는 추가적인 업데이트 요청 예시를 제공합니다. 이 예시들은 순차적으로 호출된다고 가정하면 됩니다. JSON 데이터는 가독성을 위해 포맷되어 있으며, 응답은 생략되어 있습니다.

다음과 같은 수정 작업을 수행하려면 요청은 다음과 같이 표현됩니다. (위에서 사용한 예시와 동일합니다.)

1. 이름이나 설명 없이 세 번째 사용자 그룹을 추가합니다.

2. 각 사용자 그룹에 속한 사용자 비율을 변경합니다.

twurl -X PUT -H ads-api.x.com “/8/accounts/18ce54d4x5t/ab_tests/hr7l0” -d ’

twurl -X PUT -H ads-api.x.com "/8/accounts/18ce54d4x5t/ab_tests/hr7l0" -d '
{
  "user_groups": [
    {
      "entity_ids": [
        "f2qcw",
        "f2tht"
      ],
      "size": "30.00",
      "name": "first group"
    },
    {
      "entity_ids": [
        "f2rqi",
        "f2tws"
      ],
      "size": "30.00",
      "name": "second group",
      "description": "second AB test group"
    },
    {
      "entity_ids": [
        "i1vwr",
        "i1xre"
      ],
      "size": "40.00"
    }
  ]
}'

다음과 같은 수정을 적용하려면 요청은 다음과 같이 작성합니다.

1. A/B 테스트 설명을 제거합니다.

2. 첫 번째 사용자 그룹에 설명을 추가합니다.

3. 두 번째 사용자 그룹에 엔터티 ID(f2syz)를 추가합니다.

twurl -X PUT -H ads-api.x.com “/8/accounts/18ce54d4x5t/ab_tests/hr7l0” -d ’

twurl -X PUT -H ads-api.x.com "/8/accounts/18ce54d4x5t/ab_tests/hr7l0" -d '
{
  "description": null,
  "user_groups": [
    {
      "id": "p1bcx",
      "description": "first AB test group"
    },
    {
      "id": "p1bcy",
      "entity_ids": [
        "f2rqi",
        "f2tws",
        "f2syz"
      ]
    }
  ]
}'

세 번째 변경 사항에서는 새 엔터티 ID와 함께 기존의 두 엔터티 ID를 모두 전달해야 합니다. 세 번째 사용자 그룹에는 아무런 변경도 이루어지지 않았다는 점에 유의하세요.

다음 변경 사항을 적용하기 위한 요청은 다음과 같이 표현됩니다.

1. 두 번째 사용자 그룹을 제거합니다

2. 각 사용자 그룹에 속한 사용자 비율을 변경합니다

twurl -X PUT -H ads-api.x.com "/8/accounts/18ce54d4x5t/ab_tests/hr7l0" -d '
{
  "user_groups": [
    {
      "entity_ids": [
        "f2qcw",
        "f2tht"
      ],
      "size": "55.00",
      "name": "first group"
    },
    {
      "entity_ids": [
        "i1vwr",
        "i1xre"
      ],
      "size": "45.00"
    }
  ]
}'

​

API 참조 문서

​

A/B 테스트

​

GET accounts/:account_id/ab_tests

일부 또는 전체 A/B 테스트에 대한 세부 정보를 조회합니다.

리소스 URL

https://ads-api.x.com/12/accounts/:account_id/ab_tests

Parameters

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	지정된 user ID로 생성된 A/B 테스트로 응답 범위를 제한합니다. Note: username과 동시에 지정할 수 없습니다. Type: long Example: `756201191646691328.
username optional	지정된 username으로 생성된 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

예시 응답

    {
      "request": {
        "params": {
          "account_id": "18ce54d4x5t"
        }
      },
      "data": [
        {
          "created_at": "2022-05-25T00:00:00Z",
          "created_by": {
            "user_id": "756201191646691328",
            "username": "apimctestface"
          },
          "deleted": false,
          "description": "documentation example",
          "end_time": "2022-05-30T01:00:00Z",
          "entities": [
            {
              "id": "p1bcx",
              "account_id": "18ce54d4x5t"
            },
            {
              "id": "p1bcy",
              "account_id": "18ce54d4x5t"
            }
          ],
          "entity_type": "CAMPAIGN",
          "id": "hr7l0",
          "name": "first AB test",
          "start_time": "2022-05-25T01:00:00Z",
          "status": "SCHEDULED",
          "user_groups": [
            {
              "id": "p1bcx",
              "name": "first group",
              "description": null,
              "size": "50.0",
              "entity_ids": [
                "f2qcw",
                "f2tht"
              ]
            },
            {
              "id": "p1bcy",
              "name": "second group",
              "description": "두 번째 AB 테스트 그룹",
              "size": "50.0",
              "entity_ids": [
                "f2rqi",
                "f2tws"
              ]
            }
          ],
          "updated_at": "2022-05-25T00:00:00Z",
          "updated_by": {
            "user_id": "756201191646691328",
            "username": "apimctestface"
          }
        }
      ],
      "next_cursor": null
    }

​

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입니다. 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으로 표현할 수 있습니다. 참고: objects 전체에서 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"}'

​

응답 예시

    {
      "request": {
        "params": {
          "account_id": "18ce54d4x5t",
          "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.0",
              "name": "first group"
            },
            {
              "entity_ids": [
                "f2rqi",
                "f2tws"
              ],
              "size": "50.0",
              "name": "second group",
              "description": "second AB test group"
            }
          ],
          "name": "first AB test",
          "description": "documentation example"
        }
      },
      "data": {
        "created_at": "2022-05-25T00:00:00Z",
        "created_by": {
          "user_id": "756201191646691328",
          "username": "apimctestface"
        },
        "deleted": false,
        "description": "documentation example",
        "end_time": "2022-05-30T01:00:00Z",
        "entities": [
          {
            "id": "p1bcx",
            "account_id": "18ce54d4x5t"
          },
          {
            "id": "p1bcy",
            "account_id": "18ce54d4x5t"
          }
        ],
        "entity_type": "CAMPAIGN",
        "id": "hr7l0",
        "name": "first AB test",
        "start_time": "2022-05-25T01:00:00Z",
        "status": "SCHEDULED",
        "user_groups": [
          {
            "id": "p1bcx",
            "name": "first group",
            "description": null,
            "size": "50.0",
            "entity_ids": [
              "f2qcw",
              "f2tht"
            ]
          },
          {
            "id": "p1bcy",
            "name": "second group",
            "description": "second AB test group",
            "size": "50.0",
            "entity_ids": [
              "f2rqi",
              "f2tws"
            ]
          }
        ],
        "updated_at": "2022-05-25T00:00:00Z",
        "updated_by": {
          "user_id": "756201191646691328",
          "username": "apimctestface"
        }
      }
    }

​

PUT accounts/:account_id/ab_tests/:ab_test_id

지정된 A/B 테스트를 업데이트합니다.

모든 매개변수는 요청 본문으로 전송되며, Content-Type은 application/json이어야 합니다.

이 엔드포인트는 객체 ID를 포함하는 부분 JSON을 지원합니다. 다음 원칙이 적용됩니다:

• 객체나 요소를 추가하거나 제거하려면 전체 배열(및 해당 하위 구조)을 전달해야 하며, 이는 대체 작업입니다
  • 배열을 다시 생성한다고 생각하면 됩니다
• 그 외의 경우, 키 이름 또는 ID를 참조하여 기존 필드를 수정(변경, 추가, 제거)합니다
  • 필드를 제거하려면 해당 값을 null로 설정합니다
  • 전달되지 않은 필드는 수정되지 않습니다

일반적으로 A/B 테스트는 status가 SCHEDULED일 때만 업데이트할 수 있습니다. 예외가 하나 있는데, A/B 테스트가 LIVE인 동안에도 end_time은 업데이트할 수 있습니다.

리소스 URL

https://ads-api.x.com/12/accounts/18ce54d4x5t/:ab_test_id

매개변수

Name	Description
account_id required	레버리지 계정의 식별자입니다. 리소스 경로에 포함되며, GET accounts를 제외한 대부분의 Advertiser API 요청에서 일반적으로 필수 매개변수입니다. 지정된 계정은 인증된 사용자와 연결되어 있어야 합니다. Type: string Example: 18ce54d4x5t
ab_test_id required	요청에서 사용 중인 A/B Test에 대한 참조입니다. Type: string Example: hr7l0
description optional	A/B Test에 대한 설명입니다. 최대 길이: 1,024자입니다. 참고: A/B Test status가 SCHEDULED인 동안에만 업데이트할 수 있습니다. Type: string Example: documentation example
end_time optional	A/B Test가 종료되는 시간을 ISO 8601 형식으로 표현한 값입니다. 참고: A/B Test status가 SCHEDULED 또는 LIVE인 동안에만 업데이트할 수 있습니다. Type: string Example: 2020-10-02T00:00:00Z
name optional	A/B Test의 이름입니다. 최대 길이: 255자입니다. 참고: A/B Test status가 SCHEDULED인 동안에만 업데이트할 수 있습니다. Type: string Example: first AB test
start_time optional	A/B Test가 시작되는 시간을 ISO 8601 형식으로 표현한 값입니다. 참고: A/B Test status가 SCHEDULED인 동안에만 업데이트할 수 있습니다. Type: string Example: 2022-05-30T00:00:00Z
user_groups required	사용자 그룹을 설명합니다. 아래 표에서 자세한 정보를 확인할 수 있습니다. 참고: A/B Test status가 SCHEDULED인 동안에만 업데이트할 수 있습니다. Type: array of objects

​

사용자 그룹

Name	Description
id 필수일 수 있음	요청에서 작업 중인 사용자 그룹 객체를 참조하는 값입니다. 참고: 사용자 그룹 객체의 _필드_를 수정(변경, 추가 또는 제거)할 때 필수입니다. 참고: 전체 사용자 그룹 객체를 추가하거나 제거할 때는 ID를 지정하지 마십시오. Type: string Example: p1bcx
description 선택 사항	사용자 그룹에 대한 설명입니다. 최대 길이: 1,024자입니다. 참고: null 값을 사용해 해당 필드를 지정하면 설정이 해제(제거)됩니다. Type: string Example: second AB test group
entity_ids 선택 사항	엔터티 ID의 배열입니다. 참고: 이는 교체 연산입니다. 이전에 설정된 값은 모두 덮어씁니다. 참고: 엔터티는 하나의 A/B 테스트에만 연결될 수 있습니다. Type: array Example: ["dxi0l", "e66bl"]
name 선택 사항	사용자 그룹의 이름입니다. 최대 길이: 255자입니다. 참고: null 값을 사용해 해당 필드를 지정하면 설정이 해제(제거)됩니다. Type: string Example: first group
size 선택 사항	이 사용자 그룹에 할당할 사용자 비율(%)입니다. 소수점 둘째 자리까지 표현 가능한 문자열 형식의 숫자 값입니다. 예를 들어 40%는 40, 40.0 또는 40.00으로 표현합니다. 참고: 객체 전체의 size 값 합은 반드시 100.00이 되어야 합니다. Type: string Min, Max: 1.00, 99.00

예시 요청

이 요청은 다음과 같은 변경을 수행합니다.

1. A/B 테스트 설명을 제거합니다
2. 종료 시간을 변경합니다
3. 첫 번째 사용자 그룹에 설명을 추가합니다
4. 각 사용자 그룹의 사용자 비율을 변경합니다
5. 두 번째 사용자 그룹에 엔터티 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"]}]}'

응답 예시

    {
      "request": {
        "params": {
          "account_id": "18ce54d4x5t",
          "ab_test_id": "hr7l0",
          "description": null,
          "end_time": "2022-06-01T01:00:00Z",
          "user_groups": [
            {
              "id": "p1bcx",
              "description": "first AB test group",
              "size": "60.0"
            },
            {
              "id": "p1bcy",
              "size": "40.0",
              "entity_ids": [
                "f2rqi",
                "f2tws",
                "f2syz"
              ]
            }
          ]
        }
      },
      "data": {
        "created_at": "2020-05-25T00:00:00Z",
        "created_by": {
          "user_id": "756201191646691328",
          "username": "apimctestface"
        },
        "deleted": false,
        "description": null,
        "end_time": "2022-06-01T01:00:00Z",
        "entities": [
          {
            "id": "p1bcx",
            "account_id": "18ce54d4x5t"
          },
          {
            "id": "p1bcy",
            "account_id": "18ce54d4x5t"
          }
        ],
        "entity_type": "CAMPAIGN",
        "id": "hr7l0",
        "name": "first AB test",
        "start_time": "2022-05-25T01:00:00Z",
        "status": "SCHEDULED",
        "user_groups": [
          {
            "id": "p1bcx",
            "name": "first group",
            "description": "first AB test group",
            "size": "60.0",
            "entity_ids": [
              "f2qcw",
              "f2tht"
            ]
          },
          {
            "id": "p1bcy",
            "name": "second group",
            "description": "second AB test group",
            "size": "40.0",
            "entity_ids": [
              "f2rqi",
              "f2tws",
              "f2syz"
            ]
          }
        ],
        "updated_at": "2022-05-25T00:17:23Z",
        "updated_by": {
          "user_id": "756201191646691328",
          "username": "apimctestface"
        }
      }
    }

​

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

Parameters

Name	Description
ab_test_id required	요청에서 사용 중인 A/B Test를 참조하는 값입니다. Type: string Example: hr7l0

예시 요청

DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/ab_tests/hr7l0

​

응답 예시

    {
      "request": {
        "params": {
          "account_id": "18ce54d4x5t",
          "ab_test_id": "hr7l0"
        }
      },
      "data": {
        "created_at": "2022-05-25T00:00:00Z",
        "created_by": {
          "user_id": "756201191646691328",
          "username": "apimctestface"
        },
        "deleted": true,
        "description": null,
        "end_time": "2022-06-01T01:00:00Z",
        "entities": [
          {
            "id": "p1bcx",
            "account_id": "18ce54d4x5t"
          },
          {
            "id": "p1bcy",
            "account_id": "18ce54d4x5t"
          }
        ],
        "entity_type": "CAMPAIGN",
        "id": "hr7l0",
        "name": "first AB test",
        "start_time": "2022-05-25T01:00:00Z",
        "status": "SCHEDULED",
        "user_groups": [
          {
            "id": "p1bcx",
            "name": "first group",
            "description": "first AB test group",
            "size": "60.0",
            "entity_ids": [
              "f2qcw",
              "f2tht"
            ]
          },
          {
            "id": "p1bcy",
            "name": "second group",
            "description": "second AB test group",
            "size": "40.0",
            "entity_ids": [
              "f2rqi",
              "f2tws",
              "f2syz"
            ]
          }
        ],
        "updated_at": "2022-06-02T00:18:31Z",
        "updated_by": {
          "user_id": "756201191646691328",
          "username": "apimctestface"
        }
      }
    }