Pubblico

Pubblici personalizzati

Panoramica

Esistono diversi modi per i partner per creare Custom Audiences.

Audience API (CRM)
Web
Mobile
Flessibile

Nota: non è possibile escludere le lookalike custom audiences dal targeting. Inoltre, non è possibile targetizzare sia una custom audience sia una lookalike della stessa custom audience nello stesso elemento di riga dell’annuncio (gruppo di annunci). Gestione delle audience Le audience possono essere gestite tramite partner di audience e partner della X Ads API. Offriamo una serie di endpoint nell’API per accedere e gestire le custom audiences. Per le informazioni sulle custom audiences, offriamo 2 endpoint:

Per maggiori dettagli su come caricare e gestire le audience, consulta la guida all’Audience API. Tempi di elaborazione In generale, le modifiche alle audience vengono elaborate in batch che vengono eseguiti ogni 6-8 ore. Durante l’elaborazione di una modifica, l’audience esistente da aggiornare non viene influenzata. Non consigliamo di effettuare più di un aggiornamento per aggiunte e uno per rimozioni per audience entro questo intervallo di tempo. Targeting Un’audience può essere targetizzata solo se corrisponde ad almeno 100 utenti attivi negli ultimi 90 giorni su client di proprietà e gestiti da X. GET accounts/:account_id/custom_audiences/:custom_audience_id indicherà se un’audience non può essere targetizzata perché corrisponde a un numero troppo basso di utenti. Audience API (CRM)

I partner audience o API forniscono un elenco di identificatori con hash e X esegue il matching producendo segmenti che vengono resi disponibili per l’acquisto media su X. I partner possono creare queste audience con l’Audience API. Come funziona?

Web Offriamo un processo standard di cookie matching quando lavoriamo con i partner di audience MPP per identificare i segmenti da targetizzare per l’acquisto media su X. Inoltre, gli inserzionisti possono configurare un X Web Event Tag per raccogliere i dati degli utenti del sito web e creare una corrispondente Custom Audience. Passaggi di configurazione

Come funziona?

Mobile Consulta il post del blog Custom Audiences from Mobile Apps per i dettagli. Flessibile Le Flexible audiences consentono agli inserzionisti di creare e salvare combinazioni di audience basate su custom audiences esistenti o su sottoinsiemi di custom audiences esistenti. I sottoinsiemi dei membri di una custom audience possono essere targetizzati in base alla recency e alla frequency dell’interazione. Casi d’uso con restrizioni per le Custom Audiences Ulteriori informazioni sulle restrizioni

Domande frequenti sul pubblico

D: Abbiamo inviato una grande quantità di dati: perché la dimensione del pubblico risulta TOO_SMALL? R: Attualmente i dati vengono aggiunti al pubblico in tempo reale, ma il job che elabora i dati per calcolare la dimensione del pubblico viene eseguito solo dopo un certo periodo di tempo. La dimensione corretta del pubblico dovrebbe essere visualizzata nell’interfaccia utente dopo alcune ore. D: Abbiamo terminato l’invio dei dati del pubblico e atteso 24 ore o più, ma non riusciamo ancora a eseguire il targeting del pubblico: quali sono i passaggi successivi? R: Verificare quanto segue:

L’user ID passato è corretto e non è malformato.
I nomi dei pubblici passati sono corretti e corrispondono ai precedenti aggiornamenti di appartenenza.
Confermare la risposta ai comandi POST.
Confermare che il pixel di ID Sync sia implementato correttamente e, come descritto dal processo di ID Sync, che un numero sufficiente di utenti abbia visitato il sito in questione per consentire il mapping. Gli utenti non mappati negli aggiornamenti di appartenenza non verranno convertiti in utenti targetizzabili.

Se tutto il resto è stato confermato come corretto e funzionante, contattare i referenti di prodotto di X fornendo informazioni il più dettagliate possibile (vedere la Guida ai Partner Inbounds per un esempio del tipo di informazioni preferite). D: Quante volte possiamo chiamare l’endpoint e con quale algoritmo? R: Consigliamo vivamente di chiamare il nostro sistema con delta incrementali e di non reinviare mai l’intera appartenenza al pubblico. Il sistema è stato testato con una capacità sufficiente a elaborare aggiornamenti incrementali dei dati per alcuni dei siti web più grandi al mondo. Il caricamento iniziale dei pubblici deve essere regolato con attenzione e si prevede che il primo upload richieda un tempo significativo per essere completato. D: Qual è la dimensione minima di un pubblico per poter essere utilizzato per il targeting?

La dimensione minima di un pubblico è 100 utenti (post match). Se un pubblico con meno di 500 utenti viene abbinato, non sarà disponibile per il targeting nell’X Ads UI.

D: Quanto tempo occorre per elaborare i file del pubblico? E quanto tempo prima che i file del pubblico siano pronti nell’interfaccia utente di X?

In genere occorrono 4–6 ore per elaborare i file del pubblico, ma dipende dalla dimensione del file. Una volta elaborato il file, i pubblici sono disponibili sull’X Ads UI.

D: Come viene calcolato il match rate?

Match rate = utenti X attivi negli ultimi 90 giorni / numero di utenti forniti

D: Come testare se un file di pubblico funziona correttamente?

È possibile fornire un file di pubblico di test e utilizzare “keltonlynn” come handle dell’inserzionista. Possiamo quindi verificare che il file venga correttamente acquisito e caricato nell’X UI.

D: Che cos’è un identificatore utente partner (p_user_id)?

È l’identificatore utilizzato dalla tua azienda per identificare in modo univoco ciascuno dei tuoi clienti.

D: Che cos’è un ID standard?

Può essere un indirizzo email, un device ID, un @handle di X o un ID.

D: Come ottengo l’HMAC Key?

Verrà fornita tramite email crittografata. Invia la tua chiave PGP pubblica a mpp-inquiry@x.com e ti invieremo un’email di test per verificare che tutto funzioni. Una volta verificato, ti invieremo l’HMAC Key.

D: Come verifico che il processo di hashing abbia funzionato utilizzando l’HMAC Key fornita?

X fornirà un file di test (contenente indirizzi email di esempio, device ID, ecc.) e un file di hash risultante con cui potrai confrontare i tuoi risultati.

D: Esiste un limite di dimensione per il file di full data match?

No, non esiste alcun limite di dimensione per il file di full data match.

D: Quanto tempo occorre per elaborare il file di full data match?

Una volta che il file viene ricevuto da X, l’elaborazione richiederà circa 1 giorno.

CRM

Questo documento descrive i dettagli di integrazione per i partner CRM di Custom Audiences, inclusi i formati dei file e il processo di scambio dei dati. Riepilogo L’azienda fornirà a X, per conto di un cliente, un elenco di identificatori utente comuni con hash (ad es. indirizzi e‑mail) o di id utente del partner, al fine di eseguire un blind match e generare un elenco di X User IDs per il targeting. I segmenti di targeting saranno resi disponibili all’@handle specifico dell’inserzionista indicato dal nome del file nella configurazione della campagna su ads.x.com. Tutti i file dell’azienda saranno forniti a X tramite un pacchetto sicuro su IronBox (www.golockbox.com), utilizzando un account specifico che X assegnerà all’azienda. X fornirà l’accesso a IronBox. La documentazione sulle API di IronBox è disponibile su https://secure.goironcloud.com/Docs/Help/.

Requisiti per la corrispondenza degli ID partner

Se l’azienda utilizza un proprio sistema di ID standard per tracciare gli utenti (cioè non identificatori utente comuni come indirizzi email, ID dispositivo, X user ID, ecc.), questo è il processo consigliato. 1. Corrispondenza completa dei dati Inizialmente, l’azienda fornirà un elenco completo di tutti i record utente che includano un identificatore utente comune univoco condiviso con X, in un singolo file, per eseguire una corrispondenza completa dei dati e produrre una mappatura, archiviata da X, dagli ID partner (p_user_id) agli ID X (tw_id). Questa operazione verrà eseguita regolarmente ogni 2-3 mesi per garantirne il corretto mantenimento. Al termine della corrispondenza, X condividerà via email con l’azienda un tasso di corrispondenza di riferimento ottenuto da questo file. Il formato del file dovrebbe essere: Convenzione di denominazione: FullDataMatch.[CompanyName].txt Algoritmo di hashing: HMAC_SHA-256 Formato: Colonna 1: valore HMAC hash degli identificatori comuni Colonna 2: Partner User ID (univoco per utente, non univoco nel file) Delimitatore di colonna (CSV): virgole per delimitare l’identificatore utente comune con hash dall’ID partner Valori separati da riga

Es.: se il record utente A ha Partner User ID 1 e identificatori comuni 1, 2 e 3:


common user identifier 1	p_user_1
common user identifier 2	p_user_1
common user identifier 3	p_user_1

*Vedere di seguito la sezione Indicazioni per l’hashing sugli identificatori utente comuni 2. Liste di segmenti personalizzati L’azienda fornirà elenchi di utenti sotto forma di p_user_id per creare audience personalizzate per i clienti ai fini del targeting su X.

Valori separati da riga
p_user_id
- (Come nella sezione 1. Corrispondenza completa dei dati. Se il valore fornito nella corrispondenza completa è hashed, l’azienda fornirà lo stesso valore hashed nel file dell’audience. Se il valore fornito non è hashed, l’azienda fornirà il valore in chiaro.)

Requisiti standard di corrispondenza

Se l’azienda non utilizza un id standard per la mappatura di tutti gli identificatori utente dei clienti, questo è il processo consigliato. Elenchi di segmenti personalizzati L’azienda fornirà direttamente a X, per conto dei clienti, elenchi di identificatori utente comuni sottoposti a hash per creare audience personalizzate. Il formato di questo file deve essere:

Valori separati da riga
Identificatore utente comune sottoposto a hash (ad es. indirizzo email)
Rispettare le convenzioni di denominazione dei file riportate di seguito
Rispettare le istruzioni di hashing per gli indirizzi email riportate di seguito (in Indicazioni per l’hashing)

Denominazione dei file e operazioni per le Liste di segmenti personalizzati

L’operazione applicata a un file è determinata dal suo nome, secondo le seguenti operazioni disponibili e la seguente convenzione generale di denominazione: audiencename_partnername.handle.operation.filetype

audiencename: Il nome della Custom Audience. Questo campo è il nome visualizzato quando si seleziona il pubblico nell’interfaccia di configurazione delle campagne su ads.x.com, ad es. brand_loyalty_card_holders.
partnername: Nome dell’azienda che fornisce i data per conto dell’inserzionista, ad es. company_name.
handle: Account X (@handle) che avrà accesso alle Custom Audiences, ad es. @pepsi, @dietpepsi
operation: new, add, remove, removeall, replace (dettagli di seguito)
timestamp: Epoch time Unix standard in secondi, utilizzato per garantire che ogni file pubblico caricato sia univoco
filetype: il file deve essere in formato .txt

Creazione e aggiornamento delle audience

