Vai al contenuto principale

​
Panoramica

​
Introduzione

L’A/B testing consente agli inserzionisti di segmentare gli utenti raggiunti su X, così da capire come ottimizzare al meglio le performance della campagna e raccogliere insight per orientare le loro strategie di marketing. Questi segmenti — detti suddivisioni di gruppi di utenti — sono casuali e mutualmente esclusivi. Con l’assegnazione casuale, i fattori che influenzano i risultati sono distribuiti in modo uniforme. In altre parole, non ci sono differenze intrinseche tra i gruppi né nei loro comportamenti attesi. Per questo motivo, quando si applica una singola variazione a un gruppo di utenti e non agli altri, l’eventuale differenza nelle performance della campagna può essere attribuita a quella variazione. Sebbene sia possibile testare più variazioni contemporaneamente, raccomandiamo vivamente di testarne una sola alla volta. In questo modo si isola il fattore causale alla base della differenza osservata nelle performance della campagna. Le variazioni sono impostate a livello di campagna. Ad esempio, se l’inserzionista desidera testare l’efficacia di una nuova creatività, dovrebbe creare due campagne identiche in cui l’unica differenza è la creatività. In futuro, prevediamo di supportare le variazioni a livello di line item.

​
Casi d’uso

Il testing A/B è usato più spesso per supportare: (1) casi d’uso di ottimizzazione per clienti orientati alle performance che vogliono capire cosa funziona meglio su X per ottimizzare i loro investimenti; e (2) casi d’uso di apprendimento per inserzionisti di marca che desiderano utilizzare gli insight per definire la loro strategia di marketing.  L’API supporterà il testing A/B per qualsiasi variabile di campagna, tra cui:
  • Creatività 
  • Targeting 
  • Tipo di offerta
  • Unità di offerta

​
Test A/B

I test A/B consentono agli inserzionisti di segmentare gli utenti raggiunti su X, così da capire come ottimizzare al meglio le prestazioni della campagna e raccogliere insight utili a orientare le strategie di marketing. Questi segmenti—detti suddivisioni in gruppi di utenti—sono randomizzati e mutuamente esclusivi. Con la randomizzazione, i fattori che influenzano i risultati sono distribuiti in modo uniforme. In altre parole, non ci sono differenze intrinseche tra i gruppi né nei comportamenti attesi. Per questo motivo, quando una singola variazione viene applicata a un gruppo di utenti e non agli altri, l’eventuale differenza nelle prestazioni della campagna è attribuibile a quella variazione. Sebbene sia possibile testare molte variazioni contemporaneamente, consigliamo vivamente di testarne una sola alla volta. In questo modo si isola il fattore causale della differenza osservata nelle prestazioni della campagna. Le variazioni possono essere impostate a livello di campagna o di gruppo di annunci. Il gruppo di annunci è configurato tramite line item in X Ads API. Come esempio di una variazione a livello di gruppo di annunci, se l’inserzionista desidera testare l’efficacia di una nuova creatività, dovrebbe creare una campagna con 2 gruppi di annunci identici in cui l’unica differenza è la creatività.

​
Casi d’uso

L’A/B testing è usato più frequentemente per supportare (1) casi d’uso di ottimizzazione per clienti orientati alla performance che desiderano capire cosa funziona meglio su X, così da ottimizzare il loro investimento, e (2) casi d’uso di apprendimento per inserzionisti di marca che vogliono utilizzare gli insight per definire la loro strategia di marketing. L’API supporterà l’A/B testing per qualsiasi variabile di campagna, tra cui:
  • Creatività
  • Targeting
  • Tipo di offerta
  • Unità di offerta

​
Attributi

I test A/B sono rappresentati come strutture annidate. Sono presenti campi di livello superiore per il test A/B stesso e un array di oggetti relativi ai gruppi di utenti, ciascuno con un insieme di campi descrittivi. A livello generale, ogni test A/B deve includere le seguenti informazioni.
  • La durata del test, rappresentata dai campi start_time ed end_time
  • Il livello al quale avverrà la suddivisione, rappresentato dal campo entity_type
  • Almeno due (e al massimo 30) gruppi di utenti, ciascuno rappresentato come oggetto nell’array user_groups
