Zum Hauptinhalt springen

​
Überblick

​
Einführung

A/B-Tests ermöglichen Werbetreibenden, die Nutzer, die sie auf X erreichen, in Segmente aufzuteilen, um besser zu verstehen, wie sich die Kampagnenleistung optimal steigern lässt und um Erkenntnisse zu gewinnen, die ihre Marketingstrategien fundieren. Diese Segmente – sogenannte Aufteilungen in Nutzergruppen – sind randomisiert und gegenseitig ausschließend. Durch die Randomisierung werden die Ergebnis beeinflussenden Faktoren gleichmäßig verteilt. Anders ausgedrückt gibt es keine inhärenten Unterschiede zwischen den Gruppen oder ihrem erwarteten Verhalten. Daher kann, wenn eine einzelne Variante auf eine Nutzergruppe angewendet wird und nicht auf die anderen, der Unterschied in der Kampagnenleistung dieser Variante zugeschrieben werden. Obwohl es möglich ist, viele Varianten gleichzeitig zu testen, empfehlen wir dringend, jeweils nur eine Variante zu testen. So wird der kausale Faktor für den beobachteten Unterschied in der Kampagnenleistung isoliert. Varianten werden auf Kampagnenebene festgelegt. Möchte der Werbetreibende beispielsweise die Wirksamkeit eines neuen Creatives testen, sollte er zwei identische Kampagnen erstellen, bei denen sich ausschließlich das Creative unterscheidet. Künftig planen wir, Varianten auf Line-Item-Ebene zu unterstützen.

​
Anwendungsfälle

A/B-Tests werden am häufigsten eingesetzt, um (1) Optimierungsanwendungsfälle für Performance-Kunden zu unterstützen, die verstehen möchten, was auf X am besten funktioniert, um ihre Investitionen zu optimieren, und (2) Lernanwendungsfälle für Markenwerbetreibende, die gewonnene Erkenntnisse zur Gestaltung ihrer Marketingstrategie nutzen möchten.  Die API unterstützt A/B-Tests für jede Kampagnenvariable, einschließlich:
  • Creatives 
  • Targeting 
  • Gebotsart
  • Gebotseinheit

​
A/B-Tests

A/B-Tests ermöglichen es Werbetreibenden, die Nutzer, die sie auf X erreichen, zu segmentieren, um zu verstehen, wie sich die Kampagnenleistung am besten optimieren lässt, und Erkenntnisse zu gewinnen, die ihre Marketingstrategien informieren. Diese Segmente – sogenannte Aufteilungen in Nutzergruppen – sind randomisiert und gegenseitig ausschließend. Durch die Randomisierung werden beeinflussende Faktoren gleichmäßig verteilt. Anders ausgedrückt gibt es keine inhärenten Unterschiede zwischen den Gruppen oder ihren erwarteten Verhaltensweisen. Deshalb kann, wenn eine einzelne Variation auf eine Nutzergruppe angewendet wird und nicht auf die anderen, der Unterschied in der Kampagnenleistung dieser Variation zugeschrieben werden. Auch wenn es möglich ist, viele Variationen gleichzeitig zu testen, empfehlen wir dringend, jeweils nur eine Variation zu testen. So wird der kausale Faktor für den beobachteten Unterschied in der Kampagnenleistung isoliert. Variationen werden entweder auf Kampagnenebene oder auf der Ebene der Anzeigengruppe festgelegt. Die Anzeigengruppe wird in der Ads API über line item festgelegt. Beispiel für eine Variation auf Anzeigengruppenebene: Wenn der Werbetreibende die Wirksamkeit eines neuen Creatives testen möchte, sollte er eine Kampagne mit zwei identischen Anzeigengruppen erstellen, bei denen der einzige Unterschied das Creative ist.

​
Anwendungsfälle

A/B-Tests werden am häufigsten eingesetzt, um (1) Optimierungsanwendungsfälle für Performance-Kunden zu unterstützen, die verstehen möchten, was auf X am besten funktioniert, um ihre Investitionen zu optimieren, und (2) Lernanwendungsfälle für Markenwerbetreibende, die Erkenntnisse zur Gestaltung ihrer Marketingstrategie nutzen möchten.  Die API unterstützt A/B-Tests für jede Kampagnenvariable, einschließlich:
  • Creative
  • Targeting
  • Gebotsart
  • Gebotseinheit

