ads.txt e sellers.json: cosa sono e a cosa servono

Ogni tanto un partner di domanda chiede di aggiungere una riga al tuo ads.txt, e nessuno spiega che cos'è quel file né perché esiste. Ecco il problema che è nato per risolvere, come si legge ciò che contiene, in cosa differisce da sellers.json e cosa si rompe quando è sbagliato.

La frode che ads.txt è nato per fermare

Quando un inserzionista compra un'impressione in un'asta programmatica non vede il tuo sito. Vede una richiesta di offerta: un pacchetto di dati che, tra le altre cose, indica da quale dominio arriva quello spazio pubblicitario. Per anni nessuno verificava se fosse vero: bastava che un intermediario dichiarasse un dominio altrui per vendere inventario che non era suo e incassarne il ricavo. Il settore lo chiama domain spoofing, falsificazione del dominio.

Il danno era doppio: l'inserzionista pagava prezzi da testata di qualità per impressioni servite da tutt'altra parte, e la testata impersonata non vedeva un centesimo. Quando è diventato evidente che c'era più inventario in vendita che pagine viste reali, è servito un modo perché ogni publisher dichiarasse pubblicamente chi può vendere a suo nome. Quel modo è ads.txt.

ads.txt non impedisce a nessuno di mentire sul tuo inventario. Quello che fa è trasformare quella bugia in qualcosa di verificabile in un secondo.

Che cos'è esattamente ads.txt

La sigla viene da Authorized Digital Sellers: venditori digitali autorizzati. È un file di testo semplice collocato nella radice del tuo dominio e servito a quell'indirizzo esatto: esempio-notizie.com/ads.txt. Non in una sottocartella né in un pannello di amministrazione, e senza dipendere dal CMS. È un file che si scarica e si legge.

Dentro c'è una riga per ogni piattaforma autorizzata a vendere il tuo inventario. È pubblico di proposito: chiunque può aprirlo nel browser. Gli acquirenti lo scansionano con dei bot e costruiscono la propria lista di chi può vendere che cosa. Quando arriva loro un'offerta che dice di provenire dal tuo dominio tramite un intermediario che non è nel tuo file, la scartano.

Conviene capire cosa non è. Il file non concede né toglie permessi tecnici: nulla smette di funzionare perché lo hai modificato. È una dichiarazione, e ciò che la firma è l'essere pubblicata sul tuo dominio, che è quello che un terzo non può falsificare.

Come si legge una riga di ads.txt

Una riga tipica ha questo aspetto: ssp-esempio.com, 12345, DIRECT, f1a2b3c4d5e6f7a8. Sono quattro campi separati da virgole, e ciascuno risponde a una domanda diversa.

• Il dominio del sistema pubblicitario. Non il nome commerciale della SSP, ma il dominio dove avviene l'acquisto; è sempre la piattaforma a indicarlo, perché non sempre coincide con il suo sito istituzionale.
• L'ID del publisher. Il tuo identificativo di account in quella piattaforma: è ciò che separa il tuo inventario da quello di qualsiasi altra testata che usi la stessa SSP.
• La relazione: DIRECT o RESELLER. È obbligatoria e dice se quella piattaforma lavora con un account tuo o rivende il tuo inventario tramite uno suo.
• L'ID di certificazione, facoltativo. Identifica quell'azienda nel registro del TAG (Trustworthy Accountability Group) e conferma che il dominio dichiarato è di chi dice di essere.

L'ordine delle righe non significa nulla: è un elenco, non una cascata. Quelle che iniziano con il cancelletto sono commenti e vengono ignorate. Esistono inoltre righe di variabile, come CONTACT= per lasciare un indirizzo email di riferimento o OWNERDOMAIN= per dichiarare il vero proprietario del sito.

DIRECT e RESELLER: cosa li distingue

DIRECT significa che hai un rapporto contrattuale diretto con quella piattaforma e che l'account indicato nel secondo campo è tuo. RESELLER significa che hai autorizzato quella piattaforma a rivendere il tuo inventario anche se l'account non è intestato a te. È il caso normale quando lavori con un partner di monetizzazione che ti collega alla domanda tramite i propri account su diverse SSP.

La distinzione conta per l'acquirente, perché una catena con più rivenditori impilati ha più mani lungo il percorso e più commissioni prima che il denaro arrivi a te. E non conviene truccarla: segnare come DIRECT qualcosa che è RESELLER non migliora niente, perché quell'ID viene incrociato con il sellers.json della piattaforma e la contraddizione salta fuori da sola.

sellers.json: l'altra metà della catena

ads.txt guarda verso l'esterno a partire dalla testata: dice chi autorizzo a vendere. sellers.json guarda nella direzione opposta, dalla piattaforma: dice chi rappresento. Ogni SSP o exchange lo pubblica nella radice del proprio dominio, su ssp-esempio.com/sellers.json, ed è la piattaforma a mantenerlo. Tu non lo modifichi, ma puoi leggerlo, e vale la pena farlo.

