Implementare l'API Topics

Questa pagina spiega i dettagli di implementazione per i chiamanti dell'API Topics per osservare e accedere agli argomenti. Prima di iniziare a implementare la soluzione, assicurati che il browser sia configurato correttamente. Controlla la sezione Panoramica per scoprire di più su come i chiamanti osservano e accedono agli argomenti degli utenti.

Osservare e accedere agli argomenti

Esistono due modi per osservare e accedere agli argomenti di un utente: intestazioni HTTP e API JavaScript.

Intestazioni HTTP

L'utilizzo delle intestazioni HTTP è un approccio consigliato per osservare e accedere agli argomenti degli utenti. Questo approccio può essere molto più efficiente dell'utilizzo dell'API JavaScript. Con le intestazioni HTTP, l'URL della richiesta fornisce il dominio registrabile che viene registrato come dominio chiamante. Questo è il dominio che ha osservato gli argomenti dell'utente.

Avvia richiesta

Esistono due modi per utilizzare gli argomenti con le intestazioni:

  • Accedendo alle intestazioni della richiesta e della risposta in una richiesta fetch() che include un'opzione browsingTopics: true.
  • Accedendo alle intestazioni di un elemento iframe che include un attributo browsingtopics.
Avviare la richiesta con un recupero

Utilizzando fetch, il chiamante dell'API effettua una richiesta che include {browsingTopics: true} nel parametro options. L'origine del parametro URL della richiesta di recupero è l'origine in cui sono stati osservati gli argomenti.

   fetch('<topics_caller_eTLD+1>', { browsingTopics: true })
    .then((response) => {
        // Process the response
    });
Avviare la richiesta con un iframe

Aggiungi l'attributo browsingtopics all'elemento <iframe>. Il browser includerà l'intestazione Sec-Browsing-Topics nella richiesta dell'iframe, con l'origine dell'iframe come chiamante.

   <iframe src="https://adtech.example" browsingtopics></iframe>

Interpretare i valori delle intestazioni delle richieste

Per entrambi gli approcci (recupero e iframe), gli argomenti osservati per un utente possono essere recuperati sul server dall'intestazione della richiesta Sec-Browsing-Topics. L'API Topics includerà automaticamente gli argomenti dell'utente nell'intestazione della richiesta fetch() o iframe. Se l'API restituisce uno o più argomenti, una richiesta di recupero all'origine da cui sono stati osservati gli argomenti includerà un'intestazione Sec-Browsing-Topics come questa:

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

Se l'API non restituisce argomenti, l'intestazione ha il seguente aspetto:

   ();p=P0000000000000000000000000000000

I reindirizzamenti verranno seguiti e gli argomenti inviati nella richiesta di reindirizzamento saranno specifici per l'URL di reindirizzamento. I valori dell'intestazione Sec-Browsing-Topics vengono riempiti per mitigare il rischio che un malintenzionato possa scoprire il numero di argomenti inclusi nell'ambito di un chiamante in base alla lunghezza dell'intestazione.

Gestire la risposta lato server

Se la risposta alla richiesta include un'intestazione Observe-Browsing-Topics: ?1, ciò indica che il browser deve contrassegnare gli argomenti della richiesta di accompagnamento come osservati e includere la visita alla pagina corrente nel calcolo degli argomenti dell'epoca successiva dell'utente. Includi l'intestazione Observe-Browsing-Topics: ?1 nella risposta nel codice lato server:

   res.setHeader('Observe-Browsing-Topics', '?1');
Intestazioni di richiesta e risposta per impostare e recuperare gli argomenti.
Intestazioni per iframe e fetch().

Condividere gli argomenti osservati con i partner

Poiché le SSP sono presenti solo sul lato del publisher, le DSP potrebbero voler condividere gli argomenti che osservano sui siti dell'inserzionista con le SSP partner. Possono farlo inviando una richiesta fetch() con l'intestazione degli argomenti alle SSP dal contesto di primo livello dell'inserzionista.

const response = await fetch("partner-ssp.example", {
 browsingTopics: true
});

Osservare e accedere agli argomenti con JavaScript

