Test A/B

​

Présentation

​

Introduction

Les tests A/B permettent aux annonceurs de segmenter les utilisateurs qu’ils atteignent sur X afin de déterminer la meilleure manière d’optimiser les performances des campagnes et de tirer des enseignements pour orienter leurs stratégies marketing.

Ces segments — appelés découpages en groupes d’utilisateurs — sont aléatoires et mutuellement exclusifs. Avec l’aléatorisation, les facteurs influençant les résultats sont répartis équitablement. En d’autres termes, il n’existe aucune différence intrinsèque entre les groupes ni dans leurs comportements attendus. Ainsi, lorsqu’une seule variation est appliquée à un groupe d’utilisateurs et pas aux autres, l’écart de performance de la campagne peut être attribué à cette variation.

Bien qu’il soit possible de tester de nombreuses variations simultanément, nous recommandons vivement de tester une seule variation à la fois. Cela permet d’isoler le facteur causal de la différence observée dans les performances de la campagne.

Les variations sont définies au niveau de la campagne. Par exemple, si l’annonceur souhaite tester l’efficacité d’un nouveau créatif, il doit créer deux campagnes identiques dont la seule différence est le créatif. À l’avenir, nous prévoyons de prendre en charge des variations au niveau de la ligne d’élément.

​

Cas d’utilisation

Les tests A/B sont le plus souvent utilisés pour (1) des cas d’usage d’optimisation, par des annonceurs orientés performance qui souhaitent déterminer ce qui fonctionne le mieux sur X afin d’optimiser leur investissement, et (2) des cas d’usage d’apprentissage, par des annonceurs de marque qui veulent exploiter ces enseignements pour orienter leur stratégie marketing. 

L’API prendra en charge les tests A/B pour toute variable de campagne, notamment :

• Créatif

• Ciblage

• Type d’enchère

• Unité d’enchère

​

Tests A/B

Les tests A/B permettent aux annonceurs de segmenter les utilisateurs qu’ils atteignent sur X afin de déterminer la meilleure façon d’optimiser les performances de leurs campagnes et d’en tirer des enseignements pour orienter leurs stratégies marketing.

Ces segments — appelés répartitions de groupes d’utilisateurs — sont aléatoires et mutuellement exclusifs. Grâce à l’aléatorisation, les facteurs qui influencent les résultats sont répartis équitablement. En d’autres termes, il n’existe aucune différence intrinsèque entre les groupes ni entre leurs comportements attendus. Ainsi, lorsqu’une seule variation est appliquée à un groupe d’utilisateurs et pas aux autres, la différence de performance de la campagne peut être attribuée à cette variation.

Bien qu’il soit possible de tester plusieurs variations simultanément, nous recommandons vivement de tester une seule variation à la fois. Cela isole le facteur causal de la différence observée dans les performances de la campagne.

Les variations sont définies au niveau de la campagne ou au niveau du groupe d’annonces. Le groupe d’annonces est défini via le line item dans X Ads API. À titre d’exemple de variation au niveau du groupe d’annonces, si l’annonceur souhaite tester l’efficacité d’une nouvelle création, il doit créer une campagne avec deux groupes d’annonces identiques où la seule différence est la création.

​

Cas d’utilisation

Les tests A/B sont le plus souvent utilisés pour (1) des cas d’utilisation d’optimisation, par des clients axés sur la performance qui souhaitent identifier ce qui fonctionne le mieux sur X afin d’optimiser leur investissement, et (2) des cas d’utilisation d’apprentissage, par des annonceurs de marque qui souhaitent exploiter les enseignements pour guider leur stratégie marketing.

L’API prendra en charge les tests A/B pour toute variable de campagne, notamment :

• Créatif
• Ciblage
• Type d’enchère
• Unité d’enchère

​

Attributs

Les tests A/B sont représentés sous forme de structures imbriquées. Il existe des champs de niveau supérieur pour le test A/B lui-même et un tableau d’objets de groupes d’utilisateurs, chacun avec un ensemble de champs descriptifs.