Ogni gruppo di utenti deve includere le seguenti informazioni.
  • La percentuale di utenti da allocare al gruppo di utenti in questione, rappresentata dal campo size
  • Gli ID di campagna/gli ID delle linee elemento che devono costituire il pool di utenti per il gruppo di utenti in questione, rappresentati dall’array entity_ids
Facoltativamente, è possibile impostare i valori name e description per i test A/B e per i gruppi di utenti. Di seguito sono disponibili informazioni sulle regole di convalida e su altri vincoli. Altri metadata, come l’id o la data/ora di creazione, sono anch’essi inclusi, ma vengono impostati automaticamente da X. Di seguito è mostrato un esempio di entità di test A/B a livello campagna. 
{
  "created_at": "2020-12-01T00:00:00Z",
  "created_by": {
    "user_id": "756201191646691328",
    "username": "apimctestface"
  },
  "deleted": false,
  "description": "esempio di documentazione",
  "end_time": "2020-12-05T01:00:00Z",
  "entity_type": "CAMPAIGN",
  "id": "hr7l0",
  "name": "primo test AB",
  "start_time": "2020-12-01T01:00:00Z",
  "status": "SCHEDULED",
  "user_groups": [
    {
      "id": "p1bcx",
      "name": "primo gruppo",
      "description": null,
      "size": "50.0",
      "entity_ids": [
        "f2qcw",
        "f2tht"
      ]
    },
    {
      "id": "p1bcy",
      "name": "secondo gruppo",
      "description": "secondo gruppo del test AB",
      "size": 50,
      "entity_ids": [
        "f2rqi",
        "f2tws"
      ]
    }
  ],
  "updated_at": "2020-12-01T00:00:00Z",
  "updated_by": {
    "user_id": "756201191646691328",
    "username": "apimctestface"
  }
}
Di seguito è riportato un esempio di entità di test A/B a livello di line item. 
{
   "created_by":{
      "user_id":"756201191646691328",
      "username":"apimctestface"
   },
   "name":"Test2e",
   "start_time":"2022-08-15T00:00:00Z",
   "updated_by":{
      "user_id":"756201191646691328",
      "username":"apimctestface"
   },
   "description":"Il mio secondo test A/B",
   "entity_type":"LINE_ITEM",
   "end_time":"2022-08-30T00:00:00Z",
   "id":"1ul",
   "user_groups":[
      {
         "name":"primo gruppo",
         "size":"50.0",
         "description":"descrizione del primo gruppo",
         "entity_ids":[
            "ij9dh"
         ],
         "id":"4xe"
      },
      {
         "name":"secondo gruppo",
         "size":"50.0",
         "description":"descrizione del secondo gruppo",
         "entity_ids":[
            "ihng8"
         ],
         "id":"4xf"
      }
   ],
   "status":"SCHEDULED",
   "created_at":"2022-08-11T00:10:50Z",
   "updated_at":"2022-08-11T00:10:50Z",
   "deleted":false
}

​
Utilizzo

Le sottosezioni seguenti descrivono come creare e aggiornare i test A/B. La lettura e l’eliminazione funzionano come per tutti gli altri endpoint della X Ads API.

​
Creazione

Crea un test A/B utilizzando l’endpoint POST accounts/:account_id/ab_tests. L’endpoint accetta solo payload POST in JSON. Il Content-Type deve essere impostato su application/json. Dopo che l’inserzionista ha configurato due o più campagne, è possibile creare un test A/B. Come indicato sopra, i test A/B devono includere: durata del test, livello di suddivisione e almeno due gruppi di utenti. Ogni gruppo di utenti deve dichiarare la percentuale di utenti da assegnargli, nonché gli ID campagna che devono costituire il suo pool di utenti. Ciascuno di questi aspetti è descritto più in dettaglio di seguito. Durata del test:
  • I valori start_time ed end_time devono
    • essere nel futuro (rispetto al momento in cui viene creato il test A/B)
    • sovrapporsi alle date di flight della campagna/line item
  • Il test deve durare almeno un giorno per le campagne non basate su app e almeno cinque giorni per le campagne basate su app
Livello di suddivisione:
  • entity_type può essere impostato su CAMPAIGN o LINE_ITEM
