Guida per gli sviluppatori dell'API Topics

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

Stato dell'implementazione

Prova la demo

Esistono due demo dell'API Topics che ti consentono di provare Topics come singolo utente.

Puoi anche eseguire il colab Topics per provare il modello di classificatore Topics.

Usa l'API JavaScript per accedere agli argomenti e registrarli come osservati

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

  • Indica 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).
  • Consente di accedere ad argomenti per l'utente che sono stati osservati dal chiamante.

Il metodo restituisce una promessa che si risolve in un array di massimo tre argomenti, uno per ciascuna delle tre epoca 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 l'attuale configurazione dell'API Topics, ad esempio chrome.2
  • modelVersion: una stringa che identifica il classificatore di machine learning utilizzato per dedurre gli argomenti per il 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 a settimana e il numero di argomenti restituiti per chiamata) sono soggetti a modifica man mano che incorporiamo il feedback dell'ecosistema e eseguiamo l'iterazione dell'API.

Rileva il supporto di document.browsingTopics

Prima di utilizzare l'API, verifica che sia 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

Di seguito è riportato un esempio 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, questo metodo fa sì che il browser registri anche la visita alla pagina corrente come osservato dal chiamante, per poter essere utilizzato in un secondo momento nel calcolo degli argomenti. Da Chrome 108, il metodo può essere trasmesso un argomento facoltativo per evitare che la visita alla pagina venga registrata: {skipObservation:true}.

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

Usa le intestazioni per accedere agli argomenti e contrassegnali come osservati

Puoi accedere agli argomenti e anche contrassegnare le visite alle pagine come osservate con l'aiuto request e response.

L'utilizzo dell'approccio dell'intestazione può essere molto più efficace rispetto all'utilizzo dell'API JavaScript, poiché l'API richiede la creazione di un iframe multiorigine e l'esecuzione di una chiamata document.browsingTopics() da questo. Per la chiamata è necessario utilizzare un iframe multiorigine, perché il contesto da cui viene richiamata l'API viene utilizzato per garantire che il browser restituisca gli argomenti appropriati al chiamante. Nella parte esplicativa dell'argomento Topics vengono discussi ulteriormente gli argomenti: Esiste un modo per inviare gli argomenti utilizzando lo strumento Visualizza come intestazione della richiesta? .

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

Impostazione di un'intestazione Observe-Browsing-Topics: ?1 nella risposta alla richiesta fa sì che il browser registri la visita corrente alla pagina osservata dal chiamante, in modo da poter essere successivamente utilizzata nel calcolo degli argomenti.

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

  • fetch(): aggiungi {browsingTopics: true} al parametro options di una richiesta fetch(). La demo dell'intestazione Topics mostra un esempio semplificato.
  • Attributo iframe: aggiungi l'attributo browsingtopics a un elemento <iframe> o imposta il codice JavaScript equivalente proprietà 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.
di Gemini Advanced.

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 sia presente un'intestazione della risposta corrispondente. In altre parole, senza l'intestazione della risposta, la visita alla pagina non verrà registrata come osservato, 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 che è registrato come dominio del chiamante.

Esegui il debug dell'implementazione dell'API

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

Visualizza gli argomenti calcolati per il tuo browser

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

La pagina chrome://topics-internals con il riquadro Stato degli argomenti selezionato.
Il riquadro Stato degli argomenti della pagina chrome://topics-internals mostra gli ID argomento, le assegnazioni di argomenti casuali e reali e le versioni della tassonomia e del modello.

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 seleziona Pets e Cats come due degli argomenti principali per l'epoca corrente. Gli altri tre argomenti sono stati scelti in modo casuale, in quanto la cronologia di navigazione (sui siti che osserva gli argomenti) non è sufficiente per fornire cinque argomenti.

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

Visualizza gli argomenti dedotti per i nomi host

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

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

L'implementazione corrente dell'API Topics deduce gli argomenti solo dai nomi host. non da altre parti dell'URL.

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

Visualizza le informazioni sull'API Topics

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

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

Pagina chrome://topics-internals con il riquadro Funzionalità e parametri selezionato.
Il riquadro chrome://topics-internals Funzionalità e parametri mostra le funzionalità abilitate, 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 quando viene eseguito 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

Nell'elenco che segue vengono illustrati tutti i parametri, il valore predefinito e lo 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: disattivato
Abilita la quarta release delle impostazioni UI di Privacy Sandbox.

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

BrowsingTopicsBypassIPIsPubliclyRoutableCheck
Valore predefinito: disattivato
Se abilitato, verrà effettuato il controllo per verificare se l'indirizzo IP è instradabile pubblicamente. viene bypassato per determinare l'idoneità all'inclusione di una pagina negli argomenti calcolo.

BrowsingTopics:number_of_epochs_to_expose
Valore predefinito: 3
Il numero di epoche in cui calcolare gli argomenti da assegnare a un richiedente contesto. Internamente, il browser manterrà 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 impostarlo su 15 secondi, anziché sul valore predefinito di sette giorni.

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
Probabilità che un singolo argomento in un'epoca sia restituito in modo casuale da l'intera tassonomia di 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
Per quante epoche di dati sull'utilizzo delle API (ad es. osservazioni degli argomenti) verranno utilizzati filtrando 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 per contesto da conservare per ogni argomento principale. L'intento è il limite alla memoria in uso.

BrowsingTopics:max_number_of_api_usage_context_entries_to_load_per_epoch
Valore predefinito: 100000
Il numero massimo di voci che è possibile recuperare dal database per ogni query per i contesti di utilizzo delle API. La query verrà eseguita una volta per epoca al calcolo degli argomenti nel tempo. L'intento è quello di limitare l'utilizzo massimo di memoria.

BrowsingTopics:max_number_of_api_usage_context_domains_to_store_per_page_load
Valore predefinito: 30
Il numero massimo di domini contestuali 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 mappata a un set di configurazione. L'aggiornamento dei parametri di configurazione senza aggiornare config_version deve di solito è sufficiente per i test locali, ma in alcune situazioni si potrebbe lasciare il browser in una stato incoerente e potrebbe causare un arresto anomalo del browser, ad esempio l'aggiornamento number_of_top_topics_per_epoch.

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

Disattivazione del 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 evitare il calcolo degli argomenti solo per tutti gli utenti di quella pagina. Le visite successive ad altre pagine del tuo sito non saranno interessate: se imposti un criterio per bloccare l'API Topics in una pagina, questo non influirà sulle altre.

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 ed eventuali domini a cui vuoi consentire l'accesso all'API. Ad esempio, per disabilitare completamente l'utilizzo dell'API Topics in tutti i contesti di navigazione, tranne la tua origine e 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