Przewodnik dla programistów interfejsu Topics API

Dowiedz się, jak korzystać z interfejsu API, w tym jak używać flag Chrome do testowania.

Stan wdrożenia

  • 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ą

Istnieją 2 wersje demonstracyjne interfejsu Topics API, które umożliwiają wypróbowanie tego interfejsu jako pojedynczy użytkownik.

Możesz też uruchomić colab w usłudze Topics, aby wypróbować model klasyfikacji 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:

  • Poleć przeglądarce, aby zarejestrowała bieżącą wizytę na stronie jako obserwowaną przez osobę wywołującą, aby można ją było później wykorzystać do obliczenia tematów dla użytkownika (dla osoby wywołującej).
  • Dostęp do tematów użytkownika zaobserwowanych przez wywołującego.

Ta metoda zwraca obietnicę przedstawiającą tablicę maksymalnie 3 tematów, po jednym dla każdego z 3 ostatnich epok, w kolejności losowej. Epoka to okres ustawiony na tydzień (w implementacji Chrome).

Każdy obiekt tematu w tablicy zwróconej przez funkcję document.browsingTopics() ma te właściwości:

  • configVersion: ciąg znaków identyfikujący bieżącą konfigurację interfejsu Topics API, na przykład chrome.2.
  • modelVersion: ciąg znaków identyfikujący klasyfikator systemów uczących się używany do ustalania tematów 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 taksonomii, na przykład 309
  • version: ciąg znaków łączący configVersion, taxonomyVersion i modelVersion, np. chrome.2:2:4

Parametry opisane w tym przewodniku oraz szczegóły dotyczące interfejsu API (takie jak rozmiar taksonomii, liczba tematów obliczonych na tydzień i liczba tematów zwracanych w ramach jednego wywołania) mogą ulec zmianie w miarę uwzględniania opinii z ekosystemu i powtarzania interfejsu API.

Wykrywanie obsługi interfejsu document.browsingTopics

Zanim użyjesz tego interfejsu API, sprawdź, czy jest on obsługiwany przez przeglądarkę i czy jest 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');

Dostęp do tematów za pomocą interfejsu JavaScript API

Oto podstawowy przykład wykorzystania interfejsu API do uzyskiwania dostępu do tematów dla 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.
}

Dostęp do tematów bez modyfikowania stanu

document.browsingTopics() zwraca tematy zaobserwowane przez dzwoniącego dla bieżącego użytkownika. Domyślnie metoda powoduje też, że przeglądarka rejestruje bieżącą wizytę na stronie zgodnie z obserwowaną przez osobę wywołującą, aby można ją było później wykorzystać przy obliczaniu tematów. Od wersji Chrome 108 metoda ta może przekazywać opcjonalny argument umożliwiający pominięcie rejestrowania wizyty na stronie: {skipObservation:true}.

Inaczej mówiąc, {skipObservation:true} oznacza, że wywołanie metody nie powoduje uwzględniania bieżącej strony w obliczaniu tematów.

Uzyskiwanie dostępu do tematów i oznaczanie ich jako obserwowanych za pomocą nagłówków

Możesz przeglądać tematy, a także oznaczać wizyty na stronie jako obserwowane, korzystając z request i nagłówki odpowiedzi.

Użycie nagłówka może być znacznie skuteczniejsze niż JavaScript API, ponieważ wymaga utworzenia elementu iframe z innych domen i wywołania z niego document.browsingTopics(). (Do wywołania należy użyć elementu iframe z innych domen, ponieważ kontekst, z którego wywoływany jest interfejs API, jest używany do zapewnienia, że przeglądarka zwróci tematy odpowiednie do elementu wywołującego). W ramach wyjaśnienia Topics API została opublikowana szersza dyskusja: Czy istnieje jakiś sposób wysyłania tematów za pomocą narzędzia 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 zgodnie z obserwowaną przez osobę wywołującą, aby można go było później użyć przy obliczaniu tematów.