Gruppi di utenti:
  • Ogni gruppo di utenti è rappresentato come un oggetto nell’array user_groups
    • È richiesto un minimo di due gruppi di utenti
    • È consentito un massimo di 30 gruppi di utenti
  • La dimensione di ciascun gruppo di utenti è impostata utilizzando una stringa che rappresenta un valore numerico compreso tra 1.00 e 99.00
    • Nota: i valori di dimensione complessivi tra gli oggetti devono sommare a 100.00
  • Gli ID campagna devono essere specificati nell’array entity_ids di ciascun gruppo di utenti
Facoltativamente, imposta il nome e la descrizione per il test A/B o per uno o più gruppi di utenti. La seguente richiesta crea un test A/B a livello di campagna che dura quattro giorni e prevede due gruppi di utenti con il 50% degli utenti in ciascun gruppo. Il primo gruppo di utenti si basa sulle campagne f2qcw e f2tht; il secondo gruppo di utenti si basa sulle campagne f2rqi e f2tws. La richiesta aggiunge anche nomi e descrizioni ad alcune parti dell’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"
    }
  }
}
Per l’A/B testing a livello di line item La principale differenza tra l’A/B testing a livello di campagna e a livello di line item è il valore di entity_type. Per gli A/B test a livello di line item, deve essere impostato ‘entity_type’ = ‘LINE_ITEM’. Questo si applica a tutte le azioni su un A/B test già creato riportate di seguito. Requisiti:
  1. Tutti i line item della campagna di A/B testing devono essere inclusi nello split test.
  2. A livello di line item è consentita solo una ripartizione equa.
  3. Il numero di line item per gruppi di utenti consentiti in 1 split test deve essere minore o uguale a 5.
  4. Solo 1 line item per gruppo di utenti.

​
Aggiornamento

Aggiorna un A/B Test usando l’endpoint PUT accounts/:account_id/ab_tests/:ab_test_id. L’endpoint richiede l’invio di un blob JSON nella richiesta. Il Content-Type deve essere impostato su application/json. Come per altri endpoint di aggiornamento, l’endpoint PUT accounts/:account_id/ab_tests/:ab_test_id richiede che l’ID dell’A/B Test sia indicato nell’URL. In generale, gli A/B Test possono essere aggiornati solo quando lo stato è SCHEDULED. C’è un’eccezione: è possibile aggiornare l’end_time dell’A/B Test mentre è LIVE. Questo endpoint supporta JSON parziale con ID di oggetto. Si applicano i seguenti principi:
  • Per aggiungere o rimuovere oggetti o elementi, invia l’intero array (e le relative sottostrutture); si tratta di un’operazione di sostituzione
  • In caso contrario, modifica (cambia, aggiungi, rimuovi) i fields esistenti facendo riferimento ai nomi delle chiavi o agli ID
    • Per rimuovere un field, imposta il suo valore su null
    • I field che non vengono passati non vengono modificati
Ad esempio, per aggiungere un terzo gruppo di utenti all’A/B Test creato in precedenza è necessario inviare l’array user_groups con i due oggetti gruppo di utenti esistenti e con il nuovo che si desidera aggiungere. Consideralo come il ricreare l’array user_groups; invia i data come se lo stessi creando fin dall’inizio (non passare gli ID degli oggetti gruppo di utenti). L’array user_groups nella richiesta di aggiornamento potrebbe essere rappresentato come segue. 
[
  {
    "entity_ids": [
      "f2qcw",
      "f2tht"
    ],
    "size": "30.0",
    "name": "primo gruppo"
  },
  {
    "entity_ids": [
      "f2rqi",
      "f2tws"
    ],
    "size": "30.0",
    "name": "secondo gruppo",
    "description": "secondo gruppo di test A/B"
  },
  {
    "entity_ids": [
      "i1vwr",
      "i1xre"
    ],
    "size": "40.0"
  }
]
Nota che i valori di size tra gli oggetti totalizzano comunque 100,00. Se non li avessimo aggiornati per i primi due oggetti — precedentemente impostati a 50,00 ciascuno — la richiesta sarebbe fallita. Se invece volessimo semplicemente aggiungere una description al primo gruppo di utenti, l’array user_groups nella richiesta di aggiornamento sarebbe rappresentato come segue. 
[
  {
    "id": "p1bcx",
    "description": "aggiornato tramite richiesta PUT"
  }
]
Facciamo riferimento all’oggetto gruppo di utenti tramite id e includiamo solo il campo che intendiamo modificare.

