Przewodnik po integracji interfejsu Topics API

Dowiedz się, jak korzystać z interfejsu Topics API, aby spełniać określone przypadki 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 dotyczący tematów.
   3. Wypróbuj prezentacje nagłówka i JavaScriptu z interfejsu API w Topics.
   4. Utwórz rozwidlenie wersji demonstracyjnych (obydwa zawierają linki do swojego kodu) i uruchamiaj je we własnej witrynie.
   5. Aby dowiedzieć się więcej, zapoznaj się z objaśnieniem interfejsu API.
2. Sprawdź stan implementacji i oś czasu interfejsu Topics API.
3. Poznaj rolę interfejsu API w zapewnianiu 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, aby być na bieżąco z najnowszymi aktualizacjami Topics.
5. Bądź na bieżąco z najnowszymi wiadomościami o Topics API.
6. brać udział w rozmowie, korzystając z problemów z GitHubem lub połączeń W3C;
7. Jeśli natrafisz na nieznane terminy, zajrzyj do słowniczka 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 goo.gle/cc.

Kompilowanie i testowanie lokalnie

Z tej sekcji dowiesz się, jak pojedynczy deweloper wypróbować interfejs Topics API.

1. Lokalne testy i wdrażanie (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 JavaScriptu API, by zobaczyć działanie tematów (film instruktażowy).
   2. Przeprowadź sesję Topics colab, aby przetestować wnioskowanie dotyczące tematów za pomocą modelu systemów uczących się Topics.

Włącz w przeglądarce interfejs Topics API

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

1. Włącz wszystkie interfejsy Ad Privacy API w sekcji chrome://settings/adPrivacy.
2. (Zalecane) Uruchom Chrome z poziomu wiersza poleceń, używając flag Chromium i używając parametrów specyficznych dla interfejsu Topics API, aby odpowiednio je skonfigurować.

Masz większą kontrolę nad funkcjami interfejsu Topics, uruchamiając Chrome z poziomu wiersza poleceń. Możesz na przykład ustawić przedziały czasu w interfejsie Topics (okres używany przez interfejs API do obliczania zainteresowań użytkowników) i konfigurować jego działanie zgodnie z potrzebami.

Podgląd mechaniki interfejsu Topics API

Możesz lokalnie zapoznać się z mechaniką interfejsu Topics API, korzystając z narzędzi chrome://topics-internals.

Za pomocą wewnętrznego narzędzia Topics API możesz przetestować klasyfikator lokalnie na podstawie odwiedzanych przez Ciebie stron.

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

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

Dowiedz się, jak debugować tematy za pomocą narzędzia wewnętrznego.

Jak interfejs API zwraca tematy

Jeśli w Chrome nie ma wystarczającej liczby obserwowanych tematów, aby utworzyć 5 najpopularniejszych tematów w danej epoki (tydzień), interfejs Topics API doda losowe tematy, aby uzupełnić listę 5 najpopularniejszych tematów. Kolumna Topics Internals z nagłówkiem Prawdziwe lub Losowe wskazuje, czy dany temat został powodowany prawdziwą obserwacją, czy też dodatkowym losowym wypełnieniem w celu uzupełnienia 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 epoce zaobserwowano niewystarczającą liczbę tematów, dodatkowe tematy zostaną wybrane losowo w taki sposób, aby uzyskać ich łącznie. Te losowo wybrane tematy są filtrowane.

Aby jeszcze bardziej zwiększyć prywatność i zapewnić możliwość reprezentowania wszystkich tematów, istnieje 5% prawdopodobieństwa, że temat wybrany dla danej epoki zostanie losowo wybrany ze wszystkich tematów, a nie z obserwowanych tematów. Tak jak w przykładzie powyżej, gdy zaobserwowano zbyt mało tematów, te losowo wybrane tematy nie podlegają filtrowaniu.

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

Najważniejsze rekomendacje

1. Zanim rozpoczniesz nowy proces, zamknij (i zatrzymaj) wszystkie procesy Chrome, używając odpowiednich flag.
2. Upewnij się, że wszystkie interfejsy Ad Privacy API są włączone w usłudze chrome://settings/adPrivacy.
3. Na stronie debugowania możesz sprawdzić, jak interfejs Topics działa lokalnie.
4. Jeśli masz pytania, poszukaj wyjaśnienia w problemach 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 witryn odwiedzanych przez użytkownika czy wyświetlania historii nawigacji.

Wywołujący interfejs Topics API to encja, która wywołuje metodę JavaScript document.browsingTopics() lub obserwuje tematy i uzyskuje do nich dostęp za pomocą nagłówków żądań HTTP. Twój kod i eTLD+1, z którego w tym przypadku jest wywoływane, to element wywołujący. Gdy wywołujesz interfejs Topics API, informujesz przeglądarkę użytkownika, że ma obserwować interesujące go tematy, gdy użytkownik odwiedza witrynę. Ta wizyta jest następnie uwzględniana przy obliczaniu tematów na następną epokę.

Interfejs Topics API służy do filtrowania wyników dla wywołującego użytkownika lub domeny eTLD+1 w kontekście wywołania. Inaczej mówiąc, źródło elementu iframe (w przypadku korzystania z interfejsu JavaScript API) lub adres URL żądania pobierania (w przypadku korzystania z nagłówków) jest uważane za element wywołujący, a tematy są obliczane na podstawie tego elementu wywołującego.

Tę metodę ilustruje poniższy diagram:

Na tym diagramie:

1. Użytkownik otwiera Chrome i odwiedza wiele witryn (customerA.example, customerB.example.br itp.), które zawierają element iframe Twojej technologii reklamowej (źródło: iframe.adtech.example) lub nagłówki przekazywanego wywołania pobierania.
   • Chrome będzie rejestrować tematy, które będą interesujące dla tego użytkownika.
2. Po 7 dniach nawigacji, a interfejs Topics API obserwuje interesujące Cię tematy, ten sam użytkownik na tym samym urządzeniu odwiedza witrynę docelową (publisher-e.example). Interfejs Topics API zwraca listę tematów. W tym przykładzie zostanie zwrócony 1 temat obliczony na podstawie obserwacji tego użytkownika z poprzedniego tygodnia.
   • Tylko przeglądarki użytkowników, którzy odwiedzili witryny zaobserwowane w kroku 1 przez adtech.example, 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órzy nie widzieli wcześniej).