À un niveau général, chaque test A/B doit inclure les informations suivantes.

• La durée du test, représentée par les champs start_time et end_time

• Le niveau auquel la répartition s’effectuera, représenté par le champ entity_type

• Au moins deux (et au plus 30) groupes d’utilisateurs, chacun représenté par un objet dans le tableau user_groups

Chaque groupe d’utilisateurs doit obligatoirement inclure les informations suivantes.

• Le pourcentage d’utilisateurs à affecter au groupe concerné, représenté par le champ size

• Les IDs de campagnes/IDs d’éléments de ligne qui doivent constituer le vivier d’utilisateurs pour le groupe concerné, représentés par le tableau entity_ids

En option, des valeurs name et description peuvent être définies pour les tests A/B et pour les groupes d’utilisateurs. Des informations sur les règles de validation et autres contraintes figurent ci-dessous.

D’autres metadata, telles que l’ID ou l’horodatage de création, sont également incluses, mais sont automatiquement définies par X.

Un exemple d’entité de test A/B au niveau campagne est présenté ci-dessous.

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

Un exemple d’entité de test A/B au niveau de la ligne d’articles est présenté ci-dessous.

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

​

Utilisation

Les sous-sections ci-dessous expliquent comment créer et mettre à jour des tests A/B. La lecture et la suppression fonctionnent comme pour tous les autres endpoints de la X Ads API.

​

Création

Créez un test A/B à l’aide de l’endpoint POST accounts/:account_id/ab_tests. Cet endpoint n’accepte que des corps de requête POST au format JSON. L’en-tête Content-Type doit être défini sur application/json.

Une fois que l’annonceur a configuré au moins deux campagnes, un test A/B peut être créé. Comme indiqué ci-dessus, les tests A/B doivent inclure la durée du test, le niveau de répartition et au moins deux groupes d’utilisateurs. Chaque groupe d’utilisateurs doit indiquer le pourcentage d’utilisateurs qui lui est attribué ainsi que les IDs de campagnes constituant son pool d’utilisateurs. Chacun de ces éléments est détaillé ci-dessous.

Durée du test :

• Les valeurs start_time et end_time doivent

  • être dans le futur (par rapport au moment où le test A/B est créé) ;

  • chevaucher les dates de diffusion de la campagne/de la ligne d’achat.

• Le test doit durer au moins un jour pour les campagnes non orientées App et au moins cinq jours pour les campagnes orientées App.

Niveau de répartition :

• entity_type peut être défini sur CAMPAIGN ou LINE_ITEM.

Groupes d’utilisateurs :

• Chaque groupe d’utilisateurs est représenté par un objet dans le tableau user_groups

  • Un minimum de deux groupes d’utilisateurs est requis

  • Un maximum de 30 groupes d’utilisateurs est autorisé

• La taille de chaque groupe d’utilisateurs est définie à l’aide d’une chaîne représentant une valeur numérique comprise entre 1.00 et 99.00

  • Remarque : les valeurs de taille entre les objets doivent totaliser 100.00

• Les IDs de campagnes doivent être spécifiés dans le tableau entity_ids de chaque groupe d’utilisateurs

Vous pouvez en option définir le nom et la description du test A/B ou d’un ou plusieurs groupes d’utilisateurs.

La requête suivante crée un test A/B au niveau campagne d’une durée de quatre jours, avec deux groupes d’utilisateurs contenant chacun 50 % des utilisateurs. Le premier groupe est basé sur les campagnes f2qcw et f2tht ; le second groupe est basé sur les campagnes f2rqi et f2tws. La requête ajoute également des noms et des descriptions à certaines parties de l’entité.

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

Pour les tests A/B au niveau de l’élément de campagne (line item)