​
Esempi di richieste

Questa sezione fornisce ulteriori esempi di richieste di aggiornamento. Considerale come eseguite in sequenza. I blob JSON sono formattati per facilitarne la lettura. Le risposte sono omesse. Per apportare le seguenti modifiche, la richiesta sarebbe rappresentata come segue. (Si tratta dello stesso esempio utilizzato in precedenza.)
  1. Aggiunge un terzo gruppo di utenti senza nome né descrizione
  2. Modifica la percentuale di utenti in ciascun gruppo di utenti
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": "primo gruppo"
    },
    {
      "entity_ids": [
        "f2rqi",
        "f2tws"
      ],
      "size": "30.00",
      "name": "secondo gruppo",
      "description": "secondo gruppo di test A/B"
    },
    {
      "entity_ids": [
        "i1vwr",
        "i1xre"
      ],
      "size": "40.00"
    }
  ]
}'
Per apportare le seguenti modifiche, la richiesta sarebbe la seguente.
  1. Rimuove la descrizione dell’A/B test
  2. Aggiunge una descrizione al primo gruppo di utenti
  3. Aggiunge un ID entità (f2syz) al secondo gruppo di utenti
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": "primo gruppo di test AB"
    },
    {
      "id": "p1bcy",
      "entity_ids": [
        "f2rqi",
        "f2tws",
        "f2syz"
      ]
    }
  ]
}'
La terza modifica richiede di includere i due ID di entità esistenti insieme a quello nuovo. Nota che non sono state apportate modifiche al terzo gruppo di utenti. Per applicare le seguenti modifiche, la richiesta sarebbe rappresentata come segue.
  1. Rimuove il secondo gruppo di utenti
  2. Modifica la percentuale di utenti in ciascun gruppo di utenti 
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": "primo gruppo"
    },
    {
      "entity_ids": [
        "i1vwr",
        "i1xre"
      ],
      "size": "45.00"
    }
  ]
}'

​
Riferimento all’API

​
Test A/B

​
GET accounts/:account_id/ab_tests

Recupera i dettagli di alcuni o di tutti i test A/B.
URL della risorsa
https://ads-api.x.com/12/accounts/:account_id/ab_tests
Parametri
NomeDescrizione
account_id
obbligatorio		Identificatore dell’account utilizzato. Compare nel percorso della risorsa ed è in genere un parametro obbligatorio per tutte le richieste dell’Advertiser API, escluso GET accounts. L’account specificato deve essere associato all’utente autenticato.

Tipo: string

Esempio: 18ce54d4x5t
ab_test_ids
opzionale		Limita la risposta ai soli A/B Test desiderati specificando un elenco di identificatori separati da virgole. È possibile fornire fino a 200 ID.

Tipo: string

Esempio: hr7l0
count
opzionale		Specifica il numero di record da recuperare per ciascuna richiesta.

Tipo: int

Predefinito: 200
Min, Max: 1, 1000
cursor
opzionale		Specifica un cursore per ottenere la pagina successiva di risultati. Consulta Pagination per ulteriori informazioni.

Tipo: string

Esempio: 8x7v00oow
live_during
opzionale		Limita la risposta agli A/B Test che sono stati o saranno attivi durante l’intervallo di date indicato. Restituisce gli A/B Test i cui orari di inizio e fine si sovrappongono — parzialmente o completamente — all’intervallo di date fornito.

Specifica i valori come date separate da virgole, espresse in ISO 8601. La data più antica deve essere indicata per prima.

Tipo: string

Esempio: 2020-11-01T08:00:00Z,2020-12-01T08:00:00Z
q
opzionale		Query facoltativa per limitare la risorsa in base a name. Ommetti questo parametro per recuperare tutto.

Tipo: string

Lunghezza min, max: 1, 80
sort_by
opzionale		Ordina per attributo supportato, in ordine crescente o decrescente. Consulta Sorting per ulteriori informazioni.

Tipo: string