3. Za pomocą tej listy (na razie jednego tematu) możesz wywołać interfejs API backendu (ads.adtech.example/topics-backend), aby użyć danych tematów jako części kontekstowego zbioru danych.
4. Teraz, w zależności od swojego przypadku użycia, możesz zapewnić użytkownikom bardziej spersonalizowane środowisko, korzystając z zainteresowanych tematów zaobserwowanych w ostatnich tygodniach.

Wywoływanie interfejsu Topics API

Tematy można obserwować i otwierać na 2 sposoby. Za pomocą

• Interfejs JavaScript API w elemencie iframe:
  • Dodawanie w witrynach docelowych (witrynach wydawcy) elementu iframe zawierającego kod JavaScript wywołujący interfejs Topics API przy użyciu interfejsu document.browsingTopics().
• Opcja nagłówków:
  • Pobierz (zalecane) lub XHR (niezalecane i dostępne tylko podczas zakończenia testowania origin):
    • Możesz uzyskać dostęp do tematów z nagłówka Sec-Browsing-Topics w żądaniach wysyłanych do backendu technologii reklamowych. Jest to najbardziej wydajna opcja (niewielki czas oczekiwania na obserwowanie tematów konkretnego użytkownika).
  • Korzystanie z tagu iframe z atrybutem browsingtopics:
    • Możesz dodać element iframe z atrybutem browsingtopics, a Chrome uwzględni tematy (zaobserwowane dla elementu eTLD+1) w nagłówku Sec-Browsing-Topics w żądaniu tego elementu.

Implementacja za pomocą JavaScriptu i elementów iframe

Zalecamy utworzenie demonstracji interfejsu Topics API lub prezentacji w nagłówku i wykorzystanie jednego z nich jako punktu wyjścia dla kodu.

Możesz uwzględnić element <iframe> w kodzie HTML lub dynamicznie dodawać element iframe za pomocą JavaScriptu. Jednym ze sposobów dynamicznego tworzenia elementu iframe jest użycie następującego 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 dzięki wykrywaniu 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 z poziomu tego elementu iframe:

const topics = await document.browsingTopics();

Powinna wyświetlić się lista tematów zaobserwowanych 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 ostatnich 3 tygodni.

Oto przykład danych zwracanych przez 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ę służący do wnioskowania o tematy.
• taxonomyVersion: ciąg znaków identyfikujący zbiór tematów używanych obecnie przez przeglądarkę.
• topic: liczba określająca temat w taksonomii.
• version: ciąg znaków łączący configVersion i modelVersion.

Dowiedz się więcej o tej implementacji.

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

Tematy są dostępne z poziomu nagłówka Sec-Browsing-Topics w żądaniu pobierania()/XHR lub żądania iframe.