Crea una nuova audience con un singolo file, ad es. loyalty_card_holders_partnername.pepsi.new.txt Aggiungi - Aggiungi le corrispondenze da un elenco a un’audience esistente, ad es. loyalty_card_holders_partnername.pepsi.add..txt Rimuovi - Rimuovi le corrispondenze da un elenco da un’audience esistente, ad es. loyalty_card_holders_partnername.pepsi.remove..txt Rimuovi tutto - Rimuovi le corrispondenze generate da un elenco cumulativo aggiornato regolarmente da tutte le audience di quel cliente (ovvero l’Opt-Out del cliente). Es: partnername.pepsi.removeall.txt

Può essere usato per un elenco completo di utenti che hanno effettuato l’opt‑out dall’inserzionista.
X considererà solo l’ultimo elenco fornito in questo file e lo applicherà a tutte le audience esistenti e future per le corrispondenze.

Utenti X al momento in cui questo file è stato fornito ed elaborato. Sostituisci - Rimuovi un’audience esistente e sostituiscila con un nuovo elenco di audience. Es: loyalty_card_holders_partnername.pepsi.replace..txt Opt-out generale dell’azienda - L’azienda fornirà un file cumulativo di opt‑out per rimuovere gli utenti che hanno effettuato l’opt‑out secondo la policy di opt‑out dell’azienda. X considererà solo l’ultimo elenco fornito in questo file di opt‑out dell’azienda e lo applicherà a tutte le audience esistenti e future per gli utenti X corrispondenti al momento in cui questo file è stato fornito ed elaborato. Il formato del file di opt‑out dell’azienda sarà il seguente: Es: partnername.removeall.txt DELETE - Rimuovi un’audience esistente dall’elenco corrente delle audience, ad es. loyalty_card_holders_partnername.pepsi.delete.txt

Istruzioni per l’hashing

X condividerà in modo sicuro una chiave di produzione codificata in base64 tramite PGP per eseguire l’hashing di identificatori utente comuni (ad es. indirizzi email). L’azienda eseguirà la decodifica base64 della chiave per ottenere una chiave da 32 byte da utilizzare per l’hashing. Esempio di chiave codificata in base64: BrQvOg+dACBUmKjRiNxZgJLh6zydjS0ZOv80FelTNzM= Esempio di chiave decodificata da Base64: /:� TшY Normalizzazione: l’azienda eseguirà una normalizzazione di base sugli identificatori utente comuni prima dell’hashing (ad eccezione degli ID dispositivo; vedere la sezione Normalizzazione degli ID dispositivo).

Normalizzazione dell’e-mail

In pratica, rimuovere gli spazi iniziali e finali e convertire l’indirizzo e-mail in minuscolo. Es.: Indirizzo e-mail grezzo: testemail_Organisational_baseball+884@It92I6Ev2B.Com Dopo la normalizzazione: testemail_organisational_baseball+884@it92i6ev2b.com Valore hash: 74d9584eded0ad1e5572a1c1849f3716751d371d6117a6155dad5363f4b4fbec Nota: Il numero di caratteri sia per l’HMAC codificato sia per la chiave può variare in base all’input e alla codifica, quindi può cambiare di conseguenza.

Normalizzazione degli ID del dispositivo

Applicheremo gli stessi requisiti per l’hashing degli ID del dispositivo utilizzando l’algoritmo SHA-256 e un salt comune che forniamo ai partner di dati. Rimuoviamo gli spazi come facciamo con gli indirizzi email, ma non applichiamo la conversione in minuscolo per IDFA/ID Android e va utilizzato l’esatto formato dell’IDFA/ID Android. Ecco un esempio del formato raw degli ID del dispositivo per iOS e Android, prima dell’hashing: IDFA iOS: DD99CFF7-6186-4602-9DF2-ED3FD0B2D431 ID Android: b5bf2122961b3595 IDFA iOS con hash: 134fb8cd95c7fd42e2793f469a447198ca5f990968db2dbadad70e723ed9750b ID Android con hash: 130dddff1939f229476f50bc8adab8fcb7e3525b0e9604fe8effc15e68cee4a4

Normalizzazione dell’ID utente di X

Gli ID di X verranno comunque sottoposti a hashing, poiché il raggruppamento dei dati — ad es. Customer List di @handles — è privato per l’inserzionista, anche se non si tratta di PII. I requisiti per l’hashing degli ID di X sono gli stessi: utilizzo dell’algoritmo SHA-256 e di un salt comune che forniamo ai data partner. Gli spazi devono essere rimossi sia dall’ID di X sia dall’@username, ma i User ID non richiedono normalizzazione. Gli @username devono essere convertiti in minuscolo ai fini della normalizzazione. Inoltre, il simbolo @ non deve essere incluso come parte dello username. Il formato dell’ID in chiaro sarà:

User ID: 27674040
@username: testusername

Hashed User ID: bf6b57d4e861e83bea8bbed2b800b251a64c95468ee6e8cb07c3368c9ed45e85 Hashed @username: 12201ae78ad1afa907c7112d17f498154ffb0bf9ea523f5390e072a06d7d9812

Integrazione ID Sync

I partner che inviano dati con un p_id devono eseguire un processo di ID Sync per generare una corrispondenza tra gli id utente dell’inserzionista o del partner e gli id utente di X. Questo consente agli inserzionisti di indirizzare direttamente i propri segmenti di utenti su X. I partner devono inoltre impostare il valore del parametro user_identifier_type su TALIST_PARTNER_USER_ID o TAWEB_PARTNER_USER_ID quando inviano gli aggiornamenti delle appartenenze.

Solo web: È possibile farlo inserendo un pixel sul sito dell’inserzionista, come descritto di seguito.
List: È possibile farlo utilizzando uno dei metodi descritti nella pagina CRM.

URL del pixel


URL di base
https://analytics.x.com/i/adsct

Parametri del pixel


Parametro	Descrizione
`p_id`	L’id partner assegnato da X
`p_user_id`	L’id dell’utente nel sistema del partner

Pixel di sincronizzazione ID:

Usando come esempio un partner id pari a 111 e un p_user_id pari a abc, il pixel risultante sarebbe il seguente:

    <pre class="brush: xml">
    <img height="1" width="1" src="https://analytics.x.com/i/adsct?p_id=111&p_user_id=abc" style="display:none" />
    </pre>

Configurazione del file di opt-out e invio dei file di opt-out I partner devono fornire a X un elenco di utenti che, secondo la migliore conoscenza del partner, hanno scelto di effettuare l’opt‑out dalla distribuzione di annunci mirati. Il formato del file deve essere il seguente:


Numero colonna	Nome colonna	Tipo colonna	Descrizione
1	Partner ID	string	Il “partner id” è l’ID che X fornisce al partner per identificare in modo univoco ciascun partner.
2	id dell’utente nel sistema del partner	string	Il `p_user_id` è l’ID univoco utilizzato dal partner per identificare l’utente. Il file contenente questi utenti in opt‑out deve essere caricato utilizzando l’endpoint TON upload e il percorso dei data caricati deve essere inviato all’endpoint Global Opt Out qui: PUT accounts/:account_id/custom_audiences/global_opt_out.

Invio degli aggiornamenti di membership Come specificato nella nostra documentazione dell’endpoint, quando si inviano utenti tramite l’endpoint POST custom_audience_memberships è necessario passare un customer ID per abilitare un match basato su cookie. I partner che inviano data con un p_id devono impostare user_identifier_type su TALIST_PARTNER_USER_ID o TAWEB_PARTNER_USER_ID. Tutti gli altri passaggi rimangono gli stessi di quelli elencati nella Guida all’integrazione della Real‑Time Audience API

Dati utente per Custom Audiences

Questo documento descrive il formato dei dati utente per [Custom Audience]/x-ads-api/audiences. Normalizzazione dei dati ID dispositivo:

IDFA - in minuscolo, con trattini; es.: 4b61639e-47cc-4056-a16a-c8217e029462
AdID - è richiesto il formato originale presente sul dispositivo; non in maiuscolo, con trattini; es.: 2f5f5391-3e45-4d02-b645-4575a08f86e
Android id - è richiesto il formato originale presente sul dispositivo; non in maiuscolo, senza trattini o spazi; es.: af3802a465767e36

Indirizzi email:

in minuscolo, rimuovere spazi iniziali e finali; es.: support@x.com

Username X:

senza @, in minuscolo e con spazi iniziali e finali rimossi; es.: jack

ID utente X:

Intero standard; es.: 143567

Hashing dei dati I dati di ciascuna riga devono essere sottoposti a hash con SHA256, senza salt. Inoltre, l’hash finale deve essere in minuscolo. Ad esempio, 49e0be2aeccfb51a8dee4c945c8a70a9ac500cf6f5cb08112575f74db9b1470d e non 49E0BE2AECCFB51A8DEE4C945C8A70A9AC500CF6F5CB08112575F74DB9B1470D

# hashing dell'utente @AdsAPI utilizzando python
import hashlib
hashlib.sha256("adsapi".encode()).hexdigest()

#output
49e0be2aeccfb51a8dee4c945c8a70a9ac500cf6f5cb08112575f74db9b1470d

Ulteriori esempi di codice per l’hashing sono disponibili su github.com/xdevplatform/ads-platform-tools.

Pubblici personalizzati: Web

Informazioni I partner invieranno un elenco di ID (p_user_ids) da utilizzare per il targeting per conto di un inserzionista. Questo avviene tramite un processo di sincronizzazione degli ID che crea una corrispondenza tra i p_user_ids e l’X user ID. Questa corrispondenza viene poi utilizzata per generare elenchi di X user IDs che possono essere usati per il targeting. Questi pubblici personalizzati saranno resi disponibili sullo specifico @handle dell’inserzionista, indicato dall’etichetta nella configurazione della campagna Custom Audiences Web su ads.x.com. X fornirà il pixel sicuro che può essere inserito nei tag e nei siti dei partner per associare gli ID (p_user_ids) agli X user IDs. Una volta completato il processo di sincronizzazione degli ID, i file di targeting saranno creati dal partner e resi disponibili a X tramite un endpoint HTTPS. Questi file di targeting vengono acquisiti regolarmente da X e quindi resi disponibili nell’interfaccia di X. X Secure Pixel Il pixel sicuro di X avrà il seguente aspetto: https://analytics.x.com/i/adsct?p_user_id=xyz&p_id=123 p_user_id - xyz rappresenta l’ID utente del partner fornito dal partner p_id - 123 rappresenta l’ID univoco del partner (fornito da X) Endpoint HTTPS del partner & file utenti di targeting Il partner dovrà fornire a X un endpoint HTTPS e credenziali (username/password) che possano essere utilizzati per acquisire regolarmente il file di targeting. Un endpoint HTTPS di esempio avrà il seguente aspetto:

https://<partnerdomain>/twitter/partner_targeting_%Y-%M-%D.tsv.gz

%Y - Codice di formato per l’anno (YYYY) %M - Codice di formato per il mese (MM) %D - Codice di formato per il giorno (DD) I dati trasmessi consisteranno nei seguenti file:

Partner Targeting User File
Targeting Conversion File

