Przewodnik po integracji interfejsu Topics API

Dowiedz się, jak korzystać z interfejsu Topics API pod kątem konkretnych przypadków użycia technologii reklamowych.

Zanim zaczniesz

Pierwszym krokiem jest zapoznanie się z interfejsem Topics API i usługami.

  1. Zapoznaj się z dokumentacją dla deweloperów:
    1. Zacznij od przeczytania omówienia, aby zapoznać się z interfejsem Topics API i jego możliwościami.
    2. Obejrzyj film instruktażowy z prezentacją Topics (film).
    3. Zapoznaj się z prezentacjami w nagłówku Topics i JavaScript API.
    4. Utwórz rozwidlenie wersji demonstracyjnych (obie zawierają linki do swojego kodu) i uruchom je ze swojej witryny.
    5. Aby dowiedzieć się więcej, zapoznaj się z objaśnieniem interfejsu API.
  2. Sprawdź stan implementacji i oś czasu interfejsu Topics API.
  3. Dowiedz się, jaką rolę odgrywa interfejs API w poprawianiu trafności reklam w przyszłości bez plików cookie.
  4. Aby otrzymywać powiadomienia o zmianach stanu w interfejsie API, dołącz do listy adresowej dla deweloperów i bądź na bieżąco z najnowszymi aktualizacjami Topics.
  5. Możesz być na bieżąco z najnowszymi wiadomościami o interfejsie Topics API.
  6. Weź udział w rozmowie przez problemy z GitHubem lub połączenia W3C.
  7. Jeśli napotkasz nieznane terminy, przeczytaj słowniczek Piaskownicy prywatności.
  8. Więcej informacji o pojęciach związanych z Chrome, takich jak flagi Chrome, znajdziesz w krótkich filmach i artykułach na stronie goo.gle/cc.

Kompiluj i testuj lokalnie

Z tej sekcji dowiesz się, jak możesz wypróbować interfejs Topics API jako indywidualny programista.

  1. Lokalne testy i wdrożenie (szacowany czas: około 2 dni)
    1. Włącz interfejs API w lokalnej przeglądarce z poziomu wiersza poleceń, używając flag funkcji. Przetestuj wersje demonstracyjne nagłówka i interfejsu JavaScript API, aby zobaczyć, jak działają tematy (film instruktażowy).
    2. Uruchom Topics colab, aby przetestować wnioskowanie na tematy z użyciem modelu systemów uczących się Topics.

Włącz tematy w przeglądarce

Aby włączyć interfejs Topics API we własnej instancji Chrome na potrzeby testów lokalnych, masz 2 możliwości:

  1. Otwórz stronę chrome://flags/#privacy-sandbox-ads-apis i włącz interfejsy API Piaskownicy prywatności.
  2. (Zalecane) Uruchamiaj Chrome z poziomu wiersza poleceń, używając flag Chromium przy użyciu parametrów specyficznych dla interfejsu Topics API, aby odpowiednio skonfigurować urządzenie.
Włącz interfejsy API Piaskownicy prywatności na stronie chrome://flags/#privacy-sandbox-ads-apis.
Włącz interfejsy API Piaskownicy prywatności.

Uruchamianie Chrome z poziomu wiersza poleceń zapewnia dokładniejszą kontrolę nad funkcjami Topics. Możesz na przykład ustawić okresy dla tematów (przedział czasowy używany przez interfejs API do obliczania zainteresowań użytkowników) i skonfigurować działanie interfejsu API zgodnie z własnymi potrzebami.

Pamiętaj, że jeśli włączona jest opcja chrome://flags/#privacy-sandbox-ads-apis, zastąpi ona ustawienie epoki wiersza poleceń i przywróci wartość domyślną (obecnie jest to tydzień).

Przedstawienie mechaniki interfejsu Topics API

Aby uzyskać lokalny wgląd w mechanizmy interfejsu Topics API, możesz skorzystać z narzędzi chrome://topics-internals.

Zapoznaj się z interfejsem Topics API na stronie chrome://topics-internals.
Karta stanu tematów na stronie chrome://topics-internals.

Użyj narzędzia Topics API Internals, aby przetestować klasyfikator na podstawie odwiedzanych witryn.

