Przewodnik dla programistów interfejsu Topics API

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 wersję demonstracyjną

Dostępne są 2 wersje demonstracyjne interfejsu Topics API, które umożliwiają Ci wypróbowanie interfejsu Topics jako pojedynczy użytkownik.

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 elementy configVersion, taxonomyVersion i modelVersion, 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. Użycie nagłówka może być znacznie skuteczniejsze niż wywoływanie interfejsu JavaScript API.

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 żądania fetch(). Uproszczony przykład przedstawia prezentację nagłówka Tematy.
  • Atrybut iframe: dodaj atrybut browsingtopics do elementu <iframe> lub ustaw odpowiadającą mu właściwość JavaScript iframe.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 to example.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.

Strona chrome://topics-internals z wybranym panelem stanu tematów.
Panel Stan tematów na stronie chrome://topics-internals zawiera identyfikatory tematów, losowe i rzeczywiste przypisania tematów oraz taksonomię i wersje modeli.

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.

Strona chrome://topics-internals z wybranym panelem Classifier.
Panel Classifier na stronie chrome://topics-internals zawiera wybrane tematy, odwiedzone hosty oraz wersję i ścieżkę modelu.

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

Strona chrome://topics-internals z zaznaczonym panelem Funkcje i parametry.
Panel chrome://topics-internals Funkcje i parametry na stronie chrome://topics-internals pokazuje włączone funkcje, czas na epokę, liczbę epok używanych do obliczania tematów, wersję taksonomii i inne ustawienia.

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 zaktualizowanie number_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

Więcej informacji

Angażuj i dziel się opiniami