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, quell'elenco lo mantiene lui. In ADEQ Media gestiamo l'ads.txt e il sellers.json delle testate con cui lavoriamo, così che collegare domanda premium tramite Header Bidding con SmartTag, o attivare campagne dirette, non dipenda dal fatto che qualcuno si ricordi di modificare un file. Con un solo Header Script e un'implementazione in 48 h, quella parte è risolta dal primo giorno.

Anche delegandolo, 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.