Za pomocą tego narzędzia możesz sprawdzić:

  • Stan Topics (Stan tematów): wyświetla tematy zaobserwowane dla bieżącego użytkownika.
  • Klasyfikator: wyświetla podgląd tematów wykrytych dla nazw hostów.
  • Funkcje i parametry: przejrzyj wartości parametrów interfejsu API, aby sprawdzić, czy flagi funkcji działają zgodnie z oczekiwaniami.

Dowiedz się, jak debugować Topics przy użyciu narzędzia wewnętrznego.

Jak interfejs API zwraca tematy

Jeśli Chrome nie będzie mieć wystarczającej liczby obserwowanych tematów, aby utworzyć 5 najpopularniejszych tematów w danej epoki (jeden tydzień), interfejs Topics API doda losowe tematy, aby wybrać 5 najważniejszych tematów. Kolumna Wewnętrzne dane Topics o nagłówku Prawdziwy czy Losowy wskazuje, czy dany temat był oparty na rzeczywistej obserwacji, czy dodatkowym losowym dopełnieniem, które uzupełnia 5 pierwszych tematów. Więcej informacji o tym mechanizmie znajdziesz w objaśnieniu.

Temat na potrzeby każdej epoki jest wybierany losowo spośród 5 najpopularniejszych tematów użytkownika w danym okresie. Jeśli w danej epoce nie zaobserwowano wystarczającej liczby tematów, kolejne tematy zostaną wybrane losowo, tworząc w sumie 5 tematów. Te losowo wybrane tematy są filtrowane.

Aby jeszcze bardziej zwiększyć ochronę prywatności i mieć pewność, że wszystkie tematy zostaną zaprezentowane, istnieje 5% szans na to, że temat wybrany dla danej epoki zostanie losowo wybrany ze wszystkich tematów, a nie spośród obserwowanych tematów. Tak jak w powyższym przypadku, gdy zaobserwowano zbyt mało tematów, te losowo wybrane tematy nie będą filtrowane.

Więcej informacji o sposobie wybierania tematów znajdziesz w sekcji Klasyfikacja tematów.

Najważniejsze rekomendacje

  1. Zamknij (i zatrzymaj) wszystkie procesy Chrome przed rozpoczęciem nowego z użyciem flag.
  2. Jeśli przeprowadzasz testy w środowisku lokalnym, wyłącz chrome://flags/#privacy-sandbox-ads-apis, ponieważ zastępuje on ustawienia wiersza poleceń i przywraca wartości domyślne.
  3. Na stronie debugowania dowiesz się, jak interfejs Topics działa lokalnie.
  4. Jeśli masz pytania, przeczytaj Wyjaśnienie problemów z GitHubem.
  5. Jeśli interfejs API nie działa zgodnie z oczekiwaniami, skorzystaj z naszych wskazówek dotyczących rozwiązywania problemów.

Planowanie wdrożenia minimalnej wersji produktu

Interfejs Topics API zapewnia dostęp do tematów, które interesują użytkownika, bez konieczności śledzenia odwiedzanych przez niego witryn ani ujawniania historii nawigacji.

Wywołujący interfejs Topics API to encja, która wywołuje metodę JavaScript document.browsingTopics() lub obserwuje tematy i uzyskiwała dostęp przy użyciu nagłówków żądań HTTP. Twój kod, w tym przypadku eTLD+1, to element wywołujący. Wywołując interfejs Topics API, informujesz przeglądarkę użytkownika, że ma obserwować interesujące go tematy, gdy odwiedza on witrynę. Ta wizyta jest następnie brana pod uwagę przy obliczaniu tematów dla kolejnej epoki.

Interfejs Topics API służy do filtrowania wyników według wywołania lub domeny eTLD + 1 w kontekście wywołania. Inaczej mówiąc, źródło elementu iframe (w przypadku interfejsu JavaScript API) lub adres URL żądania pobierania (w przypadku nagłówków) jest uznawane za element wywołujący, a tematy są obliczane zgodnie z tym elementem.

Tę metodę ilustruje ten diagram:

Działania wykonywane przez interfejs Topics API, gdy użytkownicy odwiedzają witryny korzystające z tego interfejsu API.
Jak interfejs API obserwuje tematy i uzyskuje do nich dostęp.

