Wdrażanie interfejsu Topics API

Na tej stronie znajdziesz szczegółowe informacje o wdrażaniu interfejsu Topics API, które pomogą Ci obserwować tematy i uzyskiwać do nich dostęp. Zanim zaczniesz wdrażać rozwiązanie, sprawdź, czy Twoja przeglądarka jest prawidłowo skonfigurowana. Więcej informacji o tym, jak wywołujące aplikacje obserwują tematy użytkowników i uzyskują do nich dostęp, znajdziesz w sekcji z omówieniem.

Obserwowanie i uzyskiwanie dostępu do interfejsu Topics API

Tematy użytkownika można obserwować i uzyskiwać do nich dostęp na 2 sposoby: za pomocą nagłówków HTTP i interfejsu JavaScript API.

Nagłówki HTTP

Korzystanie z nagłówków HTTP to zalecane podejście do obserwowania tematów użytkownika i uzyskiwania do nich dostępu. To podejście może być znacznie wydajniejsze niż korzystanie z interfejsu JavaScript API. W przypadku nagłówków HTTP adres URL żądania zawiera domenę podlegającą rejestracji, która jest rejestrowana jako domena wywołująca. Jest to domena, w której zaobserwowano tematy użytkownika.

Zainicjuj prośbę

Z interfejsu Topics z nagłówkami można korzystać na 2 sposoby:

  • Uzyskując dostęp do nagłówków żądań i odpowiedzi w przypadku żądania fetch(), które zawiera opcję browsingTopics: true.
  • Uzyskując dostęp do nagłówków elementu iframe, który zawiera atrybut browsingtopics.
Inicjowanie żądania za pomocą pobierania

Za pomocą funkcji fetch wywołujący interfejs API wysyła żądanie, które zawiera {browsingTopics: true} w parametrze options. Źródłem parametru adresu URL żądania pobierania jest źródło, które według obserwacji widziało tematy.

   fetch('<topics_caller_eTLD+1>', { browsingTopics: true })
    .then((response) => {
        // Process the response
    });
Inicjowanie żądania za pomocą elementu iframe

Dodaj atrybut browsingtopics do elementu <iframe>. Przeglądarka dołączy nagłówek Sec-Browsing-Topics do żądania elementu iframe, a jako wywołującego ustawi pochodzenie elementu iframe.

   <iframe src="https://adtech.example" browsingtopics></iframe>

Interpretowanie wartości nagłówków żądań

W przypadku obu metod (pobierania i elementu iframe) tematy obserwowane u użytkownika można pobrać na serwerze z nagłówka żądania Sec-Browsing-Topics. Interfejs Topics API będzie automatycznie uwzględniać tematy użytkownika w nagłówku żądania fetch() lub żądania elementu iframe. Jeśli interfejs API zwróci co najmniej 1 temat, żądanie pobierania do źródła, z którego pochodzą zaobserwowane 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

Przekierowania będą śledzone, a tematy wysyłane w żądaniu przekierowania będą dotyczyć adresu URL przekierowania. Wartości nagłówka Sec-Browsing-Topics są uzupełniane, aby zmniejszyć ryzyko, że osoba atakująca pozna liczbę tematów ograniczonych do wywołującego na podstawie długości nagłówka.

Obsługa odpowiedzi po stronie serwera

Jeśli odpowiedź na żądanie zawiera nagłówek Observe-Browsing-Topics: ?1, oznacza to, że przeglądarka powinna oznaczyć tematy z powiązanego żądania jako obserwowane i uwzględnić bieżącą wizytę na stronie w obliczeniach tematów użytkownika w następnej epoce. W kodzie po stronie serwera umieść w odpowiedzi nagłówek Observe-Browsing-Topics: ?1:

   res.setHeader('Observe-Browsing-Topics', '?1');
Nagłówki żądań i odpowiedzi dotyczące ustawiania i pobierania tematów.
Nagłówki tagu iframe i fetch().

Udostępnianie partnerom obserwowanych tematów

Platformy dostawców mają dostęp tylko do witryn wydawców, więc platformy DSP mogą chcieć udostępniać platformom dostawców, z którymi współpracują, tematy obserwowane w witrynach reklamodawców. Mogą to zrobić, wysyłając do platform SSP fetch()żądanie z nagłówkiem tematówfetch() z kontekstu najwyższego poziomu reklamodawcy.

const response = await fetch("partner-ssp.example", {
 browsingTopics: true
});

