Vai al contenuto principale

​
Configurazione della Conversion API

​
Prerequisiti 

​
Accesso alla X Ads API - Nuove applicazioni

Step 1: Developer Account
  • Quando si richiede un Developer Account, sottoscrivere uno dei nostri piani di abbonamento per l’approvazione immediata.
  • Nota: Come best practice, consigliamo vivamente di utilizzare l’handle X ufficiale della vostra azienda per creare un account sviluppatore e richiedere l’accesso alla Ads API. Se l’account sviluppatore è associato a un handle personale/sviluppatore, non sarà possibile trasferire tali credenziali, se necessario. È preferibile mantenerlo sotto un account aziendale per una gestione continuativa e utilizzare, se necessario, il Multi-user login. In caso contrario, come minimo, l’account dovrebbe essere configurato con impostazioni non predefinite (immagine dell’header, avatar, descrizione della bio e URL della bio) e utilizzare l’autenticazione a due fattori.
Step 2: Ads API Application
  • Assicurarsi di avere a disposizione il corretto App ID per la vostra Ads API Application. L’App ID è reperibile nel Developer Portal in Projects & Apps. Esempio: 16489123
  • Richiedere l’accesso alla X Ads API contattando il vostro referente X.

​
Accesso a X Ads API - Applicazioni esistenti

  • Se disponi già di un’App X Ads API attivamente utilizzata, sia l’App sia gli access token esistenti possono essere utilizzati per la Conversion API.

​
Access Tokens

  • Gli User Access Tokens per l’handle dell’utente proprietario dell’applicazione X Ads API possono essere generati e recuperati direttamente dal developer portal. Questo è chiamato “personal access token” perché è destinato all’utilizzo con il tuo handle su X. Informazioni generali su autenticazione e developer portal sono disponibili qui.
  • Gli User Access Tokens per handle utente diversi dall’handle proprietario dell’applicazione X Ads API devono essere generati con un flusso OAuth a 3 vie. Le opzioni per generare l’Access Token con OAuth a 3 vie includono:
  • Qualsiasi token utente utilizzato con la Conversion API deve appartenere a utenti con livello di accesso AD_MANAGER o ACCOUNT_ADMIN, verificabile tramite l’endpoint authenticated_user_access.
  • Nota: i token stessi (dopo la creazione come sopra) possono essere condivisi con utenti privi del livello di accesso AD_MANAGER o ACCOUNT_ADMIN per l’utilizzo.

​
Procedure

​
Creazione dell’evento della Conversion API

Per utilizzare la Conversion API, devi creare un nuovo evento di conversione in Ads Manager oppure usare un evento esistente già creato e utilizzato con X Pixel. Se vuoi deduplicare gli eventi tra Pixel e Conversion API, devi usare l’evento esistente creato per Pixel. 
Opzione 1: Utilizzare un evento di conversione esistente in Ads Manager
Se vuoi utilizzare un evento già configurato con il pixel di X, puoi farlo: ti servirà l’Event ID di quell’evento. Se utilizzi sia il pixel sia la Conversion API per lo stesso evento, assicurati di usare la chiave di deduplicazione sia nello snippet di codice del Pixel sia nella richiesta della Conversion API (come conversion_id) per deduplicare gli eventi tra Pixel e Conversion API per lo stesso evento. Vedi la sezione d. Testing Events and Deduplication per maggiori informazioni. 
Opzione 2: Creazione di un nuovo evento di conversione in Ads Manager:
È importante avere una Sorgente evento creata in Events Manager prima di creare un evento. Per verificare se nel tuo account è stata aggiunta una Sorgente evento (X Pixel), vai su Events Manager e controlla se nel menu a sinistra è presente X Pixel. Se non hai ancora aggiunto una Sorgente evento, segui i passaggi riportati di seguito per crearne una.
  1. Vai su ads.x.com
  2. Vai alla sezione Tools in alto a sinistra e fai clic su Events Manager
  3. Seleziona Add event source in alto a destra per Add an event source se nella barra laterale sinistra non è ancora presente una sorgente evento X Pixel
    1. L’id della sorgente evento X Pixel è il tuo Pixel ID
Ora hai una Sorgente evento e un Pixel ID. Devi creare un evento all’interno della sorgente evento per gli eventi di conversione che desideri tracciare:
  1. All’interno della sorgente evento X Pixel, seleziona Add events sul lato destro
  2. Seleziona Install with Conversion API
  3. Vedrai il Pixel ID e l’Event ID di questo evento che verranno utilizzati nell’API
    1. L’id dell’evento è il tuo Event ID
  4. Fai clic su Save e il tuo evento di conversione verrà creato ed è pronto per l’uso

​
Preparazione degli identificatori per gli eventi di conversione 

Al momento è necessario trasmettere almeno un identificatore, ad esempio il Click ID (twclid), l’indirizzo email o il numero di telefono. Se si utilizza l’indirizzo IP o lo user agent, è necessario inviare un secondo identificatore per un corretto abbinamento della conversione. Fornire più identificatori migliorerà il tasso di abbinamento delle conversioni.
Campo per l’abbinamento del clienteFormatoÈ necessario l’hashing?
X Click IDGenerato da X (scopri di più)No
Indirizzo emailRimuovere spazi iniziali e finaliRichiesto (SHA256)
Numero di telefonoStandard E.164Richiesto (SHA256)
Indirizzo IPRimuovere spazi iniziali e finaliNo
User agentRimuovere spazi iniziali e finaliNo

​
1. Preparare l’identificatore X Click ID 

