Guida all'integrazione dell'API Topics

Scopri come utilizzare l'API Topics per soddisfare casi d'uso specifici di ad tech.

Prima di iniziare

Il primo passaggio consiste nell'acquisire familiarità con l'API e i servizi Topics.

  1. Esamina la documentazione per gli sviluppatori:
    1. Inizia a leggere la panoramica per acquisire dimestichezza con l'API Topics e le sue funzionalità.
    2. Guarda la procedura dettagliata della demo di Topics (video).
    3. Prova le demo dell'intestazione Topics e dell'API JavaScript.
    4. Crea un fork delle demo (entrambe forniscono link al proprio codice) ed eseguile dal tuo sito.
    5. Leggi la spiegazione dell'API per comprendere meglio i dettagli.
  2. Controlla lo stato dell'implementazione e la sequenza temporale dell'API Topics.
  3. Comprendi il ruolo dell'API nel supporto della pertinenza degli annunci in un futuro senza cookie.
  4. Per ricevere notifiche sulle modifiche dello stato nell'API, iscriviti alla mailing list per gli sviluppatori e continua a seguirci per ricevere gli ultimi aggiornamenti di Topics.
  5. Resta al passo con le ultime notizie sull'API Topics.
  6. Partecipa alla conversazione tramite i problemi di GitHub o le chiamate W3C.
  7. Se trovi termini sconosciuti, consulta il glossario di Privacy Sandbox.
  8. Per ulteriori informazioni sui concetti di base di Chrome, ad esempio sui flag di Chrome, consulta i brevi video e gli articoli disponibili all'indirizzo goo.gle/cc.

Crea e testa localmente

Questa sezione descrive come provare l'API Topics come singolo sviluppatore.

  1. Test e deployment in locale (tempo stimato: circa 2 giorni)
    1. Attiva l'API con il browser locale dalla riga di comando con i flag di funzionalità. Testa le demo sull'intestazione e sull'API JavaScript per vedere Topics in azione (video della procedura dettagliata).
    2. Esegui la Colab Topics per testare l'inferenza dell'argomento utilizzando il modello di machine learning di Topics.

Attivare Topics nel browser

Per abilitare l'API Topics nella tua istanza di Chrome per i test locali, hai due opzioni:

  1. Apri chrome://flags/#privacy-sandbox-ads-apis e attiva le API Privacy Sandbox.
  2. (Consigliato) Esegui Chrome dalla riga di comando con i flag di Chromium utilizzando parametri specifici dell'API Topics per eseguire la configurazione in base alle esigenze.
Attiva le API Privacy Sandbox all'indirizzo chrome://flags/#privacy-sandbox-ads-apis.
Abilitazione delle API Privacy Sandbox.

Hai un controllo più granulare sulle funzionalità di Topics eseguendo Chrome dalla riga di comando. Ad esempio, puoi impostare le epoche di Topics (l'intervallo di tempo utilizzato dall'API per calcolare gli interessi degli utenti) e configurare il comportamento dell'API in base alle tue esigenze.

È importante ricordare che se l'opzione chrome://flags/#privacy-sandbox-ads-apis è abilitata, l'impostazione dell'epoca della riga di comando verrà ignorata e verrà ripristinata al valore predefinito (attualmente una settimana).

Visualizza l'anteprima dei meccanismi dell'API Topics

Puoi ottenere visibilità sulle meccaniche sottostanti dell'API Topics in locale utilizzando gli strumenti chrome://topics-internals.

Dai un'occhiata all'interno dell'API Topics all'indirizzo chrome://topics-internals.
La scheda Stato Argomenti di chrome://topics-internals strumenti.

Utilizza lo strumento Internals API Topics per testare a livello locale il classificatore in base ai siti che visiti.

Con questo strumento, puoi esaminare:

  • Stato argomenti: mostra gli argomenti osservati per l'utente corrente.
  • Categoria di classificazione: visualizza l'anteprima degli argomenti dedotti per i nomi host.
  • Funzionalità e parametri: visualizza i valori dei parametri API per verificare che i flag funzionalità funzionino come previsto.

Scopri come eseguire il debug di Topics con lo strumento Internals.

Come l'API restituisce gli argomenti

Se Chrome non dispone di un numero sufficiente di argomenti osservati per creare i cinque argomenti principali per un'epoca (una settimana), l'API Topics aggiungerà argomenti casuali per completare i primi cinque. La colonna Argomenti interni intitolata Reale o Casuale indica se l'argomento in questione si basava su un'osservazione reale o su un'ulteriore "spaziatura" casuale per completare i primi cinque. Scopri di più su questo meccanismo nel spiegatore.