Obserwowanie i uzyskiwanie dostępu do interfejsu Topics za pomocą JavaScriptu

Metoda interfejsu Topics JavaScript API document.browsingTopics() umożliwia obserwowanie i pobieranie tematów zainteresowań użytkownika w środowisku przeglądarki: – Rejestrowanie obserwacji: informuje przeglądarkę, że wywołujący zaobserwował użytkownika odwiedzającego bieżącą stronę. Ta obserwacja przyczynia się do obliczania tematów użytkownika dla osoby dzwoniącej w przyszłych epokach. – Dostęp do tematów: pobiera tematy, które wywołujący wcześniej zaobserwował w przypadku użytkownika. Metoda zwraca tablicę zawierającą maksymalnie 3 obiekty tematów, po jednym dla każdej z najnowszych epok, w losowej kolejności.

Zalecamy skopiowanie wersji demonstracyjnej interfejsu Topics JavaScript API i użycie jej jako punktu wyjścia dla swojego kodu.

Dostępność interfejsu API

Zanim zaczniesz korzystać z interfejsu API, sprawdź, czy jest on obsługiwany i dostępny:

 if ('browsingTopics' in document && document.featurePolicy.allowsFeature('browsing-topics')) {
    console.log('document.browsingTopics() is supported on this page');
 } else {
    console.log('document.browsingTopics() is not supported on this page');
 }

Umieszczanie elementu iframe

Do wywołania musi być użyty element iframe z innego źródła, ponieważ kontekst, z którego wywoływany jest interfejs API, służy do zapewnienia, że przeglądarka zwróci tematy odpowiednie dla wywołującego. Umieść w kodzie HTML element <iframe>:

<iframe src="https://example.com" browsingtopics></iframe>

Możesz też utworzyć element iframe dynamicznie za pomocą JavaScriptu:

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

Wywoływanie interfejsu API z poziomu elementu iframe

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

Domyślnie metoda document.browsingTopics() powoduje też, że przeglądarka rejestruje bieżącą wizytę na stronie jako zaobserwowaną przez wywołującego, dzięki czemu można ją później wykorzystać do obliczania tematów. Metoda może przyjmować argument opcjonalny, który powoduje pominięcie rejestrowania wizyty na stronie: {skipObservation:true}.

 // current page won't be included in the calculation of topics:
 const topics = await document.browsingTopics({skipObservation:true});

Interpretowanie odpowiedzi

Zwracane są maksymalnie 3 tematy: po jednym lub zero z każdego z 3 ostatnich tygodni, w zależności od tego, czy tematy zostały zaobserwowane. Zwracane są tylko tematy zaobserwowane przez wywołującego w przypadku bieżącego użytkownika. Oto przykład odpowiedzi interfejsu API:

 [{
'configVersion': chrome.2,
 'modelVersion': 4,
 'taxonomyVersion': 2,
 'topic': 309,
 'version': chrome.2:2:4
}]
  • configVersion: ciąg znaków identyfikujący wersję konfiguracji algorytmu tematów przeglądarki.
  • modelVersion: ciąg znaków identyfikujący klasyfikator uczenia maszynowego użyty do wywnioskowania tematów.
  • taxonomyVersion: ciąg znaków identyfikujący zestaw tematów używanych przez przeglądarkę.
  • topic: liczba identyfikująca temat w mapie kategorii.
  • version: ciąg znaków będący połączeniem configVersion, taxonomyVersion i modelVersion. Parametry opisane w tym przewodniku oraz szczegóły interfejsu API (takie jak rozmiar taksonomii, liczba tematów obliczanych tygodniowo i liczba tematów zwracanych w ramach jednego wywołania) mogą ulec zmianie w miarę uwzględniania przez nas opinii ekosystemu i ulepszania interfejsu API.

Na stronie Testowanie i wdrażanie dowiesz się, jakiej odpowiedzi możesz się spodziewać i jak używać tematów jako dodatkowego sygnału, aby wyświetlać bardziej trafne reklamy.

Dalsze kroki

Dowiedz się, jak wdrażać, testować i skalować rozwiązania oparte na tematach.
Dowiedz się więcej o narzędziach dostępnych w Chrome, które umożliwiają wyświetlanie informacji z interfejsu Topics API, poznawanie sposobu przypisywania tematów oraz debugowanie implementacji.

Zobacz też

Zapoznaj się z naszymi materiałami, aby lepiej zrozumieć interfejs Topics API w internecie.