Tutti i file saranno in formato TSV, in cui i singoli campi di ogni riga sono separati da un carattere di tabulazione. I valori validi dei campi non conterranno mai il carattere di tabulazione. Intervallo di IP X consentito: Di seguito è riportato l’intervallo di IP che può essere autorizzato per l’accesso al Partner endpoint.

199.16.156.0/22
199.59.148.0/22

Partner Targeting User File:

Numero colonna	Nome colonna	Tipo di colonna	Descrizione
1	partner id	string	Il “partner id” è l’ID che X fornisce al partner per identificare in modo univoco ciascun partner.
2	advertiser id	string	L’“advertiser id” è l’@handle dell’inserzionista.
3	p_user_id	string	Il “p_user_id” è l’ID univoco utilizzato dal partner per identificare l’utente.
3	confidence score	integer	Il “confidence score” è facoltativo. Consigliamo di utilizzare un intervallo 0-100. Se il caso d’uso è il retargeting, un confidence score di “100” indica un utente che è stato retargettizzato direttamente. Qualsiasi punteggio da 0 a 99 corrisponde al livello di confidenza del look-alike.
4	segment label	string	Il “segment label” è facoltativo. I partner possono usare “segment label” per specificare, ad esempio, categorie di prodotto. Consigliamo di usare questo “segment label” poiché è il nome leggibile dagli utenti per le Custom Audiences nell’interfaccia ads.x.com.

Note: Ogni volta che riceviamo un nuovo Partner Targeting File, ci aspettiamo che sia l’elenco completo degli utenti che il partner ci raccomanda di targettizzare, non incrementale, salvo diverso accordo. Con ciascun partner concorderemo la frequenza di consegna di questo Partner Targeting File. Se non riceviamo un Partner Targeting File come previsto, utilizzeremo la versione precedente con un tempo di scadenza predefinito.

Integrazione con l’API Audience

Panoramica

L’Audience API è stata introdotta come parte della v4 della X Ads API e porta con sé diversi miglioramenti rispetto agli endpoint legacy per le Audiences. Questo nuovo endpoint si basa su un nuovo backend di elaborazione delle Audience e offre numerosi miglioramenti in termini di stabilità, robustezza e affidabilità. Lo scopo di questa guida è mettere in evidenza le differenze tra l’Audience API e i processi legacy di caricamento e gestione delle Audience. La documentazione di riferimento è disponibile nella pagina di riferimento della Audience API. Nota: Tutti i dati utente delle Audience devono essere sottoposti a hash SHA-256 prima del caricamento. Ulteriori dettagli, insieme ai tipi di identificatori utente accettati e alla normalizzazione dei dati, sono disponibili nella pagina user data. Modifiche alla funzionalità delle Audience Le seguenti modifiche alle Custom Audiences sono state introdotte a partire dalla v4; tutti gli endpoint deprecati non saranno più disponibili una volta che la v3 della X Ads API sarà stata dismessa:

Deprecato caricamento TON:
- GET accounts/:account_id/custom_audience_changes
- GET accounts/:account_id/custom_audience_changes/:custom_audience_change_id
- POST accounts/:account_id/custom_audience_changes
- PUT accounts/:account_id/custom_audiences/global_opt_out
Deprecato Real Time Audiences:
- POST custom_audience_memberships
Custom Audience:
- Il parametro list_type verrà rimosso dalla richiesta e dalla risposta su tutti gli endpoint Custom Audience. In precedenza, questo parametro veniva utilizzato per identificare il tipo di identificatore utente dell’Audience (ad es. email, X User ID, ecc.); ora, però, le Audience possono accettare più identificatori utente per la stessa Audience, rendendo questo valore irrilevante.
Generale:
- La finestra di lookback dell’Audience è stata aggiornata per considerare gli utenti attivi negli ultimi 90 giorni (invece di 30 giorni)
- Il numero minimo di utenti corrispondenti richiesto affinché un’Audience sia targetizzabile è stato ridotto a 100 utenti (da 500 utenti)

Prerequisiti

Accesso alla X Ads API
Per accedere all’endpoint Audience, dovrai essere aggiunto a una allowlist. Compila questo modulo e accetta il nuovo X Ads Products and Services Agreement se inizialmente accettato prima del 2018-08-01

Processo di caricamento delle Audience La tabella seguente elenca le principali differenze tra i vecchi e i nuovi flussi di creazione delle Audience, con ulteriori dettagli disponibili più sotto:

Step in Process	Audience API	(Deprecated) TON Upload
Create a shell Audience	Can be created via the [POST custom_audience endpoint]/x-ads-api/audiences	Can be created via the [POST custom_audience endpoint]/x-ads-api/audiences
Add a new user	Use the `operation_type` `Update` with the Audience endpoint	Use the `operation` `ADD` with the POST custom_audience_changes endpoint
Remove a user	Use the `operation_type` `Delete` with the Audience endpoint	Use the `operation` `REMOVE` with the POST custom_audience_changes endpoint
Opting-Out Users	Use the `operation_type` `Delete` with the Audience endpoint and the corresponding `custom_audience_id`s that the user is a part of	Use the Global opt-out endpoint

Nota Qualsiasi Audience aggiornata o esclusa tramite il percorso di caricamento TON deve avere una lista corrispondente caricata tramite l’endpoint TON Upload e associata a un’Audience utilizzando l’endpoint custom_audience_changes. Limitazione della velocità L’endpoint Audience API ha un limite di velocità di 1500/1min per account. Non ci sono limiti al numero di utenti che possono essere inviati in un singolo payload. I soli vincoli sul payload sono:

Numero totale di operazioni: 2500 operazioni
Dimensione massima del payload: 5.000.000 byte

Gestione degli utenti dell’Audience Per creare una nuova Audience, sono necessari i passaggi seguenti

Crea una nuova Custom Audience

Crea uno “shell” di Custom Audience utilizzando l’endpoint [POST custom_audience]/x-ads-api/audiences e recupera il relativo id della Custom Audience. Questo passaggio è necessario se stai creando un’Audience da zero. Se stai aggiornando un’Audience esistente, passa alla sezione successiva

Aggiungere utenti a un pubblico

Usa POST accounts/:account_id/custom_audiences/:custom_audience_id/users con l’id della Custom Audience e un payload di esempio come segue: POST https://ads-api.x.com/11/accounts/18ce54d4x5t/custom_audiences/1nmth/users

    # Tutti i valori devono essere sottoposti a hash, i valori non sottoposti a hash sono utilizzati in questo esempio a scopo illustrativo
    [
      {
        "operation_type": "Update",
        "params": {
          "effective_at": "2018-05-15T00:00:00Z",
          "expires_at": "2019-01-01T07:00:00Z",
          "users": [
            {
              "email": [
                "abc@x.com"
              ],
              "handle": [
                "x",
                "adsapi"
              ]
            },
            {
              "email": [
                "edf@x.com"
              ],
              "twitter_id": [
                "121291606",
                "17874544"
              ]
            }
          ]
        }
      }
    ]

Per aggiungere un utente a un’Audience, usa operation_type Update. La nuova interfaccia di Audience consente di passare più chiavi utente per un singolo utente. Ogni oggetto nell’array di oggetti JSON corrisponde a un singolo utente. Usando il payload di esempio sopra, la richiesta aggiungerà due utenti a un’Audience: uno con email e handle e un altro con email e twitter_id.

Rimuovere utenti da un’audience

Analogamente al processo descritto per l’aggiunta degli utenti, gli utenti possono essere rimossi da un’audience come segue: POST https://ads-api.x.com/11/accounts/18ce54d4x5t/custom_audiences/1nmth/users

    # Tutti i valori devono essere sottoposti a hash, i valori non sottoposti a hash sono utilizzati in questo esempio a scopo illustrativo
    [
      {
        "operation_type": "Delete",
        "params": {
          "effective_at": "2018-05-15T00:00:00Z",
          "expires_at": "2019-01-01T07:00:00Z",
          "users": [
            {
              "email": [
                "abc@x.com"
              ],
              "twitter_id": [
                "783214",
                "1225933934"
              ]
            },
            {
              "email": [
                "edf@x.com"
              ],
              "twitter_id": [
                "121291606",
                "17874544"
              ]
            }
          ]
        }
      }
    ]

Il operation_type deve essere impostato su Delete e gli utenti verranno abbinati in base a qualsiasi chiave presente al momento dell’aggiunta degli utenti all’audience. Ad esempio, se un utente è stato aggiunto a un’audience utilizzando email e twitter_id, lo stesso utente può essere rimosso utilizzando una qualsiasi di queste chiavi, ossia email oppure twitter_id, o entrambe. Inoltre, è possibile aggiungere e rimuovere utenti dalla stessa Audience nella medesima richiesta. L’endpoint supporta più valori di operation_type per richiesta.

Utenti con opt-out

Con la dismissione dell’endpoint di opt-out globale, i partner sono tenuti a Delete tutti gli utenti che hanno effettuato l’opt-out da qualsiasi Audience. Esistono alcuni modi per farlo:

Tenere traccia di quali utenti appartengono a quali Audience e rimuovere questi utenti singolarmente da ciascuna Audience.
Rimuovere l’utente da tutte le Audience associate a un account Ads.

Best practice generali

Consigliamo vivamente di chiamare questo endpoint in batch quasi in tempo reale per evitare code a picchi, che richiedono più tempo per essere elaborate e, in generale, causano un carico non necessario sul nostro sistema. Questo assicura anche che gli utenti siano disponibili prima per il targeting delle campagne.
Una chiamata all’API eseguita correttamente restituirà success_count e total_count, corrispondenti al numero di oggetti user ricevuti nella richiesta.
Questo endpoint è atomico: o l’intera richiesta ha esito positivo oppure, in caso di errori, fallisce l’intera richiesta. In caso di risposta di errore, si raccomanda ai consumer dell’API di correggere l’errore e ripetere la richiesta con l’intero payload.
In caso di errore, si consiglia ai partner di usare un approccio di backoff esponenziale con tentativi di ritentativo. Ad esempio, ritentare immediatamente al primo errore, dopo 1 minuto al secondo errore e dopo 5 minuti al terzo errore consecutivo, e così via.

Riferimento all’API

Approfondimenti sulle parole chiave

GET insights/keywords/search

Dato un gruppo di keyword, recupera il volume di Tweet associato e un set di 30 keyword correlate. Il volume di Tweet si riferisce solo alle keyword in input, non a quelle correlate. È consentito un intervallo temporale massimo (end_time - start_time) di 7 giorni. Nota: i risultati sono limitati a una singola area geografica (paese). Resource URL https://ads-api.x.com/12/insights/keywords/search Parameters

