Guida per gli sviluppatori dell'API Topics

Scopri come utilizzare l'API e come usare i flag di Chrome per i test.

Stato implementazione

Prova la demo

Sono disponibili due demo dell'API Topics che consentono di provare Topics come utente singolo.

Puoi anche eseguire la colab di Topics per provare il modello di classificazione di Topics.

Usare l'API JavaScript per accedere agli argomenti e registrarli nel modo osservato

L'API JavaScript Topics ha un metodo: document.browsingTopics(). Questo ha due scopi:

  • Comunica al browser di registrare la visita alla pagina corrente come osservata per il chiamante, in modo che possa essere utilizzata in un secondo momento per calcolare gli argomenti per l'utente (per il chiamante).
  • Accedi agli argomenti dell'utente osservati dal chiamante.

Il metodo restituisce una promessa che si risolve in un array di massimo tre argomenti, uno per ognuna delle tre epoche più recenti, in ordine casuale. Un'epoca è un periodo di tempo impostato su una settimana nell'implementazione di Chrome.

Ogni oggetto argomento nell'array restituito da document.browsingTopics() ha le seguenti proprietà:

  • configVersion: una stringa che identifica la configurazione corrente dell'API Topics, ad esempio chrome.2
  • modelVersion: una stringa che identifica il classificatore di machine learning utilizzato per dedurre gli argomenti del sito, ad esempio 4
  • taxonomyVersion: una stringa che identifica l'insieme di argomenti utilizzati dal browser, ad esempio 2
  • topic: un numero che identifica l'argomento nella tassonomia, ad esempio 309
  • version: una stringa che concatena configVersion, taxonomyVersion e modelVersion, ad esempio chrome.2:2:4

I parametri descritti in questa guida e i dettagli dell'API (come le dimensioni della tassonomia, il numero di argomenti calcolati per settimana e il numero di argomenti restituiti per chiamata) sono soggetti a modifiche man mano che incorporiamo il feedback sull'ecosistema e l'iterazione dell'API.

Rilevamento del supporto per document.browsingTopics

Prima di utilizzare l'API, verifica se è supportata dal browser e disponibile nel documento:

'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');

Accedere agli argomenti con l'API JavaScript

Ecco un esempio di base del possibile utilizzo dell'API per accedere agli argomenti per l'utente corrente.

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.
}

Accedi agli argomenti senza modificare lo stato

document.browsingTopics() restituisce gli argomenti osservati dal chiamante per l'utente corrente. Per impostazione predefinita, il metodo fa anche in modo che il browser registri la visita alla pagina corrente osservata dal chiamante, per poterla utilizzare in un secondo momento nel calcolo degli argomenti. A partire da Chrome 108, è possibile passare un argomento facoltativo per evitare la registrazione della visita alla pagina: {skipObservation:true}.

In altre parole, {skipObservation:true} significa che la chiamata al metodo non comporterà l'inclusione della pagina corrente nel calcolo degli argomenti.

Utilizza le intestazioni per accedere agli argomenti e contrassegnarli come osservati

Puoi accedere agli argomenti e anche contrassegnare le visite alle pagine come osservate, con l'aiuto delle intestazioni request e response. L'uso dell'approccio header può essere molto più efficiente rispetto alla chiamata dell'API JavaScript.

È possibile accedere agli argomenti dall'intestazione Sec-Browsing-Topics di una richiesta fetch() o XHR.

L'impostazione di un'intestazione Observe-Browsing-Topics: ?1 nella risposta alla richiesta fa sì che il browser registri la visita alla pagina corrente osservata dal chiamante, per poterla utilizzare in un secondo momento nel calcolo degli argomenti.

È possibile accedere agli argomenti e osservarli con le intestazioni HTTP in due modi:

  • fetch(): aggiungi {browsingTopics: true} al parametro delle opzioni di una richiesta fetch(). La demo dell'intestazione Topics mostra un esempio semplificato.
  • Attributo iframe: aggiungi l'attributo browsingtopics a un elemento <iframe> oppure imposta la proprietà JavaScript equivalente iframe.browsingTopics = true. Il dominio registrabile dell'origine iframe è il dominio del chiamante: ad esempio, per <iframe src="https://example.com" browsingtopics></iframe>: il chiamante è example.com.