Na tym schemacie:

  1. Użytkownik otwiera Chrome i odwiedza wiele witryn (klientA.example, klientB.example.br itp.), które zawierają element iframe Twojej technologii reklamowej (źródło: iframe.adtech.example) lub nagłówki pobierania przekazywanych połączeń.
    • Chrome będzie zapisywać tematy, które interesują tego użytkownika.
  2. Po 7 dniach korzystania z nawigacji, a interfejs Topics API rejestruje interesujące tematy, ten sam użytkownik na tym samym urządzeniu odwiedza witrynę docelową (wydawca-t.example). Topics API zwraca listę tematów, a w tym konkretnym przykładzie zwraca 1 temat obliczony na podstawie obserwacji tego użytkownika w poprzednim tygodniu.
    • Tylko przeglądarki użytkowników, którzy odwiedzili witryny zarejestrowane przez adtech.example w kroku 1, będą zwracać wyniki dotyczące tematów w kroku 2 (nazywamy to filtrowaniem obserwacji – nie możesz zobaczyć tematów użytkowników, których nie widziałeś wcześniej).
  3. Dzięki tej liście (na razie obejmującej 1 temat) możesz wywołać backend interfejsu API (ads.adtech.example/topics-backend), aby użyć danych dotyczących tematów jako części kontekstowego zbioru danych.
  4. Teraz, w zależności od konkretnego przypadku użycia, możesz zapewnić mu bardziej spersonalizowane środowisko, uzyskując dostęp do interesujących go tematów, które zaobserwowałeś w ciągu ostatnich tygodni.

Wywoływanie interfejsu Topics API

Istnieją 2 sposoby obserwowania tematów użytkownika i uzyskiwania do nich dostępu. Możesz użyć

  • Interfejs JavaScript API z elementu iframe:
    • Dodanie elementu iframe w witrynach docelowych (witrynach wydawców) zawierających kod JavaScript wywołujący interfejs Topics API za pomocą document.browsingTopics().
  • Opcja nagłówków:
    • Pobierz (zalecane) lub XHR (niezalecane i dostępne tylko podczas zakończonego testowania origin):
      • W żądaniach wysyłanych do backendu technologii reklamowych możesz uzyskać dostęp do tematów z nagłówka Sec-Browsing-Topics. To najskuteczniejsza opcja (małe opóźnienia umożliwiające obserwację tematów konkretnego użytkownika).
    • Używanie tagu iframe z atrybutem browsingtopics:
      • Możesz dodać element iframe z atrybutem browsingtopics, a Chrome uwzględni tematy (zaobserwowane w przypadku eTLD+1 elementu iframe) w nagłówku Sec-Browsing-Topics w żądaniu elementu iframe.

Implementacja za pomocą JavaScriptu i elementów iframe

Zalecamy utworzenie rozwidlenia prezentacji interfejsu JavaScript API interfejsu Topics lub prezentacji nagłówka i wykorzystania jednej z nich jako punktu wyjścia dla tworzenia kodu.

Możesz umieścić element <iframe> w kodzie HTML lub dodać element iframe dynamicznie za pomocą JavaScriptu. Jednym ze sposobów dynamicznego tworzenia elementu iframe jest użycie tego kodu JavaScript:

const iframe = document.createElement('iframe');
iframe.setAttribute('src', 'https://...');
document.body.appendChild(iframe);

Sprawdź, czy interfejs Topics API jest obsługiwany i dostępny na tym urządzeniu za pomocą wykrywania funkcji:

'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');

Wywołaj interfejs Topics API w tym elemencie iframe:

const topics = await document.browsingTopics();

Powinna wyświetlić się lista tematów obserwowanych przez tego użytkownika w ciągu ostatnich 3 tygodni. Pamiętaj, że ta lista może być pusta lub zawierać 1, 2 lub 3 tematy z okresu do 3 ostatnich tygodni.

Oto przykład tego, co zwraca interfejs API:

