Dowiedz się, jak korzystać z tego interfejsu API, w tym jak używać flag Chrome do testowania.
Stan implementacji
- Interfejs Topics API został właśnie ukończony w fazie dyskusji publicznych i jest obecnie dostępny dla 99% użytkowników, skalowalny w zakresie 100%.
- Aby przesłać opinię o interfejsie Topics API, zgłoś problem za pomocą wyjaśnienia Topics lub weź udział w dyskusjach w grupie o ulepszaniu reklam internetowych. Wyjaśnienie zawiera kilka pytań otwartych, które nadal wymagają doprecyzowania.
- Oś czasu Piaskownicy prywatności zawiera ramy czasowe wdrożenia interfejsu Topics API i innych ofert pakietowych Piaskownicy prywatności.
- Topics API: najnowsze aktualizacje – szczegółowe informacje o zmianach i ulepszeniach interfejsu Topics API oraz ich implementacjach.
Wypróbuj
Dostępne są 2 wersje demonstracyjne interfejsu Topics API, które umożliwiają Ci wypróbowanie interfejsu Topics jako pojedynczy użytkownik.
- Prezentacja interfejsu JavaScript API: topics-demo.glitch.me.
- Demonstracja w nagłówku: topics-fetch-demo.glitch.me
Aby wypróbować model klasyfikacji Topics, możesz też uruchomić colab Topics.
Używaj interfejsu JavaScript API, aby uzyskiwać dostęp do tematów i rejestrować je jako zaobserwowane
Interfejs Topics JavaScript API ma 1 metodę: document.browsingTopics()
. Ma to 2 cele:
- Powiedz przeglądarce, aby zarejestrowała bieżącą wizytę na stronie jako zaobserwowaną przez rozmówcę, aby później można było wykorzystać te informacje do obliczenia tematów dla użytkownika (dla rozmówcy).
- Dostęp do tematów użytkownika, które zostały zaobserwowane przez rozmówcę.
Metoda zwraca obietnicę, która prowadzi do tablicy obejmującej maksymalnie 3 tematy, po 1 dla każdej z 3 ostatnich epoz, w losowej kolejności. Epoka to przedział czasu w implementacji Chrome ustawiony na tydzień.
Każdy obiekt tematu w tablicy zwróconej przez document.browsingTopics()
ma te właściwości:
configVersion
: ciąg znaków identyfikujący bieżącą konfigurację Topics API, np.chrome.2
modelVersion
: ciąg znaków identyfikujący klasyfikator systemów uczących się używany do ustalenia tematów dla witryny, np.4
taxonomyVersion
: ciąg znaków identyfikujący zbiór tematów używanych przez przeglądarkę, np.2
topic
: liczba identyfikująca temat w mapie kategorii, np.309
version
: ciąg znaków zawierający elementyconfigVersion
,taxonomyVersion
imodelVersion
, np.chrome.2:2:4
Parametry opisane w tym przewodniku oraz szczegóły interfejsu API (takie jak rozmiar taksonomii, liczba tematów obliczonych na tydzień i liczba tematów zwracanych w przypadku każdego wywołania) mogą się zmieniać w miarę uwzględniania opinii ekosystemu i powtarzania interfejsu API.
Wykrywanie obsługi metody document.browsingTopics.
Zanim użyjesz tego interfejsu API, sprawdź, czy jest on obsługiwany przez przeglądarkę i dostępny w dokumencie:
'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');
Uzyskiwanie dostępu do tematów przez JavaScript API
Oto podstawowy przykład możliwego użycia interfejsu API w celu uzyskania dostępu do tematów bieżącego użytkownika.
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.
}
Uzyskiwanie dostępu do tematów bez zmiany stanu
document.browsingTopics()
zwraca tematy zaobserwowane przez rozmówcę w przypadku bieżącego użytkownika. Domyślnie metoda powoduje również, że przeglądarka rejestruje bieżącą wizytę na stronie jako zaobserwowaną przez element wywołujący, więc może ona być później używana do obliczania tematów. Od wersji Chrome 108 metoda może być przekazywana jako opcjonalny argument, który pozwala pomijać rejestrowanie wizyty na stronie: {skipObservation:true}
.
Innymi słowy, {skipObservation:true}
oznacza, że wywołanie metody nie spowoduje uwzględnienia bieżącej strony w obliczeniach dotyczących tematów.
Uzyskiwanie dostępu do tematów za pomocą nagłówków i oznaczanie ich jako obserwowanych
Możesz uzyskiwać dostęp do tematów, a także oznaczać wizyty na stronie jako zaobserwowane za pomocą nagłówków żądania i odpowiedzi.
Korzystanie z nagłówka może być znacznie skuteczniejsze niż korzystanie z interfejsu JavaScript API, ponieważ interfejs API wymaga utworzenia elementu iframe z innych domen i wywołania z niego wywołania document.browsingTopics()
. (W wywołaniu należy użyć elementu iframe z innych domen, ponieważ do zapewnienia, że przeglądarka zwraca tematy odpowiednie do elementu wywołującego używany jest kontekst, z którego jest wywoływany interfejs API). Szczegółowe omówienie wyjaśnienia Topics: Czy istnieje sposób wysyłania tematów przy użyciu opcji Pobierz jako nagłówek żądania? .
Tematy są dostępne z poziomu nagłówka Sec-Browsing-Topics
żądania fetch()
lub XHR
.
Ustawienie nagłówka Observe-Browsing-Topics: ?1
w odpowiedzi na żądanie sprawia, że przeglądarka rejestruje bieżącą wizytę na stronie jako zaobserwowaną przez element wywołujący, więc może ona być później używana przy obliczaniu tematów.
Dostęp do tematów i ich rejestrowanie za pomocą nagłówków HTTP można uzyskać na 2 sposoby:
fetch()
: dodaj{browsingTopics: true}
do parametru opcji żądaniafetch()
. Uproszczony przykład przedstawia prezentację nagłówka Tematy.- Atrybut iframe: dodaj atrybut
browsingtopics
do elementu<iframe>
lub ustaw odpowiadającą mu właściwość JavaScriptiframe.browsingTopics = true
. Domena źródła elementu iframe, którą można zarejestrować, to domena wywołująca, np. w przypadku<iframe src="https://example.com" browsingtopics></iframe>
element wywołujący toexample.com
.
Kilka dodatkowych uwag na temat nagłówków:
- Nastąpi śledzenie przekierowań, a tematy wysłane w żądaniu przekierowania będą powiązane z adresem URL przekierowania.
- Nagłówek żądania nie zmieni stanu elementu wywołującego, chyba że istnieje odpowiedni nagłówek odpowiedzi. Oznacza to, że bez nagłówka odpowiedzi wizyta na stronie nie zostanie zarejestrowana jako zaobserwowana, więc nie będzie miała wpływu na obliczenie tematu użytkownika w następnej epoce.
- Nagłówek odpowiedzi jest uznawany tylko wtedy, gdy odpowiednie żądanie zawiera nagłówek tematów.
- Adres URL żądania zawiera domenę, którą można zarejestrować, która jest zarejestrowana jako domena wywołująca.
Debugowanie implementacji interfejsu API
Strona chrome://topics-internals
będzie dostępna w Chrome na komputery po włączeniu interfejsu Topics API. Zostaną wyświetlone tematy dotyczące bieżącego użytkownika, tematy ustalone dla nazw hostów oraz informacje techniczne dotyczące implementacji interfejsu API. Cały czas ulepszamy i ulepszamy jej wygląd na podstawie opinii deweloperów. Możesz też przesłać opinię na bugs.chromium.org.
Wyświetlanie tematów obliczonych dla Twojej przeglądarki
Użytkownicy mogą wyświetlać informacje o tematach zaobserwowanych w przeglądarce w bieżącej i poprzedniej epoce, korzystając z usługi chrome://topics-internals
.
Ten zrzut ekranu pokazuje, że ostatnio odwiedzone strony to topics-demo-cats.glitch.me
i cats-cats-cats-cats.glitch.me
. Powoduje to, że interfejs Topics API wybiera Pets
i Cats
jako 2 najpopularniejsze tematy w bieżącej epoki. Pozostałe 3 tematy zostały wybrane losowo, ponieważ nie ma wystarczającej historii przeglądania (w witrynach, które obserwują tematy), aby wyświetlić 5 tematów.
Kolumna Obserwowane przez domeny kontekstowe (zaszyfrowane) zawiera zaszyfrowaną wartość nazwy hosta, w której zaobserwowano temat.
Wyświetl tematy ustalone dla nazw hostów
Możesz też wyświetlać tematy ustalane przez model klasyfikacji Topics w przypadku co najmniej 1 nazwy hosta w interfejsie chrome://topics-internals
.
Obecna implementacja interfejsu Topics API określa tematy wyłącznie na podstawie nazw hostów, a nie innych części adresu URL.
Aby wyświetlać tematy domniemane z klasyfikatora chrome://topics-internals
, używaj tylko nazw hostów (bez protokołu i ścieżki). Jeśli spróbujesz umieścić znak „/” w polu Host, chrome://topics-internals
wyświetli błąd.
Wyświetlanie informacji o interfejsie Topics API
Informacje o implementacji i ustawieniach interfejsu Topics API, takich jak wersja mapy kategorii i czas trwania epoki, znajdziesz na stronie chrome://topics-internals
. Te wartości odzwierciedlają domyślne ustawienia interfejsu API lub parametry skonfigurowane z poziomu wiersza poleceń. Może to pomóc w potwierdzeniu, czy flagi wiersza poleceń działają zgodnie z oczekiwaniami.
W tym przykładzie wartość time_period_per_epoch
została ustawiona na 15 sekund (wartość domyślna to 7 dni).
Parametry widoczne na zrzucie ekranu odpowiadają flagom, które można ustawić, gdy uruchamiasz Chrome z poziomu wiersza poleceń. Na przykład w wersji demonstracyjnej pod adresem topics-fetch-demo.glitch.me zaleca się użycie tych flag:
--enable-features=BrowsingTopics,BrowsingTopicsParameters:time_period_per_epoch/15s/max_epoch_introduction_delay/3s,PrivacySandboxAdsAPIsOverride,PrivacySandboxSettings3,OverridePrivacySandboxSettingsLocalTesting
Na liście poniżej objaśniamy poszczególne parametry, ich wartości domyślne i przeznaczenie.
Flagi Chrome
BrowsingTopics
- Wartość domyślna: włączona
- Wskazuje, czy interfejs Topics API jest włączony.
PrivacySandboxAdsAPIsOverride
- Wartość domyślna: włączona
- Włącza interfejsy API reklam: Attribution Reporting, Protected Audience, Tematy, Chronione ramki.
PrivacySandboxSettings4
- Wartość domyślna: wyłączona
- Włącza czwartą wersję ustawień interfejsu Piaskownicy prywatności.
OverridePrivacySandboxSettingsLocalTesting
- Wartość domyślna: włączona
- Jeśli ta opcja jest włączona, do włączenia funkcji Piaskownicy prywatności przeglądarka nie wymaga już włączenia ustawień.
BrowsingTopicsBypassIPIsPubliclyRoutableCheck
- Wartość domyślna: wyłączona
- Jeśli ta opcja jest włączona, przy określaniu, czy strona może być uwzględniana w obliczeniach tematów, pomijane jest sprawdzanie, czy adres IP jest publicznie dostępny.
BrowsingTopics:number_of_epochs_to_expose
- Wartość domyślna: 3
- Liczba okresów, od których oblicza się tematy do przekazania do kontekstu żądania. Przeglądarka będzie wewnętrznie zachowywać nie więcej niż N+1 epok.
BrowsingTopics:time_period_per_epoch
- Wartość domyślna: 7d-0h-0m-0s
- Czas trwania każdej epoki. Do debugowania warto ustawić tę wartość na (np.) 15 sekund zamiast domyślnej wartości 7 dni.
BrowsingTopics:number_of_top_topics_per_epoch
- Wartość domyślna: 5
- Liczba tematów obliczonych dla każdej epoki.
BrowsingTopics:use_random_topic_probability_percent
- Wartość domyślna: 5
- prawdopodobieństwo, że konkretny temat w danej epoki jest zwracany losowo z całej taksonomii tematów. Losowość jest zależna od epoki i miejsca.
BrowsingTopics:number_of_epochs_of_observation_data_to_use_for_filtering
- Wartość domyślna: 3
- Liczba okresów, z których dane o korzystaniu z interfejsu API (np. obserwacje tematów) zostaną wykorzystane do filtrowania tematów pod kątem kontekstu wywołania.
BrowsingTopics:max_number_of_api_usage_context_domains_to_keep_per_topic
- Wartość domyślna: 1000
- Maksymalna liczba obserwowanych domen kontekstowych, które mają być przechowywane w przypadku każdego z głównych tematów. Celem jest ograniczenie używanej pamięci.
BrowsingTopics:max_number_of_api_usage_context_entries_to_load_per_epoch
- Wartość domyślna: 100 000
- Maksymalna liczba wpisów, które można pobrać z bazy danych dla każdego zapytania w kontekście użycia interfejsu API. Zapytanie zostanie zrealizowane raz na okres w czasie obliczania tematów. Celem jest ograniczenie szczytowego wykorzystania pamięci.
BrowsingTopics:max_number_of_api_usage_context_domains_to_store_per_page_load
- Wartość domyślna: 30
- Maksymalna liczba domen kontekstu wykorzystania interfejsu API, które mogą być przechowywane przy każdym wczytaniu strony.
BrowsingTopics:config_version
- Wartość domyślna: 1
- koduje parametry konfiguracji interfejsu Topics API. Każdy numer wersji powinien być zmapowany tylko na jeden zbiór konfiguracji. Aktualizowanie parametrów konfiguracji bez aktualizowania parametru
config_version
powinno się sprawdzić w przypadku testów lokalnych, ale w niektórych sytuacjach może spowodować niespójność stanu przeglądarki i doprowadzić do jej awarii, na przykład przez zaktualizowanienumber_of_top_topics_per_epoch
. BrowsingTopics:taxonomy_version
- Wartość domyślna: 1
- wersja taksonomii używana przez interfejs API.
Rezygnacja z używania witryny
Możesz zrezygnować z obliczania tematów na określonych stronach w swojej witrynie, umieszczając na danej stronie nagłówek Permissions-Policy: browsing-topics=()
Permissions-Policy. W ten sposób zapobiegnie to obliczaniu tematów tylko wszystkim użytkownikom tej strony. Kolejne wizyty na innych stronach w witrynie nie będą miały wpływu na kolejne strony: jeśli skonfigurujesz zasadę blokowania interfejsu Topics API na jednej stronie, nie będzie to miało wpływu na pozostałe strony.
Możesz też kontrolować, które osoby trzecie mają dostęp do tematów na Twojej stronie, używając nagłówka Permissions-Policy
do kontrolowania dostępu aplikacji zewnętrznych do interfejsu Topics API. Jako parametrów nagłówka użyj self
i wszelkich domen, którym chcesz zezwolić na dostęp do interfejsu API. Aby na przykład całkowicie wyłączyć korzystanie z interfejsu Topics API we wszystkich kontekstach przeglądania z wyjątkiem Twojego źródła i https://example.com
, ustaw ten nagłówek odpowiedzi HTTP:
Permissions-Policy: browsing-topics=(self "https://example.com")
Dalsze kroki
- Dowiedz się więcej o tym, jakie są tematy i jak działają.
- Wypróbuj prezentację.
Więcej informacji
Angażuj i dziel się opiniami
- GitHub czytanie objaśnień interfejsu Topics API oraz zgłaszanie pytań i podsumowanie dyskusji w repozytorium API.
- W3C omówienia przypadków użycia w branży w ramach udoskonalania grupy biznesowej związanej z reklamami internetowymi.
- Ogłoszenia: dołącz do listy adresowej lub wyświetl ją.
- Pomoc dla deweloperów Piaskownicy prywatności: zadawaj pytania i bierz udział w dyskusjach w repozytorium pomocy dla deweloperów Piaskownicy prywatności.
- Chromium zgłoś błąd Chromium, aby zadać pytania na temat implementacji, która jest obecnie dostępna do testowania w Chrome.