Name	Description
granularity required	Specifica la granularità dei dati restituiti per l’intervallo di tempo indicato da `start_time` e `end_time`. Ad esempio, quando impostata su `HOUR`, verrà restituito un datapoint per ogni ora compresa tra `start_time` e `end_time`. Type: enum Possible values: `DAY`, `HOUR`
keywords required	Una stringa di keyword separate da virgola per restringere la ricerca. Tutte le keyword sono combinate con l’operatore OR. Nota: è possibile utilizzare al massimo 10 keyword (somma di `keywords` e `negative_keywords`). Type: string Example: `developers`
start_time required	Limita i dati recuperati a quelli raccolti nella finestra temporale tra `start_time` e `end_time`. Espressa in ISO 8601. Type: string Example: `2017-07-10T00:00:00Z`
end_time optional	Limita i dati recuperati a quelli raccolti nella finestra temporale tra `start_time` e `end_time`. Espressa in ISO 8601. Nota: predefinita all’ora corrente. Type: string Example: `2017-07-11T00:00:00Z`
location optional	Un valore di targeting ottenuto dall’endpoint GET targeting_criteria/locations per restringere i risultati in base alla posizione dell’utente dell’account. Nota che al momento sono supportate solo località a livello di paese. Type: string Example: `0ce8b9a7b2742f7e`
negative_keywords optional	Una stringa di keyword separate da virgola da escludere. Tutte le keyword negative sono combinate con l’operatore OR. Nota: è possibile utilizzare al massimo 10 keyword (somma di `keywords` e `negative_keywords`). Type: string Example: `rain`

Example Request

GET https://ads-api.x.com/12/insights/keywords/search?end_time=2018-02-02&granularity=DAY&keywords=developers&start_time=2018-02-01

Esempio di risposta*

    {
      "request": {
        "params": {
          "start_time": "2018-02-01T00:00:00Z",
          "end_time": "2018-02-02T00:00:00Z",
          "granularity": "DAY",
          "keywords": [
            "sviluppatori"
          ]
        }
      },
      "data": {
        "related_keywords": [
          "dev",
          "sviluppatore",
          "programmatori",
          "mysql",
          "sviluppatori",
          "#tecnologia",
          "#sviluppatori",
          "sicurezza",
          "programmatori",
          "#tech",
          "javascript",
          "#iot",
          "#bigdata",
          "cloud",
          "devops",
          "php",
          "sviluppatore",
          "programmatore",
          "ingegnere",
          "big data",
          "agile",
          "app",
          "programmazione",
          "ios",
          "creatore",
          "startup",
          "dello sviluppatore",
          "java",
          "#devops",
          "startup"
        ],
        "tweet_volume": [
          15707
        ]
      }
    }

Autorizzazioni per i Pubblici Personalizzati

GET accounts/:account_id/tailored_audiences/:tailored_audience_id/permissions

Recupera i dettagli di alcune o tutte le autorizzazioni associate alla tailored audience specificata. Resource URL https://ads-api.x.com/5/accounts/:account_id/tailored_audiences/:tailored_audience_id/permissions Parameters

Name	Description
account_id required	L’identificatore dell’account utilizzato. Compare nel percorso della risorsa ed è generalmente un parametro obbligatorio per tutte le richieste dell’Advertiser API, esclusa GET accounts. L’account specificato deve essere associato all’utente autenticato. Type: string Example: `18ce54d4x5t`
tailored_audience_id required	Un riferimento alla tailored audience con cui si opera nella richiesta. Type: string Example: `1nmth`
count optional	Specifica il numero di record da recuperare per ciascuna richiesta. Type: int Default: `200` Min, Max: `1`, `1000`
cursor optional	Specifica un cursore per ottenere la pagina successiva dei risultati. Vedere Pagination per maggiori informazioni. Type: string Example: `8x7v00oow`
granted_account_ids optional	Limita la risposta ai soli account desiderati specificando un elenco di identificatori separati da virgola. È possibile fornire fino a 200 ID. Type: string Example: `18ce54aymz3`
sort_by optional	Ordina per un attributo supportato in ordine crescente o decrescente. Vedere Sorting per maggiori informazioni. Type: string Example: `created_at-asc`
tailored_audience_permission_ids optional	Limita la risposta alle sole autorizzazioni della tailored audience desiderate specificando un elenco di identificatori separati da virgola. È possibile fornire fino a 200 ID. Type: string Example: `ri`
with_total_count optional	Include l’attributo di risposta `total_count`. Nota: Questo parametro e `cursor` sono mutuamente esclusivi. Nota: Le richieste che includono `total_count` avranno limiti di velocità inferiori, attualmente pari a 200 per 15 minuti. Type: boolean Default: `false` Possible values: `true`, `false`

Example Request GET https://ads-api.x.com/5/accounts/18ce54d4x5t/tailored_audiences/1nmth/permissions Example Response

    {
      "request": {
        "params": {
          "account_id": "18ce54d4x5t",
          "tailored_audience_id": "1nmth"
        }
      },
      "next_cursor": null,
      "data": [
        {
          "tailored_audience_id": "1nmth",
          "permission_level": "READ_ONLY",
          "id": "ri",
          "created_at": "2017-06-08T23:17:59Z",
          "granted_account_id": "18ce54aymz3",
          "updated_at": "2017-06-08T23:17:59Z",
          "deleted": false
        }
      ]
    }

POST accounts/:account_id/tailored_audiences/:tailored_audience_id/permissions

Crea un nuovo oggetto di autorizzazione che consente di condividere il pubblico specificato con un determinato account. Nota: Per creare o modificare le autorizzazioni di un pubblico personalizzato, il pubblico deve essere di proprietà dell’account che tenta di modificarle. Puoi verificare la proprietà di un pubblico personalizzato controllando l’attributo di risposta is_owner nella risposta relativa a quello specifico pubblico. Nota: I pubblici possono essere condivisi solo tra account pubblicitari appartenenti alla stessa azienda oppure se l’account pubblicitario proprietario del pubblico dispone della funzionalità di account SHARE_AUDIENCE_OUTSIDE_BUSINESS. Resource URL https://ads-api.x.com/5/accounts/:account_id/tailored_audiences/:tailored_audience_id/permissions Parameters

Name	Description
account_id required	Identificatore dell’account utilizzato. 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`
granted_account_id required	L’account a cui desideri concedere le autorizzazioni per il pubblico personalizzato. Type: string Example: `18ce54aymz3`
permission_level required	Il tipo di accesso al pubblico personalizzato che deve avere `granted_account_id`. Type: enum Possible values: `READ_ONLY`, `READ_WRITE`
tailored_audience_id required	Riferimento al pubblico personalizzato con cui stai operando nella richiesta. Type: string Example: `2906h`

Example Request

POST https://ads-api.x.com/5/accounts/18ce54d4x5t/tailored_audiences/2906h/permissions?granted_account_id=18ce54aymz3&permission_level=READ_ONLY

Example Response

    {
      "request": {
        "params": {
          "account_id": "18ce54d4x5t",
          "granted_account_id": "18ce54aymz3",
          "permission_level": "READ_ONLY",
          "tailored_audience_id": "2906h"
        }
      },
      "data": {
        "tailored_audience_id": "2906h",
        "permission_level": "READ_ONLY",
        "id": "14m",
        "created_at": "2017-09-12T23:49:34Z",
        "granted_account_id": "18ce54aymz3",
        "updated_at": "2017-09-12T23:49:34Z",
        "deleted": false
      }
    }

DELETE accounts/:account_id/tailored_audiences/:tailored_audience_id/permissions/:tailored_audience_permission_id

Revoca l’autorizzazione specificata per la condivisione di una Tailored Audience. Nota: La creazione o la modifica delle autorizzazioni per una tailored audience richiede che l’audience sia di proprietà dell’account che tenta di modificarle. È possibile verificare la proprietà di una tailored audience controllando l’attributo di risposta is_owner nella risposta per una determinata audience. Una volta revocata, garantiamo che l’account a cui era stata concessa l’autorizzazione (granted_account_id) non potrà più targettizzare l’audience nelle campagne future. Le campagne esistenti continueranno a essere eseguite con le audience condivise; le campagne non si interrompono e l’audience non viene rimossa dalla campagna. Non è possibile duplicare tale campagna dopo la revoca dell’autorizzazione alla condivisione dell’audience. Resource URL

https://ads-api.x.com/5/accounts/:account_id/tailored_audiences/:tailored_audience_id/permissions/:tailored_audience_permission_id

Parameters

Name	Description
account_id required	L’identificatore dell’account utilizzato. Compare nel percorso della risorsa ed è generalmente un parametro obbligatorio per tutte le richieste dell’API Advertiser, escluso GET accounts. L’account specificato deve essere associato all’utente autenticato. Type: string Example: `18ce54d4x5t`
tailored_audience_id required	Riferimento alla tailored audience su cui si sta operando nella richiesta. Type: string Example: `1nmth`
tailored_audience_permission_id required	Riferimento all’autorizzazione della tailored audience su cui si sta operando nella richiesta. Type: string Example: `ri`

Example Request DELETE https://ads-api.x.com/5/accounts/18ce54d4x5t/tailored_audiences/1nmth/permissions/ri Example Response

    {
      "request": {
        "params": {
          "account_id": "18ce54d4x5t",
          "tailored_audience_permission_id": "ri",
          "tailored_audience_id": "1nmth"
        }
      },
      "data": {
        "tailored_audience_id": "1nmth",
        "permission_level": "READ_ONLY",
        "id": "ri",
        "created_at": "2017-06-08T23:17:59Z",
        "granted_account_id": "18ce54aymz3",
        "updated_at": "2017-08-30T18:29:35Z",
        "deleted": true
      }
    }

Pubblici di destinazione

GET accounts/:account_id/custom_audiences/:custom_audience_id/targeted

Recupera un elenco di elementi di riga e campagne attivi o di tutti quelli che hanno come target un dato custom_audience_id

Name	Description
account_id required	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`
custom_audience_id required	Un riferimento all’audience personalizzata con cui stai operando nella richiesta. Type: string Example: `2906h`
with_active optional	Se `false`, include gli elementi di riga con stato `servable=false` Type: boolean Default: `true` Possible values: `true`, `false`
cursor optional	Specifica un cursore per ottenere la pagina successiva dei risultati. Vedi Paginazione per maggiori informazioni. Type: string Example: `8x7v00oow`

Example Request GET https://ads-api.x.com/12/accounts/18ce54d4x5t/custom_audiences/2906h/targeted Example Response

    {
      "request": {
        "params": {
          "account_id": "18ce54d4x5t",
          "custom_audience_id": "2906h",
        }
      },
      "next_cursor": null,
      "data": [
        {
          "campaign_id": "59hod",
          "campaign_name": "campagna-test",
          "line_items": [
            {
              "id": "5gzog",
              "name": "elemento-linea-test",
              "servable": true
            }
          ]
        },
        {
          "campaign_id": "arja7",
          "campaign_name": "Campagna senza titolo",
          "line_items": [
            {
              "id": "bjw1q",
              "name": null,
              "servable": true
            }
          ]
        }
      ]
    }

Utenti delle Custom Audience

POST accounts/:account_id/custom_audiences/:custom_audience_id/users

Questo endpoint consente ai partner di aggiungere, aggiornare e rimuovere utenti da uno specifico custom_audience_id. L’endpoint accetta anche più tipi di identificatori per ogni utente. Tutti i dati forniti nel campo users della richiesta, eccetto partner_user_id, devono essere sottoposti a hashing con SHA256 e normalizzati. Batch Requests