[{'configVersion': String, 
  'modelVersion': String, 
  'taxonomyVersion': String, 
  'topic': Number, 
  'version': String}]
  • configVersion: ciąg znaków identyfikujący bieżącą konfigurację.
  • modelVersion: ciąg znaków identyfikujący klasyfikator systemów uczących się używany do wnioskowania na podstawie tematów.
  • taxonomyVersion: ciąg znaków identyfikujący zbiór tematów aktualnie używanych przez przeglądarkę.
  • topic: liczba identyfikująca temat w taksonomii.
  • version: ciąg znaków zawierający połączenie configVersion i modelVersion.

Poczytaj więcej o tej implementacji.

Implementacja z użyciem nagłówków HTTP

Dostęp do tematów można uzyskać z nagłówka Sec-Browsing-Topics żądania fetch()/XHR lub z żądania iframe.

Nagłówki żądania i odpowiedzi służące do ustawiania i pobierania tematów.
Nagłówki elementów iframe i fetch().

Możesz oznaczyć tematy podane przez nagłówki żądań jako zaobserwowane, ustawiając nagłówek Observe-Browsing-Topics: ?1 w odpowiedzi na żądanie. Na podstawie tych tematów przeglądarka określa tematy interesujące użytkownika.

Jeśli interfejs API zwróci co najmniej 1 temat, żądanie pobierania do domeny eTLD+1, w której zaobserwowano tematy, będzie zawierać nagłówek Sec-Browsing-Topics podobny do tego: 

(325);v=chrome.1:1:1, ();p=P000000000

Jeśli interfejs API nie zwróci żadnych tematów, nagłówek będzie wyglądał tak:

();p=P0000000000000000000000000000000

Wartości nagłówków Sec-Browsing-Topics są dopełnione, co zmniejsza ryzyko, że osoba przeprowadzająca atak poznaje liczbę tematów ograniczonych do elementu wywołującego na podstawie długości nagłówka.

Wdróż za pomocą usługi fetch()

Na stronie wydawcy dodaj kod żądania pobierania, pamiętając, aby uwzględnić {browsingTopics: true}.

fetch('<topics_caller_eTLD+1>', {browsingTopics: true})
    .then((response) => {
        // Process the response
 })

W przeglądarkach, które obsługują interfejs API, żądanie fetch() będzie zawierać nagłówek Sec-Browsing-Topics z listą tematów zaobserwowanych dla nazwy hosta adresu URL żądania.

Implementacja za pomocą elementu iframe

Podobnie jak w przypadku żądania fetch() nagłówek Sec-Browsing-Topics zostanie wysłany, gdy użyjesz atrybutu browsingtopics w elemencie iframe.

<iframe src="<topics_caller_eTLD+1>" browsingtopics></iframe>

W tym przypadku będzie to , podobnie jak wywołanie pobierania.

Po stronie serwera – identyczne we wszystkich przypadkach

Aby tematy w nagłówku żądania Sec-Browsing-Topics zostały oznaczone przez przeglądarkę jako zaobserwowane, a jednocześnie uwzględniono obecną wizytę na stronie w obliczeniach głównego tematu w następnej epoce użytkownika, odpowiedź serwera musi zawierać parametr Observe-Browsing-Topics: ?1.

Oto przykład kodu JavaScript z użyciem elementu setHeader():

res.setHeader('Observe-Browsing-Topics', '?1');

Implementacja backendu Topics

Dodanie backendu do interfejsu Topics jest opcjonalne. Wybór zależy od tego, jak i gdzie chcesz używać tematów obliczanych na urządzeniu (w przeglądarce). 

// Use the language/framework/stack of your preference
function processTopicsBackendAPI(topics, user, domain, caller) {
  // Validate inputs
  // If the list is not empty, continue
  // Use topics as an additional contextual signal
}

Używaj tematów jako danych kontekstowych

Dane dotyczące tematów można traktować razem z innymi sygnałami, takimi jak adresy URL, słowa kluczowe, a nawet tagi, jako dodatkowy sygnał o odbiorcach.

Jak wyjaśniamy w artykule Maksymalizacja trafności reklam po plikach cookie innych firm, istnieje kilka metod wykorzystywania Topics do wyświetlania trafnych reklam. Część z nich zakłada tworzenie grup odbiorców na podstawie tematów, a inne jako sygnał do trenowania modeli systemów uczących się, które będą używane do określania dodatkowych zainteresowań odbiorców, a nawet do optymalizacji logiki ustalania stawek.