​
Attribute

A/B-Tests werden als verschachtelte Strukturen dargestellt. Es gibt Top-Level-fields für den A/B-Test selbst und ein Array von Nutzergruppenobjekten, jeweils mit einem Satz von fields, die sie beschreiben. Auf übergeordneter Ebene muss jeder A/B-Test die folgenden Informationen enthalten.
  • Die Testdauer, dargestellt durch die Felder start_time und end_time
  • Die Ebene, auf der die Aufteilung erfolgt, dargestellt durch das Feld entity_type
  • Mindestens zwei (und höchstens 30) Nutzergruppen, jeweils als Objekt im Array user_groups
Jede Nutzergruppe muss die folgenden Informationen enthalten.
  • Den Prozentsatz der Nutzer, die der jeweiligen Nutzergruppe zugewiesen werden sollen, dargestellt durch das Feld size
  • Die Campaign-IDs/Line-Item-IDs, die den Pool der Nutzer für die jeweilige Nutzergruppe bilden sollen, dargestellt durch das Array entity_ids
Optional können name- und description-Werte für A/B-Tests und für Nutzergruppen gesetzt werden. Informationen zu Validierungsregeln und anderen Einschränkungen finden Sie unten. Weitere metadata, wie die ID oder der Erstellungszeitpunkt, sind ebenfalls enthalten, werden jedoch automatisch von X gesetzt. Ein Beispiel für eine A/B-Test-Entität auf Kampagnenebene ist unten dargestellt. 
{
  "created_at": "2020-12-01T00:00:00Z",
  "created_by": {
    "user_id": "756201191646691328",
    "username": "apimctestface"
  },
  "deleted": false,
  "description": "Dokumentationsbeispiel",
  "end_time": "2020-12-05T01:00:00Z",
  "entity_type": "CAMPAIGN",
  "id": "hr7l0",
  "name": "erster AB-Test",
  "start_time": "2020-12-01T01:00:00Z",
  "status": "SCHEDULED",
  "user_groups": [
    {
      "id": "p1bcx",
      "name": "erste Gruppe",
      "description": null,
      "size": "50.0",
      "entity_ids": [
        "f2qcw",
        "f2tht"
      ]
    },
    {
      "id": "p1bcy",
      "name": "zweite Gruppe",
      "description": "zweite AB-Test-Gruppe",
      "size": 50,
      "entity_ids": [
        "f2rqi",
        "f2tws"
      ]
    }
  ],
  "updated_at": "2020-12-01T00:00:00Z",
  "updated_by": {
    "user_id": "756201191646691328",
    "username": "apimctestface"
  }
}
Nachfolgend ist ein Beispiel für eine A/B-Test-Entität auf Ebene des Line-Items dargestellt. 
{
   "created_by":{
      "user_id":"756201191646691328",
      "username":"apimctestface"
   },
   "name":"Test2e",
   "start_time":"2022-08-15T00:00:00Z",
   "updated_by":{
      "user_id":"756201191646691328",
      "username":"apimctestface"
   },
   "description":"Mein zweiter AB-Test",
   "entity_type":"LINE_ITEM",
   "end_time":"2022-08-30T00:00:00Z",
   "id":"1ul",
   "user_groups":[
      {
         "name":"erste Gruppe",
         "size":"50.0",
         "description":"Beschreibung der ersten Gruppe",
         "entity_ids":[
            "ij9dh"
         ],
         "id":"4xe"
      },
      {
         "name":"zweite Gruppe",
         "size":"50.0",
         "description":"Beschreibung der zweiten Gruppe",
         "entity_ids":[
            "ihng8"
         ],
         "id":"4xf"
      }
   ],
   "status":"SCHEDULED",
   "created_at":"2022-08-11T00:10:50Z",
   "updated_at":"2022-08-11T00:10:50Z",
   "deleted":false
}

​
Verwendung

Die folgenden Unterabschnitte beschreiben das Erstellen und Aktualisieren von A/B-Tests. Lesen und Löschen funktionieren wie bei allen anderen Ads API endpoints.

​
Erstellen