La dimensione massima attuale del batch è 2500 per questo endpoint. La dimensione del batch è determinata dal numero di operazioni (Update/Delete) per richiesta. Ad esempio, più di 2500 oggetti operazione ({"operation_type": "Update/Delete", [..] }) in un unico array producono un errore.
La dimensione massima del body della richiesta POST che questo endpoint può accettare è 5,000,000 byte.
I limiti di velocità per questo endpoint sono 1500 per finestra di 1 minuto.
Tutti i parametri sono inviati nel body della richiesta ed è richiesto un Content-Type di application/json.
Le richieste batch falliscono o riescono come gruppo e tutte le risposte API, sia di errore sia di successo, preservano l’ordine degli elementi della richiesta iniziale.

Batch Responses La risposta restituita dalla X Ads API contiene due campi, success_count e total_count. Questi valori devono sempre essere uguali e rappresentano il numero di record nella richiesta che sono stati elaborati dal backend. Una situazione in cui il numero di record inviati nel body della richiesta non è uguale a success_count e total_count deve essere trattata come una condizione di errore, che richiede un nuovo tentativo. Batch Errors

Gli errori a livello di richiesta (es. dimensione massima del batch superata) sono mostrati nella risposta all’interno dell’oggetto errors.
Gli errori a livello di elemento (es. parametri richiesti mancanti) sono mostrati nella risposta all’interno dell’oggetto operation_errors.
L’indice dell’errore in operation_errors si riferisce all’indice dell’elemento di input, con il corrispondente messaggio di errore.

URL della risorsa

https://ads-api.x.com/12/accounts/:account_id/custom_audiences/:custom_audience_id/users

Parametri

Nome	Descrizione
operation_type obbligatorio	Il tipo di operazione per gruppo di `users` in esecuzione. Tipo: enum Valori possibili: `Update`, `Delete`
params obbligatorio	Un oggetto JSON contenente l’array `users` e i timestamp `effective_at` ed `expires_at`. Tipo: JSON
users obbligatorio	Un array di oggetti JSON contenenti tutti i parametri per un singolo utente. Tipo: JSON
effective_at opzionale	L’ora UTC alla quale le associazioni della custom audience devono entrare in vigore. Espressa in ISO 8601. Impostazione predefinita: data e ora correnti. Tipo: string Esempio: `2017-07-05T07:00:00Z`
expires_at opzionale	L’ora UTC alla quale le associazioni della custom audience devono scadere. L’orario specificato deve essere successivo al valore di `effective_at`. Espressa in ISO 8601. Impostazione predefinita: 13 mesi dal timestamp della richiesta. Tipo: string Esempio: `2017-07-05T07:00:00Z`

Dato l’approccio multi-chiave all’oggetto users, ciascun elemento di questo oggetto è documentato di seguito:

Nome	Descrizione
email opzionale	Indirizzo/i email dell’utente. Tipo: Array[String]
device_id opzionale	IDFA/AdID/Android ID Tipo: Array[String]
handle opzionale	Gli @handle appartenenti all’utente Tipo: Array[String]
twitter_id opzionale	L’ID X appartenente all’utente Tipo: Array[String]
phone_number opzionale	Numero/i di telefono dell’utente Tipo: Array[String]
partner_user_id opzionale	L’id dell’utente nel sistema dei partner. Tipo: Array[String]

Esempio di richiesta

POST https://ads-api.x.com/12/accounts/18ce54d4x5t/custom_audiences/1nmth/users

    [
      {
        "operation_type": "Update",
        "params": {
          "effective_at": "2018-05-15T00:00:00Z",
          "expires_at": "2019-01-01T07:00:00Z",
          "users": [
            {
              "email": [
                "4798b8bbdcf6f2a52e527f46a3d7a7c9aefb541afda03af79c74809ecc6376f3"
              ],
              "handle": [
                "7352f353c460e74c7ae226952d04f8aa307b12329c5512ec8cb6f1a0f8f9b2cb",
                "49e0be2aeccfb51a8dee4c945c8a70a9ac500cf6f5cb08112575f74db9b1470d"
              ]
            },
            {
              "email": [
                "5bf13d5ad4200407c5bc8b9bb578e425d05ef936fd488e3799a9d0806669223c"
              ],
              "twitter_id": [
                "34d56c7159a7eea941f359653029410f813f65a1d2d13ecc5ccbdd5a8cb755cf",
                "00e7b76c9739dec57f4c4a20ec021a20ffcf26bd00f519b17ea00f0ed6048f85"
              ]
            }
          ]
        }
      },
      {
        "operation_type": "Delete",
        "params": {
          "effective_at": "2018-05-15T00:00:00Z",
          "expires_at": "2019-01-01T07:00:00Z",
          "users": [
            {
              "device_id": [
                "8d969eef6ecad3c29a3a629280e686cf0c3f5d5a86aff3ca12020c923adc6c92"
              ],
              "email": [
                "4798b8bbdcf6f2a52e527f46a3d7a7c9aefb541afda03af79c74809ecc6376f3"
              ],
              "handle": [
                "461222f5dd690a20651c3d19848015cb0369db3f8e937571ffb775de70750847"
              ],
              "twitter_id": [
                "c623c7e163984493b46c547088542e95d0aaa529bc52bbecce3ff91eb6b7843b"
              ]
            },
            {
              "email": [
                "5bf13d5ad4200407c5bc8b9bb578e425d05ef936fd488e3799a9d0806669223c"
              ],
              "twitter_id": [
                "858cdc7f313f84a3f3c48e9a6323307c1ef1bb7439b8e3623e140454b0fd8fa5",
                "bb074e154657b91d99bd1bb3757409149670e8ae7a0fe9136fae29a26a7881c8"
              ]
            }
          ]
        }
      }
    ]

Esempio di risposta

    {
      "request": {
        "params": {
          "account_id": "18ce54d4x5t",
          "custom_audience_id": "1nmth"
        }
      },
      "data": {
        "success_count": 4,
        "total_count": 4
      }
    }

Autorizzazioni per Audience personalizzate

GET accounts/:account_id/custom_audiences/:custom_audience_id/permissions

Recupera i dettagli di alcune o tutte le autorizzazioni associate alla custom audience specificata. Resource URL https://ads-api.x.com/12/accounts/:account_id/custom_audiences/:custom_audience_id/permissions Parameters

Name	Description
account_id required	L’identificatore dell’account utilizzato. Compare nel percorso della risorsa ed è generalmente un parametro richiesto per tutte le richieste della Advertiser API, ad eccezione di GET accounts. L’account specificato deve essere associato all’utente autenticato. Type: string Example: `18ce54d4x5t`
custom_audience_id required	Riferimento alla custom audience con cui operi nella richiesta. Type: string Example: `1nmth`
count optional	Specifica il numero di record da recuperare per ciascuna richiesta. Type: int Default: `200` Min, Max: `1`, `1000`
cursor optional	Specifica un cursore per ottenere la pagina successiva dei risultati. Vedi Pagination per maggiori informazioni. Type: string Example: `8x7v00oow`
granted_account_ids optional	Limita la risposta ai soli account desiderati specificando un elenco di identificatori separati da virgola. Possono essere forniti fino a 200 ID. Type: string Example: `18ce54aymz3`
sort_by optional	Ordina in base a un attributo supportato, in ordine crescente o decrescente. Vedi Sorting per maggiori informazioni. Type: string Example: `created_at-asc`
custom_audience_permission_ids optional	Limita la risposta alle sole autorizzazioni della custom audience desiderate specificando un elenco di identificatori separati da virgola. Possono essere forniti fino a 200 ID. Type: string Example: `ri`
with_total_count optional	Include l’attributo di risposta `total_count`. Nota: Questo parametro e `cursor` sono mutuamente esclusivi. Nota: Le richieste che includono `total_count` avranno limiti di velocità più bassi, attualmente impostati a 200 per 15 minuti. Type: boolean Default: `false` Possible values: `true`, `false`

Example Request GET https://ads-api.x.com/12/accounts/18ce54d4x5t/custom_audiences/1nmth/permissions Example Response

    {
      "request": {
        "params": {
          "account_id": "18ce54d4x5t",
          "custom_audience_id": "1nmth"
        }
      },
      "next_cursor": null,
      "data": [
        {
          "permission_level": "SOLa_LETTURA",
          "permission_level": "READ_ONLY",
          "id": "ri",
          "created_at": "2017-06-08T23:17:59Z",
          "granted_account_id": "18ce54aymz3",
          "updated_at": "2017-06-08T23:17:59Z",
          "deleted": false
        }
      ]
    }

POST accounts/:account_id/custom_audiences/:custom_audience_id/permissions

Crea un nuovo oggetto autorizzazione che consente di condividere il pubblico specificato con un determinato account. Nota: La creazione o la modifica delle autorizzazioni per un pubblico personalizzato richiede che il pubblico sia di proprietà dell’account che tenta di modificarle. Puoi verificare la proprietà di un pubblico personalizzato consultando l’attributo di risposta is_owner nella risposta per il pubblico in questione. Nota: I pubblici possono essere condivisi solo tra account pubblicitari appartenenti alla stessa azienda oppure se l’account pubblicitario proprietario del pubblico dispone della funzionalità di account SHARE_AUDIENCE_OUTSIDE_BUSINESS. Resource URL https://ads-api.x.com/12/accounts/:account_id/custom_audiences/:custom_audience_id/permissions Parameters

Name	Description
account_id required	Identificatore dell’account utilizzato. Compare nel percorso della risorsa ed è generalmente un parametro obbligatorio per tutte le richieste dell’API Advertiser, esclusa GET accounts. L’account specificato deve essere associato all’utente autenticato. Type: string Example: `18ce54d4x5t`
granted_account_id required	L’account a cui desideri concedere le autorizzazioni sul pubblico personalizzato. Type: string Example: `18ce54aymz3`
permission_level required	Il tipo di accesso al pubblico personalizzato che deve avere `granted_account_id`. Type: enum Possible values: `READ_ONLY`, `READ_WRITE`
custom_audience_id required	Riferimento al pubblico personalizzato oggetto della richiesta. Type: string Example: `2906h`

Example Request

POST https://ads-api.x.com/12/accounts/18ce54d4x5t/custom_audiences/2906h/permissions?granted_account_id=18ce54aymz3&permission_level=READ_ONLY

Esempio di risposta

    {
      "request": {
        "params": {
          "account_id": "18ce54d4x5t",
          "granted_account_id": "18ce54aymz3",
          "permission_level": "READ_ONLY",
          "custom_audience_id": "2906h"
        }
      },
      "data": {
        "custom_audience_id": "2906h",
        "permission_level": "READ_ONLY",
        "id": "14m",
        "created_at": "2017-09-12T23:49:34Z",
        "granted_account_id": "18ce54aymz3",
        "updated_at": "2017-09-12T23:49:34Z",
        "deleted": false
      }
    }

DELETE accounts/:account_id/custom_audiences/:custom_audience_id/permissions/:custom_audience_permission_id