Il formato è JSON, non testo semplice. Ogni voce collega un identificativo di venditore a chi è davvero: nome, dominio e tipo. Il tipo può essere PUBLISHER, se l'account è del proprietario dell'inventario; INTERMEDIARY, se rivende quello di altri; oppure BOTH. Esistono anche voci contrassegnate come riservate, senza nome né dominio visibili: è consentito, ed è il punto in cui la catena smette di poter essere verificata.

I due file si leggono insieme, ed è lì che sta il senso di tutto. Il tuo ads.txt dice che ssp-esempio.com può vendere per te con l'ID 12345; il sellers.json di ssp-esempio.com deve dire che quell'ID corrisponde al tuo dominio. Se coincidono, l'acquirente ricostruisce l'intera catena dall'inserzionista fino a te. Se non coincidono, l'offerta perde valore o viene scartata.

Cosa succede quando manca o è sbagliato

• Il file non c'è. Gli acquirenti che accettano solo inventario autorizzato smettono di fare offerte su di te: l'inventario non sparisce, ma resta a competere per i budget più economici.
• Manca la riga di un partner nuovo. La domanda che collega viene scartata perché non trova riscontro nel tuo file, e si vede come un fill rate basso senza causa apparente.
• C'è un errore di sintassi. Una virgola di troppo invalida quella riga intera; il resto del file continua a essere letto. È il guasto più silenzioso di tutti.
• Il file non arriva. Restituisce un 404, reindirizza a un altro dominio oppure lo blocca un firewall quando arriva il crawler. Per l'acquirente equivale a non esistere.
• Restano righe vecchie. Un partner con cui hai smesso di lavorare un anno fa resta autorizzato a vendere a tuo nome finché la sua riga è lì.

Nessuno di questi casi produce un errore visibile. Il sito carica uguale, gli annunci si vedono uguale e non scatta nessun avviso. L'unico posto in cui il problema emerge sono i ricavi, diverse settimane dopo.

app-ads.txt: lo stesso per le applicazioni

Un'applicazione per cellulare o per TV connessa non ha una radice di dominio in cui mettere un file, quindi il meccanismo fa un giro: il crawler entra nella scheda dell'app nello store, legge il sito dichiarato dallo sviluppatore e cerca il file nella radice di quel dominio: esempio-app.com/app-ads.txt. Il formato delle righe è identico.

Per questo il guasto più frequente non sta nel contenuto del file ma nel percorso che porta a esso: la scheda dello store punta a un dominio che non lo serve, oppure non ne dichiara nessuno. E se hai sia il sito sia l'applicazione, sono due file distinti con due elenchi propri; ads.txt non copre l'app e app-ads.txt non copre il sito.

Perché vanno tenuti aggiornati

Non è una cosa che si scrive una volta e si dimentica. Ogni partner che entra è una riga nuova e ognuno che esce è una riga di troppo. C'è poi uno sfasamento: gli acquirenti non rileggono il tuo file ogni giorno, quindi tra il pubblicare una riga e il vederla fare effetto possono passare diversi giorni. La riga si aggiunge prima che il partner cominci a vendere, non dopo.

Quando la monetizzazione passa da un partner, è lui a dirti quali righe aggiungere. In ADEQ Media diamo alle testate con cui lavoriamo le righe da inserire nel loro ads.txt e controlliamo che siano corrette; la testata le carica sul proprio dominio, e il nostro sellers.json lo manteniamo noi. Così collegare domanda premium tramite Header Bidding con SmartTag, o attivare campagne dirette, non dipende dall'indovinare cosa scrivere in un file. Da parte tua servono un Header Script e il tuo ads.txt, con un'implementazione in 48 h.

Comunque, c'è un controllo di mezzo minuto che conviene fare ogni tanto: aprire tuodominio.com/ads.txt nel browser e guardare cosa compare. Se quell'elenco non somiglia a quello di chi vende il tuo inventario oggi, ecco il lavoro da fare.

Come funziona con ADEQ Media

In pratica non devi scoprire quali righe ti servono. Ti diamo quelle che vanno nel tuo ads.txt e tu le carichi: è uno dei tre passi dell'integrazione, insieme all'Header Script e alla configurazione che facciamo noi.

L'account manager verifica che sia corretto prima che inizi a contare, che è proprio dove queste cose tendono a fallire: una riga copiata male non dà errore, semplicemente fa sì che gli acquirenti scartino le tue impressioni senza che tu te ne accorga.

Il nostro sellers.json lo pubblichiamo e lo manteniamo noi. Il resto del processo è in le domande frequenti.