Erstellen Sie einen A/B-Test mit dem endpoint POST accounts/:account_id/ab_tests. Der endpoint akzeptiert ausschließlich JSON-POST-Bodies. Der Content-Type muss auf application/json gesetzt sein. Nachdem der Werbetreibende zwei oder mehr Kampagnen eingerichtet hat, kann ein A/B-Test erstellt werden. Wie oben beschrieben, müssen A/B-Tests Folgendes enthalten: Testdauer, Split-Ebene und mindestens zwei Nutzergruppen. Jede Nutzergruppe muss den prozentualen Anteil der ihr zugewiesenen Nutzer sowie die Kampagnen-IDs angeben, aus denen sich ihr Nutzerpool zusammensetzt. Jedes dieser Elemente wird nachfolgend näher beschrieben. Testdauer:
  • Die Werte für start_time und end_time müssen
    • in der Zukunft liegen (relativ zum Zeitpunkt der Erstellung des A/B-Tests)
    • sich mit den Laufzeiten der Kampagnen/Line Items überschneiden
  • Der Test muss bei nicht App-basierten Kampagnen mindestens einen Tag dauern und bei App-basierten Kampagnen mindestens fünf Tage.
Split-Ebene:
  • Der entity_type kann auf CAMPAIGN oder LINE_ITEM gesetzt werden
Nutzergruppen:
  • Jede Nutzergruppe wird als Objekt im Array user_groups dargestellt
    • Es sind mindestens zwei Nutzergruppen erforderlich
    • Es sind höchstens 30 Nutzergruppen zulässig
  • Die Größe jeder Nutzergruppe wird als String-Darstellung eines numerischen Werts zwischen 1.00 und 99.00 festgelegt
    • Hinweis: Die Größenwerte über alle Objekte hinweg müssen in Summe 100.00 ergeben
  • Die Kampagnen-IDs sollten im Array entity_ids der jeweiligen Nutzergruppe angegeben werden
Optional können Name und Beschreibung für den A/B-Test oder für eine oder mehrere Nutzergruppen festgelegt werden. Die folgende Anfrage erstellt einen A/B-Test auf Kampagnenebene, der vier Tage dauert und zwei Nutzergruppen mit jeweils 50 % der Nutzer umfasst. Die erste Nutzergruppe basiert auf den Kampagnen f2qcw und f2tht; die zweite Nutzergruppe basiert auf den Kampagnen f2rqi und f2tws. Die Anfrage fügt außerdem Namen und Beschreibungen zu einigen Teilen der Entität hinzu. 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"
    }
  }
}
Für A/B-Tests auf Line-Item-Ebene Der Hauptunterschied zwischen A/B-Tests auf Kampagnen- und Line-Item-Ebene ist der entity_type. Für A/B-Tests auf der Line-Item-Ebene muss „entity_type“ auf „LINE_ITEM“ gesetzt werden. Dies gilt für alle unten aufgeführten Aktionen bei einem bereits erstellten A/B-Test. Anforderungen:
  1. Alle Line Items der A/B-Test-Kampagne müssen in den Split-Test einbezogen werden.
  2. Auf Line-Item-Ebene ist nur eine gleichmäßige Aufteilung zulässig.
  3. Die Anzahl der Line Items pro Nutzergruppe in einem Split-Test muss kleiner oder gleich 5 sein.
  4. Pro Nutzergruppe ist nur 1 Line Item zulässig.

​
Aktualisierung

Aktualisieren Sie einen A/B-Test über den Endpoint PUT accounts/:account_id/ab_tests/:ab_test_id. Der Endpoint erfordert, dass ein JSON-Blob in der Anfrage gesendet wird. Der Content-Type muss auf application/json gesetzt sein. Wie bei anderen Update-Endpoints erfordert der Endpoint PUT accounts/:account_id/ab_tests/:ab_test_id, dass die A/B-Test-ID in der URL referenziert wird. Im Allgemeinen können A/B-Tests nur aktualisiert werden, wenn ihr Status SCHEDULED ist. Es gibt eine Ausnahme: Es ist möglich, die end_time des A/B-Tests zu aktualisieren, während er LIVE ist. Dieser Endpoint unterstützt partielles JSON mit Objekt-IDs. Es gelten die folgenden Grundsätze:
  • Um Objekte oder Elemente hinzuzufügen oder zu entfernen, übergeben Sie das gesamte Array (und seine Unterstrukturen); dies ist eine Ersetzungs-Operation
  • Andernfalls ändern (ändern, hinzufügen, entfernen) Sie bestehende fields, indem Sie Schlüsselnamen oder IDs referenzieren
    • Um ein Feld zu entfernen, setzen Sie seinen Wert auf null
    • Felder, die nicht übergeben werden, werden nicht geändert