Revoca l’autorizzazione di condivisione della Custom Audience specificata. Nota: La creazione o la modifica delle autorizzazioni per una custom audience richiedono che l’audience sia di proprietà dell’account che tenta di modificarle. È possibile verificare la proprietà di una custom audience consultando l’attributo di risposta is_owner nella risposta per una determinata audience. Una volta revocata, garantiamo che l’account destinatario dell’autorizzazione (granted_account_id) non potrà più targettizzare l’audience nelle campagne future. Le campagne esistenti continueranno a essere eseguite con le audience condivise; le campagne non si interrompono e l’audience non viene rimossa dalla campagna. Non è possibile copiare questa campagna dopo la revoca dell’autorizzazione di condivisione dell’audience. URL risorsa

https://ads-api.x.com/12/accounts/:account_id/custom_audiences/:custom_audience_id/permissions/:custom_audience_permission_id

Parametri

Nome	Descrizione
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`
custom_audience_id obbligatorio	Riferimento alla custom audience con cui operi nella richiesta. Type: string Example: `1nmth`
custom_audience_permission_id obbligatorio	Riferimento all’autorizzazione della custom audience con cui operi nella richiesta. Type: string Example: `ri`

Esempio di richiesta DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/custom_audiences/1nmth/permissions/ri Esempio di risposta

    {
      "request": {
        "params": {
          "account_id": "18ce54d4x5t",
          "custom_audience_permission_id": "ri",
          "custom_audience_id": "1nmth"
        }
      },
      "data": {
        "custom_audience_id": "1nmth",
        "permission_level": "SOLO_LETTURA",
        "id": "ri",
        "created_at": "2017-06-08T23:17:59Z",
        "granted_account_id": "18ce54aymz3",
        "updated_at": "2017-08-30T18:29:35Z",
        "deleted": true
      }
    }

Pubblici personalizzati

GET accounts/:account_id/custom_audiences

Recupera i dettagli di alcune o tutte le Custom Audiences associate all’account corrente. Resource URL https://ads-api.x.com/12/accounts/:account_id/custom_audiences Parameters

Name	Description
account_id required	L’identificatore dell’account utilizzato. Compare nel percorso della risorsa ed è generalmente un parametro richiesto 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`
count optional	Specifica il numero di record da recuperare per ciascuna richiesta distinta. Type: int Default: `200` Min, Max: `1`, `1000`
cursor optional	Specifica un cursore per ottenere la pagina successiva di risultati. Vedi Pagination per maggiori informazioni. Type: string Example: `8x7v00oow`
permission_scope optional	Consente di filtrare la risposta alle liste di tua proprietà o alle liste condivise con te. Per impostazione predefinita, senza specificare questo parametro, vedrai solo le audience di cui sei proprietario. Type: enum Default: `OWNER` Possible values: `OWNER`, `SHARED`
q optional	Una query opzionale per limitare la risorsa in base a `name`. Note: Esegue un confronto per prefisso senza distinzione tra maiuscole e minuscole (case-insensitive). Type: string Min, Max length: `1`, `255`
sort_by optional	Ordina per un attributo supportato in ordine crescente o decrescente. Vedi Sorting per maggiori informazioni. Type: string Example: `created_at-asc`
custom_audience_ids optional	Limita la risposta alle sole Custom Audiences desiderate specificando un elenco di identificatori separati da virgola. È possibile fornire fino a 200 ID. Type: string Example: `1nmth`
with_deleted optional	Includi i risultati eliminati nella richiesta. Type: boolean Default: `false` Possible values: `true`, `false`
with_total_count optional	Includi l’attributo di risposta `total_count`. Note: Questo parametro e `cursor` sono mutuamente esclusivi. Note: Le richieste che includono `total_count` avranno limiti di velocità inferiori, attualmente pari a 200 per 15 minuti. Type: boolean Default: `false` Possible values: `true`, `false`

Example Request GET https://ads-api.x.com/12/accounts/18ce54d4x5t/custom_audiences?custom_audience_ids=1nmth Example Response

    {
      "request": {
        "params": {
          "custom_audience_ids": [
            "1nmth"
          ],
          "account_id": "18ce54d4x5t"
        }
      },
      "next_cursor": null,
      "data": [
        {
          "targetable": true,
          "name": "twurl-using-subshell-for-file",
          "targetable_types": [
            "CRM",
            "EXCLUDED_CRM"
          ],
          "audience_type": "CRM",
          "description": null,
          "permission_level": "READ_WRITE",
          "owner_account_id": "18ce54d4x5t",
          "id": "1nmth",
          "reasons_not_targetable": [],
          "created_at": "2017-01-08T08:19:58Z",
          "updated_at": "2017-01-08T16:21:13Z",
          "partner_source": "OTHER"
          "deleted": false,
          "audience_size": 1470
        }
      ]
    }

GET accounts/:account_id/custom_audiences/:custom_audience_id

Recupera specifiche Custom Audiences associate all’account corrente. Resource URL https://ads-api.x.com/12/accounts/:account_id/custom_audiences/:custom_audience_id Parameters

Name	Description
account_id required	Identificatore dell’account utilizzato. Compare nel percorso della risorsa ed è generalmente un parametro obbligatorio per tutte le richieste dell’Advertiser API, eccetto GET accounts. L’account specificato deve essere associato all’utente autenticato. Type: string Example: `18ce54d4x5t`
custom_audience_id required	Riferimento alla custom audience su cui stai operando nella richiesta. Type: string Example: `2906h`
with_deleted optional	Includi i risultati eliminati nella richiesta. Type: boolean Default: `false` Possible values: `true`, `false`

Example Request GET https://ads-api.x.com/12/accounts/18ce54d4x5t/custom_audiences/2906h Example Response

    {
      "request": {
        "params": {
          "custom_audience_id": "2906h",
          "account_id": "18ce54d4x5t"
        }
      },
      "data": {
        "targetable": false,
        "name": "developers",
        "targetable_types": [
          "CRM",
          "EXCLUDED_CRM"
        ],
        "audience_type": "CRM",
        "description": null,
        "permission_level": "READ_WRITE",
        "owner_account_id": "18ce54d4x5t",
        "id": "2906h",
        "reasons_not_targetable": [],
        "created_at": "2017-08-22T23:34:26Z",
        "updated_at": "2017-08-22T23:34:26Z",
        "partner_source": "OTHER",
        "deleted": false,
        "audience_size": 140321
      }
    }

POST accounts/:account_id/custom_audiences

Crea un nuovo segnaposto di Custom Audience associato all’account corrente. Resource URL https://ads-api.x.com/12/accounts/:account_id/custom_audiences Parameters

Nome	Descrizione
account_id required	L’identificatore dell’account utilizzato. Compare nel percorso della risorsa ed è generalmente un parametro richiesto per tutte le richieste dell’Ads API, ad eccezione di GET accounts. L’account specificato deve essere associato all’utente autenticato. Type: string Example: `18ce54d4x5t`
name required	Il nome visualizzato per questa audience. Deve essere un valore univoco; in caso contrario viene restituito un errore. Type: string Example: `ads api users`
description optional	Una descrizione per questa audience. Type: string Example: `Collection of all users of the Ads API`

Example Request POST https://ads-api.x.com/12/accounts/18ce54d4x5t/custom_audiences?name=developers Example Response

    {
      "data": {
        "targetable": false,
        "name": "developers",
        "targetable_types": [
          "CRM",
          "EXCLUDED_CRM"
        ],
        "audience_type": "CRM",
        "description": null,
        "permission_level": "READ_WRITE",
        "owner_account_id": "18ce54d4x5t",
        "id": "2906h",
        "reasons_not_targetable": [
          "PROCESSING",
          "TOO_SMALL",
        ],
        "created_at": "2017-08-22T23:34:26Z",
        "updated_at": "2017-08-22T23:34:26Z",
        "partner_source": "OTHER",
        "deleted": false,
        "audience_size": null
      },
      "request": {
        "params": {
          "account_id": "18ce54d4x5t",
          "name": "developers"
        }
      }
    }

PUT accounts/:account_id/custom_audiences/:custom_audience_id

Aggiorna la specifica Custom Audience associata all’account corrente. Resource URL https://ads-api.x.com/12/accounts/:account_id/custom_audiences/:custom_audience_id Parameters

Name	Description
account_id required	L’identificatore dell’account utilizzato. Compare nel percorso della risorsa ed è generalmente un parametro obbligatorio per tutte le richieste dell’X Ads API, ad eccezione di GET accounts. L’account specificato deve essere associato all’utente autenticato. Type: string Example: `18ce54d4x5t`
custom_audience_id required	Un riferimento alla Custom Audience con cui operi nella richiesta. Type: string Example: `2906h`
name optional	Il nome visualizzato per questa audience. Deve essere un valore univoco; in caso contrario verrà restituito un errore. Type: string Example: `ads api users`
description optional	Una descrizione per questa audience. Type: string Example: `Collection of all users of the Ads API`

Example Request PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/custom_audiences/2906h?name=developers_changed Example Response

    {
      "data": {
        "targetable": false,
        "name": "developers_changed",
        "targetable_types": [
          "CRM",
          "EXCLUDED_CRM"
        ],
        "audience_type": "CRM",
        "description": null,
        "permission_level": "READ_WRITE",
        "is_owner": true,
        "id": "2906h",
        "reasons_not_targetable": [
          "PROCESSING",
          "TOO_SMALL",
        ],
        "created_at": "2017-08-22T23:34:26Z",
        "updated_at": "2017-08-22T23:34:26Z",
        "partner_source": "OTHER",
        "deleted": false,
        "audience_size": null
      },
      "request": {
        "params": {
          "account_id": "18ce54d4x5t",
          "name": "developers_changed"
        }
      }
    }

POST batch/accounts/:account_id/custom_audiences

Consente la creazione in batch di Custom Audiences. Consulta la pagina Custom Audiences Overview per informazioni sulle audience. Nota: Questo endpoint batch è attualmente in closed beta e disponibile per un numero selezionato di inserzionisti. Durante questo periodo di beta, è possibile creare solo Flexible Audiences basate su mobile custom audiences. Batch Requests

L’attuale dimensione massima del batch è 10.
Tutti i parametri sono inviati nel body della richiesta ed è richiesto un Content-Type pari a application/json.
Le richieste batch vengono elaborate come gruppo: falliscono o riescono insieme e tutte le risposte dell’API, sia in caso di errore sia di successo, mantengono l’ordine degli elementi della richiesta iniziale.

Batch Responses Le risposte dell’API batch restituiscono una raccolta ordinata di elementi. Per il resto, sono identiche nella struttura ai corrispondenti endpoint a singolo elemento. Batch Errors

Gli errori a livello di richiesta (ad es. superamento della dimensione massima del batch) sono mostrati nella risposta sotto l’oggetto errors.
Gli errori a livello di elemento (ad es. parametro obbligatorio mancante) sono mostrati nella risposta sotto l’oggetto operation_errors.

Flexible Audiences