L'argomento selezionato per ogni epoca viene selezionato in modo casuale tra i cinque argomenti più apprezzati dall'utente nel periodo di tempo in questione. Se durante questo periodo non è stato osservato un numero sufficiente di argomenti, ne verranno scelti altri a caso per raggiungere un totale di cinque. Questi argomenti selezionati casualmente sono soggetti a filtro.

Per migliorare ulteriormente la privacy e garantire che tutti gli argomenti possano essere rappresentati, esiste una probabilità del 5% che l'argomento selezionato per un'epoca sia selezionato casualmente da tutti gli argomenti, invece di essere scelto tra gli argomenti osservati. Come nel caso sopra in cui è stato osservato un numero insufficiente di argomenti, questi argomenti selezionati casualmente non vengono filtrati.

Per saperne di più su come vengono selezionati gli argomenti, consulta Classificazione degli argomenti.

Suggerimenti principali

  1. Assicurati di chiudere (e interrompere) tutti i processi di Chrome prima di avviare il nuovo processo utilizzando i flag.
  2. Se esegui i test nel tuo ambiente locale, devi disattivare chrome://flags/#privacy-sandbox-ads-apis, poiché sostituisce le impostazioni della riga di comando e vengono ripristinati i valori predefiniti.
  3. Utilizza la pagina di debug per comprendere il funzionamento locale di Topics.
  4. In caso di domande, consulta la sezione Problemi di GitHub nel testo esplicativo.
  5. Se l'API non funziona come previsto, prova i nostri suggerimenti per la risoluzione dei problemi.

Pianifica l'implementazione dell'MVP

L'API Topics consente di accedere ad argomenti di interesse osservati per un utente, senza dover ricorrere al monitoraggio dei siti visitati dall'utente o all'esposizione della sua cronologia di navigazione.

Il caller dell'API Topics è l'entità che chiama il metodo JavaScript document.browsingTopics() o che osserva e accede agli argomenti utilizzando le intestazioni delle richieste HTTP. Il tuo codice e il dominio eTLD+1 da cui viene chiamato, in questo caso, sono il chiamante. Quando chiami l'API Topics, indichi al browser dell'utente di osservare gli argomenti di interesse quando l'utente visita un sito web. Questa visita viene quindi considerata nel calcolo degli argomenti per il periodo successivo.

L'API Topics è progettata per filtrare i risultati per chiamante o per-eTLD+1 del contesto di chiamata. In altre parole, l'origine dell'iframe (se si utilizza l'API JavaScript) o l'URL della richiesta di recupero (se si utilizzano le intestazioni) viene considerata il chiamante e gli argomenti vengono calcolati in base a quel chiamante.

Il seguente diagramma illustra questo approccio:

I passaggi che l'API Topics esegue quando gli utenti visitano siti che utilizzano l'API.
In che modo l'API osserva e accede agli argomenti.

In questo diagramma:

  1. Un utente apre Chrome e visita più siti web (customerA.example, customerB.example.br e così via) che includono l'iframe della tua tecnologia pubblicitaria (fonte: iframe.adtech.example) o le intestazioni di trasmissione della chiamata di recupero.
    • Chrome registrerà gli argomenti di interesse di questo utente.
  2. Dopo una navigazione di sette giorni, con argomenti di interesse osservati dall'API Topics, lo stesso utente sullo stesso dispositivo visita un sito web di destinazione (publisher-e.example). L'API Topics restituisce un elenco di argomenti e, in questo esempio specifico, verrà restituito un argomento calcolato dalla settimana precedente di osservazioni di questo utente.
    • Solo i browser degli utenti che hanno visitato i siti osservati da adtech.example nel passaggio 1 restituiranno risultati relativi agli argomenti nel passaggio 2 (questo viene chiamato filtro delle osservazioni: non puoi visualizzare gli argomenti degli utenti che non hai mai visto prima).
  3. Con questo elenco (di un argomento per ora) puoi chiamare la tua API di backend (ads.adtech.example/topics-backend) per utilizzare i dati degli argomenti come parte del tuo set di dati contestuale.
  4. Ora, in base al vostro caso d'uso, potete creare un'esperienza più personalizzata per l'utente accedendo agli argomenti di suo interesse che avete osservato nelle ultime settimane.

Chiama l'API Topics