Tematy podane w nagłówkach żądań możesz oznaczać jako obserwowane, ustawiając nagłówek Observe-Browsing-Topics: ?1 w odpowiedzi na żądanie. Następnie na podstawie tych tematów przeglądarka oblicza tematy, które interesują użytkownika.

Jeśli interfejs API zwróci co najmniej 1 temat, żądanie pobrania 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łniane, aby zmniejszyć ryzyko, że atakujący zapozna się z liczbą tematów w zakresie osoby wywołującej na podstawie długości nagłówka.

Wdróż za pomocą fetch()

Na stronie wydawcy dodaj kod żądania pobierania, pamiętając o tym, że zawiera on dyrektywę {browsingTopics: true}.

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

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

Implementacja za pomocą elementu iframe

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

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

W tym przypadku elementem wywołującym będzie – podobnie jak w przypadku wywołania 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, ale także aby bieżąca wizyta na stronie została uwzględniona w obliczaniu kolejnego najważniejszego tematu w epoce użytkownika, odpowiedź serwera musi zawierać parametr Observe-Browsing-Topics: ?1.

Oto przykład JavaScriptu z użyciem parametru setHeader():

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

Implementacja Topics w backendzie

Dodanie backendu do Topics jest opcjonalne. Wybór zależy od tego, jak i gdzie chcesz używać tematów obliczonych 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żesz analizować razem z innymi sygnałami, takimi jak adresy URL, słowa kluczowe, a nawet tagi, jako dodatkowy sygnał dotyczący Twoich odbiorców.

Jak wyjaśniliśmy w artykule Maksymalizacja trafności reklam po zastosowaniu plików cookie innych firm, istnieje kilka sposobów wykorzystania interfejsu Topics do wyświetlania trafnych reklam. Niektóre z nich obejmują wykorzystywanie tematów do tworzenia list odbiorców, a inne – jako sygnały do trenowania modeli systemów uczących się, które posłużą do określania dodatkowych zainteresowań odbiorców lub nawet do optymalizacji logiki określania stawek.

Kompiluj i wdróż

1. Zbieraj tematy, obserwując użytkowników w środowisku produkcyjnym, które nie zostały jeszcze przeskalowane (szacowany czas: około 1 tygodnia)
   1. Poznaj dostępne opcje: nagłówki iframe i JavaScript lub nagłówki HTTP
   2. Określ domenę elementu iframe.
   3. Utwórz kod JavaScript, korzystając z aplikacji demonstracyjnej jako odniesienia do kodu, lub zaimplementuj opcję nagłówków.
   4. Wdróż interfejs Topics w swoim kontrolowanym środowisku (w niektórych witrynach produkcyjnych).
   5. Dodanie implementacji interfejsu 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 (wraz z adresami URL, tagami itp.) (Szacowany czas: około 3 dni).
   1. Po otrzymaniu listy tematów możesz przesłać ją do swojego backendu wraz z innymi sygnałami kontekstowymi.

Wdróż w niektórych witrynach docelowych

Teraz, gdy masz już kod, dodajmy go do witryn docelowych w ramach pierwszego testu i upewnijmy się, że interfejs API jest stabilny i działa w kontrolowanym środowisku.

Zalecamy wybranie witryn, które:

• Uzyskuj niewielką liczbę wizyt miesięcznie (mniej niż milion wizyt miesięcznie): zacznij od wdrożenia interfejsu API na małej grupie odbiorców.
• Ty jesteś właścicielem i kontrolą: w razie potrzeby możesz szybko wyłączyć implementację bez konieczności zatwierdzania.
• Nie są kluczowe dla działania firmy: takie wdrożenie może negatywnie wpłynąć na wrażenia użytkownika, dlatego zacznij od witryn docelowych o niskim ryzyku.
• Łącznie maksymalnie pięć witryn: nie potrzebujesz na razie takiego ruchu ani dużej ekspozycji.
• Przedstaw różne tematy: wybierz witryny reprezentujące różne kategorie (np. jedną o sporcie, inną z wiadomościami, a jeszcze jedną na temat jedzenia i napojów). Do sprawdzania domen i sposobu ich klasyfikowania przez klasyfikator systemów uczących się Topics możesz użyć wewnętrznego narzędzia tematów w Chrome. Więcej informacji o debugowaniu znajdziesz w przewodniku dla programistów po interfejsie Topics API.

Testy funkcjonalne i weryfikacja

Gdy wywołujesz interfejs Topics API w tym ograniczonym środowisku, możesz spodziewać się:

• Pusty tablica tematów [], jeśli jest to pierwsze wywołanie tego urządzenia, dotyczące tej witryny i rozmówcy w ciągu ostatnich 7 dni.
• Lista od 0 do 3 tematów reprezentujących zainteresowania tego użytkownika.
• Po 7 dniach obserwacji otrzymasz:
  • 1 temat reprezentujący zainteresowania użytkownika obliczony na podstawie historii nawigacji w danym tygodniu.
    • Ważna informacja: jeśli nie zaobserwujesz wystarczającej liczby tematów, aby interfejs Topics API nie mógł obliczyć 5 najpopularniejszych tematów w danym tygodniu, usługa Topics doda tyle losowych tematów, ile potrzebujesz, aby uzyskać łączną liczbę 5. Dowiedz się więcej o interfejsie API.
• Nowy wpis na temat, który zastąpi jeden z trzech, jeśli wywołujesz go po czterech tygodniach obserwacji.
  • Wynika to z faktu, że interfejs Topics API będzie działać stabilnie przez kilka kolejnych tygodni i nie będzie ujawniać zbyt wielu zainteresowań użytkowników. Więcej informacji znajdziesz w GitHubie.
• Jeśli nie obserwujesz tematów danego użytkownika przez ponad 3 tygodnie, interfejs Topics API ponownie zwróci pustą tablicę [].

Mierz skuteczność i dane związane z wrażeniami użytkowników.

• Czas wykonywania wywołań JavaScript do interfejsu Topics API w elemencie iframe z innej domeny należy mierzyć na potrzeby przyszłej analizy wydajności. Zadbaj o poprawne zbieranie i przechowywanie danych telemetrycznych w swoim zapleczu.
  • Kolejnym możliwym parametrem do obliczenia jest czas potrzebny na utworzenie elementu iframe i tematów postMessage() po otrzymaniu tematów.

Rozwiązywanie problemów

Wywołuję interfejs Topics API, ale w rezultacie otrzymuję wartość null. Co mogę zrobić?

Jeśli wywołujesz interfejs Topics API w ciągu pierwszego tygodnia od obserwacji użytkownika, jest to normalne.

Najważniejsze rekomendacje

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

2. Przetestuj swój interfejs, aby otrzymać wyniki dotyczące tematów.

   1. Pamiętaj o prawidłowej konfiguracji typów danych i parametrów interfejsu API backendu.
   2. Upewnij się, że backend jest skonfigurowany do odpowiedniego skalowania.

3. Z naszego doświadczenia wynika, że uzyskanie trafniejszych wyników dotyczących tematów wymaga odczekania co najmniej 3 tygodni.

4. Nie wszyscy użytkownicy mają włączony interfejs Topics:

   1. Użytkownicy mogą samodzielnie wyłączyć interfejs Topics API.
   2. Strony wydawcy mogą zarządzać zasadami dotyczącymi uprawnień. Zapoznaj się z informacjami na temat rezygnacji z przewodnika dla programistów interfejsu Topics API.
   3. Więcej informacji znajdziesz na stronie chromestatus.com.

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

   1. czas oczekiwania na połączenie;
   2. błędy HTTP w wywołaniach tematów;

6. Spróbuj ograniczyć zmiany w implementacji przez pierwsze 3 tygodnie.

Przenoszenie do środowiska produkcyjnego

Oto szczegółowe omówienie możliwości przejścia na wersję produkcyjną. Poniżej objaśniamy poszczególne kroki.

1. Skalowanie implementacji (produkcyjnej). Poniżej opisano to.
   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ł do innych danych.
   2. Źródłowymi partnerami testującymi określanie stawek w czasie rzeczywistym.
   3. Przeprowadzaj testy narzędziowe, korzystając z tematów jako sygnałów sumujących się do innych danych.

Skalowanie implementacji

Na tym etapie dane dotyczące tematów z niektórych witryn powinny być zbierane w środowisku kontrolowanym, gdzie masz większą pewność co do wiarygodności całego rozwiązania.

Nadszedł czas na skalowanie implementacji, 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 dotyczących tematów i lepiej poznać 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. Przetestuj obciążenie danych dotyczących tematów w zależności od oczekiwanego natężenia ruchu.
   1. Sprawdź, czy Twój backend może obsłużyć dużą liczbę połączeń.
   2. Skonfiguruj zbieranie wskaźników i logi do analizy.
3. Natychmiast po wdrożeniu interfejsu Topics API sprawdź wskaźniki, aby wykryć poważne problemy użytkowników. Regularnie sprawdzaj dane.
4. W przypadku zakłóceń lub nieoczekiwanego działania wycofaj wdrożenie i przeanalizuj logi, aby przeanalizować i rozwiązać problem.

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.