概要
はじめに
ユースケース
- クリエイティブ
- ターゲティング
- 入札タイプ
- 入札単位
A/B Testing
ユースケース
- クリエイティブ
- ターゲティング
- 入札タイプ
- 入札単位
属性
- テスト期間（start_time と end_time のfieldsで表現）
- 分割を行うレベル（entity_type のfieldで表現）
- 少なくとも2つ（最大30）のユーザーグループ（user_groups 配列内のオブジェクトで表現）
- 当該ユーザーグループに割り当てるユーザーの割合（size のfieldで表現）
- 当該ユーザーグループのユーザープールを構成するキャンペーンID／ラインアイテムID（entity_ids 配列で表現）
使用方法
作成
-
start_time と end_time の値は以下を満たす必要があります
- （A/B Test の作成時点から見て）将来であること
- キャンペーン／ラインアイテムのフライト期間と重複していること
- テストは、App ベースでないキャンペーンでは少なくとも 1 日、App ベースのキャンペーンでは少なくとも 5 日間継続する必要があります
- entity_type は CAMPAIGN または LINE_ITEM に設定できます
-
各ユーザーグループは user_groups 配列内のオブジェクトとして表されます
- 少なくとも 2 つのユーザーグループが必要です
- 最大 30 のユーザーグループまで許可されます
-
各ユーザーグループのサイズは、1.00 から 99.00 の数値を文字列で表した値で設定します
- 注意: オブジェクト間の size の合計値は必ず 100.00 になる必要があります
- 各ユーザーグループの entity_ids 配列でキャンペーン ID を指定する必要があります
- A/Bテスト対象キャンペーン内のすべてのラインアイテムをスプリットテストに含める必要があります。
- ラインアイテムレベルでは均等割りのみが許可されます。
- 1つのスプリットテストで許可されるユーザーグループのラインアイテム数は5以下でなければなりません。
- ユーザーグループあたりラインアイテムは1つのみ。
更新
- オブジェクトや要素を追加または削除する場合は、配列（およびその下位構造）全体を渡してください。これは置換操作です
-
それ以外の場合は、キー名または ID を参照して既存のfieldsを変更（追加・削除・更新）します
- フィールドを削除するには、その値を null に設定します
- 渡されていないフィールドは変更されません
リクエスト例
- 名前と説明のない 3 番目のユーザーグループを追加
- 各ユーザーグループに属するユーザーの割合を変更
- A/Bテストの説明を削除
- 最初のユーザーグループに説明を追加
- 2番目のユーザーグループにエンティティID（f2syz）を追加
- 2番目のユーザーグループを削除する
- 各ユーザーグループのユーザー割合を変更する
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 必須 | 利用対象のアカウントを識別する ID。リソースのパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで一般的に必須です。指定したアカウントは認証済みユーザーに関連付けられている必要があります。 Type: string Example: 18ce54d4x5t |
| ab_test_ids 任意 | 識別子のカンマ区切りリストを指定して、対象の A/B テストのみにレスポンスを絞り込みます。最大 200 個の ID を指定できます。 Type: string Example: hr7l0 |
| count 任意 | 個々のリクエストで取得を試みるレコード数を指定します。 Type: int Default: 200 Min, Max: 1, 1000 |
| cursor 任意 | 次の結果ページを取得するためのカーソルを指定します。詳細は Pagination を参照してください。 Type: string Example: 8x7v00oow |
| live_during 任意 | 指定した日付範囲の期間中に実施中、または実施予定の A/B テストにレスポンスを絞り込みます。開始時刻と終了時刻が指定した日付範囲と部分的または完全に重なる A/B テストを返します。 値はカンマ区切りの日時として、ISO 8601 形式で指定してください。早い日時を先に記載します。 Type: string Example: 2020-11-01T08:00:00Z,2020-12-01T08:00:00Z |
| q 任意 | name によるリソースの絞り込みに用いる任意の query。すべて取得する場合はこのパラメータを省略します。Type: string Min, Max length: 1, 80 |
| sort_by 任意 | サポートされている属性で昇順または降順に並べ替えます。詳細は Sorting を参照してください。 Type: string Example: created_at-asc |
| status 任意 | 指定したステータスの A/B テストにレスポンスを絞り込みます。 Type: enum Possible values: COMPLETED, LIVE, SCHEDULED |
| user_id 任意 | 指定したユーザー ID が作成した A/B テストにレスポンスを絞り込みます。 Note: username と同時には指定できません。Type: long Example: 756201191646691328 |
| username 任意 | 指定したユーザー名が作成した A/B テストにレスポンスを絞り込みます。先頭の「@」記号は含めないでください。 Note: user_id と同時には指定できません。Type: string Example: apimctestface |
| with_deleted 任意 | 削除済みの結果をレスポンスに含めます。 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の配列。 注: エンティティは1つのA/Bテストにのみ関連付け可能です。 Type: array Example: ["dxi0l", "e66bl"] |
| size required | このユーザーグループに割り当てるユーザーの割合。小数点以下2桁までの数値を文字列で表します。例: 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"}'
レスポンスの例
PUT accounts/:account_id/ab_tests/:ab_test_id
指定した A/B テストを更新します。 すべてのパラメータはリクエストボディで送信され、Content-Type は application/json を指定する必要があります。
この endpoint は、オブジェクト ID を含む部分的な JSON をサポートします。以下の原則が適用されます。
- オブジェクトや要素を追加または削除する場合は、配列全体（およびそのサブ構造）を渡します。これは置換操作です
- 配列を再作成するイメージです
- それ以外の場合は、キー名または ID を参照して既存の fields を変更（変更・追加・削除）します
- フィールドを削除するには、その値を
nullに設定します - 渡されなかったフィールドは変更されません
- フィールドを削除するには、その値を
status が SCHEDULED の間のみ更新できます。例外が 1 つあります。LIVE の間でも、A/B テストの end_time は更新可能です。
リソースURL
https://ads-api.x.com/12/accounts/18ce54d4x5t/:ab_test_id
パラメータ
| 名前 | 説明 |
|---|---|
| account_id 必須 | 連携先アカウントの識別子。リソースのパスに含まれ、GET accounts を除くすべての Advertiser API リクエストで一般的に必須のパラメータです。指定したアカウントは認証済みユーザーに紐づいている必要があります。 Type: string Example: 18ce54d4x5t |
| ab_test_id 必須 | リクエストで操作対象となる A/B Test への参照。 Type: string Example: hr7l0 |
| description 任意 | A/B Test の説明。最大 1,024 文字。 注: A/B Test の status が SCHEDULED の場合にのみ更新できます。Type: string Example: documentation example |
| end_time 任意 | A/B Test の終了時刻（ISO 8601）。 注: A/B Test の status が SCHEDULED または LIVE の場合にのみ更新できます。Type: string Example: 2020-10-02T00:00:00Z |
| name 任意 | A/B Test の名前。最大 255 文字。 注: A/B Test の status が SCHEDULED の場合にのみ更新できます。Type: string Example: first AB test |
| start_time 任意 | A/B Test の開始時刻（ISO 8601）。 注: A/B Test の status が SCHEDULED の場合にのみ更新できます。Type: string Example: 2022-05-30T00:00:00Z |
| user_groups 必須 | ユーザーグループの定義。詳細は下表を参照してください。 注: A/B Test の status が SCHEDULED の場合にのみ更新できます。Type: array of objects |
ユーザーグループ
| Name | Description |
|---|---|
| id 場合によっては必須 | リクエストで操作対象となるユーザーグループオブジェクトへの参照。 注: ユーザーグループオブジェクトの fields を変更（変更・追加・削除）する場合は必須です。 注: ユーザーグループオブジェクト全体を追加または削除する場合は、ID を指定しないでください。 Type: string Example: p1bcx |
| description 任意 | ユーザーグループの説明。最大長: 1,024 文字。 注: フィールドに null を指定すると未設定（削除）になります。Type: string Example: second AB test group |
| entity_ids 任意 | エンティティ ID の配列。 注: これは置換操作です。以前の設定を上書きします。 注: エンティティは 1 つの A/B テストにのみ関連付けられます。 Type: array Example: ["dxi0l", "e66bl"] |
| name 任意 | ユーザーグループの名前。最大長: 255 文字。 注: フィールドに null を指定すると未設定（削除）になります。Type: string Example: first group |
| size 任意 | このユーザーグループに割り当てるユーザーの割合。数値を文字列で表し、小数点以下は最大 2 桁まで。例: 40% は 40、40.0、または 40.00。 注: objects 全体の size の合計は必ず 100.00 でなければなりません。 Type: string Min, Max: 1.00, 99.00 |
リクエスト例
- A/Bテストの説明を削除する
- end_time を変更する
- 最初のユーザーグループに説明を追加する
- 各ユーザーグループのユーザー割合を変更する
- 2番目のユーザーグループにエンティティ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 テストの削除は元に戻せません。以後このリソースを delete しようとすると、HTTP 404 が返されます。リソース URL
https://ads-api.x.com/12/accounts/:account_id/ab_tests/:ab_test_id
パラメータ
| Name | 説明 |
|---|---|
| ab_test_id 必須 | このリクエストで対象とする A/B テストを参照する ID。 Type: string Example: hr7l0 |
リクエスト例
DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/ab_tests/hr7l0