Kompilowanie i wdrażanie

  1. Zbieraj tematy, obserwując użytkowników w wersji produkcyjnej – jeszcze nieprzeskalowane (szacowany czas: około 1 tygodnia)
    1. Dostępne opcje: iframe i JavaScript lub nagłówki HTTP
    2. Zdefiniuj domenę elementu iframe.
    3. Utwórz kod JavaScript, używając jako odniesienia do kodu aplikacji demonstracyjnej, lub zaimplementuj opcję nagłówków.
    4. wdrożyć Topics w kontrolowanym środowisku (niektóre witryny produkcyjne).
    5. Dodaj implementację Topics do niektórych witryn docelowych (obecnie nie więcej niż 5 witryn).
    6. Testy funkcjonalne i weryfikacja.
  2. [Opcjonalnie] Użyj danych z Topics jako sygnału kontekstowego (z adresami URL, tagami itp.). (Szacowany czas: około 3 dni).
    1. Po otrzymaniu listy tematów możesz ją wysłać na zaplecze wraz z innymi sygnałami kontekstowymi.

Wdróż w niektórych witrynach docelowych

Teraz, gdy masz już kod, dodajmy go do niektórych witryn docelowych na potrzeby pierwszego testu i upewnij się, że interfejs API działa stabilnie i działa w tym kontrolowanym środowisku.

Zalecamy wybranie witryn docelowych, które:

  • Miesięczna liczba wizyt na stronie jest niewielka (mniej niż około 1 mln wizyt w miesiącu): zacznij od wdrożenia interfejsu API na małej grupie odbiorców.
  • Własność i kontrola: w razie potrzeby możesz szybko wyłączyć implementację bez złożonych zatwierdzeń.
  • Nie mają znaczenia biznesowego: takie wdrożenie może zakłócić wygodę użytkowników, dlatego zacznij od witryn o niskim ryzyku.
  • Łącznie maksymalnie 5 witryn: na razie nie potrzebujesz aż tak dużego ruchu ani ekspozycji.
  • Używaj różnych tematów: wybierz witryny z różnych kategorii (np. jedną na temat sportu, inną związaną z wiadomościami, inną związaną z jedzeniem i napojami itd.). Aby zweryfikować domeny i ich klasyfikację przez klasyfikator systemów uczących się Topics, możesz użyć wewnętrznego narzędzia do obsługi tematów w Chrome. Więcej informacji o debugowaniu znajdziesz w przewodniku dla programistów interfejsu Topics API.

Testy funkcjonalne i weryfikacja

Po wywołaniu interfejsu Topics API w tym ograniczonym środowisku możesz spodziewać się, że:

  • Pusta tablica tematów [], jeśli jest to pierwsze połączenie z tego urządzenia, dotyczące tej witryny i rozmówcy w ciągu ostatnich 7 dni.
  • Lista zawierająca od 0 do 3 tematów reprezentujących zainteresowania danego użytkownika.
  • Po 7 dniach obserwacji otrzymasz:
    • 1 temat reprezentujący zainteresowania danego użytkownika obliczony na podstawie historii nawigacji w danym tygodniu.
      • Ważna informacja: jeśli nie odnotujesz wystarczającej liczby tematów, aby umożliwić interfejsowi Topics API obliczenie 5 najpopularniejszych tematów w danym tygodniu, Topics doda do niej tyle losowych tematów, ile to konieczne, aby uzyskać łączną liczbę 5. Dowiedz się więcej o interfejsie API.
  • Nowy temat, który zastąpi 1 z 3, jeśli nawiążesz kontakt po upływie 4 tygodni obserwacji.
    • Dzieje się tak, ponieważ interfejs Topics API będzie działać stabilnie przez kolejne tygodnie i nie ujawnia zbyt wielu zainteresowań użytkowników. Szczegółowe informacje znajdziesz na GitHubie.
  • Jeśli nie będziesz obserwować tematów użytkownika przez ponad 3 tygodnie, interfejs Topics API ponownie zwróci pustą tablicę [].