Dostęp do tematów i obserwowanie tematów można uzyskać za pomocą nagłówków HTTP na 2 sposoby:

  • fetch(): dodaj {browsingTopics: true} do parametru „Options” (Opcje) w żądaniu fetch(). Demonstracja nagłówka Topics API to uproszczony przykład.
  • Atrybut iframe: dodaj atrybut browsingtopics do elementu <iframe> lub ustaw jego odpowiedni kod JavaScript usługę iframe.browsingTopics = true. Możliwą do zarejestrowania domeną źródła iframe jest domena wywołująca: na przykład w przypadku <iframe src="https://example.com" browsingtopics></iframe>: rozmówca to example.com.
.

Kilka dodatkowych uwag na temat nagłówków:

  • Następnie będziemy śledzić przekierowania, a tematy wysłane w żądaniu przekierowania będą powiązane z odpowiednim adresem URL przekierowania.
  • Nagłówek żądania nie zmienia stanu elementu wywołującego, chyba że ma 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 przez użytkownika w następnej epoce.
  • Nagłówek odpowiedzi jest uwzględniany tylko wtedy, gdy odpowiednie żądanie zawierało nagłówek tematów.
  • Adres URL żądania zawiera domenę, którą można zarejestrować, która jest zarejestrowana jako domena wywołującego.

Debugowanie implementacji interfejsu API

Strona chrome://topics-internals będzie dostępna w Chrome na komputerach po włączeniu interfejsu Topics API. Zostaną wyświetlone tematy dla bieżącego użytkownika, tematy ustalone na podstawie nazw hostów oraz informacje techniczne dotyczące implementacji interfejsu API. Kierując się opiniami deweloperów, pracujemy nad tą stroną ponownie i poprawiamy jej wygląd. Swoją opinię możesz zgłosić na stronie bugs.chromium.org.

Wyświetlanie tematów obliczonych dla przeglądarki

Użytkownicy mogą przeglądać informacje o tematach obserwowanych w przeglądarce w obecnej i poprzedniej epoce, otwierając stronę chrome://topics-internals.

Strona chrome://topics-internals z wybranym panelem Stan tematów
Panel stanu 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 najważniejsze tematy w bieżącej epoce. Pozostałe 3 tematy zostały wybrane losowo, ponieważ historia przeglądania (w witrynach z uwzględnieniem tematów) jest niewystarczająca, aby można było przedstawić 5 tematów.

Kolumna Obserwowane przez domeny kontekstu (zahaszowane) zawiera zaszyfrowaną wartość nazwy hosta, w której przypadku zaobserwowano temat.

Wyświetl tematy ustalone na podstawie nazw hostów

Możesz też wyświetlać tematy wywnioskowane przez model klasyfikacji Topics w przypadku co najmniej 1 nazwy hosta w interfejsie chrome://topics-internals.

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

Obecna implementacja Topics API określa tematy tylko na podstawie nazw hostów. a nie z żadnej innej części adresu URL.

Używaj tylko nazw hostów (bez protokołu i ścieżki) do wyświetlania tematów wywnioskowanych z klasyfikatora chrome://topics-internals. Jeśli spróbujesz dodać znak „/”, chrome://topics-internals wyświetli błąd w polu Host.

Wyświetlanie informacji o interfejsie Topics API

Informacje o implementacji i ustawieniach interfejsu Topics API, takie jak wersja taksonomii i czas trwania epoki, znajdziesz w tym artykule: 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, że flagi wiersza poleceń działają zgodnie z oczekiwaniami.

W tym przykładzie pole time_period_per_epoch zostało ustawione na 15 sekund (domyślna wartość to 7 dni).