Esempio: created_at-asc
status
opzionale		Limita la risposta agli A/B Test con lo stato desiderato.

Tipo: enum

Valori possibili: COMPLETED, LIVE, SCHEDULED
user_id
opzionale		Limita la risposta agli A/B Test creati dall’ID utente specificato.

Nota: non può essere specificato insieme a username.

Tipo: long

Esempio: 756201191646691328
username
opzionale		Limita la risposta agli A/B Test creati dallo username specificato. Non includere il simbolo iniziale ”@”.

Nota: non può essere specificato insieme a user_id.

Tipo: string

Esempio: apimctestface
with_deleted
opzionale		Includi i risultati eliminati nella richiesta.

Tipo: boolean

Predefinito: false
Valori possibili: true, false
Esempio di richiesta
GET https://ads-api.x.com/12/accounts/18ce54d4x5t/ab_tests
Esempio di risposta
    {
      "request": {
        "params": {
          "account_id": "18ce54d4x5t"
        }
      },
      "data": [
        {
          "created_at": "2022-05-25T00:00:00Z",
          "created_by": {
            "user_id": "756201191646691328",
            "username": "apimctestface"
          },
          "deleted": false,
          "description": "esempio per la documentazione",
          "end_time": "2022-05-30T01:00:00Z",
          "entities": [
            {
              "id": "p1bcx",
              "account_id": "18ce54d4x5t"
            },
            {
              "id": "p1bcy",
              "account_id": "18ce54d4x5t"
            }
          ],
          "entity_type": "CAMPAIGN",
          "id": "hr7l0",
          "name": "primo test A/B",
          "start_time": "2022-05-25T01:00:00Z",
          "status": "SCHEDULED",
          "user_groups": [
            {
              "id": "p1bcx",
              "name": "primo gruppo",
              "description": null,
              "size": "50.0",
              "entity_ids": [
                "f2qcw",
                "f2tht"
              ]
            },
            {
              "id": "p1bcy",
              "name": "secondo gruppo",
              "description": "secondo gruppo del test A/B"
              "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

Crea un nuovo test A/B. Tutti i parametri devono essere inviati nel corpo della richiesta ed è necessario impostare Content-Type su application/json.
URL risorsa
https://ads-api.x.com/12/accounts/:account_id/ab_tests
Parametri
NomeDescrizione
account_id
obbligatorio		L’identificatore dell’account utilizzato. Compare nel percorso della risorsa ed è generalmente un parametro obbligatorio per tutte le richieste dell’API per inserzionisti, ad eccezione di GET accounts. L’account specificato deve essere associato all’utente autenticato.

Type: string

Example: 18ce54d4x5t
end_time
obbligatorio		L’ora, in formato ISO 8601, in cui terminerà l’A/B test.

Type: string

Example: 2020-10-02T00:00:00Z
entity_type
obbligatorio		Il tipo di entità da utilizzare per la suddivisione dei gruppi di utenti.

Type: enum

Possible values: CAMPAIGN, LINE_ITEM
start_time
obbligatorio		L’ora, in formato ISO 8601, in cui inizierà l’A/B test.

Type: string

Example: 2022-05-30T00:00:00Z
user_groups
obbligatorio		Descrive i gruppi di utenti. Maggiori informazioni nella tabella seguente. È possibile specificare da 2 a 30 gruppi di utenti.

Type: array of objects
description
facoltativo		La descrizione dell’A/B test. Lunghezza massima: 1.024 caratteri.

Type: string

Example: documentation example
name
facoltativo		Il nome dell’A/B test. Lunghezza massima: 255 caratteri.

Type: string

Example: first AB test

​
Gruppi di utenti

NomeDescrizione
entity_ids
obbligatorio		Un array di ID entità.

Nota: Le entità possono essere associate a un solo test A/B.

Type: array

Example: ["dxi0l", "e66bl"]
size
obbligatorio		La percentuale di utenti da assegnare a questo gruppo di utenti. È un valore numerico rappresentato come stringa, con al massimo due cifre decimali. Ad esempio, rappresenta il 40% come: 40, 40.0 o 40.00.

Nota: I valori di size tra gli oggetti devono sommare a 100.00.

Type: array

Min, Max: 1.00, 99.00
description
opzionale		La descrizione del gruppo di utenti. Lunghezza massima: 1.024 caratteri.

Type: string

Example: second AB test group
name
opzionale		Il nome del gruppo di utenti. Lunghezza massima: 255 caratteri.

Type: string

Example: first group

​
Esempio di richiesta

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": "primo gruppo"},{"entity_ids": ["f2rqi", "f2tws"], "size": "50.00", "name": "secondo gruppo", "description": "secondo gruppo di test A/B"}], "name": "primo test A/B", "description": "esempio di documentazione"}'

​
Esempio di risposta

    {
      "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": "primo gruppo"
            },
            {
              "entity_ids": [
                "f2rqi",
                "f2tws"
              ],
              "size": "50.0",
              "name": "second group",
              "description": "secondo gruppo del test AB"
            }
          ],
          "name": "primo test AB",
          "description": "esempio della documentazione"
        }
      },
      "data": {
        "created_at": "2022-05-25T00:00:00Z",
        "created_by": {
          "user_id": "756201191646691328",
          "username": "apimctestface"
        },
        "deleted": false,
        "description": "esempio della documentazione",
        "end_time": "2022-05-30T01:00:00Z",
        "entities": [
          {
            "id": "p1bcx",
            "account_id": "18ce54d4x5t"
          },
          {
            "id": "p1bcy",
            "account_id": "18ce54d4x5t"
          }
        ],
        "entity_type": "CAMPAIGN",
        "id": "hr7l0",
        "name": "primo test AB",
        "start_time": "2022-05-25T01:00:00Z",
        "status": "SCHEDULED",
        "user_groups": [
          {
            "id": "p1bcx",
            "name": "primo gruppo",
            "description": null,
            "size": "50.0",
            "entity_ids": [
              "f2qcw",
              "f2tht"
            ]
          },
          {
            "id": "p1bcy",
            "name": "secondo gruppo",
            "description": "secondo gruppo del test AB",
            "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

Aggiorna l’A/B Test specificato. Tutti i parametri vengono inviati nel corpo della richiesta ed è richiesto un Content-Type di application/json. Questo endpoint supporta JSON parziale con ID di oggetto. Si applicano i seguenti principi:
  • Per aggiungere o rimuovere oggetti o elementi, invia l’intero array (e le sue sottostrutture); si tratta di un’operazione di sostituzione
    • Pensalo come una ricostruzione dell’array
  • In caso contrario, modifica (cambia, aggiungi, rimuovi) i campi esistenti facendo riferimento ai nomi delle chiavi o agli ID
    • Per rimuovere un campo, imposta il relativo valore su null
    • I campi non inclusi non vengono modificati
In generale, gli A/B Test possono essere aggiornati solo quando lo status è SCHEDULED. C’è un’eccezione: è possibile aggiornare l’end_time dell’A/B Test quando è LIVE.
URL della risorsa
https://ads-api.x.com/12/accounts/18ce54d4x5t/:ab_test_id
Parametri
NomeDescrizione
account_id
obbligatorio		L’identificatore dell’account utilizzato. Compare nel percorso della risorsa ed è generalmente un parametro obbligatorio per tutte le richieste dell’Advertiser API, ad eccezione di GET accounts. L’account specificato deve essere associato all’utente autenticato.

Type: string

Example: 18ce54d4x5t
ab_test_id
obbligatorio		Un riferimento all’A/B Test utilizzato nella richiesta.

Type: string

Example: hr7l0
description
opzionale		La descrizione dell’A/B Test. Lunghezza massima: 1.024 caratteri.

Nota: Può essere aggiornata solo quando lo status dell’A/B Test è SCHEDULED.

Type: string

Example: documentation example
end_time
opzionale		L’orario, in formato ISO 8601, in cui l’A/B Test terminerà.

Nota: Può essere aggiornato solo quando lo status dell’A/B Test è SCHEDULED o LIVE.

Type: string

Example: 2020-10-02T00:00:00Z
name
opzionale		Il nome dell’A/B Test. Lunghezza massima: 255 caratteri.

Nota: Può essere aggiornato solo quando lo status dell’A/B Test è SCHEDULED.

Type: string

Example: first AB test
start_time
opzionale		L’orario, in formato ISO 8601, di inizio dell’A/B Test.

Nota: Può essere aggiornato solo quando lo status dell’A/B Test è SCHEDULED.

Type: string

Example: 2022-05-30T00:00:00Z
user_groups
obbligatorio		Descrive i gruppi di utenti. Ulteriori informazioni nella tabella seguente.

Nota: Può essere aggiornato solo quando lo status dell’A/B Test è SCHEDULED.

Type: array of objects

​
Gruppi di utenti

NomeDescrizione
id
a volte richiesto		Un riferimento all’oggetto gruppo di utenti utilizzato nella richiesta.

Nota: Obbligatorio quando si modificano (si cambiano, si aggiungono o si rimuovono) i fields dell’oggetto gruppo di utenti.

Nota: Non specificare un ID quando si aggiungono o si rimuovono interi oggetti gruppo di utenti.

Type: string

Example: p1bcx
description
opzionale		La descrizione del gruppo di utenti. Lunghezza massima: 1.024 caratteri.

Nota: Per annullare l’impostazione (rimuovere), specificare il campo con valore null.

Type: string

Example: second AB test group
entity_ids
opzionale		Un array di ID di entità.

Nota: Si tratta di un’operazione di sostituzione. Sovrascrive qualsiasi valore impostato in precedenza.

Nota: Le entità possono essere associate a un solo test A/B.

Type: array

Example: ["dxi0l", "e66bl"]
name
opzionale		Il nome del gruppo di utenti. Lunghezza massima: 255 caratteri.

Nota: Per annullare l’impostazione (rimuovere), specificare il campo con valore null.

Type: string

Example: first group
size
opzionale		La percentuale di utenti da assegnare a questo gruppo di utenti. È un valore numerico rappresentato come stringa con al massimo due cifre decimali. Ad esempio, rappresentare il 40% come: 40, 40.0 o 40.00.

Nota: I valori di size tra gli objects devono sommare a 100.00.

Type: string

Min, Max: 1.00, 99.00
Esempio di richiesta
Questa richiesta applica le seguenti modifiche.
  1. Rimuove la descrizione dell’A/B test
  2. Modifica l’end_time
  3. Aggiunge una descrizione al primo gruppo di utenti
  4. Modifica la percentuale di utenti in ciascun gruppo di utenti
  5. Aggiunge un entity ID (f2syz) al secondo gruppo di utenti
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"]}]}'
Esempio di risposta
    {
      "request": {
        "params": {
          "account_id": "18ce54d4x5t",
          "ab_test_id": "hr7l0",
          "description": null,
          "end_time": "2022-06-01T01:00:00Z",
          "user_groups": [
            {
              "id": "p1bcx",
              "description": "primo gruppo del 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": "primo test A/B",
        "start_time": "2022-05-25T01:00:00Z",
        "status": "SCHEDULED",
        "user_groups": [
          {
            "id": "p1bcx",
            "name": "primo gruppo",
            "description": "primo gruppo del test A/B",
            "size": "60.0",
            "entity_ids": [
              "f2qcw",
              "f2tht"
            ]
          },
          {
            "id": "p1bcy",
            "name": "secondo gruppo",
            "description": "secondo gruppo del 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

Elimina l’A/B test specificato. Nota: L’eliminazione di un A/B test è irreversibile e gli eventuali tentativi successivi di eliminare la risorsa restituiranno HTTP 404.
URL risorsa
https://ads-api.x.com/12/accounts/:account_id/ab_tests/:ab_test_id
Parametri
NomeDescrizione
ab_test_id
obbligatorio		Riferimento all’A/B test con cui si opera nella richiesta.

Type: string

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

​
Esempio di risposta

    {
      "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": "primo test A/B",
        "start_time": "2022-05-25T01:00:00Z",
        "status": "SCHEDULED",
        "user_groups": [
          {
            "id": "p1bcx",
            "name": "primo gruppo",
            "description": "primo gruppo del test A/B",
            "size": "60.0",
            "entity_ids": [
              "f2qcw",
              "f2tht"
            ]
          },
          {
            "id": "p1bcy",
            "name": "secondo gruppo",
            "description": "secondo gruppo del 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"
        }
      }
    }
⌘I