Pomiar skuteczności i danych związanych z wrażeniami użytkowników.

  • Czas działania wywołań JavaScriptu kierowanych do interfejsu Topics API w elemencie iframe z innych domen powinien być mierzony na potrzeby przyszłej analizy wydajności. Pamiętaj, aby prawidłowo zbierać i przechowywać dane telemetryczne w zapleczu.
    • Kolejnym możliwym rodzajem danych do obliczania jest czas, jaki po otrzymaniu tematów zajmuje utworzenie elementu iframe i postMessage() tematów.

Rozwiązywanie problemów

Wywołuję interfejs Topics API, ale w wyniku widzę wartość null. Co mogę zrobić?
Jeśli wywołujesz Topics API w ciągu pierwszego tygodnia od obserwacji użytkownika, jest to normalne.

Najważniejsze rekomendacje

  1. Przetestuj kod frontendu, aby upewnić się, że JavaScript działa zgodnie z oczekiwaniami.

  2. Przetestuj zaplecze, aby otrzymać wyniki dotyczące tematów.

    1. Pamiętaj, aby prawidłowo skonfigurować typy danych i parametry interfejsu API backendu.
    2. Sprawdź, czy zaplecze są odpowiednio skonfigurowane.

  3. Z naszego doświadczenia wynika, że zanim zaczniesz otrzymywać wyniki dotyczące bardziej trafnych tematów, odczekaj co najmniej 3 tygodnie.

  4. Nie wszyscy użytkownicy będą mieli włączone tematy:

    1. Użytkownicy mogą jawnie wyłączyć interfejs Topics API.
    2. Strony wydawcy mogą kontrolować uprawnienia. Przeczytaj informacje o (rezygnacji) z przewodnika dla programistów interfejsu Topics API.
    3. Więcej informacji znajdziesz na chromestatus.com.

  5. Dodaj do tego środowiska wskaźniki i dostrzegalność: będą one potrzebne do analizy pierwszych wyników. Przykładowe dane:

    1. opóźnienia połączeń;
    2. błędy HTTP dotyczące wywołań tematów;

  6. Postaraj się ograniczyć zmiany w implementacji w ciągu pierwszych 3 tygodni.

Skalowanie do produkcji

Oto szczegółowy opis tego, jak zacząć z niego korzystać. Etapy procesu opisano poniżej.

  1. Skalowanie implementacji (produkcyjnej). Zostało to opisane poniżej.
    1. Dodaj element iframe do witryn wielu wydawców.
  2. Przetwarzanie i wykorzystywanie danych dotyczących tematów (szacowany czas: około 4 tygodni).
    1. Uwzględnij dane dotyczące tematów jako dodatkowy sygnał w połączeniu z innymi danymi.
    2. Pozyskuj partnerów testowych z określaniem stawek w czasie rzeczywistym.
    3. Przeprowadzaj testy praktyczne z tematami jako dodatkowym sygnałem do innych danych.

Skalowanie implementacji

W takim przypadku dane dotyczące tematów powinny być zbierane z niektórych witryn w kontrolowanym środowisku, co daje większą pewność co do całego rozwiązania.

Nadszedł czas, aby przeskalować tę implementację, wdrażając ten sam kod w większej liczbie witryn docelowych. Dzięki temu możesz obserwować więcej użytkowników, zbierać więcej danych o tematach i lepiej zrozumieć swoich odbiorców.

Zalecamy wykonanie tych czynności:

  1. Wdrażaj je stopniowo w swoich witrynach, zwłaszcza jeśli ruch jest duży.
  2. Przeprowadź testy obciążenia danych dotyczących tematów pod kątem oczekiwanego natężenia ruchu.
    1. Sprawdź, czy Twój zaplecze może obsługiwać dużą liczbę połączeń.
    2. Skonfiguruj zbieranie i logi wskaźników na potrzeby analizy.
  3. Bezpośrednio po wdrożeniu interfejsu Topics API sprawdź dane, aby wykryć ewentualne poważne problemy ze strony użytkowników. Regularnie sprawdzaj swoje dane.
  4. W przypadku zakłóceń lub nieoczekiwanych działań wycofaj wdrożenie i przeanalizuj logi, aby zrozumieć i rozwiązać problem.

Angażuj i dziel się opiniami