Strona chrome://topics-internals z wybranym panelem Funkcje i Parametry.
Panel Funkcje i Parametry na stronie chrome://topics-internals pokazują włączone funkcje, czas w poszczególnych epokach, 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ć podczas uruchamiania Chrome z poziomu wiersza poleceń. Na przykład w wersji demonstracyjnej na topics-fetch-demo.glitch.me zalecamy 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 opisano każdy parametr, jego wartość domyślną i jego przeznaczenie.

Flagi Chrome

BrowsingTopics
Wartość domyślna: włączona
Określa, czy interfejs Topics API jest włączony.

PrivacySandboxAdsAPIsOverride
Wartość domyślna: włączona
Włącza interfejsy API reklam: Attribution Reporting, Protected Audience, Topics i Fenceed Frame.

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, przeglądarka nie wymaga już włączenia podstawowych ustawień dla włączenie funkcji Piaskownicy prywatności.

BrowsingTopicsBypassIPIsPubliclyRoutableCheck
Wartość domyślna: wyłączona
Jeśli ta opcja jest włączona, umożliwia sprawdzenie, czy adres IP można kierować publicznie pomijane przy określaniu, czy strona może być uwzględniana w tematach. obliczeń.

BrowsingTopics:number_of_epochs_to_expose
Wartość domyślna: 3
Liczba epok, z którego ma obliczyć tematy, które mają zostać przekazane osobie, która przesłała żądanie i dodaje kontekst. Wewnętrznie przeglądarka zachowuje do N+1 epo.

BrowsingTopics:time_period_per_epoch
Wartość domyślna: 7d-0h-0m-0s
Czas trwania każdej epoki. Do debugowania może być korzystne ustawienie tego ustawienia na 15 sekund zamiast domyślnych 7 dni.

BrowsingTopics:number_of_top_topics_per_epoch
Wartość domyślna: 5
Liczba tematów obliczonych na epokę.

BrowsingTopics:use_random_topic_probability_percent
Wartość domyślna: 5
Prawdopodobieństwo, że dany temat w danej epoce będzie zwracany losowo z całą taksonomię 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
Ile epok danych o korzystaniu z interfejsu API (np. dotyczących obserwacji tematów) zostaną wykorzystane do filtrowanie tematów pod kątem kontekstu połączenia.

BrowsingTopics:max_number_of_api_usage_context_domains_to_keep_per_topic
Wartość domyślna: 1000
Maksymalna liczba domen kontekstu, które można zachować dla każdego głównego tematu. Zamiar jest ograniczanie ilości 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 dla kontekstu użycia interfejsu API. Zapytanie będzie wykonywane raz na epokę przy obliczaniu tematów obecnie się znajdujesz. Ma to na celu 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 na wczytanie strony.

BrowsingTopics:config_version
Wartość domyślna: 1
Koduje parametry konfiguracyjne interfejsu Topics API. Każdy numer wersji powinien być mapowanych na jeden zbiór konfiguracji. Aktualizowanie parametrów konfiguracji bez aktualizowania parametru config_version powinno zwykle sprawdza się w testach lokalnych, ale w niektórych przypadkach może spowodować, że przeglądarka będzie i może spowodować awarię przeglądarki, np. zaktualizowanie number_of_top_topics_per_epoch

BrowsingTopics:taxonomy_version
Wartość domyślna: 1
Mapa kategorii wersji używanej przez interfejs API.

Rezygnowanie z udostępniania witryny

Możesz zrezygnować z obliczania tematów na wybranych stronach w swojej witrynie. Aby to zrobić, umieść na stronie nagłówek Permissions-Policy: browsing-topics=() Permissions-Policy, aby uniemożliwić obliczanie tematów tylko w przypadku wszystkich użytkowników tej strony. Kolejne wizyty na innych stronach w witrynie nie będą miały wpływu na inne strony. Jeśli ustawisz zasadę blokowania interfejsu Topics API na jednej stronie, nie będzie to miało wpływu na inne 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 innych firm do interfejsu Topics API. Jako parametrów nagłówka użyj pola self i 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 elementu 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