Scopri come utilizzare l'API e come usare i flag di Chrome per i test.
Stato implementazione
- L'API Topics ha completato la fase di discussione pubblica ed è attualmente disponibile per il 99% degli utenti, con una scalabilità fino al 100%.
- Per fornire il tuo feedback sull'API Topics, crea un problema nel messaggio esplicativo di Topics o partecipa alle discussioni nell'Migliorare il Web Advertising Business Group. Il testo esplicativo contiene una serie di domande aperte che richiedono ancora un'ulteriore definizione.
- La sequenza temporale di Privacy Sandbox indica le tempistiche di implementazione dell'API Topics e di altre proposte di Privacy Sandbox.
- L'API Topics: aggiornamenti più recenti descrive in dettaglio le modifiche e i miglioramenti apportati all'API Topics e alle implementazioni.
Prova la demo
Sono disponibili due demo dell'API Topics che consentono di provare Topics come utente singolo.
- Demo dell'API JavaScript: topics-demo.glitch.me.
- Demo intestazione: topics-fetch-demo.glitch.me
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 esempiochrome.2
modelVersion
: una stringa che identifica il classificatore di machine learning utilizzato per dedurre gli argomenti del sito, ad esempio4
taxonomyVersion
: una stringa che identifica l'insieme di argomenti utilizzati dal browser, ad esempio2
topic
: un numero che identifica l'argomento nella tassonomia, ad esempio309
version
: una stringa che concatenaconfigVersion
,taxonomyVersion
emodelVersion
, ad esempiochrome.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 richiestafetch()
. La demo dell'intestazione Topics mostra un esempio semplificato.- Attributo iframe: aggiungi l'attributo
browsingtopics
a un elemento<iframe>
oppure imposta la proprietà JavaScript equivalenteiframe.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
.
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
.
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).
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 dinumber_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ù su quali sono gli argomenti e come funzionano.
- Prova la demo.
Scopri di più
Interagisci e condividi il tuo feedback
- GitHub: leggi il spiegazione dell'API Topics, solleva domande e segui la discussione in merito ai problemi relativi al repository dell'API.
- W3C: analizza i casi d'uso del settore nell'Migliorare il Web Advertising Business Group.
- Annunci: visualizza o partecipa alla mailing list.
- Assistenza per gli sviluppatori di Privacy Sandbox: fai domande e partecipa alle discussioni nel repository dell'assistenza per gli sviluppatori di Privacy Sandbox.
- Chromium: segnala un bug di Chromium per porre domande sull'implementazione attualmente disponibile per i test in Chrome.