Le Flexible Audiences sono immutabili una volta create.
Le Custom Audiences vengono fornite in una struttura ad albero con combinazioni di logica booleana per creare Flexible Audiences.
È possibile utilizzare fino a 10 nodi foglia di Custom Audiences per creare una Flexible Audience.

Resource URL https://ads-api.x.com/12/batch/accounts/:account_id/custom_audiences Parameters

Nome	Descrizione
account_id obbligatorio	L’identificatore dell’account utilizzato. Compare nel percorso della risorsa ed è generalmente un parametro obbligatorio per tutte le richieste all’API Advertiser, ad eccezione di GET accounts. L’account specificato deve essere associato all’utente autenticato. Tipo: string Esempio: `18ce54d4x5t`
audience_type obbligatorio	Il tipo di audience da creare. Tipo: enum Valori possibili: `FLEXIBLE`, `MOBILE_AUDIENCE`
child_segments obbligatorio	Un array che contiene oggetti che definiscono il sottoinsieme dei membri di una Custom Audience che si desidera raggiungere. Ogni oggetto deve contenere `custom_audience_id`, `frequency`, `frequency_comparator`, `lookback_window`, `negate` e, in alcuni casi, ulteriori `child_segments`. Tipo: array
name obbligatorio	Il nome visualizzato dell’audience. È necessario utilizzare un valore univoco; in caso contrario si verificherà un errore. Tipo: string Esempio: `my_flexible_audience_name`
operation_type obbligatorio	Il tipo di operazione eseguita per elemento. Tipo: enum Valori possibili: `Create`, `Update`, `Delete`
boolean_operator a volte obbligatorio	La relazione logica tra i segmenti figli nell’oggetto padre (contenitore). Obbligatorio se `child_segments` non è vuoto per l’oggetto padre. Tipo: enum Valori possibili: `AND`, `OR`
lookback_window a volte obbligatorio	Un valore intero che specifica l’intervallo di giorni entro il quale l’utente ha eseguito l’azione specifica risultando idoneo per la custom audience indicata. Tipo: int Valori possibili: `1`, `7`, `14`, `30`
segments a volte obbligatorio	Un oggetto contenente `boolean_operator` e `child_segments` che definiscono il sottoinsieme dei membri di una Custom Audience che si desidera raggiungere. Tipo: object
custom_audience_id a volte obbligatorio	L’id della custom audience da utilizzare come segmento figlio. Tipo: string Esempio: `tyfo`
frequency opzionale	Un valore intero che specifica, all’interno della lookback window, la frequenza con cui l’utente ha eseguito l’azione specifica risultando idoneo per la custom audience indicata. Tipo: int Valore predefinito: `1`
frequency_comparator opzionale	Il comparatore per la `frequency` inviata nella richiesta. Nota: Nei valori riportati di seguito, `GTE` indica maggiore o uguale, `LT` minore di, e così via. Tipo: string Valori possibili: `NUM_GTE`, `NUM_GT`, `NUM_EQ`, `NUM_LTE`, `NUM_LT` Valore predefinito: `NUM_GTE`
negate opzionale	Negazione del segmento, che quindi viene escluso dalla combinazione. Tipo: boolean Valore predefinito: `true` Valori possibili: `true`, `false`

Esempio di richiesta POST https://ads-api.x.com/12/batch/accounts/18ce54d4x5t/custom_audiences

    [
      {
        "operation_type":"Create",
        "params":{
          "name":"my_flexible_audience_name",
          "audience_type":"FLEXIBLE",
          "segments":{
            "boolean_operator":"AND",
            "child_segments":[
              {
                "custom_audience_id":"TYIF",
                "frequency":1,
                "frequency_comparator":"NUM_GT",
                "lookback_window":30,
                "negate":true,
                "child_segments":[

                ]
              },
              {
                "boolean_operator":"OR",
                "child_segments":[
                  {
                    "custom_audience_id":"TXR1",
                    "lookback_window":30,
                    "child_segments":[

                    ]
                  },
                  {
                    "custom_audience_id":"TYFO",
                    "frequency":1,
                    "frequency_comparator":"NUM_GT",
                    "lookback_window":30,
                    "negate":true
                    "child_segments":[

                    ]
                  }
                ]
              }
            ]
          }
        }
      }
    ]

Esempio di risposta

    {
      "data": {
        "targetable": false,
        "name": "nome_della_mia_flexible_audience",
        "targetable_types": [
          "FLEXIBLE",
          "EXCLUDED_FLEXIBLE"
        ],
        "audience_type": "FLEXIBLE",
        "id": "13ld7",
        "reasons_not_targetable": [
          "PROCESSING",
          "TOO_SMALL"
        ],
        "metadata": [
          {
            "custom_audience_id": "13ld7",
            "account_id": "qsx3w2",
            "name": "nome_della_mia_flexible_audience",
            "audience_source": "FLEXIBLE_AUDIENCE",
            "upload_status": "UPLOADED",
            "segments": {
              "boolean_operator": "AND",
              "frequency": 1,
              "frequency_comparator": "NUM_GTE",
              "negate": false,
              "child_segments": [
                {
                  "custom_audience_id": "tyif",
                  "lookback_window": 30,
                  "frequency": 1,
                  "frequency_comparator": "NUM_GT",
                  "negate": true,
                  "child_segments": [

                  ]
                },
                {
                  "boolean_operator": "OR",
                  "frequency": 1,
                  "frequency_comparator": "NUM_GTE",
                  "negate": false,
                  "child_segments": [
                    {
                      "custom_audience_id": "txr1",
                      "lookback_window": 30,
                      "frequency": 1,
                      "frequency_comparator": "NUM_GTE",
                      "negate": false,
                      "child_segments": [

                      ]
                    },
                    {
                      "custom_audience_id": "tyfo",
                      "lookback_window": 30,
                      "frequency": 1,
                      "frequency_comparator": "NUM_GT",
                      "negate": true,
                      "child_segments": [

                      ]
                    }
                  ]
                }
              ]
            }
          }
        ],
        "created_at": "2015-11-10T21:26:43Z",
        "updated_at": "2015-11-11T01:11:47Z",
        "partner_source": "OTHER",
        "deleted": false,
        "audience_size": null
      },
      "request": [
        {
          "params": {
            "name": "my_flexible_audience_name",
            "audience_type": "FLEXIBLE",
            "segments": {
              "boolean_operator": "AND",
              "child_segments": [
                {
                  "custom_audience_id": "TYIF",
                  "lookback_window": 30,
                  "frequency": 1,
                  "frequency_comparator": "NUM_GT",
                  "negate": true,
                  "child_segments": [

                  ]
                },
                {
                  "boolean_operator": "OR",
                  "child_segments": [
                    {
                      "custom_audience_id": "TXR1",
                      "lookback_window": 30,
                      "child_segments": [

                      ]
                    },
                    {
                      "custom_audience_id": "TYFO",
                      "lookback_window": 30,
                      "frequency": 1,
                      "frequency_comparator": "NUM_GT",
                      "negate": true,
                      "child_segments": [

                      ]
                    }
                  ]
                }
              ]
            },
            "account_id": "qsx3w2"
          },
          "operation_type": "Create"
        }
      ]
    }

DELETE accounts/:account_id/custom_audiences/:custom_audience_id

Elimina la Custom Audience specificata appartenente all’account corrente. Resource URL https://ads-api.x.com/12/accounts/:account_id/custom_audiences/:custom_audience_id Parameters

Name	Description
account_id required	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`
custom_audience_id required	Riferimento alla Custom Audience con cui operi nella richiesta. Type: string Example: `2906h`

Example Request DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/custom_audiences/2906h Example Response

    {
      "data": {
        "targetable": false,
        "name": "developers",
        "targetable_types": [
          "CRM",
          "EXCLUDED_CRM"
        ],
        "audience_type": "CRM",
        "description": null,
        "permission_level": "READ_WRITE",
        "owner_account_id": "18ce54d4x5t",
        "id": "2906h",
        "reasons_not_targetable": [
          "TOO_SMALL"
        ],
        "created_at": "2017-08-22T23:34:26Z",
        "updated_at": "2017-08-30T18:09:00Z",
        "partner_source": "OTHER",
        "deleted": true,
        "audience_size": null
      },
      "request": {
        "params": {
          "custom_audience_id": "2906h",
          "account_id": "18ce54d4x5t"
        }
      }
    }

Liste di non contatto

GET accounts/:account_id/do_not_reach_lists

Recupera i dettagli di una o di tutte le Do Not Reach List associate all’account corrente. Nota: Un account_id può avere al massimo una Do Not Reach List Resource URL https://ads-api.x.com/12/accounts/:account_id/do_not_reach_lists Parameters

Nome	Descrizione
account_id obbligatorio	L’identificatore dell’account utilizzato. Compare nel percorso della risorsa ed è generalmente 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`
with_deleted opzionale	Includi i risultati eliminati nella richiesta. Type: boolean Default: `false` Possible values: `true`, `false`

Example Request GET https://ads-api.x.com/12/accounts/18ce54bgxky/do_not_reach_lists Example Response

    {
      "request": {
        "params": {
          "account_id": "18ce54bgxky"
        }
      },
      "next_cursor": null,
      "data": [
        {
          "targetable": false,
          "name": "Lista da non contattare",
          "description": "test DNRL",
          "id": "4kzrq",
          "reasons_not_targetable": [
            "TOO_SMALL"
          ],
          "created_at": "2021-10-28T22:09:29Z",
          "list_size": null,
          "updated_at": "2021-11-04T03:33:06Z",
          "deleted": false
        }
      ]
    }

POST accounts/:account_id/do_not_reach_lists

Crea una nuova Do Not Reach List associata all’account corrente. Nota: Un account_id può avere al massimo una Do Not Reach List URL della risorsa https://ads-api.x.com/12/accounts/:account_id/do_not_reach_lists Parametri