La principale différence entre les tests A/B au niveau de la campagne et au niveau de l’élément de campagne est le champ entity_type. Nous devons le définir sur ‘entity_type’ = ‘LINE_ITEM’ pour les tests A/B au niveau de l’élément de campagne. Cela s’applique à toutes les actions sur un test A/B déjà créé ci-dessous. 

Exigences :

1. Tous les éléments de campagne de la campagne de test A/B doivent être inclus dans le test fractionné.
2. Seule une répartition égale est autorisée au niveau de l’élément de campagne.
3. Le nombre d’éléments de campagne par groupes d’utilisateurs autorisés dans 1 test fractionné doit être inférieur ou égal à 5. 
4. Un seul élément de campagne par groupe d’utilisateurs.

​

Mise à jour

Mettez à jour un test A/B à l’aide de l’endpoint PUT accounts/:account_id/ab_tests/:ab_test_id. L’endpoint exige qu’un blob JSON soit envoyé dans la requête. L’en-tête Content-Type doit être défini sur application/json.

Comme pour les autres endpoints de mise à jour, l’endpoint PUT accounts/:account_id/ab_tests/:ab_test_id exige que l’id du test A/B soit référencé dans l’URL. En général, les tests A/B ne peuvent être mis à jour que lorsque le statut est SCHEDULED. Il existe une exception : il est possible de mettre à jour le end_time du test A/B lorsqu’il est LIVE.

Cet endpoint prend en charge du JSON partiel avec des id d’objet. Les principes suivants s’appliquent :

• Pour ajouter ou supprimer des objets ou des éléments, envoyez l’intégralité du tableau (et ses sous-structures) ; il s’agit d’une opération de remplacement

• Sinon, modifiez (ajoutez, changez, supprimez) les fields existants en référencant des noms de clé ou des id

  • Pour supprimer un field, définissez sa valeur sur null

  • Les fields qui ne sont pas transmis ne sont pas modifiés

Par exemple, ajouter un troisième groupe d’utilisateurs au test A/B précédemment créé nécessiterait d’envoyer le tableau user_groups avec les deux objets de groupe d’utilisateurs existants ainsi qu’avec le nouveau que nous souhaitons ajouter. Considérez cela comme une recréation du tableau user_groups ; envoyez les data comme si vous le créiez de cette manière dès le départ (ne transmettez pas d’id d’objet de groupe d’utilisateurs). Le tableau user_groups dans la requête de mise à jour pourrait être représenté comme suit.

[
  {
    "entity_ids": [
      "f2qcw",
      "f2tht"
    ],
    "size": "30.0",
    "name": "premier groupe"
  },
  {
    "entity_ids": [
      "f2rqi",
      "f2tws"
    ],
    "size": "30.0",
    "name": "deuxième groupe",
    "description": "deuxième groupe de test AB"
  },
  {
    "entity_ids": [
      "i1vwr",
      "i1xre"
    ],
    "size": "40.0"
  }
]

Remarquez que les valeurs de taille pour l’ensemble des objets totalisent toujours 100,00. Si nous ne les avions pas mises à jour pour les deux premiers objets — auparavant fixés à 50,00 chacun —, la requête aurait échoué.

Si, à la place, nous voulions simplement ajouter une description au premier groupe d’utilisateurs, le tableau user_groups dans la requête de mise à jour serait représenté comme suit.

[
  {
    "id": "p1bcx",
    "description": "mis à jour via une requête PUT"
  }
]

Nous faisons référence à l’objet groupe d’utilisateurs par son id et n’incluons que le champ que nous souhaitons modifier.

​

Exemples de requêtes

Cette section propose des exemples supplémentaires de requêtes de mise à jour. Considérez qu’elles sont exécutées séquentiellement. Les objets JSON sont formatés pour en faciliter la lecture. Les réponses sont omises.

Pour effectuer les modifications suivantes, la requête serait la suivante. (Il s’agit du même exemple que celui utilisé plus haut.)

1. Ajoute un troisième groupe d’utilisateurs sans nom ni description