Alcune note aggiuntive sulle intestazioni:

  • Verranno seguiti i reindirizzamenti e gli argomenti inviati nella richiesta di reindirizzamento saranno specifici dell'URL di reindirizzamento.
  • L'intestazione della richiesta non modifica lo stato del chiamante, a meno che non esista un'intestazione della risposta corrispondente. Ciò significa che senza l'intestazione della risposta la visita alla pagina non verrà registrata come osservata, quindi non influirà sul calcolo dell'argomento dell'utente per il periodo successivo.
  • L'intestazione della risposta viene rispettata solo se la richiesta corrispondente includeva l'intestazione degli argomenti.
  • L'URL della richiesta fornisce il dominio registrabile registrato come dominio del chiamante.

Debug dell'implementazione dell'API

La pagina chrome://topics-internals è disponibile in Chrome su computer dopo aver attivato l'API Topics. Vengono visualizzati argomenti per l'utente corrente, argomenti dedotti per i nomi host e informazioni tecniche sull'implementazione dell'API. Stiamo rielaborando e migliorando il design della pagina in base al feedback degli sviluppatori: aggiungi il tuo feedback all'indirizzo bugs.chromium.org.

Visualizzare gli argomenti calcolati per il browser

Gli utenti possono visualizzare informazioni sugli argomenti osservati per il proprio browser durante il periodo attuale e precedente visualizzando chrome://topics-internals.

La pagina chrome://topics-internals con il riquadro di stato Argomenti selezionato.
Il riquadro Stato Topics della pagina chrome://topics-internals mostra gli ID argomento, le assegnazioni di argomenti casuali e reali, nonché le versioni tassonomiche e dei modelli.

Questo screenshot mostra che i siti visitati di recente includono topics-demo-cats.glitch.me e cats-cats-cats-cats.glitch.me. Questo fa sì che l'API Topics selezioni Pets e Cats come due degli argomenti principali per l'epoca attuale. I tre argomenti rimanenti sono stati scelti in modo casuale, poiché la cronologia di navigazione (sui siti che seguono argomenti) non è sufficiente per fornire cinque argomenti.

La colonna Domini di contesto osservati (con hashing) fornisce il valore sottoposto ad hashing di un nome host per il quale è stato osservato un argomento.

Visualizza argomenti dedotti per i nomi host

Puoi anche visualizzare gli argomenti dedotti dal modello di classificazione di Topics per uno o più nomi host in chrome://topics-internals.

La pagina chrome://topics-internals con il riquadro Classificatore selezionato.
Il riquadro Classificazione della pagina chrome://topics-internals mostra gli argomenti selezionati, gli host visitati, nonché la versione e il percorso del modello.

L'attuale implementazione dell'API Topics deduce gli argomenti solo dai nomi host e non da qualsiasi altra parte di un URL.

Utilizza solo nomi host (senza protocollo o percorso) per visualizzare gli argomenti dedotti dal classificatore chrome://topics-internals. chrome://topics-internals mostrerà un errore se tenti di includere "/" nel campo Host.

Visualizzare le informazioni sull'API Topics

Puoi trovare informazioni sull'implementazione e sulle impostazioni dell'API Topics, ad esempio la versione della tassonomia e la durata dell'epoca, in chrome://topics-internals. Questi valori riflettono le impostazioni predefinite dell'API o i parametri impostati correttamente dalla riga di comando. Questo può essere utile per confermare che i flag della riga di comando abbiano funzionato come previsto.

Nell'esempio, time_period_per_epoch è stato impostato su 15 secondi (il valore predefinito è sette giorni).

Pagina chrome://topics-internals con il riquadro Funzionalità e parametri selezionato.
Il riquadro Funzionalità e parametri chrome://topics-internals mostra le funzionalità attivate, il tempo per epoca, il numero di epoche da utilizzare per calcolare gli argomenti, la versione della tassonomia e altre impostazioni.

I parametri mostrati nello screenshot corrispondono ai flag che possono essere impostati durante l'esecuzione di Chrome dalla riga di comando. Ad esempio, la demo all'indirizzo topics-fetch-demo.glitch.me consiglia di utilizzare i seguenti flag:

--enable-features=BrowsingTopics,BrowsingTopicsParameters:time_period_per_epoch/15s/max_epoch_introduction_delay/3s,PrivacySandboxAdsAPIsOverride,PrivacySandboxSettings3,OverridePrivacySandboxSettingsLocalTesting

Il seguente elenco illustra ogni parametro, il relativo valore predefinito e il relativo scopo.

Flag di Chrome

BrowsingTopics
Valore predefinito: abilitato
Indica se l'API Topics è abilitata.