Name	Description
account_id required	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`
description optional	Una descrizione per questo segmento di pubblico. Type: string Example: `A list of users to exclude`

Esempio di richiesta POST https://ads-api.x.com/12/accounts/18ce54bgxky/do_not_reach_lists?description=A list of users to exclude Esempio di risposta

    {
      "request": {
        "params": {
          "description": "Un elenco di utenti da escludere",
          "account_id": "18ce54bgxky"
        }
      },
      "data": {
        "targetable": false,
        "name": "Elenco da non contattare",
        "description": "Un elenco di utenti da escludere"
        "id": "4ofrq",
        "reasons_not_targetable": [
          "PROCESSING",
          "TOO_SMALL"
        ],
        "created_at": "2022-02-08T23:02:48Z",
        "list_size": null,
        "updated_at": "2022-02-08T23:02:48Z",
        "deleted": false
      }
    }

POST batch/accounts/:account_id/do_not_reach_lists/:do_not_reach_list_id/users

Questo endpoint consente di aggiungere, aggiornare e rimuovere utenti da un determinato do_not_reach_list_id. Questo endpoint accetta solo email come tipo valido di identificatore utente. Tutti i dati forniti nel campo emails della richiesta devono essere sottoposti a hash utilizzando SHA256 e normalizzati. Note

Un account_id può avere al massimo una Do Not Reach List
Gli utenti aggiunti a questo elenco devono avere un timestamp expires_at impostato a meno di 13 mesi rispetto al timestamp corrente
La Do Not Reach List API non accetta un timestamp effective_at e per impostazione predefinita utilizza il timestamp corrente
La Do Not Reach List non rimuove gli utenti da nessuna delle audience personalizzate dell’account, ma funge da targeting di esclusione per tutte le campagne erogate per l’account

Richieste batch

L’attuale dimensione massima del batch è 2500 per questo endpoint. La dimensione del batch è determinata dal numero di operazioni (Update/Delete) per richiesta. Ad esempio, più di 2500 oggetti operazione ({"operation_type": "Update/Delete", [..] }) in un unico array determinano un errore.
La dimensione massima del body della richiesta POST che questo endpoint può accettare è 5,000,000 byte.
I limiti di velocità per questo endpoint sono 1500 per finestra di 1 minuto
Tutti i parametri sono inviati nel body della richiesta ed è richiesto un Content-Type di application/json.
Le richieste batch falliscono o riescono insieme come gruppo e tutte le risposte API, sia di errore sia di successo, preservano l’ordine degli elementi della richiesta iniziale.

Risposte batch La risposta restituita dalla X Ads API contiene due campi, success_count e total_count. Questi valori devono sempre essere uguali e rappresentano il conteggio dei record nella richiesta che sono stati elaborati dal backend. Una situazione in cui il numero di record inviati nel body della richiesta non è uguale a success_count e total_count deve essere trattata come una condizione di errore, che richiede un nuovo tentativo. Errori batch

Gli errori a livello di richiesta (ad es. dimensione massima del batch superata) sono riportati nella risposta sotto l’oggetto errors.
Gli errori a livello di elemento (ad es. parametri obbligatori mancanti) sono riportati nella risposta sotto l’oggetto operation_errors.
L’indice dell’errore in operation_errors si riferisce all’indice dell’elemento di input, con il corrispondente messaggio di errore

URL della risorsa https://ads-api.x.com/12/batch/accounts/:account_id/do_not_reach_lists/:do_not_reach_list_id/users Parametri

Name	Description
account_id required	L’identificatore dell’account utilizzato. Compare all’interno del percorso della risorsa ed è generalmente un parametro obbligatorio per tutte le richieste dell’Ads API, esclusa GET accounts. L’account specificato deve essere associato all’utente autenticato. Type: string Example: `18ce54d4x5t`
do_not_reach_list_id required	Un riferimento alla Do Not Reach List con cui si opera nella richiesta Type: string Example: `2906h`
operation_type required	Il tipo di operazione per il gruppo `users` che viene eseguita. Type: enum Possible values: `Update`, `Delete`
params required	Un oggetto JSON contenente l’array `emails` e il timestamp `expires_at`. Type: JSON
users required	Un array di oggetti JSON contenente tutti i parametri per un singolo utente. Type: JSON
expires_at optional	L’ora UTC alla quale le associazioni dell’utente dovrebbero scadere. L’ora specificata deve essere successiva al valore del timestamp corrente. Espressa in ISO 8601. Predefinito a 13 mesi dal timestamp corrente. Type: string Example: `2017-07-05T07:00:00Z`

Dato l’approccio multi-chiave all’oggetto users, ogni elemento di questo oggetto è documentato di seguito:

Nome	Descrizione
email facoltativo	Indirizzo email dell’utente (uno o più). type: Array[String]
phone_number facoltativo	Numero di telefono dell’utente (uno o più). type: Array[String]

Esempio di richiesta

`POST https://ads-api.x.com/12/batch/accounts/18ce54bgxky/do_not_reach_lists/4kzro/users`

    [
      {
        "operation_type": "Update",
        "params": {
          "expires_at": "2023-01-22T00:00:00Z",
          "users": [
            {
              "email": [
                "FEAD76F6ADF99FFFB997AA4E3C8AD38FF531BC4C956DBD03CD0163F744D8AABC"
              ],
              "phone_number": [
                "CCABF1B62A202E0FE28BC6C014983C89A65451DD4482BD66A0ADB65366F38A9A"
              ]
            },
            {
              "email": [
                "FEAD76F6ADF99FFFB997AA4E3C8AD38FF531BC4C956DBD03CD0163F744D8AABA"
              ],
              "phone_number": [
                "CCABF1B62A202E0FE28BC6C014983C89A65451DD4482BD66A0ADB65366F38A9E"
              ]
            }
          ]
        }
      }
    ]

Esempio di risposta

    {
      "data": [
        {
          "success_count": 2,
          "total_count": 2
        }
      ],
      "request": [
        {
          "params": {
            "do_not_reach_list_id": "4ofrq",
            "expires_at": "2023-01-22T00:00:00Z",
            "account_id": "18ce54bgxky"
          },
          "operation_type": "Update"
        }
      ]
    }

DELETE accounts/:account_id/do_not_reach_lists/:do_not_reach_list_id

Elimina la Do Not Reach List specificata appartenente all’account corrente. URL della risorsa https://ads-api.x.com/12/accounts/:account_id/do_not_reach_lists/:do_not_reach_list_id Parametri Nessuno Esempio di richiesta DELETE https://ads-api.x.com/12/accounts/18ce54bgxky/do_not_reach_lists/4ofrp Esempio di risposta

    {
      "request": {
        "params": {
          "do_not_reach_list_id": "4ofrp",
          "account_id": "18ce54bgxky"
        }
      },
      "data": {
        "targetable": false,
        "name": "Elenco da non contattare",
        "description": null,
        "id": "4ofrp",
        "reasons_not_targetable": [
          "IN_ELABORAZIONE",
          "TROPPO PICCOLO"
        ],
        "created_at": "2022-02-08T23:02:07Z",
        "list_size": null,
        "updated_at": "2022-02-08T23:02:21Z",
        "deleted": true
      }
    }

X Ads API

Fondamenti

Risorse

Misurazione

​Pubblici personalizzati

​Panoramica

​Domande frequenti sul pubblico

​CRM

​Requisiti per la corrispondenza degli ID partner

​Requisiti standard di corrispondenza

​Denominazione dei file e operazioni per le Liste di segmenti personalizzati

​Creazione e aggiornamento delle audience

​Istruzioni per l’hashing

​Normalizzazione dell’e-mail

​Normalizzazione degli ID del dispositivo

​Normalizzazione dell’ID utente di X

​Integrazione ID Sync

​URL del pixel

​Parametri del pixel

​Pixel di sincronizzazione ID:

​Dati utente per Custom Audiences

​Pubblici personalizzati: Web

​Integrazione con l’API Audience

​Panoramica

​Crea una nuova Custom Audience

​Aggiungere utenti a un pubblico

​Rimuovere utenti da un’audience

​Utenti con opt-out

​Riferimento all’API

​Approfondimenti sulle parole chiave

​GET insights/keywords/search

​Autorizzazioni per i Pubblici Personalizzati

​GET accounts/:account_id/tailored_audiences/:tailored_audience_id/permissions

​POST accounts/:account_id/tailored_audiences/:tailored_audience_id/permissions

​DELETE accounts/:account_id/tailored_audiences/:tailored_audience_id/permissions/:tailored_audience_permission_id

​Pubblici di destinazione

​GET accounts/:account_id/custom_audiences/:custom_audience_id/targeted

​Utenti delle Custom Audience

​POST accounts/:account_id/custom_audiences/:custom_audience_id/users

​URL della risorsa

​Parametri

​Esempio di richiesta

​Esempio di risposta

​Autorizzazioni per Audience personalizzate

​GET accounts/:account_id/custom_audiences/:custom_audience_id/permissions

​POST accounts/:account_id/custom_audiences/:custom_audience_id/permissions

​DELETE accounts/:account_id/custom_audiences/:custom_audience_id/permissions/:custom_audience_permission_id

​Pubblici personalizzati

​GET accounts/:account_id/custom_audiences

​GET accounts/:account_id/custom_audiences/:custom_audience_id

​POST accounts/:account_id/custom_audiences

​PUT accounts/:account_id/custom_audiences/:custom_audience_id

​POST batch/accounts/:account_id/custom_audiences

​DELETE accounts/:account_id/custom_audiences/:custom_audience_id

​Liste di non contatto

​GET accounts/:account_id/do_not_reach_lists

​POST accounts/:account_id/do_not_reach_lists

​POST batch/accounts/:account_id/do_not_reach_lists/:do_not_reach_list_id/users

​DELETE accounts/:account_id/do_not_reach_lists/:do_not_reach_list_id

Pubblici personalizzati

Panoramica

Domande frequenti sul pubblico

CRM

Requisiti per la corrispondenza degli ID partner

Requisiti standard di corrispondenza

Denominazione dei file e operazioni per le Liste di segmenti personalizzati

Creazione e aggiornamento delle audience

Istruzioni per l’hashing

Normalizzazione dell’e-mail

Normalizzazione degli ID del dispositivo

Normalizzazione dell’ID utente di X

Integrazione ID Sync

URL del pixel

Parametri del pixel

Pixel di sincronizzazione ID:

Dati utente per Custom Audiences

Pubblici personalizzati: Web

Integrazione con l’API Audience

Panoramica

Crea una nuova Custom Audience

Aggiungere utenti a un pubblico

Rimuovere utenti da un’audience

Utenti con opt-out

Riferimento all’API

Approfondimenti sulle parole chiave

GET insights/keywords/search

Autorizzazioni per i Pubblici Personalizzati

GET accounts/:account_id/tailored_audiences/:tailored_audience_id/permissions

POST accounts/:account_id/tailored_audiences/:tailored_audience_id/permissions

DELETE accounts/:account_id/tailored_audiences/:tailored_audience_id/permissions/:tailored_audience_permission_id

Pubblici di destinazione

GET accounts/:account_id/custom_audiences/:custom_audience_id/targeted

Utenti delle Custom Audience

POST accounts/:account_id/custom_audiences/:custom_audience_id/users

URL della risorsa

Parametri

Esempio di richiesta

Esempio di risposta

Autorizzazioni per Audience personalizzate

GET accounts/:account_id/custom_audiences/:custom_audience_id/permissions

POST accounts/:account_id/custom_audiences/:custom_audience_id/permissions

DELETE accounts/:account_id/custom_audiences/:custom_audience_id/permissions/:custom_audience_permission_id

Pubblici personalizzati

GET accounts/:account_id/custom_audiences

GET accounts/:account_id/custom_audiences/:custom_audience_id

POST accounts/:account_id/custom_audiences

PUT accounts/:account_id/custom_audiences/:custom_audience_id

POST batch/accounts/:account_id/custom_audiences

DELETE accounts/:account_id/custom_audiences/:custom_audience_id

Liste di non contatto

GET accounts/:account_id/do_not_reach_lists

POST accounts/:account_id/do_not_reach_lists

POST batch/accounts/:account_id/do_not_reach_lists/:do_not_reach_list_id/users

DELETE accounts/:account_id/do_not_reach_lists/:do_not_reach_list_id