2. Modifie le pourcentage d’utilisateurs dans chaque groupe d’utilisateurs

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": "premier groupe"
    },
    {
      "entity_ids": [
        "f2rqi",
        "f2tws"
      ],
      "size": "30.00",
      "name": "deuxième groupe",
      "description": "deuxième groupe de test A/B"
    },
    {
      "entity_ids": [
        "i1vwr",
        "i1xre"
      ],
      "size": "40.00"
    }
  ]
}'

Pour apporter les modifications suivantes, la requête se présenterait comme suit.

1. Supprime la description du test A/B

2. Ajoute une description au premier groupe d’utilisateurs

3. Ajoute un id d’entité (f2syz) au deuxième groupe d’utilisateurs

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": "premier groupe de test A/B"
    },
    {
      "id": "p1bcy",
      "entity_ids": [
        "f2rqi",
        "f2tws",
        "f2syz"
      ]
    }
  ]
}'

La troisième modification exige que nous transmettions les deux id d’entité existants ainsi que le nouveau. Notez qu’aucune modification n’a été apportée au troisième groupe d’utilisateurs.

Pour effectuer les modifications suivantes, la requête se présenterait comme suit.

1. Supprime le deuxième groupe d’utilisateurs

2. Modifie le pourcentage d’utilisateurs dans chaque groupe d’utilisateurs

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": "premier groupe"
    },
    {
      "entity_ids": [
        "i1vwr",
        "i1xre"
      ],
      "size": "45.00"
    }
  ]
}'

​

Référence de l’API

​

Tests A/B

Exécuter dans Postman

​

GET accounts/:account_id/ab_tests

Récupère les détails d’une partie ou de l’ensemble des tests A/B.

URL de ressource

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

Paramètres

Nom	Description
account_id obligatoire	Identifiant du compte utilisé. Apparaît dans le chemin de la ressource et est généralement un paramètre requis pour toutes les requêtes de l’API Ads, à l’exception de GET accounts. Le compte spécifié doit être associé à l’utilisateur authentifié. Type : string Exemple : 18ce54d4x5t
ab_test_ids optionnel	Limite la réponse aux tests A/B souhaités en spécifiant une liste d’identifiants séparés par des virgules. Jusqu’à 200 id peuvent être fournis. Type : string Exemple : hr7l0
count optionnel	Spécifie le nombre d’enregistrements à tenter de récupérer par requête distincte. Type : int Valeur par défaut : 200 Min, Max : 1, 1000
cursor optionnel	Spécifie un curseur pour obtenir la page suivante de résultats. Voir Pagination pour plus d’informations. Type : string Exemple : 8x7v00oow
live_during optionnel	Limite la réponse aux tests A/B qui étaient ou seront actifs pendant l’intervalle de dates indiqué. Renvoie les tests A/B dont les heures de début et de fin se chevauchent — partiellement ou totalement — avec cet intervalle. Indiquez les valeurs comme des dates séparées par des virgules, au format ISO 8601. Renseignez d’abord la date la plus ancienne. Type : string Exemple : 2020-11-01T08:00:00Z,2020-12-01T08:00:00Z
q optionnel	Paramètre query facultatif pour filtrer la ressource par name. Omettez ce paramètre pour tout récupérer. Type : string Longueur min, max : 1, 80
sort_by optionnel	Trie selon un attribut pris en charge, par ordre croissant ou décroissant. Voir Sorting pour plus d’informations. Type : string Exemple : created_at-asc
status optionnel	Limite la réponse aux tests A/B avec l’état souhaité. Type : enum Valeurs possibles : COMPLETED, LIVE, SCHEDULED
user_id optionnel	Limite la réponse aux tests A/B créés par l’id utilisateur spécifié. Remarque : Ne peut pas être utilisé en même temps que username. Type : long Exemple : 756201191646691328.
username optionnel	Limite la réponse aux tests A/B créés par le nom d’utilisateur spécifié. N’incluez pas le symbole « @ » initial. Remarque : Ne peut pas être utilisé en même temps que user_id. Type : string Exemple : apimctestface.
with_deleted optionnel	Inclut les résultats supprimés dans votre requête. Type : boolean Valeur par défaut : false Valeurs possibles : true, false

