Ta strona została przetłumaczona przez Cloud Translation API.

Definiowanie danych o odbiorcach

Dowiedz się, jak zdefiniować listę odbiorców przez utworzenie grupy zainteresowań za pomocą interfejsu Protected Audience API. Przeczytaj przewodnik dla programistów, aby poznać pełny cykl życia interfejsu Protected Audience API, i zapoznaj się z wyjaśnieniem na temat tego, jak przeglądarki rejestrują grupy zainteresowań.

Nie jesteś programistą? Zapoznaj się z omówieniem interfejsu Protected Audience API.

Grupy zainteresowań Protected Audience API

Grupa zainteresowań w Protected Audience API reprezentuje grupę osób o wspólnych zainteresowaniach, co odpowiada liście remarketingowej. Każda grupa zainteresowań w ramach Protected Audience API ma swojego właściciela.

Właściciele grup zainteresowań działają jako kupujący w aukcji reklam w ramach Protected Audience API. Przynależność do grupy zainteresowań jest przechowywana przez przeglądarkę oraz na urządzeniu użytkownika i nie jest udostępniana dostawcy przeglądarki ani żadnym innym osobom.

Funkcje interfejsu API

`joinAdInterestGroup()`

Platforma DSP reklamodawcy lub sam reklamodawca wywołuje metodę navigator.joinAdInterestGroup(), aby poprosić przeglądarkę o dodanie grupy zainteresowań do jej listy użytkowników.

Źródło kontekstu wywołującego joinAdInterestGroup() musi odpowiadać źródłom pochodzenia właściciela grupy zainteresowań, więc funkcja joinAdInterestGroup() musi być wywoływana z elementu iframe (np. z platformy DSP), chyba że źródło pochodzenia właściciela grupy zainteresowań pasuje do pochodzenia bieżącego dokumentu (na przykład witryny z własnymi grupami zainteresowań).

joinAdInterestGroup() wymaga pozwolenia od:

odwiedzaną witrynę,
Właściciel grupy zainteresowań

Oznacza to, że malicious.example nie może wywołać funkcji joinAdInterestGroup() w przypadku grupy zainteresowań należącej do użytkownika dsp.example.com bez dsp.example.com przyznania odpowiednich uprawnień.

Zgoda z odwiedzonej witryny

Uprawnienia można przyznawać z tego samego źródła lub z innych domen. Domyślnie uprawnienia są przyznawane w przypadku wywołań funkcji joinAdInterestGroup() z tego samego źródła co odwiedzana witryna (czyli z tego samego źródła co ramka najwyższego poziomu bieżącej strony).

Przykład użycia

Oto przykład tego, jak można zdefiniować grupę zainteresowań i poprosić przeglądarkę o dołączenie do grupy.

const interestGroup = {
  owner: 'https://dsp.example',
  name: 'custom-bikes',
  biddingLogicUrl: ...,
  biddingWasmHelperUrl: ...,
  updateUrl: ...,
  trustedBiddingSignalsUrl: ...,
  trustedBiddingSignalsKeys: ['key1', 'key2'],
  userBiddingSignals: {...},
  ads: [bikeAd1, bikeAd2, bikeAd3],
  adComponents: [customBike1, customBike2, bikePedal, bikeFrame1, bikeFrame2],
};

navigator.joinAdInterestGroup(interestGroup, 7 * kSecsPerDay);

Obiekt interestGroup przekazywany do funkcji nie może mieć więcej niż 50 kiB. W przeciwnym razie wywołanie się nie powiedzie. Drugi parametr określa czas trwania grupy zainteresowań ograniczony do 30 dni. Kolejne wywołania zastępują wcześniej zapisane wartości.

Ważne: wszystkie adresy URL używane jako parametry w metodach Protected Audience API muszą pochodzić z bezpiecznych źródeł: wszystkie zasoby muszą być wyświetlane przy użyciu adresów URL HTTPS. W artykule Jak używać protokołu HTTPS do programowania lokalnego, dowiesz się, jak to zrobić w przypadku lokalnego uruchomienia interfejsu Protected Audience API. Dodatkowo żądania biddingLogicUrl, decisionLogicUrl i trustedBiddingSignals wymagają nagłówka odpowiedzi HTTP X-Allow-FLEDGE: true.

Właściwości wymagane

Jedyne właściwości wymagane w przypadku grup zainteresowań to owner i name:

Właściwość	Przykład	Rola
`owner`	`https://dsp.example`	Pochodzenie właściciela grupy zainteresowań.
`name`	`custom-bikes`	Nazwa grupy zainteresowań.

Właściwości opcjonalne

Pozostałe właściwości są opcjonalne:

biddingLogicUrl^{1, 2}: Przykład: https://dsp.example/bid/custom-bikes/bid.js; Rola: adres URL do określania stawek JavaScript uruchamiany w workletze.
biddingWasmHelperUrl^{1, 2}: Przykład: https://dsp.example/bid/custom-bikes/bid.wasm; Rola: adres URL kodu WebAssembly na podstawie kodu biddingLogicUrl.
updateUrl²: Przykład: https://dsp.example/bid/custom-bikes/update; Rola: adres URL, który zwraca kod JSON, aby zaktualizować atrybuty grupy zainteresowań. (Przeczytaj artykuł Aktualizowanie danych o odbiorcach i odświeżanie reklam).
trustedBiddingSignalsUrl²: Przykład: https://dsp.example/trusted/bidding-signals; Rola: podstawowy adres URL dla żądań pary klucz-wartość wysyłanych do zaufanej usługi klucz-wartość licytującego.
trustedBiddingSignalsKeys: Przykład: ['key1', 'key2' ...]; Rola: klucze żądań wysyłanych do zaufanej usługi klucz-wartość par klucz-wartość.
userBiddingSignals: Przykład: {...}; Rola: dodatkowe metadane, których właściciel może używać podczas określania stawek.
ads¹: Przykład: [bikeAd1, bikeAd2, bikeAd3]; Rola: reklamy, które mogą być renderowane dla tej grupy zainteresowań.
adComponents: Przykład: [customBike1, customBike2, bikePedal, bikeFrame1, bikeFrame2]; Rola: komponenty reklam złożonych z wielu elementów.