Esistono due modi per osservare e accedere agli argomenti per un utente. Puoi utilizzare la modalità

  • L'API JavaScript dall'interno di un iframe:
    • Aggiunta di un iframe sui siti web di destinazione (siti web del publisher) contenente il codice JavaScript che chiama l'API Topics utilizzando document.browsingTopics().
  • Opzione per le intestazioni:
    • Recupero (consigliato) o XHR (sconsigliato ed è stato disponibile solo durante la prova dell'origine completata):
      • Puoi accedere agli argomenti dall'intestazione Sec-Browsing-Topics nelle richieste al backend di tecnologia pubblicitaria. Questa è l'opzione più efficiente (bassa latenza per osservare gli argomenti di un utente specifico).
    • Utilizzo di un tag iframe con l'attributo browsingtopics:
      • Puoi aggiungere un iframe con un attributo browsingtopics e Chrome includerà gli argomenti (osservati per l'eTLD+1 dell'iframe) nell'intestazione Sec-Browsing-Topics della richiesta per l'iframe.

Implementazione con JavaScript e iframe

Ti consigliamo di creare un fork della demo dell'API JavaScript Topics o della demo dell'intestazione e utilizzarne una come punto di partenza per il tuo codice.

Puoi includere un elemento <iframe> nel codice HTML o aggiungere un iframe in modo dinamico con JavaScript. Un modo per creare dinamicamente un iframe è utilizzare il seguente codice JavaScript:

const iframe = document.createElement('iframe');
iframe.setAttribute('src', 'https://...');
document.body.appendChild(iframe);

Controlla se l'API Topics è supportata e disponibile su questo dispositivo tramite il rilevamento delle funzionalità:

'browsingTopics' in document && document.featurePolicy.allowsFeature('browsing-topics') ?
  console.log('document.browsingTopics() is supported on this page') :
  console.log('document.browsingTopics() is not supported on this page');

Chiama l'API Topics dall'interno dell'iframe:

const topics = await document.browsingTopics();

Dovresti ricevere un elenco degli argomenti osservati per questo utente nelle ultime tre settimane. Ricorda che questo elenco può essere vuoto o includere 1, 2 o 3 argomenti, relativi alle ultime tre settimane.

Ecco un esempio di ciò che l'API restituisce:

[{'configVersion': String, 
  'modelVersion': String, 
  'taxonomyVersion': String, 
  'topic': Number, 
  'version': String}]
  • configVersion: una stringa che identifica la configurazione corrente.
  • modelVersion: una stringa che identifica il classificatore di machine learning utilizzato per dedurre gli argomenti.
  • taxonomyVersion: una stringa che identifica l'insieme di argomenti attualmente in uso dal browser.
  • topic: un numero che identifica l'argomento nella tassonomia.
  • version: una stringa che combina configVersion e modelVersion.

Leggi ulteriori informazioni su questa implementazione.

Implementazione con intestazioni HTTP

Puoi accedere agli argomenti dall'intestazione Sec-Browsing-Topics di una richiesta fetch()/XHR o di una richiesta iframe.

Intestazioni di richiesta e risposta per l&#39;impostazione e il recupero degli argomenti.
Intestazioni per iframe e fetch().

Puoi contrassegnare gli argomenti forniti dalle intestazioni della richiesta come osservati impostando un'intestazione Observe-Browsing-Topics: ?1 nella risposta alla richiesta. Il browser li utilizzerà quindi per calcolare gli argomenti di interesse per un utente.

Se l'API restituisce uno o più argomenti, una richiesta di recupero inviata a eTLD+1 da cui sono stati osservati gli argomenti includerà un'intestazione Sec-Browsing-Topics come la seguente: 

(325);v=chrome.1:1:1, ();p=P000000000

Se l'API non restituisce alcun argomento, l'intestazione sarà simile a questa:

();p=P0000000000000000000000000000000

I valori dell'intestazione Sec-Browsing-Topics vengono riempiti per ridurre il rischio che un utente malintenzionato impari a conoscere il numero di argomenti limitati a un chiamante in base alla lunghezza dell'intestazione.

Implementa con fetch()

Nella pagina del publisher, aggiungi il codice per la richiesta di recupero e assicurati di includere {browsingTopics: true}.

fetch('<topics_caller_eTLD+1>', {browsingTopics: true})
    .then((response) => {
        // Process the response
 })

Nei browser che supportano l'API, la richiesta fetch() includerà un'intestazione Sec-Browsing-Topics che elenca gli argomenti osservati per il nome host dell'URL della richiesta.

Implementazione con un iframe

Analogamente a una richiesta fetch(), l'intestazione Sec-Browsing-Topics viene inviata quando si utilizza l'attributo browsingtopics su un iframe.

<iframe src="<topics_caller_eTLD+1>" browsingtopics></iframe>

In questo caso, il chiamante sarà , simile alla chiamata di recupero.

Lato server: identico per tutti i casi

Affinché gli argomenti nell'intestazione della richiesta Sec-Browsing-Topics vengano contrassegnati dal browser come osservati, ma anche per includere la visita alla pagina corrente nel calcolo dell'argomento principale del periodo successivo dell'utente, la risposta del server deve includere Observe-Browsing-Topics: ?1.

Ecco un esempio JavaScript che utilizza setHeader():

res.setHeader('Observe-Browsing-Topics', '?1');

Implementazione back-end di Topics

L'aggiunta di un backend per Topics è facoltativa. La tua scelta dipende da come e dove vuoi utilizzare gli argomenti calcolati sul dispositivo (nel browser). 

// Use the language/framework/stack of your preference
function processTopicsBackendAPI(topics, user, domain, caller) {
  // Validate inputs
  // If the list is not empty, continue
  // Use topics as an additional contextual signal
}

Utilizza gli argomenti come dati contestuali

I dati relativi agli argomenti possono essere presi in considerazione insieme ad altri indicatori come URL, parole chiave e persino tag, come ulteriore indicatore sul tuo pubblico.

Come spiegato in Massimizza la pertinenza degli annunci dopo i cookie di terze parti, esistono diversi approcci per sfruttare gli argomenti per pubblicare annunci pertinenti. Alcuni di questi prevedono l'utilizzo di argomenti per creare segmenti di pubblico, mentre altri suggeriscono di utilizzare Topics come indicatore, tra gli altri, per addestrare modelli di machine learning che verranno utilizzati per dedurre ulteriori interessi del pubblico o anche per ottimizzare la logica di offerta.

Creazione e deployment

  1. Raccogli argomenti osservando gli utenti in fase di produzione, non ancora scalati (tempo stimato: circa 1 settimana)
    1. Comprendere le opzioni: iframe e JavaScript o intestazioni HTTP
    2. Definisci il dominio dell'iframe.
    3. Crea il codice JavaScript utilizzando l'app demo come riferimento al codice oppure implementa l'opzione delle intestazioni.
    4. Eseguire il deployment di Topics nel tuo ambiente controllato (alcuni siti di produzione).
    5. Aggiungere l'implementazione Topics ad alcuni siti di destinazione (massimo cinque siti al momento).
    6. Test funzionali e convalida.
  2. [Facoltativo] Utilizzare i dati di Topics come indicatore contestuale (con URL, tag e così via) (tempo stimato: circa 3 giorni).
    1. Dopo aver ricevuto l'elenco degli argomenti, puoi inviarlo al tuo backend con altri indicatori di contesto.

Esegui il deployment in alcuni siti di destinazione

Ora che hai il codice, aggiungiamolo ad alcuni siti di destinazione per un primo test e per assicurarci che l'API sia stabile e funzionante in questo ambiente controllato.

Ti consigliamo di scegliere siti web di destinazione che:

  • Ricevi un numero limitato di visite mensili (meno di un milione di visite al mese): per iniziare, esegui il deployment dell'API per un pubblico ristretto.
  • Sei tu il proprietario e il controllo: se necessario, puoi disattivare rapidamente l'implementazione senza approvazioni complesse.
  • Non sono fondamentali per l'attività: poiché questa implementazione può interrompere l'esperienza utente, inizia con siti target a basso rischio.
  • Non più di cinque siti in totale: per il momento non hai bisogno di molto traffico o esposizione.
  • Rappresentare temi diversi: scegli siti web che rappresentano categorie diverse (ad esempio, uno sullo sport, un altro sulle notizie, un altro su cibi e bevande e così via). Puoi utilizzare lo strumento per gli argomenti interni in Chrome per convalidare i domini e la relativa classificazione mediante il classificatore di machine learning Topics. Scopri di più sul debug nella guida per gli sviluppatori dell'API Topics.

Test funzionali e convalida

Quando chiami l'API Topics in questo ambiente limitato puoi aspettarti:

  • Un array di argomenti vuoto [] se questa è la prima chiamata di questo dispositivo, per questo sito e il chiamante negli ultimi sette giorni.
  • Un elenco di zero-tre argomenti, che rappresentano gli interessi di questo utente.
  • Dopo sette giorni di osservazione dovresti ricevere:
    • Un argomento che rappresenta l'interesse di tale utente calcolato dalla cronologia di navigazione della settimana.
      • Un dettaglio importante: se non hai osservato un numero sufficiente di argomenti affinché un utente consenta all'API Topics di calcolare i cinque argomenti principali della settimana, Topics aggiungerà tutti gli argomenti casuali necessari per arrivare al numero totale di cinque. Scopri ulteriori dettagli sull'API.
  • Una nuova voce di argomento che sostituisce uno dei tre se lo chiami dopo quattro settimane di osservazione.
    • Questo accade perché l'API Topics sarà stabile per le settimane successive, senza esporre troppi interessi dell'utente. Puoi trovare ulteriori dettagli su GitHub.
  • Se non hai osservato argomenti per l'utente per più di tre settimane, l'API Topics restituirà di nuovo un array vuoto [].

Misura le prestazioni e le metriche dell'esperienza utente.

  • Il tempo di esecuzione delle chiamate JavaScript all'API Topics all'interno di un iframe multiorigine deve essere misurato per essere utilizzato in future analisi delle prestazioni. Assicurati di raccogliere e archiviare correttamente i dati di telemetria nel backend.
    • Un'altra possibile metrica da calcolare è il tempo impiegato per creare un iframe e postMessage() argomenti dopo la ricezione degli argomenti.

Risolvere i problemi

Sto chiamando l'API Topics ma non ricevo alcun risultato. Che cosa posso fare?
Se chiami l'API Topics entro la prima settimana dall'osservazione di un utente, si tratta di un comportamento previsto.

Suggerimenti principali

  1. Testa il tuo codice front-end per assicurarti che JavaScript funzioni come previsto.

  2. Testa il tuo backend per ricevere i risultati degli argomenti.

    1. Ricordati di assicurarti che i tipi di dati e i parametri dell'API di backend siano configurati correttamente.
    2. Assicurati che il backend sia configurato per la scalabilità corretta.

  3. Dalla nostra esperienza è necessario attendere almeno tre settimane prima di iniziare a ricevere risultati più pertinenti relativi ad argomenti.

  4. Non tutti gli utenti avranno attivato Topics:

    1. Gli utenti possono disabilitare esplicitamente l'API Topics.
    2. Le pagine del publisher possono controllare le norme relative alle autorizzazioni. Consulta la sezione relativa alla disattivazione della guida per gli sviluppatori dell'API Topics.
    3. Per ulteriori dettagli, visita il sito chromestatus.com.

  5. Aggiungi metriche e osservabilità a questo ambiente: ti serviranno per analizzare i primi risultati. Ecco alcuni esempi di metriche:

    1. Latenza delle chiamate;
    2. errori HTTP nelle chiamate agli argomenti;

  6. Prova a limitare le modifiche all'implementazione nelle prime tre settimane.

Scalabilità in produzione

Ecco un riepilogo dettagliato di come puoi scalare in produzione. La procedura è spiegata di seguito.

  1. Scalare l'implementazione (produzione). La procedura è descritta di seguito.
    1. Aggiungere l'iframe a più siti web di publisher.
  2. Elabora e utilizza i dati degli argomenti (tempo stimato: circa 4 settimane).
    1. Incorpora i dati degli argomenti come indicatore additivo insieme ad altri dati.
    2. Origine partner per i test con offerte in tempo reale.
    3. Esegui test di utilità con gli argomenti come segnale aggiuntivo agli altri tuoi dati.

Scalare l'implementazione

A questo punto, dovresti aver raccolto i dati degli argomenti da alcuni siti in un ambiente controllato, con un livello maggiore di affidabilità dell'intera soluzione.

È arrivato il momento di scalare questa implementazione eseguendo il deployment dello stesso codice in più siti web di destinazione. In questo modo, potrai osservare più utenti, raccogliere più dati sugli argomenti e approfondire la tua comprensione dei segmenti di pubblico.

È consigliabile:

  1. Implementa gradualmente sui tuoi siti, soprattutto se hai un volume di traffico elevato.
  2. Esegui un test di carico per i dati degli argomenti in base al traffico previsto.
    1. Verifica che il tuo backend sia in grado di gestire un volume elevato di chiamate.
    2. Configura la raccolta delle metriche e i log per l'analisi.
  3. Subito dopo aver eseguito il deployment dell'API Topics, controlla le metriche per rilevare eventuali problemi gravi degli utenti finali. Continua a controllare regolarmente le tue metriche.
  4. In caso di interruzione o comportamento imprevisto, esegui il rollback del deployment e analizza i log per comprendere e risolvere il problema.

Interagisci e condividi il tuo feedback