Exemple de requête

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

Exemple de réponse

    {
      "request": {
        "params": {
          "account_id": "18ce54d4x5t"
        }
      },
      "data": [
        {
          "created_at": "2022-05-25T00:00:00Z",
          "created_by": {
            "user_id": "756201191646691328",
            "username": "apimctestface"
          },
          "deleted": false,
          "description": "exemple de documentation",
          "end_time": "2022-05-30T01:00:00Z",
          "entities": [
            {
              "id": "p1bcx",
              "account_id": "18ce54d4x5t"
            },
            {
              "id": "p1bcy",
              "account_id": "18ce54d4x5t"
            }
          ],
          "entity_type": "CAMPAIGN",
          "id": "hr7l0",
          "name": "premier test AB",
          "start_time": "2022-05-25T01:00:00Z",
          "status": "SCHEDULED",
          "user_groups": [
            {
              "id": "p1bcx",
              "name": "premier groupe",
              "description": null,
              "size": "50.0",
              "entity_ids": [
                "f2qcw",
                "f2tht"
              ]
            },
            {
              "id": "p1bcy",
              "name": "deuxième groupe",
              "description": "deuxième groupe de test 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

Créez un nouveau test A/B.

Tous les paramètres sont transmis dans le corps de la requête et l’en-tête Content-Type doit être défini sur application/json.

URL de ressource

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

Paramètres

Nom	Description
account_id obligatoire	L’identifiant du compte exploité. Apparaît dans le chemin de la ressource et constitue généralement un paramètre requis pour toutes les requêtes de l’API Ads, à l’exception de GET accounts. Le compte spécifié doit être associé à l’utilisateur authentifié. Type : string Exemple : 18ce54d4x5t
end_time obligatoire	L’heure, exprimée en ISO 8601, à laquelle le test A/B se termine. Type : string Exemple : 2020-10-02T00:00:00Z
entity_type obligatoire	Le type d’entité à utiliser pour la répartition des groupes d’utilisateurs. Type : enum Valeurs possibles : CAMPAIGN, LINE_ITEM
start_time obligatoire	L’heure, exprimée en ISO 8601, à laquelle le test A/B commence. Type : string Exemple : 2022-05-30T00:00:00Z
user_groups obligatoire	Décrit les groupes d’utilisateurs. Plus d’informations dans le tableau ci-dessous. Entre 2 et 30 groupes d’utilisateurs peuvent être spécifiés. Type : array of objects
description facultatif	Description du test A/B. Longueur maximale : 1 024 caractères. Type : string Exemple : documentation example
name facultatif	Nom du test A/B. Longueur maximale : 255 caractères. Type : string Exemple : first AB test

​

Groupes d’utilisateurs

Nom	Description
entity_ids requis	Un tableau d’id d’entité. Remarque : Les entités ne peuvent être associées qu’à un seul test A/B. Type : array Exemple : ["dxi0l", "e66bl"]
size requis	Le pourcentage d’utilisateurs à attribuer à ce groupe d’utilisateurs. Il s’agit d’une valeur numérique représentée sous forme de chaîne, avec au plus deux chiffres après la virgule. Par exemple, représenter 40 % par : 40, 40.0 ou 40.00. Remarque : Les valeurs de taille au sein des objets doivent totaliser 100.00. Type : array Min, Max : 1.00, 99.00
description optionnel	La description du groupe d’utilisateurs. Longueur maximale : 1 024 caractères. Type : string Exemple : second AB test group
name optionnel	Le nom du groupe d’utilisateurs. Longueur maximale : 255 caractères. Type : string Exemple : first group

​

Exemple de requête

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"}'

​

Exemple de réponse

    {
      "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": "premier groupe"
            },
            {
              "entity_ids": [
                "f2rqi",
                "f2tws"
              ],
              "size": "50.0",
              "name": "second group",
              "description": "deuxième groupe de test A/B"
            }
          ],
          "name": "premier test A/B",
          "description": "exemple de la documentation"
        }
      },
      "data": {
        "created_at": "2022-05-25T00:00:00Z",
        "created_by": {
          "user_id": "756201191646691328",
          "username": "apimctestface"
        },
        "deleted": false,
        "description": "exemple de la documentation",
        "end_time": "2022-05-30T01:00:00Z",
        "entities": [
          {
            "id": "p1bcx",
            "account_id": "18ce54d4x5t"
          },
          {
            "id": "p1bcy",
            "account_id": "18ce54d4x5t"
          }
        ],
        "entity_type": "CAMPAIGN",
        "id": "hr7l0",
        "name": "premier test A/B",
        "start_time": "2022-05-25T01:00:00Z",
        "status": "SCHEDULED",
        "user_groups": [
          {
            "id": "p1bcx",
            "name": "premier groupe",
            "description": null,
            "size": "50.0",
            "entity_ids": [
              "f2qcw",
              "f2tht"
            ]
          },
          {
            "id": "p1bcy",
            "name": "deuxième groupe",
            "description": "deuxième groupe de test A/B"
            "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

Met à jour le test A/B spécifié.

Tous les paramètres sont envoyés dans le corps de la requête et l’en-tête Content-Type doit être application/json.

Cet endpoint prend en charge du JSON partiel avec des id d’objet. Les principes suivants s’appliquent :

• Pour ajouter ou supprimer des objets ou des éléments, transmettez le tableau entier (et ses sous-structures) ; il s’agit d’une opération de remplacement
  • Considérez cela comme la recréation du tableau
• Sinon, modifiez (ajoutez, supprimez, mettez à jour) les champs existants en faisant référence aux noms de clés ou aux id
  • Pour supprimer un champ, définissez sa valeur sur null
  • Les champs non transmis ne sont pas modifiés

En règle générale, les tests A/B ne peuvent être mis à jour que lorsque status est SCHEDULED. Une exception existe : il est possible de mettre à jour end_time du test A/B lorsqu’il est LIVE.

URL de ressource

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

Paramètres

Nom	Description
account_id requis	L’identifiant du compte exploité. Apparaît dans le chemin de la ressource et constitue généralement un paramètre requis pour toutes les requêtes de l’API des publicités, à l’exception de GET accounts. Le compte spécifié doit être associé à l’utilisateur authentifié. Type : string Exemple : 18ce54d4x5t
ab_test_id requis	Référence au test A/B utilisé dans la requête. Type : string Exemple : hr7l0
description optionnel	Description du test A/B. Longueur maximale : 1 024 caractères. Remarque : Ne peut être mise à jour que lorsque le status du test A/B est SCHEDULED. Type : string Exemple : documentation example
end_time optionnel	Heure, au format ISO 8601, à laquelle le test A/B se termine. Remarque : Ne peut être mise à jour que lorsque le status du test A/B est SCHEDULED ou LIVE. Type : string Exemple : 2020-10-02T00:00:00Z
name optionnel	Nom du test A/B. Longueur maximale : 255 caractères. Remarque : Ne peut être mis à jour que lorsque le status du test A/B est SCHEDULED. Type : string Exemple : first AB test
start_time optionnel	Heure, au format ISO 8601, à laquelle le test A/B commence. Remarque : Ne peut être mise à jour que lorsque le status du test A/B est SCHEDULED. Type : string Exemple : 2022-05-30T00:00:00Z
user_groups requis	Décrit les groupes d’utilisateurs. Plus d’informations dans le tableau ci‑dessous. Remarque : Ne peut être mis à jour que lorsque le status du test A/B est SCHEDULED. Type : array of objects

​

Groupes d’utilisateurs

Nom	Description
id parfois requis	Référence à l’objet « groupe d’utilisateurs » avec lequel la requête opère. Remarque : Requis lors de la modification (changement, ajout ou suppression) des fields de l’objet groupe d’utilisateurs. Remarque : Ne spécifiez pas d’ID lors de l’ajout ou de la suppression d’objets groupe d’utilisateurs entiers. Type : string Exemple : p1bcx
description facultatif	Description du groupe d’utilisateurs. Longueur maximale : 1 024 caractères. Remarque : Pour annuler (supprimer), indiquez le champ avec la valeur null. Type : string Exemple : second AB test group
entity_ids facultatif	Tableau d’ID d’entité. Remarque : Il s’agit d’une opération de remplacement. Elle écrase toute valeur définie précédemment. Remarque : Les entités ne peuvent être associées qu’à un seul test A/B. Type : array Exemple : ["dxi0l", "e66bl"]
name facultatif	Nom du groupe d’utilisateurs. Longueur maximale : 255 caractères. Remarque : Pour annuler (supprimer), indiquez le champ avec la valeur null. Type : string Exemple : first group
size facultatif	Pourcentage d’utilisateurs à allouer à ce groupe d’utilisateurs. Valeur numérique représentée sous forme de chaîne, avec au plus deux chiffres après la virgule. Par exemple, représentez 40 % ainsi : 40, 40.0 ou 40.00. Remarque : Les valeurs de taille entre les objects doivent totaliser 100.00. Type : string Min, Max : 1.00, 99.00

Exemple de requête

Cette requête apporte les modifications suivantes.

1. Supprime la description du test A/B
2. Modifie l’heure de fin
3. Ajoute une description au premier groupe d’utilisateurs
4. Modifie le pourcentage d’utilisateurs dans chaque groupe d’utilisateurs
5. Ajoute un id d’entité (« f2syz ») au deuxième groupe d’utilisateurs

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

Exemple de réponse

    {
      "request": {
        "params": {
          "account_id": "18ce54d4x5t",
          "ab_test_id": "hr7l0",
          "description": null,
          "end_time": "2022-06-01T01:00:00Z",
          "user_groups": [
            {
              "id": "p1bcx",
              "description": "premier groupe de test A/B",
              "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": "premier test A/B"
        "start_time": "2022-05-25T01:00:00Z",
        "status": "SCHEDULED",
        "user_groups": [
          {
            "id": "p1bcx",
            "name": "premier groupe",
            "description": "premier groupe de test A/B",
            "size": "60.0",
            "entity_ids": [
              "f2qcw",
              "f2tht"
            ]
          },
          {
            "id": "p1bcy",
            "name": "deuxième groupe",
            "description": "deuxième groupe de test A/B",
            "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

Supprime le test A/B spécifié.

Remarque : La suppression d’un test A/B est irréversible et toute tentative ultérieure de suppression de la ressource renverra un HTTP 404.

URL de ressource

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

Paramètres

Nom	Description
ab_test_id obligatoire	Référence au test A/B utilisé dans la requête. Type : string Exemple : hr7l0

Exemple de requête

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

​

Exemple de réponse

    {
      "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": "premier test A/B",
        "start_time": "2022-05-25T01:00:00Z",
        "status": "SCHEDULED",
        "user_groups": [
          {
            "id": "p1bcx",
            "name": "premier groupe",
            "description": "premier groupe de test A/B",
            "size": "60.0",
            "entity_ids": [
              "f2qcw",
              "f2tht"
            ]
          },
          {
            "id": "p1bcy",
            "name": "deuxième groupe",
            "description": "deuxième groupe de test A/B"
            "size": "40.0",
            "entity_ids": [
              "f2rqi",
              "f2tws",
              "f2syz"
            ]
          }
        ],
        "updated_at": "2022-06-02T00:18:31Z",
        "updated_by": {
          "user_id": "756201191646691328",
          "username": "apimctestface"
        }
      }
    }