Il metodo dell'API Topics JavaScript document.browsingTopics() fornisce un modo per osservare e recuperare gli argomenti di interesse di un utente nell'ambiente del browser: - Registrazione dell'osservazione:comunica al browser che il chiamante ha osservato la visita dell'utente alla pagina corrente. Questa osservazione contribuisce al calcolo degli argomenti dell'utente per il chiamante nelle epoche future. - Access Topics: recupera gli argomenti che il chiamante ha osservato in precedenza per l'utente. Il metodo restituisce un array di massimo tre oggetti argomento, uno per ciascuno dei periodi più recenti, in ordine casuale.

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

Disponibilità API

Prima di utilizzare l'API, assicurati che sia supportata e disponibile:

 if ('browsingTopics' in document && document.featurePolicy.allowsFeature('browsing-topics')) {
    console.log('document.browsingTopics() is supported on this page');
 } else {
    console.log('document.browsingTopics() is not supported on this page');
 }

Incorporare un iframe

Per la chiamata deve essere utilizzato un iframe multiorigine, perché il contesto da cui viene richiamata l'API viene utilizzato per garantire che il browser restituisca gli argomenti appropriati per il chiamante. Includi un elemento <iframe> nel codice HTML:

<iframe src="https://example.com" browsingtopics></iframe>

Puoi anche creare un iframe in modo dinamico utilizzando JavaScript:

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

Chiama l'API dall'interno dell'iframe

 try {
   // Get the array of top topics for this user.
   const topics = await document.browsingTopics();
  
   // Request an ad creative, providing topics information.
   const response = await fetch('https://ads.example/get-creative', {
   method: 'POST',
   headers: {
    'Content-Type': 'application/json',
   },
   body: JSON.stringify(topics)
   })
  
   // Get the JSON from the response.
   const creative = await response.json();
  
   // Display ad.

 } catch (error) {
   // Handle error.
 }

Per impostazione predefinita, il metodo document.browsingTopics() fa sì che il browser registri anche la visita alla pagina corrente osservata dal chiamante, in modo che possa essere utilizzata in un secondo momento nel calcolo degli argomenti. Al metodo può essere passato un argomento facoltativo per impedire la registrazione della visita alla pagina: {skipObservation:true}.

 // current page won't be included in the calculation of topics:
 const topics = await document.browsingTopics({skipObservation:true});

Comprendere la risposta

Vengono restituiti al massimo tre argomenti: uno o zero per ciascuna delle ultime tre settimane, a seconda che siano stati osservati o meno. Vengono restituiti solo gli argomenti osservati dal chiamante per l'utente corrente. Ecco un esempio di ciò che restituisce l'API:

 [{
'configVersion': chrome.2,
 'modelVersion': 4,
 'taxonomyVersion': 2,
 'topic': 309,
 'version': chrome.2:2:4
}]
  • configVersion: una stringa che identifica la versione della configurazione dell'algoritmo dei browser.
  • modelVersion: una stringa che identifica il classificatore di machine learning utilizzato per dedurre gli argomenti.
  • taxonomyVersion: una stringa che identifica l'insieme di argomenti in uso nel browser.
  • topic: un numero che identifica l'argomento nella tassonomia.
  • version: una stringa che concatena configVersion, taxonomyVersion e modelVersion. I parametri descritti in questa guida e i dettagli dell'API (ad esempio le dimensioni della tassonomia, il numero di argomenti calcolati per ogni settimana e il numero di argomenti restituiti per ogni chiamata) sono soggetti a variazione man mano che incorporiamo i feedback dell'ecosistema ed eseguiamo l'iterazione sull'API.

Consulta la pagina Testa e pubblica per scoprire quale risposta aspettarti e come utilizzare gli argomenti come segnale aggiuntivo per annunci più pertinenti.

Passaggi successivi

Scopri come eseguire il deployment, testare e scalare le soluzioni basate su Topics.
Scopri gli strumenti disponibili in Chrome per visualizzare le informazioni sull'API Topics, comprendere come vengono assegnati gli argomenti e eseguire il debug dell'implementazione.

Vedi anche

Consulta le nostre risorse per comprendere meglio l'API Topics sul web.