PrivacySandboxAdsAPIsOverride
Valore predefinito: abilitato
Abilita le API Google Ads: Attribution Reporting, Protected Audience, Topics, Fenced Frames.

PrivacySandboxSettings4
Valore predefinito: disabilitato
Abilita la quarta release delle impostazioni UI di Privacy Sandbox.

OverridePrivacySandboxSettingsLocalTesting
Valore predefinito: abilitato
Se abilitato, il browser non richiede più l'attivazione delle impostazioni sottostanti per abilitare le funzionalità di Privacy Sandbox.

BrowsingTopicsBypassIPIsPubliclyRoutableCheck
Valore predefinito: disabilitato
Se abilitato, il controllo se l'indirizzo IP è instradabile pubblicamente verrà ignorato al momento di determinare l'idoneità di una pagina da includere nel calcolo degli argomenti.

BrowsingTopics:number_of_epochs_to_expose
Valore predefinito: 3
Il numero di epoche da cui calcolare gli argomenti da assegnare a un contesto richiedente. Il browser manterrà internamente fino a N+1 epoche.

BrowsingTopics:time_period_per_epoch
Valore predefinito: 7d-0h-0m-0s
Durata di ogni epoca. Per il debug, può essere utile impostare l'opzione su 15 secondi, ad esempio sui 7 giorni predefiniti.

BrowsingTopics:number_of_top_topics_per_epoch
Valore predefinito: 5
Numero di argomenti calcolati per epoca.

BrowsingTopics:use_random_topic_probability_percent
Valore predefinito: 5
La probabilità che un singolo argomento in un'epoca venga restituita in modo casuale dall'intera tassonomia degli argomenti. La casualità è fissata a un'epoca e a un sito.

BrowsingTopics:number_of_epochs_of_observation_data_to_use_for_filtering
Valore predefinito: 3
Quante epoche di dati sull'utilizzo delle API (ad es. osservazioni degli argomenti) verranno utilizzate per filtrare gli argomenti per un contesto di chiamata.

BrowsingTopics:max_number_of_api_usage_context_domains_to_keep_per_topic
Valore predefinito: 1000
Il numero massimo di domini di contesto osservati da conservare per ogni argomento principale. L'intento è quello di limitare la memoria in uso.

BrowsingTopics:max_number_of_api_usage_context_entries_to_load_per_epoch
Valore predefinito: 100.000
Numero massimo di voci che è possibile recuperare dal database per ogni query per i contesti di utilizzo dell'API. La query verrà eseguita una volta per epoca al momento del calcolo degli argomenti. L'intento è quello di limitare l'utilizzo massimo della memoria.

BrowsingTopics:max_number_of_api_usage_context_domains_to_store_per_page_load
Valore predefinito: 30
Numero massimo di domini di contesto di utilizzo delle API che è possibile archiviare per ogni caricamento pagina.

BrowsingTopics:config_version
Valore predefinito: 1
Codifica i parametri di configurazione dell'API Topics. Ogni numero di versione deve essere associato a un solo set di configurazione. L'aggiornamento dei parametri di configurazione senza aggiornare config_version dovrebbe di solito andare bene per i test locali, ma in alcune situazioni potrebbe lasciare il browser in uno stato incoerente e causare un arresto anomalo del browser, ad esempio l'aggiornamento di number_of_top_topics_per_epoch.

BrowsingTopics:taxonomy_version
Valore predefinito: 1
La versione della tassonomia utilizzata dall'API.

Disattivare il sito

Puoi disattivare il calcolo degli argomenti per pagine specifiche del tuo sito includendo l'intestazione Permissions-Policy: browsing-topics=() Permissions-Policy in una pagina per impedire il calcolo degli argomenti solo per tutti gli utenti di quella pagina. Le visite successive ad altre pagine del sito non saranno interessate: se imposti un criterio per bloccare l'API Topics in una pagina, non verrà applicata alle altre pagine.

Puoi anche controllare quali terze parti hanno accesso agli argomenti della tua pagina utilizzando l'intestazione Permissions-Policy per controllare l'accesso di terze parti all'API Topics. Come parametri dell'intestazione, utilizza self e i domini a cui vuoi consentire l'accesso all'API. Ad esempio, per disattivare completamente l'utilizzo dell'API Topics in tutti i contesti di navigazione, ad eccezione della tua origine e di https://example.com, imposta la seguente intestazione della risposta HTTP:

Permissions-Policy: browsing-topics=(self "https://example.com")

Passaggi successivi

Scopri di più

Interagisci e condividi il tuo feedback