Wenn wir beispielsweise eine dritte Nutzergruppe zu dem zuvor erstellten A/B-Test hinzufügen möchten, müssen wir das user_groups-Array mit den beiden bestehenden Nutzergruppenobjekten sowie mit der neuen Gruppe senden, die wir hinzufügen möchten. Betrachten Sie dies als ein Neuerstellen des user_groups-Arrays; übergeben Sie die data so, als würden Sie es von Anfang an auf diese Weise erstellen (übergeben Sie keine Objekt-IDs von Nutzergruppen). Das user_groups-Array in der Update-Anfrage könnte wie folgt dargestellt werden. 
[
  {
    "entity_ids": [
      "f2qcw",
      "f2tht"
    ],
    "size": "30.0",
    "name": "erste Gruppe"
  },
  {
    "entity_ids": [
      "f2rqi",
      "f2tws"
    ],
    "size": "30.0",
    "name": "zweite Gruppe",
    "description": "zweite AB-Test-Gruppe"
  },
  {
    "entity_ids": [
      "i1vwr",
      "i1xre"
    ],
    "size": "40.0"
  }
]
Beachten Sie, dass die Größenwerte über alle Objekte hinweg weiterhin 100,00 ergeben. Hätten wir sie für die ersten beiden Objekte nicht aktualisiert — zuvor jeweils auf 50,00 gesetzt —, wäre die Anfrage fehlgeschlagen. Wenn wir stattdessen lediglich eine Beschreibung für die erste Benutzergruppe hinzufügen wollten, sähe das user_groups-Array in der Aktualisierungsanfrage wie folgt aus. 
[
  {
    "id": "p1bcx",
    "description": "aktualisiert mit einer PUT-Anfrage"
  }
]
Wir verweisen auf das Benutzergruppenobjekt anhand der id und nehmen nur das Feld auf, das wir ändern möchten.

​
Beispielanfragen

Dieser Abschnitt enthält zusätzliche Beispiel-Update-Anfragen. Gehen Sie davon aus, dass diese nacheinander aufgerufen werden. JSON-Blöcke sind zur besseren Lesbarkeit formatiert. Antworten sind ausgelassen. Um die folgenden Änderungen vorzunehmen, würde die Anfrage wie folgt aussehen. (Dies entspricht dem zuvor verwendeten Beispiel oben.)
  1. Fügt eine dritte Nutzergruppe ohne Namen oder Beschreibung hinzu
  2. Ändert den prozentualen Anteil der Nutzer in jeder Nutzergruppe
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": "erste Gruppe"
    },
    {
      "entity_ids": [
        "f2rqi",
        "f2tws"
      ],
      "size": "30.00",
      "name": "zweite Gruppe",
      "description": "zweite AB-Test-Gruppe"
    },
    {
      "entity_ids": [
        "i1vwr",
        "i1xre"
      ],
      "size": "40.00"
    }
  ]
}'
Um die folgenden Änderungen vorzunehmen, würde die Anfrage wie folgt aussehen:
  1. Entfernt die A/B-Test-Beschreibung
  2. Fügt der ersten Nutzergruppe eine Beschreibung hinzu
  3. Fügt der zweiten Nutzergruppe eine Entity-ID (f2syz) hinzu
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": "erste AB-Test-Gruppe"
    },
    {
      "id": "p1bcy",
      "entity_ids": [
        "f2rqi",
        "f2tws",
        "f2syz"
      ]
    }
  ]
}'
Die dritte Änderung erfordert, dass wir die beiden vorhandenen Entity-IDs zusammen mit der neuen übergeben. Beachten Sie, dass an der dritten Nutzergruppe keine Änderungen vorgenommen wurden. Um die folgenden Änderungen vorzunehmen, würde die Anfrage wie folgt aussehen.
  1. Entfernt die zweite Nutzergruppe
  2. Ändert den Prozentsatz der Nutzer in jeder Nutzergruppe 
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": "erste Gruppe"
    },
    {
      "entity_ids": [
        "i1vwr",
        "i1xre"
      ],
      "size": "45.00"
    }
  ]
}'