Si consiglia di includere sempre il Click ID nella richiesta di conversione. Il Click ID deve essere recuperato dal parametro della query string query twclid, quando disponibile dopo che l’utente è arrivato sul sito di destinazione.  Esempio di codice JavaScript di base: 
var queryString = document.location.search;
if (queryString.has('twclid') {
  twitterClickID = getParam(queryString, 'twclid');
  // Passaggi consigliati successivi: logging, salvataggio nello storage locale
}
Si consiglia di:
  1. Eseguire sempre il parsing del valore twclid quando è presente nei parametri query dell’URL.
  2. Archiviare i data insieme ai campi del modulo pertinenti o alle informazioni sull’evento di conversione.
Associare il Click ID agli eventi di conversione e alle informazioni sul flusso di lavoro abilita scenari come l’elaborazione in batch, l’uso di algoritmi per analizzare e creare eventi di conversione basati su più percorsi di navigazione del sito e i caricamenti in blocco. L’URL dell’origine evento deve essere URL encoded e rappresenta la pagina web che ha attivato l’evento.

​
2. Preparare l’identificatore email 

È possibile inviare i campi supportati per il customer matching, ma devono essere normalizzati e, quando richiesto, sottoposti a hashing per proteggere la privacy. Le informazioni devono essere sottoposte a hashing utilizzando SHA256, senza salt.  Ad esempio, per l’indirizzo email test@x.com, dovrebbe essere inviato in formato hash: d360d510a224510f373931ce2d6215a799f5a9c1cef221b0149b6b6b50cced62.

​
3. Preparare l’identificatore del telefono 

Il numero di telefono deve essere fornito secondo lo standard E.164 e i dati devono essere sottoposti a hash con SHA‑256, senza salt.  Ad esempio, per un numero di telefono statunitense: +11234567890, deve esserci inviato in formato hash: 1fa6b8d986d9b9cd01bf36951815158bbde9f520c0567c835dfe34783d0a4231.

​
4. Preparare l’identificatore dell’indirizzo IP

L’indirizzo IP deve essere trasmesso insieme a un altro identificatore (twclid, indirizzo email, numero di telefono o user agent). Per questo identificatore non è richiesto alcun hash. Questo valore è scritto in notazione decimale puntata, con quattro numeri separati da punti. Ad esempio, l’indirizzo IP di un utente può essere 8.25.197.25.

​
5. Preparare l’identificatore dello User Agent

Lo User Agent deve essere inviato insieme a un altro identificatore (twclid, indirizzo email, numero di telefono o indirizzo IP). Per questo identificatore non è richiesto alcun hashing. Questo identificatore consente al server di riconoscere l’applicazione, il sistema operativo, il vendor e/o la versione dello user agent che effettua la richiesta. Ad esempio, questo valore può essere inviato come Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/127.0.0.0 Safari/537.36.

​
Creazione della richiesta dell’evento di conversione

POST: version/measurement/conversions/:pixel_id Invia eventi di conversione per uno specifico account pubblicitario. Verifica il codice di risposta per confermare l’esito positivo (HTTP 200 OK). Si consiglia di implementare un meccanismo di retry e un logging di base nel caso vengano restituiti codici di errore. Per informazioni dettagliate sull’URL dell’endpoint e sui parametri del body della richiesta POST, consulta la sezione API Reference. 

​
Esempio di richiesta (formattato per leggibilità)


    twurl -H 'ads-api.x.com' -X POST '/12/measurement/conversions/oka17' --data '
    {
      "conversions":[
         {
            "conversion_time":"2022-02-18T01:14:00.603Z",
            "event_id":"ol288",
            "identifiers":[
               {
                  "twclid":"23opevjt88psuo13lu8d020qkn"
               },
               {
                  "hashed_email":"d360d510a224510f373931ce2d6215a799f5a9c1cef221b0149b6b6b50cced62"
               },
               {
                  "hashed_phone_number":"1fa6b8d986d9b9cd01bf36951815158bbde9f520c0567c835dfe34783d0a4231"
               },
               {
                  "ip_address":"1.0.0.0",
                  "user_agent":"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/127.0.0.0 Safari/537.36"
               }
            ],
            "value":"20.00",
            "number_items":3,
            "conversion_id":"23294827",
            "description":"Acquisti di prodotti per animali domestici",
            "contents":[
               {
                  "content_id":"1",
                  "content_name":"Coperte",
                  "content_type":"Prodotti per animali domestici",
                  "content_price":100.99,
                  "num_items":1,
                  "content_group_id":"123"
               }
            ]
         }
      ]
    }' --header 'Content-Type: application/json'

​
Esempio di risposta

{"request": {
 "params": {
     "account_id":"18ce552mlaq"}
 },
 "data": {
    "conversions_processed":1,
     "debug_id":"ff02e052-36e4-47d6-bdf0-6d8986446562"}
}

​
Limite di velocità

Il limite di velocità è di 60.000 eventi per account per intervallo di 15 minuti. Nota che il codice del server potrebbe dover implementare logica al di fuori di questa chiamata, tra cui:
  1. Strumentare le azioni degli utenti (logging) per poter inviare i dati di conversione corretti per evento
  2. Qualsiasi logica necessaria per filtrare gli eventi di conversione degli utenti che hanno esercitato scelte di privacy pertinenti — ad esempio, se hanno disattivato il tracciamento o la vendita delle proprie informazioni personali sul sito web dell’inserzionista
  3. Integrazione con i trigger e le pagine degli eventi per acquisire gli eventi e inviare le conversioni

​
Test degli eventi e deduplicazione

​
Test degli eventi

Quando il tuo evento avrà ricevuto correttamente le conversioni, entro 12-24 ore lo stato di “Single event web tag” dovrebbe indicare TRACKING nella pagina Conversion Tracking di Ads Manager. L’invio di conversioni tramite la Conversion API non influirà sulle campagne in corso. Puoi anche verificare i risultati di analisi del tuo evento di conversione per ID tag tramite:

​
Duplicazione tra Pixel e Conversion API

Se desideri deduplicare le conversioni tra le richieste Pixel e Conversion API, utilizziamo conversion_id come chiave di deduplicazione. La deduplicazione avviene solo a livello di evento. In altre parole, per deduplicare tra richieste Pixel e CAPI, un inserzionista deve utilizzare lo stesso evento sia nelle richieste Pixel sia in quelle CAPI, oltre a usare lo stesso conversion_id. La deduplicazione può avvenire solo per eventi ricevuti entro una finestra temporale di 48 ore.

​
Monitoraggio delle conversioni (Panoramica)

Il tracciamento delle conversioni consente di misurare il numero di utenti di X che eseguono un’azione desiderata dopo aver visualizzato e interagito con i tuoi annunci su X. Ti permette di capire quali campagne generano azioni come visite al sito, iscrizioni e acquisti. Fornisce agli inserzionisti funzionalità di misurazione off-X per valutare le prestazioni delle campagne di direct response, in modo da acquisire clienti in modo efficiente in termini di costi. Utilizzando un tag di conversione, gli inserzionisti possono tracciare le conversioni degli utenti e ricondurle alle campagne pubblicitarie su X. Questo offre la visibilità necessaria per ottimizzare le campagne e raggiungere gli obiettivi di costo per acquisizione (CPA). Sono disponibili diverse azioni sul sito web che un inserzionista può misurare con il tracciamento delle conversioni. È possibile selezionarne una o più, in base alle azioni che si intende generare con la campagna:
  • Visita al sito: l’utente visita una landing page del sito dell’inserzionista
  • Acquisto: l’utente completa l’acquisto di un prodotto o servizio sul sito dell’inserzionista
  • Download: l’utente scarica un file, come un white paper o un pacchetto software, dal sito dell’inserzionista
  • Iscrizione: l’utente si iscrive al servizio, alla newsletter o alle comunicazioni e-mail dell’inserzionista
  • Personalizzato: categoria generica per un’azione personalizzata che non rientra in una delle categorie sopra
Il tracciamento delle conversioni di X offre agli inserzionisti una visione completa dell’attribuzione delle conversioni. Rispetto ai sistemi di misurazione di terze parti che i clienti potrebbero aver utilizzato al posto della funzionalità di tracciamento delle conversioni di X, come URL di clic univoci abbinati a tag di tracciamento di terze parti, il tag di conversione di X consente agli inserzionisti di tracciare le conversioni attribuite a interazioni di medio e alto funnel, come espansioni dei Tweet, Retweet, preferiti, risposte e follow, nonché alle impression.

​
FAQ

Innanzitutto, un inserzionista crea un tag di conversione, ovvero uno snippet di codice fornito da X, e lo inserisce nel proprio sito web. Il tag è quindi pronto a misurare la conversione quando un utente completa l’azione prevista.Gli utenti vengono esposti all’annuncio dell’inserzionista sul client X, che li porta al sito web dell’inserzionista e all’azione che è stata taggata. Se l’utente completa tale azione entro la/le finestra/e di attribuzione specificata/e durante la configurazione del tag, il tag riconosce che l’utente ha precedentemente interagito con un annuncio su X. Il tag quindi “si attiva”, ovvero invia una notifica ai server di X affinché la conversione possa essere attribuita all’annuncio che l’ha generata.
No, il nostro prodotto non consente di associare tag di conversione specifici a campagne specifiche. Una volta configurato un tag, il sistema tiene automaticamente traccia di quale annuncio ha generato conversioni su quel determinato tag.
Finestra di attribuzione post-view predefinita: 1 giornoAttribuzione post-engagement predefinita: 14 giorniQuesti valori predefiniti possono essere modificati durante la configurazione del tag di conversione o in qualsiasi momento dopo la creazione del tag. Le opzioni per le finestre di attribuzione post-engagement sono 1, 7, 14, 30, 60 e 90 giorni. Le opzioni per le finestre di attribuzione post-view sono nessuna, 1, 7, 14, 30, 60 e 90 giorni.
Sebbene obiettivi, contesto e strategie varino da cliente a cliente, ecco alcune idee che hanno funzionato per chi ha partecipato alle fasi alpha o beta del monitoraggio delle conversioni:Creatività:
  • Offerte: Abbina uno sconto, una promozione o la spedizione gratuita al Tweet Promosso per suscitare maggiore interesse verso l’azione
  • Concorsi e giveaway: In particolare per brand molto noti, concorsi e giveaway hanno generato conversioni
  • Sperimentazione del copy del Tweet: Testare maiuscole vs minuscole (FREE vs free o NOW vs now)
  • Scadenze: Indica una scadenza per incoraggiare le persone a compiere subito l’azione (Offerta valida fino al 12 dicembre!)
  • Foto accattivanti: Vale la pena testare se immagini visivamente accattivanti nella creatività del Tweet favoriscano le conversioni; i risultati possono variare o dipendere dall’offerta del cliente.
Targeting:
  • Targeting per @handle e per categoria di interesse: Un forte allineamento tra copy del Tweet e @handle e il pubblico previsto del Tweet ha generato conversioni
  • Uso di parole chiave di nicchia ma ad alto volume: Nel settore dei concerti, l’utilizzo di parole chiave legate all’artista/musicista (ad es. il nome) si è rivelato efficace
  • Pubblici personalizzati: I clienti che hanno utilizzato TA web e monitoraggio delle conversioni insieme hanno registrato CPA più bassi rispetto ai gruppi di controllo con altri tipi di targeting
Quanto più granulare è la segmentazione della campagna, tanto più azionabili saranno i risultati di conversione riportati. Ad esempio, è molto più semplice ottimizzare una campagna con 4 parole chiave che ottimizzarne una con 50.

​
Risoluzione dei problemi e supporto per la Conversion API

Per domande sui codici di errore dopo una chiamata all’API, consulta la sezione seguente. Per tutte le altre domande, non esitare a contattare il tuo referente di Twitter e lavoreremo per risolverle il prima possibile. 

​
Gestione ed esplicazione degli errori

Una richiesta ha esito positivo solo se non si verifica alcun errore per tutte le conversioni in essa incluse. In presenza di un errore in una singola conversione, l’endpoint restituirà un elenco di tutti gli errori pertinenti.

​
Panoramica dei codici di errore della X Ads API

Ecco un elenco completo dei codici di errore della Ads API: https://developer.x.com/en/docs/twitter-ads-api/response-codes Le risposte riuscite della Conversion API sono contrassegnate da un codice HTTP della serie 200 e da un payload in JSON contenente l’oggetto richiesto.

​
Quando viene restituito un codice HTTP della serie 500, il problema riguarda il server, non la tua richiesta o la configurazione dell’account. Controlla la X API status page o il developer community forum per verificare se altri riscontrano problemi simili.

​
Quando viene restituito un codice HTTP della serie 400, i casi comuni sono

  • 400 Bad Request (la richiesta non rispetta gli standard)
  • 401 Unauthorized (problemi di autenticazione)
  • 403 Forbidden (problemi di accesso all’API associati a quell’account sviluppatore)
  • 404 Not Found (l’URL o i parametri potrebbero non essere corretti per l’endpoint)

​
Codici di errore della Conversion API

​
Scenari di errore 400 Bad Request

MotivoTipoMessaggio di errore
Identificatore mancante (attualmente email con hash o X click ID - twclid)400 Bad RequestDeve essere fornito almeno un identificatore utente
Email con hash non valida400 Bad RequestHashed_email non è un hash SHA-256 valido
Il tipo di event_id non è un Single Event Tag (SET)400 Bad RequestEvent_id (<event_id>) non è un Single Event Tag (SET)
Gli eventi di conversione richiesti superano il limite (attualmente 500 eventi per richiesta)400 Bad RequestIl limite del numero di conversioni è 500
Event ID mancante400 Bad RequestEvent ID non è stato trovato

​
Esempio di codice di errore JSON

Richiesta:
POST '/11/measurement/conversions/o6dkt' --data '{"conversions":[{"conversion_time": "2022-06-16T01:14:00.603Z", "event_id":"o6dkt", "identifiers": [{"twclid": "23opevjt88psuo13lu8d020qkn"}]}]}' --header 'Content-Type: application/json

​
Messaggio di errore:

{"errors":[{"code":"INVALID_PARAMETER","message":"event_id (o6dkt) non è un tag evento singolo (SET)","parameter":"event_id"}],"request":{"params":{"account_id":"18ce552mlaq"}}}

​
Richiesta:

twurl_ads -X POST '/11/measurement/conversions/o6dkt' --data '{"conversions":[{"conversion_time": "2022-06-16T01:14:00.603Z", "event_id":"o6dl3", "identifiers": [{"twclid": ""}]}]}' --header 'Content-Type: application/json'

​
Messaggio di errore:

{"errors":[{"code":"INVALID_PARAMETER","message":"Devi fornire almeno un identificatore utente","parameter":""}],"request":{"params":{"account_id":"18ce552mlaq"}}}

​
Richiesta:

twurl_ads -X POST '/11/measurement/conversions/o6dkt' --data '{"conversions":[{"conversion_time": "2022-06-16T01:14:00.603Z", "event_id":"o6dl3", "identifiers": [{"hashed_email": "abc"}]}]}' --header 'Content-Type: application/json'

​
Messaggio di errore:

{"errors":[{"code":"INVALID_PARAMETER","message":"hashed_email (abc) is not a valid SHA-256 hash","parameter":"hashed_email"}],"request":{"params":{"account_id":"18ce552mlaq"}}}

​
Richiesta:

twurl_ads -X POST '/11/measurement/conversions/o6dkt' --data '{"conversions":[{"conversion_time": "2022-06-16T01:14:00.603", "event_id":"o6dl3", "identifiers": [{"twclid": "23opevjt88psuo13lu8d020qkn"}]}]}' --header 'Content-Type: application/json'

​
Messaggio di errore:

{"errors":[{"code":"INVALID_PARAMETER","message":"Expected Time in yyyy-MM-ddTHH:mm:ss.SSSZ, got \"2022-06-16T01:14:00.603\" for conversion_time","parameter":"conversion_time"}],"request":{"params":{"account_id":"18ce552mlaq"}}}

​
401 Non autorizzato

Motivo: Credenziali di autenticazione mancanti o non corrette Soluzione: Segui i passaggi di autenticazione nella documentazione di configurazione utilizzando uno dei 3 metodi di autenticazione: Gli Access Tokens utente per handle diversi da quello del proprietario dell’App della X Ads API devono essere generati con un flusso OAuth a 3 vie. Le opzioni per generare l’Access Token con OAuth a 3 vie includono Qualsiasi token utente utilizzato con la Conversion API deve appartenere a utenti con livello di accesso AD_MANAGER o ACCOUNT_ADMIN*, verificabile tramite l’endpoint authenticated_user_access.

​
403 Accesso vietato

MotivoTipoMessaggio di errore
L’account sviluppatore che stai utilizzando non dispone dell’accesso a X Ads API. Richiedi l’accesso qui.403 Unauthorized ClientL’applicazione client con id <> che sta effettuando questa richiesta non dispone dell’accesso a X Ads API. Assicurati che la tua applicazione abbia l’accesso advertiser-api. Usa ‘twurl accounts’ e ‘twurl set default <username> <key>’ per cambiare l’applicazione in uso.

​
404 Non trovato 

MotivoTipoMessaggio di errore
L’URL della richiesta o i parametri non sono corretti per l’endpoint404 Route Not FoundLa risorsa richiesta non è stata trovata
Non disponi dell’accesso all’account proprietario di pixel_id/Universal website tag404 Not FoundL’utente <user_id> non ha accesso all’account <account_id>. Digita ‘sn <user_id>’ per ottenere l’handle dell’utente. Usa ‘twurl accounts’ e ‘twurl set default \u003Cusername\u003E’ per cambiare l’utente in uso.
L’event_id non appartiene all’account fornito associato al pixel ID (UWT ID)404 Not Foundevent_id <event_id> non appartiene all’account fornito

​
Esempio di codice di errore JSON

​
Richiesta:

twurl_ads -X POST '/11/measurement/conversions/o8z6j' --data '{"conversions":[{"conversion_time": "2022-06-16T01:14:00.603Z", "event_id":"abc", "identifiers": [{"twclid": "23opevjt88psuo13lu8d020qkn"}]}]}' --header 'Content-Type: application/json' Messaggio di errore: {"errors":[{"code":"NOT_FOUND","message":"event_id (abc) does not belong to provided account","parameter":"event_id"},{"code":"INVALID_PARAMETER","message":"event_id (abc) is not a single event tag (SET)","parameter":"event_id"}],"request":{"params":{"account_id":"18ce55gze09"}}}

​
Indice di riferimento dell’API

Per la reference completa dell’API, seleziona un endpoint dall’elenco:

​
Conversioni web

API delle conversionimeasurement/conversions/:pixel_id
Tag degli eventi webaccounts/:account_id/web_event_tags

​
Conversioni web

POST version/measurement/conversions/:pixel_id Invia eventi di conversione del sito per un singolo Event Tag ID. Verificare il codice di risposta per confermare l’esito positivo (HTTP 200 OK). Si consiglia di implementare un meccanismo di retry e un logging di base nel caso vengano restituiti codici di errore. Il limite di velocità è di 100.000 richieste per intervalli di 15 minuti per account (ogni richiesta consente 500 eventi).
URL risorsa
https://ads-api.x.com/12/measurement/conversions/:pixel_id
Parametri URL della richiesta
NameDescription
pixel_id
obbligatorio		L’ID Base Tag per un account pubblicitario. Rappresenta il valore codificato in base36 per l’ID Base Tag di un account pubblicitario.

Type: string

Example: o8z6j
conversions
obbligatorio		L’oggetto nel corpo della richiesta POST dell’API. Elenco di eventi di conversione. È possibile fornire fino a 500 eventi di conversione. Vedi la tabella sotto per i fields supportati.

Type: array

Example: "conversions":[{"conversion_time": "2022-02-18T01:14:00.603Z", "event_id":"o87ne", "identifiers": [{"twclid": "23opevjt88psuo13lu8d020qkn"}], "conversion_id": "23294827"}]
oggetto conversions
NameDescription
conversion_time
required		L’ora, espressa in ISO 8601.

Type: string

Example: 2017-10-05T00:00:00Z
event_id
required		L’ID in base 36 di un evento specifico. Corrisponde a un evento preconfigurato presente in questo account pubblicitario. Questo è chiamato ID nell’evento corrispondente in Events Manager.

Type: string

Example: o87ne oppure tw-o8z6j-o87ne (tw-pixel_id-event-id), entrambi accettati
identifiers
required		Un elenco di oggetti identificatori a cui associare l’evento di conversione. I campi supportati sono elencati in una tabella più sotto. È richiesto almeno uno degli oggetti identificatori.

Se si utilizza l’indirizzo IP o lo user agent, è necessario inviare un secondo identificatore per un corretto abbinamento della conversione.

Type: array

Example: "identifiers": [{"twclid": "23opevjt88psuo13lu8d020qkn"},{"hashed_email": "e586883b2b4faf78d48300a79e0e15138d664cdf796ffb86e533170a9893eda8"}]
number_items
optional		Il numero di articoli acquistati nell’evento. Deve essere un numero positivo maggiore di zero.

Type: integer

Example: 4
price_currency
optional		La valuta degli articoli acquistati nell’evento, espressa secondo ISO-4217. Vedere Currency per informazioni dettagliate.

Type: string

Default: USD

Example: JPY
value
optional		Il valore di prezzo degli articoli acquistati nell’evento, espresso nella valuta price_currency.

Type: double

Example: 100.00
conversion_id
optional		Per la deduplicazione tra conversioni del pixel e della Conversion API. Un identificatore per un evento di conversione che può essere utilizzato per la deduplicazione tra Web Pixel e Conversion API nelle conversioni dello stesso tag evento. Consultare la sezione Testing Events and Deduplication della Conversions Guide per maggiori informazioni.

Type: string

Example: 23294827
description
optional		Descrizione con eventuali informazioni aggiuntive sulle conversioni.

Type: string

Example: test conversion
contents
optional		Elenco di dettagli relativi a uno specifico prodotto/contenuto per fornire informazioni granulari. Vedere la tabella sottostante per i campi supportati.

Type: array

Example: contents": [{"content_id": "1", "content_name": "Blankets", "content_type": "home improvement", "content_price": 100.99, "num_items": 1, "content_group_id": "123"}, {"content_id": "2"}]
oggetto identifiers
NameDescription
twclid
a volte obbligatorio		Click ID estratto dall’URL di click-through. È obbligatorio se non viene aggiunto alcun altro identificatore.

Type: string

Example: 26l6412g5p4iyj65a2oic2ayg2
hashed_email
a volte obbligatorio		Un indirizzo email sottoposto a hash con SHA256. Il testo deve essere in minuscolo ed è necessario rimuovere eventuali spazi iniziali o finali prima di applicare l’hash. È obbligatorio se non viene aggiunto alcun altro identificatore.

Type: string

Example: Per test-email@test.com = e586883b2b4faf78d48300a79e0e15138d664cdf796ffb86e533170a9893eda8
hashed_phone_number
a volte obbligatorio		Un numero di telefono in formato E164 e sottoposto a hash con SHA256. Il numero di telefono deve essere in formato E164 prima di applicare l’hash. È obbligatorio se non viene aggiunto alcun altro identificatore.

Type: string

Example: Per +11234567890 = 1fa6b8d986d9b9cd01bf36951815158bbde9f520c0567c835dfe34783d0a4231
ip_address
a volte obbligatorio		Valore in notazione decimale puntata, con quattro numeri separati da punti.

L’indirizzo IP deve essere inviato insieme a un altro identificatore (twclid, indirizzo email, numero di telefono o user agent).

Type: string

Example: 8.25.197.25
user_agent
a volte obbligatorio		Questo identificatore consente al server di riconoscere l’applicazione, il sistema operativo, il fornitore e/o la versione dell’user agent richiedente.

Lo user agent deve essere inviato insieme a un altro identificatore (twclid, indirizzo email, numero di telefono o indirizzo IP).

Type: string

Example: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/127.0.0.0 Safari/537.36.
oggetto contents
NameDescription
content_id
opzionale		SKU o GTIN; identificatore del contenuto.

Type: string

Example: jhp
content_group_id
opzionale		ID associato a un gruppo di varianti di prodotto

Type: integer

Example: group 1
content_name
opzionale		Nome del prodotto o del servizio.

Type: string

Example: radio flyer
content_price
opzionale		Prezzo del prodotto o del servizio.

Type: double

Example: 5.00
content_type
opzionale		Categoria del prodotto acquistato.

Type: string

Example: clothes
num_items
opzionale		Numero di prodotti acquistati

Type: integer

Example: 1
Parametri della risposta
NomeDescrizione
conversions_processedNumero di conversioni elaborate correttamente

Type: integer

Example: 1
debug_idUUID di debug che può essere usato per indagini successive

Type: string

Example: ff02e052-36e4-47d6-bdf0-6d8986446562
Esempio di richiesta
    twurl -H 'ads-api.x.com' -X POST '/12/measurement/conversions/oka17' --data '
    {
      "conversions":[
         {
            "conversion_time":"2022-02-18T01:14:00.603Z",
            "event_id":"ol288",
            "identifiers":[
               {
                  "twclid":"23opevjt88psuo13lu8d020qkn"
               },
               {
                  "hashed_email":"d360d510a224510f373931ce2d6215a799f5a9c1cef221b0149b6b6b50cced62"
               },
               {
                  "hashed_phone_number":"1fa6b8d986d9b9cd01bf36951815158bbde9f520c0567c835dfe34783d0a4231"
               },
               {
                  "ip_address":"1.0.0.0",
                  "user_agent":"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/127.0.0.0 Safari/537.36"
               }
            ],
            "value":"20.00",
            "number_items":3,
            "conversion_id":"23294827",
            "description":"Acquisti di prodotti per animali domestici",
            "contents":[
               {
                  "content_id":"1",
                  "content_name":"Coperte",
                  "content_type":"Prodotti per animali domestici"
                  "content_price":100.99,
                  "num_items":1,
                  "content_group_id":"123"
               }
            ]
         }
      ]
    }' --header 'Content-Type: application/json'
Esempio di richiesta
    {
       "request":{
          "params":{
             "account_id":"18ce552mlaq"
          }
       },
       "data":{
          "conversions_processed":1,
          "debug_id":"ff02e052-36e4-47d6-bdf0-6d8986446562"
       }
    }

​
Tag di eventi web

GET accounts/:account_id/web_event_tags Recupera i dettagli di alcuni o tutti i tag di eventi web associati all’account corrente.

​
URL della risorsa

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

​
Parametri

NomeDescrizione
account_id
obbligatorio		Identificatore dell’account sfruttato. Compare nel percorso della risorsa ed è generalmente un parametro obbligatorio per tutte le richieste dell’Advertiser API, escluso GET accounts. L’account specificato deve essere associato all’utente autenticato.

Type: string

Example: 18ce54d4x5t
count
opzionale		Specifica il numero di record da recuperare per ciascuna richiesta.

Type: int

Default: 200
Min, Max: 1, 1000
cursor
opzionale		Specifica un cursore per ottenere la pagina successiva dei risultati. Vedi Paginazione per maggiori informazioni.

Type: string

Example: 8x7v00oow
sort_by
opzionale		Ordina in base a un attributo supportato, in ordine crescente o decrescente. Vedi Ordinamento per maggiori informazioni.

Type: string

Example: created_at-asc
web_event_tag_ids
opzionale		Limita la risposta ai soli web event tag desiderati specificando un elenco di identificatori separati da virgole. È possibile fornire fino a 200 ID.

Type: string

Example: o3bk1
with_deleted
opzionale		Includi i risultati eliminati nella richiesta.

Type: boolean

Default: false
Possible values: true, false
with_total_count
opzionale		Includi l’attributo di risposta total_count.

Nota: Questo parametro e cursor si escludono a vicenda.

Nota: Le richieste che includono total_count avranno limiti di velocità inferiori, attualmente pari a 200 ogni 15 minuti.

Type: boolean

Default: false
Possible values: true, false

​
Esempio di richiesta

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/web_event_tags?web_event_tag_ids=o3bk1

​
Esempio di risposta

    {
      "request": {
        "params": {
          "web_event_tag_ids": [
            "o3bk1"
          ],
          "account_id": "18ce54d4x5t"
        }
      },
      "next_cursor": null,
      "data": [
        {
          "name": "tag evento web",
          "view_through_window": 7,
          "click_window": 7,
          "embed_code": "<script src=\"//platform.x.com/oct.js\" type=\"text/javascript\"></script><script type=\"text/javascript\">twttr.conversion.trackPid('ny3od',  { tw_sale_amount: 0, tw_order_quantity: 0 });</script><noscript><img height=\"1\" width=\"1\" style=\"display:none;\" alt=\"\"  src=\"https://analytics.x.com/i/adsct?txn_id=ny3od&amp;p_id=Twitter&amp;tw_sale_amount=0&amp;tw_order_quantity=0\" /><img height=\"1\" width=\"1\" style=\"display:none;\" alt=\"\"  src=\"//t.co/i/adsct?txn_id=ny3od&amp;p_id=Twitter&amp;tw_sale_amount=0&amp;tw_order_quantity=0\" /></noscript>",
          "id": "o3bk1",
          "retargeting_enabled": false,
          "last_tracked_at": "2021-05-22T17:00:04Z",
          "status": "TRACKING",
          "type": "DOWNLOAD"
          "website_tag_id": "ny3od",
          "deleted": false
        }
      ]
    }

​
GET accounts/:account_id/web_event_tags/:web_event_tag_id

Recupera uno specifico tag evento web associato all’account corrente.
URL della risorsa
https://ads-api.x.com/12/accounts/:account_id/web_event_tags/:web_event_tag_id
Parametri
NomeDescrizione
account_id
obbligatorio		Identificatore dell’account con leva. Compare nel percorso della risorsa ed è in genere un parametro obbligatorio per tutte le richieste dell’API Advertiser, ad eccezione di GET accounts. L’account specificato deve essere associato all’utente autenticato.

Type: string

Example: 18ce54d4x5t
web_event_tag_id
obbligatorio		Riferimento al web event tag utilizzato nella richiesta.

Type: string

Example: o3bk1
with_deleted
opzionale		Includi anche i risultati eliminati nella richiesta.

Type: boolean

Default: false
Possible values: true, false
Esempio di richiesta
GET https://ads-api.x.com/12/accounts/18ce54d4x5t/web_event_tags/o3bk1
Esempio di risposta
    {
      "request": {
        "params": {
          "web_event_tag_id": "o3bk1",
          "account_id": "18ce54d4x5t"
        }
      },
      "data": {
        "name": "tag di evento web",
        "view_through_window": 7,
        "click_window": 7,
        "embed_code": "<script src=\"//platform.x.com/oct.js\" type=\"text/javascript\"></script><script type=\"text/javascript\">twttr.conversion.trackPid('ny3od',  { tw_sale_amount: 0, tw_order_quantity: 0 });</script><noscript><img height=\"1\" width=\"1\" style=\"display:none;\" alt=\"\"  src=\"https://analytics.x.com/i/adsct?txn_id=ny3od&amp;p_id=Twitter&amp;tw_sale_amount=0&amp;tw_order_quantity=0\" /><img height=\"1\" width=\"1\" style=\"display:none;\" alt=\"\"  src=\"//t.co/i/adsct?txn_id=ny3od&amp;p_id=Twitter&amp;tw_sale_amount=0&amp;tw_order_quantity=0\" /></noscript>",
        "id": "o3bk1",
        "retargeting_enabled": false,
        "last_tracked_at": "2021-05-22T17:00:04Z",
        "status": "TRACKING",
        "type": "DOWNLOAD"
        "website_tag_id": "ny3od",
        "deleted": false
      }
    }

​
POST accounts/:account_id/web_event_tags

Crea un nuovo tag evento web associato all’account corrente.

​
URL della risorsa

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

​
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
click_window
obbligatorio		La finestra di attribuzione post‑clic per questo web tag.

Nota: Sono accettati solo i valori elencati di seguito.

Type: int

Possible values: 1, 7, 14, 30
name
obbligatorio		Il nome del web tag.

Type: string

Example: Sample single conversion event
retargeting_enabled
obbligatorio		Indica se il retargeting deve essere abilitato per questo web tag.

Type: boolean

Possible values: true, false
type
obbligatorio		Il tipo di web tag.

Type: enum

Possible values: ADDED_PAYMENT_INFO, ADD_TO_CART, ADD_TO_WISHLIST, CHECKOUT_INITIATED, CONTENT_VIEW, CUSTOM, DOWNLOAD, PRODUCT_CUSTOMIZATION,PURCHASE, SEARCH, SIGN_UP, SITE_VISIT, START_TRIAL, SUBSCRIBE

(Nell’interfaccia, SITE_VISIT è visualizzato come “Page view” e SIGN_UP come “Lead”)
view_through_window
obbligatorio		La finestra di attribuzione post‑view per questo web tag. Questo valore deve essere sempre minore o uguale al valore di click_window.

Nota: Sono accettati solo i valori elencati di seguito.

Type: int

Possible values: 0, 1, 7, 14, 30
Esempio di richiesta
POST https://ads-api.x.com/12/accounts/18ce54d4x5t/web_event_tags?click_window=7&name=web event tag&retargeting_enabled=false&type=SITE_VISIT&view_through_window=7

​
Esempio di risposta

    {
      "data": {
        "name": "tag evento web",
        "view_through_window": 7,
        "click_window": 7,
        "embed_code": "<script src='"//platform.x.com/oct.js"' type='"text/javascript"'></script><script type='"text/javascript"'>twttr.conversion.trackPid('ny3od',  { tw_sale_amount: 0, tw_order_quantity: 0 });</script><noscript><img alt='""' height='"1"' src='"https://analytics.x.com/i/adsct?txn_id=ny3od&p_id=Twitter&tw_sale_amount=0&tw_order_quantity=0"' style='"display:none;"' width='"1"'/><img alt='""' height='"1"' src='"//t.co/i/adsct?txn_id=ny3od&p_id=Twitter&tw_sale_amount=0&tw_order_quantity=0"' style='"display:none;"' width='"1"'/></noscript>",
        "id": "o3bk1",
        "retargeting_enabled": false,
        "last_tracked_at": null,
        "status": "NON VERIFICATO",
        "type": "SITE_VISIT",
        "website_tag_id": "ny3od",
        "deleted": false
      },
      "request": {
        "params": {
          "name": "tag evento web",
          "view_through_window": 7,
          "click_window": 7,
          "retargeting_enabled": false,
          "account_id": "18ce54d4x5t",
          "type": "SITE_VISIT"
        }
      }
    }

​
PUT accounts/:account_id/web_event_tags/:web_event_tag_id

Aggiorna un tag evento web associato all’account corrente.
URL della risorsa
https://ads-api.x.com/12/accounts/:account_id/web_event_tags/:web_event_tag_id

​
Parametri

NomeDescrizione
account_id
obbligatorio		L’identificatore dell’account utilizzato. Compare nel percorso della risorsa ed è in genere un parametro obbligatorio per tutte le richieste dell’Advertiser API, ad eccezione di GET accounts. L’account specificato deve essere associato all’utente autenticato.

Tipo: string

Esempio: 18ce54d4x5t
web_event_tag_id
obbligatorio		L’identificatore di un tag web nell’account corrente.

Tipo: string

Esempio: o3bk1
click_window
opzionale		La finestra di clic per questo tag web.

Nota: Sono accettati solo i valori elencati di seguito.

Tipo: int

Valori possibili: 1, 7, 14, 30
name
opzionale		Il nome del tag web.

Tipo: string

Esempio: Sample single conversion event
retargeting_enabled
opzionale		Indica se abilitare il retargeting per questo tag web.

Tipo: boolean

Valori possibili: true, false
type
opzionale		Il tipo di tag web.

Tipo: enum

Valori possibili: ADDED_PAYMENT_INFO, ADD_TO_CART, ADD_TO_WISHLIST, CHECKOUT_INITIATED, CONTENT_VIEW, CUSTOM, DOWNLOAD, PRODUCT_CUSTOMIZATION, PURCHASE, SEARCH, SIGN_UP, SITE_VISIT, START_TRIAL, SUBSCRIBE

(Nell’interfaccia, SITE_VISIT è mostrato come “Page view” e SIGN_UP è mostrato come “Lead”)
view_through_window
opzionale		La finestra di visualizzazione per questo tag web. Questo valore deve essere sempre minore o uguale a click_window.

Nota: Sono accettati solo i valori elencati di seguito.

Tipo: int

Valori possibili: 0, 1, 7, 14, 30

​
Esempio di richiesta

PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/web_event_tags/o3bk1?type=DOWNLOAD

​
Esempio di risposta

    {
      "data": {
        "name": "tag evento web",
        "view_through_window": 7,
        "click_window": 7,
        "embed_code": "<script src='"//platform.x.com/oct.js"' type='"text/javascript"'></script><script type='"text/javascript"'>twttr.conversion.trackPid('ny3od',  { tw_sale_amount: 0, tw_order_quantity: 0 });</script><noscript><img alt='""' height='"1"' src='"https://analytics.x.com/i/adsct?txn_id=ny3od&p_id=Twitter&tw_sale_amount=0&tw_order_quantity=0"' style='"display:none;"' width='"1"'/><img alt='""' height='"1"' src='"//t.co/i/adsct?txn_id=ny3od&p_id=Twitter&tw_sale_amount=0&tw_order_quantity=0"' style='"display:none;"' width='"1"'/></noscript>",
        "id": "o3bk1",
        "retargeting_enabled": false,
        "last_tracked_at": "2021-05-22T17:00:04Z",
        "status": "NON VERIFICATO",
        "type": "DOWNLOAD"
        "website_tag_id": "ny3od",
        "deleted": false
      },
      "request": {
        "params": {
          "web_event_tag_id": "o3bk1",
          "type": "DOWNLOAD"
          "account_id": "18ce54d4x5t"
        }
      }
    }

​
DELETE accounts/:account_id/web_event_tags/:web_event_tag_id

Elimina un tag di evento web specifico associato all’account corrente.

​
URL della risorsa

https://ads-api.x.com/12/accounts/:account_id/web_event_tags/:web_event_tag_id
Parametri
NomeDescrizione
account_id
obbligatorio		Identificatore dell’account utilizzato. Compare nel percorso della risorsa ed è generalmente un parametro obbligatorio per tutte le richieste dell’API Ads, ad eccezione di GET accounts. L’account specificato deve essere associato all’utente autenticato.

Type: string

Example: 18ce54d4x5t
web_event_tag_id
obbligatorio		Identificatore di un tag web sull’account corrente.

Type: string

Example: o3bk1
Esempio di richiesta
DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/web_event_tags/o3bk1
Esempio di risposta
    {
      "data": {
        "name": "tag evento web",
        "view_through_window": 7,
        "click_window": 7,
        "embed_code": "<script src='"//platform.x.com/oct.js"' type='"text/javascript"'></script><script type='"text/javascript"'>twttr.conversion.trackPid('ny3od',  { tw_sale_amount: 0, tw_order_quantity: 0 });</script><noscript><img alt='""' height='"1"' src='"https://analytics.x.com/i/adsct?txn_id=ny3od&p_id=Twitter&tw_sale_amount=0&tw_order_quantity=0"' style='"display:none;"' width='"1"'/><img alt='""' height='"1"' src='"//t.co/i/adsct?txn_id=ny3od&p_id=Twitter&tw_sale_amount=0&tw_order_quantity=0"' style='"display:none;"' width='"1"'/></noscript>",
        "id": "o3bk1",
        "retargeting_enabled": false,
        "last_tracked_at": "2021-05-22T17:00:04Z",
        "status": "NON VERIFICATO",
        "type": "DOWNLOAD"
        "website_tag_id": "ny3od",
        "deleted": true
      },
      "request": {
        "params": {
          "web_event_tag_id": "o3bk1",
          "account_id": "18ce54d4x5t"
        }
      }
    }
⌘I