¹ Właściwości biddingLogicUrl i ads są opcjonalne, ale wymagane, aby wziąć udział w aukcji. Może się zdarzyć, że utworzysz grupę zainteresowań bez tych właściwości, np. właściciel grupy zainteresowań może chcieć dodać przeglądarkę do grupy zainteresowań na potrzeby kampanii, która jeszcze nie jest aktywna, albo do innego wykorzystania w przyszłości, albo może tymczasowo wyczerpać budżet reklamowy.

² W bieżącej implementacji interfejsu Protected Audience API wartości biddingLogicUrl, biddingWasmHelperUrl, updateUrl i trustedBiddingSignalsUrl muszą mieć to samo pochodzenie co właściciel. To może nie być długoterminowe ograniczenie, a adresy URL ads i adComponents nie mają takiego ograniczenia.

Określanie reklam dla grupy zainteresowań

Obiekty ads i adComponents zawierają adres URL kreacji i opcjonalnie metadane, których można użyć podczas ustalania stawek.

Na przykład:

{
  renderUrl: 'https://cdn.example/.../bikeAd1.html',
  metadata: bikeAd1metadata // optional
}

`leaveAdInterestGroup()`

Właściciel grupy zainteresowań może poprosić o usunięcie z grupy zainteresowań przeglądarki. Przeglądarka usunie grupę zainteresowań z listy członków.

navigator.leaveAdInterestGroup({
  owner: 'https://dsp.example',
  name: 'custom-bikes'
});

Jeśli użytkownik wróci do witryny, która poprosi przeglądarkę o dodanie grupy zainteresowań, właściciel grupy zainteresowań może wywołać funkcję navigator.leaveAdInterestGroup(), aby zażądać usunięcia przez przeglądarkę tej grupy.

Kod reklamy może również wywoływać tę funkcję dla odpowiedniej grupy zainteresowań.

Najczęstsze pytania

Jaka jest maksymalna liczba grup zainteresowań przypadających na jednego właściciela grupy przez jednego użytkownika?

Chrome zezwala na maksymalnie 1000 grup zainteresowań na właściciela i do 1000 właścicieli grup zainteresowań. Ograniczenia te służą jako bariery, a nie podczas normalnego działania.

Jak mogę zmaksymalizować reklamy kierowane na grupy zainteresowań, które spełniają progi k-anon?

Jak zaznacza wyjaśnienie publiczne, ponieważ jedna grupa zainteresowań może wyświetlać wiele możliwych reklam, grupa ta będzie miała możliwość ponownego ustalania stawki jednej z jej reklam jako „reklamy zastępczej”. za każdym razem, gdy preferowana opcja jest poniżej progu. Oznacza to, że mała, wyspecjalizowana reklama, która nie została osiągnięta jeszcze progu k-anonimowości, nadal może brać udział w aukcjach, a w przypadku tej grupy zainteresowań może wyświetlać się reklama bardziej ogólna do momentu, gdy bardziej specjalistyczna reklama zbierze odpowiednio dużą liczbę odbiorców.

Z taktycznego punktu widzenia możesz rozważyć takie kwestie:

Aby zacząć wyświetlać nową reklamę, wystarczy zacząć z niej określać stawki w przypadkach, gdy chcesz ją wyświetlać. Nie musisz robić nic więcej.
Możesz mieć reklamę zastępczą, która będzie używana, gdy nowe reklamy nie będą miały k-anon. Istnieje ryzyko, że reklama zastępcza nie będzie k-anon, dlatego czasem warto po prostu ustalać stawki za reklamę zastępczą. Warto robić to przez 1% czasu, np. wtedy, gdy jest to dobry poziom, aby mieć pewność, że wartość zastępcza nie przekroczy wartości progowej.

Ostatnio przeprowadzono dyskusję na temat innych możliwości działania interfejsu API, więc jeśli masz jakiś przypadek użycia, w którym ten mechanizm może stanowić problem, kontynuuj publiczną dyskusję na temat możliwych sposobów ulepszenia interfejsu API.

Wszystkie pliki referencyjne interfejsu Protected Audience API

Dostępne są przewodniki po interfejsach API:

Przewodnik dla programistów dotyczący interfejsu Protected Audience API.
Przewodnik dla kupujących reklamę po grupach zainteresowań i generowaniu stawek w ramach Protected Audience API.
Przewodnik po aukcjach reklam w ramach Protected Audience API
Przewodnik po raportowaniu wyników aukcji.
Sprawdzone metody dotyczące opóźnienia aukcji reklam w ramach Protected Audience API
Rozwiązywanie problemów z chronioną grupą odbiorców

Wyjaśnienie interfejsu Protected Audience API zawiera też szczegółowe informacje o obsłudze i ograniczeniach funkcji.