​
API-Referenz

​
A/B-Tests

​
GET accounts/:account_id/ab_tests

Rufen Sie Details zu einigen oder allen A/B-Tests ab.
Ressourcen-URL
https://ads-api.x.com/12/accounts/:account_id/ab_tests
Parameter
NameBeschreibung
account_id
erforderlich		Der Bezeichner für das genutzte Konto. Er erscheint im Ressourcenpfad und ist im Allgemeinen ein erforderlicher Parameter für alle Advertiser-API-Anfragen mit Ausnahme von GET accounts. Das angegebene Konto muss dem authentifizierten Benutzer zugeordnet sein.

Type: string

Example: 18ce54d4x5t
ab_test_ids
optional		Beschränken Sie die Antwort auf die gewünschten A/B-Tests, indem Sie eine kommagetrennte Liste von Bezeichnern angeben. Es können bis zu 200 IDs angegeben werden.

Type: string

Example: hr7l0
count
optional		Gibt die Anzahl der Datensätze an, die pro einzelner Anfrage abgerufen werden sollen.

Type: int

Default: 200
Min, Max: 1, 1000
cursor
optional		Gibt einen Cursor an, um die nächste Ergebnisseite abzurufen. Siehe Pagination für weitere Informationen.

Type: string

Example: 8x7v00oow
live_during
optional		Beschränken Sie die Antwort auf A/B-Tests, die während des angegebenen Datumsbereichs live waren oder sein werden. Dadurch werden A/B-Tests zurückgegeben, deren Start- und Endzeiten sich ganz oder teilweise mit dem angegebenen Datumsbereich überschneiden.

Geben Sie die Werte als kommagetrennte Daten im Format ISO 8601 an. Das frühere Datum sollte zuerst angegeben werden.

Type: string

Example: 2020-11-01T08:00:00Z,2020-12-01T08:00:00Z
q
optional		Eine optionale Abfrage, um die Ressource nach name zu filtern. Lassen Sie diesen Parameter weg, um alle abzurufen.

Type: string

Min, Max length: 1, 80
sort_by
optional		Sortiert nach einem unterstützten Attribut in auf- oder absteigender Reihenfolge. Siehe Sorting für weitere Informationen.

Type: string

Example: created_at-asc
status
optional		Beschränkt die Antwort auf A/B-Tests mit dem gewünschten Status.

Type: enum

Possible values: COMPLETED, LIVE, SCHEDULED
user_id
optional		Beschränkt die Antwort auf A/B-Tests, die von der angegebenen Benutzer-ID erstellt wurden.

Hinweis: Kann nicht gleichzeitig mit username angegeben werden.

Type: long

Example: 756201191646691328
username
optional		Beschränkt die Antwort auf A/B-Tests, die vom angegebenen Benutzernamen erstellt wurden. Lassen Sie das führende „@“-Symbol weg.

Hinweis: Kann nicht gleichzeitig mit user_id angegeben werden.

Type: string

Example: apimctestface
with_deleted
optional		Schließt gelöschte Ergebnisse in die Anfrage ein.

Type: boolean

Default: false
Possible values: true, false
Beispielanfrage
GET https://ads-api.x.com/12/accounts/18ce54d4x5t/ab_tests
Beispielantwort
    {
      "request": {
        "params": {
          "account_id": "18ce54d4x5t"
        }
      },
      "data": [
        {
          "created_at": "2022-05-25T00:00:00Z",
          "created_by": {
            "user_id": "756201191646691328",
            "username": "apimctestface"
          },
          "deleted": false,
          "description": "Dokumentationsbeispiel",
          "end_time": "2022-05-30T01:00:00Z",
          "entities": [
            {
              "id": "p1bcx",
              "account_id": "18ce54d4x5t"
            },
            {
              "id": "p1bcy",
              "account_id": "18ce54d4x5t"
            }
          ],
          "entity_type": "CAMPAIGN",
          "id": "hr7l0",
          "name": "erster AB-Test",
          "start_time": "2022-05-25T01:00:00Z",
          "status": "SCHEDULED",
          "user_groups": [
            {
              "id": "p1bcx",
              "name": "erste Gruppe",
              "description": null,
              "size": "50.0",
              "entity_ids": [
                "f2qcw",
                "f2tht"
              ]
            },
            {
              "id": "p1bcy",
              "name": "zweite Gruppe",
              "description": "zweite AB-Test-Gruppe",
              "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

Erstellen Sie einen neuen A/B-Test. Alle Parameter werden im Anforderungstext (Request Body) übermittelt; der Content-Type muss application/json sein.
Ressourcen-URL
https://ads-api.x.com/12/accounts/:account_id/ab_tests
Parameter
NameBeschreibung
account_id
erforderlich		Der Bezeichner des verwendeten Kontos. Er erscheint im Ressourcenpfad und ist im Allgemeinen ein erforderlicher Parameter für alle Advertiser-API-Anfragen mit Ausnahme von GET accounts. Das angegebene Konto muss dem authentifizierten Nutzer zugeordnet sein.

Type: string

Example: 18ce54d4x5t
end_time
erforderlich		Der Zeitpunkt im ISO-8601-Format, zu dem der A/B-Test endet.

Type: string

Example: 2020-10-02T00:00:00Z
entity_type
erforderlich		Der Entitätstyp, der für die Aufteilung der Nutzergruppen verwendet wird.

Type: enum

Possible values: CAMPAIGN, LINE_ITEM
start_time
erforderlich		Der Zeitpunkt im ISO-8601-Format, zu dem der A/B-Test beginnt.

Type: string

Example: 2022-05-30T00:00:00Z
user_groups
erforderlich		Beschreibt die Nutzergruppen. Weitere Informationen in der Tabelle unten. Es können zwischen 2 und 30 Nutzergruppen angegeben werden.

Type: array of objects
description
optional		Die Beschreibung des A/B-Tests. Maximale Länge: 1.024 Zeichen.

Type: string

Example: documentation example
name
optional		Der Name des A/B-Tests. Maximale Länge: 255 Zeichen.

Type: string

Example: first AB test

​
Nutzergruppen

NameBeschreibung
entity_ids
erforderlich		Ein Array von Entity-IDs.

Hinweis: Entities können nur einem einzigen A/B-Test zugeordnet sein.

Type: array

Beispiel: ["dxi0l", "e66bl"]
size
erforderlich		Der Prozentsatz der Nutzer, die dieser Nutzergruppe zugewiesen werden. Dies ist ein numerischer Wert, der als Zeichenfolge dargestellt wird, mit höchstens zwei Dezimalstellen. Geben Sie beispielsweise 40 % als 40, 40.0 oder 40.00 an.

Hinweis: Die size-Werte über die Objekte hinweg müssen in Summe 100.00 ergeben.

Type: array

Min, Max: 1.00, 99.00
description
optional		Die Beschreibung der Nutzergruppe. Maximale Länge: 1.024 Zeichen.

Type: string

Beispiel: second AB test group
name
optional		Der Name der Nutzergruppe. Maximale Länge: 255 Zeichen.

Type: string

Beispiel: first group

​
Beispielanfrage

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": "erste Gruppe"},{"entity_ids": ["f2rqi", "f2tws"], "size": "50.00", "name": "zweite Gruppe", "description": "zweite AB‑Testgruppe"}], "name": "erster AB‑Test", "description": "Beispiel aus der Dokumentation"}'

​
Beispielantwort

    {
      "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": "erste Gruppe"
            },
            {
              "entity_ids": [
                "f2rqi",
                "f2tws"
              ],
              "size": "50.0",
              "name": "zweite Gruppe",
              "description": "zweite AB-Test-Gruppe"
            }
          ],
          "name": "erster AB-Test",
          "description": "Dokumentationsbeispiel"
        }
      },
      "data": {
        "created_at": "2022-05-25T00:00:00Z",
        "created_by": {
          "user_id": "756201191646691328",
          "username": "apimctestface"
        },
        "deleted": false,
        "description": "Dokumentationsbeispiel",
        "end_time": "2022-05-30T01:00:00Z",
        "entities": [
          {
            "id": "p1bcx",
            "account_id": "18ce54d4x5t"
          },
          {
            "id": "p1bcy",
            "account_id": "18ce54d4x5t"
          }
        ],
        "entity_type": "CAMPAIGN",
        "id": "hr7l0",
        "name": "erster AB-Test",
        "start_time": "2022-05-25T01:00:00Z",
        "status": "SCHEDULED",
        "user_groups": [
          {
            "id": "p1bcx",
            "name": "erste Gruppe",
            "description": null,
            "size": "50.0",
            "entity_ids": [
              "f2qcw",
              "f2tht"
            ]
          },
          {
            "id": "p1bcy",
            "name": "zweite Gruppe",
            "description": "zweite AB-Test-Gruppe",
            "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

Aktualisieren Sie den angegebenen A/B-Test. Alle Parameter werden im Request-Body gesendet, und ein Content-Type von application/json ist erforderlich. Dieser endpoint unterstützt partielles JSON mit Objekt-IDs. Es gelten die folgenden Prinzipien:
  • Um Objekte oder Elemente hinzuzufügen oder zu entfernen, übergeben Sie das gesamte Array (einschließlich seiner Unterstrukturen); dies ist eine Ersetzungs-Operation
    • Stellen Sie sich dies als Neuerstellung des Arrays vor
  • Andernfalls ändern (ändern, hinzufügen, entfernen) Sie bestehende fields, indem Sie sich auf Schlüsselnamen oder IDs beziehen
    • Um ein Feld zu entfernen, setzen Sie seinen Wert auf null
    • Nicht übergebene fields werden nicht geändert
Im Allgemeinen können A/B-Tests nur aktualisiert werden, während der status SCHEDULED ist. Es gibt eine Ausnahme: Es ist möglich, die end_time des A/B-Tests zu aktualisieren, während er LIVE ist.
Ressourcen-URL
https://ads-api.x.com/12/accounts/18ce54d4x5t/:ab_test_id
Parameter
NameBeschreibung
account_id
erforderlich		Der Bezeichner für das genutzte Konto. Er erscheint im Pfad der Ressource und ist im Allgemeinen ein erforderlicher Parameter für alle Advertiser-API-Anfragen mit Ausnahme von GET accounts. Das angegebene Konto muss dem authentifizierten Benutzer zugeordnet sein.

Type: string

Beispiel: 18ce54d4x5t
ab_test_id
erforderlich		Eine Referenz auf den A/B-Test, mit dem Sie in der Anfrage arbeiten.

Type: string

Beispiel: hr7l0
description
optional		Die Beschreibung des A/B-Tests. Maximale Länge: 1.024 Zeichen.

Hinweis: Kann nur aktualisiert werden, solange der status des A/B-Tests SCHEDULED ist.

Type: string

Beispiel: documentation example
end_time
optional		Der Zeitpunkt (im ISO-8601-Format), zu dem der A/B-Test endet.

Hinweis: Kann nur aktualisiert werden, solange der status des A/B-Tests SCHEDULED oder LIVE ist.

Type: string

Beispiel: 2020-10-02T00:00:00Z
name
optional		Der Name des A/B-Tests. Maximale Länge: 255 Zeichen.

Hinweis: Kann nur aktualisiert werden, solange der status des A/B-Tests SCHEDULED ist.

Type: string

Beispiel: first AB test
start_time
optional		Der Zeitpunkt (im ISO-8601-Format), zu dem der A/B-Test beginnt.

Hinweis: Kann nur aktualisiert werden, solange der status des A/B-Tests SCHEDULED ist.

Type: string

Beispiel: 2022-05-30T00:00:00Z
user_groups
erforderlich		Beschreibt die Nutzergruppen. Weitere Informationen in der Tabelle unten.

Hinweis: Kann nur aktualisiert werden, solange der status des A/B-Tests SCHEDULED ist.

Type: array of objects

​
Nutzergruppen

NameBeschreibung
id
manchmal erforderlich		Ein Verweis auf das Nutzergruppenobjekt, mit dem die Anfrage arbeitet.

Hinweis: Erforderlich beim Modifizieren (Ändern, Hinzufügen oder Entfernen) von fields des Nutzergruppenobjekts.

Hinweis: Geben Sie keine ID an, wenn ganze Nutzergruppenobjekte hinzugefügt oder entfernt werden.

Type: string

Example: p1bcx
description
optional		Die Beschreibung der Nutzergruppe. Maximale Länge: 1.024 Zeichen.

Hinweis: Aufheben (entfernen), indem Sie das Feld mit dem Wert null angeben.

Type: string

Example: second AB test group
entity_ids
optional		Ein Array von Entity-IDs.

Hinweis: Dies ist eine Ersetzungsoperation. Sie überschreibt alle zuvor gesetzten Werte.

Hinweis: Entities können nur einem A/B-Test zugeordnet sein.

Type: array

Example: ["dxi0l", "e66bl"]
name
optional		Der Name der Nutzergruppe. Maximale Länge: 255 Zeichen.

Hinweis: Aufheben (entfernen), indem Sie das Feld mit dem Wert null angeben.

Type: string

Example: first group
size
optional		Der Prozentsatz der Nutzer, die dieser Nutzergruppe zugewiesen werden. Dies ist ein numerischer Wert, der als Zeichenfolge dargestellt wird, mit höchstens zwei Stellen nach dem Dezimalpunkt. Beispielsweise 40 % als 40, 40.0 oder 40.00 angeben.

Hinweis: Die size-Werte über alle objects hinweg müssen in Summe 100.00 ergeben.

Type: string

Min, Max: 1.00, 99.00
Beispielanfrage
Diese Anfrage nimmt die folgenden Änderungen vor.
  1. Entfernt die A/B-Testbeschreibung
  2. Ändert die Endzeit
  3. Fügt der ersten Nutzergruppe eine Beschreibung hinzu
  4. Ändert den Prozentsatz der Nutzer in jeder Nutzergruppe
  5. Fügt der zweiten Nutzergruppe eine Entitäts-id (f2syz) hinzu
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"]}]}'
Beispielantwort
    {
      "request": {
        "params": {
          "account_id": "18ce54d4x5t",
          "ab_test_id": "hr7l0",
          "description": null,
          "end_time": "2022-06-01T01:00:00Z",
          "user_groups": [
            {
              "id": "p1bcx",
              "description": "erste AB-Test-Gruppe",
              "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": "erster AB-Test",
        "start_time": "2022-05-25T01:00:00Z",
        "status": "SCHEDULED",
        "user_groups": [
          {
            "id": "p1bcx",
            "name": "erste Gruppe",
            "description": "erste AB-Test-Gruppe",
            "size": "60.0",
            "entity_ids": [
              "f2qcw",
              "f2tht"
            ]
          },
          {
            "id": "p1bcy",
            "name": "zweite Gruppe",
            "description": "zweite AB-Test-Gruppe",
            "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

Löscht den angegebenen A/B-Test. Hinweis: Das Löschen eines A/B-Tests ist irreversibel, und spätere Versuche, die Ressource zu delete, führen zu HTTP 404.
Ressourcen-URL
https://ads-api.x.com/12/accounts/:account_id/ab_tests/:ab_test_id
Parameter
NameBeschreibung
ab_test_id
erforderlich		Ein Verweis auf den A/B-Test, auf den sich die Anfrage bezieht.

Type: string

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

​
Beispielantwort

    {
      "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": "erster AB-Test",
        "start_time": "2022-05-25T01:00:00Z",
        "status": "SCHEDULED",
        "user_groups": [
          {
            "id": "p1bcx",
            "name": "erste Gruppe",
            "description": "erste AB-Test-Gruppe",
            "size": "60.0",
            "entity_ids": [
              "f2qcw",
              "f2tht"
            ]
          },
          {
            "id": "p1bcy",
            "name": "zweite Gruppe",
            "description": "zweite AB-Test-Gruppe",
            "size": "40.0",
            "entity_ids": [
              "f2rqi",
              "f2tws",
              "f2syz"
            ]
          }
        ],
        "updated_at": "2022-06-02T00:18:31Z",
        "updated_by": {
          "user_id": "756201191646691328",
          "username": "apimctestface"
        }
      }
    }
⌘I