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

Definiowanie danych o odbiorcach

Dowiedz się, jak zdefiniować listę odbiorców, tworząc grupę zainteresowań za pomocą interfejsu Protected Audience API. Przeczytaj przewodnik dla programistów, aby poznać cały cykl życia interfejsu Protected Audience API, i zapoznaj się z wyjaśnieniem interfejsu Protected Audience API, aby uzyskać szczegółową propozycję rejestrowania grup zainteresowań.

Nie jesteś programistą? Więcej informacji znajdziesz w artykule Omówienie interfejsu Protected Audience API.

Grupy zainteresowań interfejsu Protected Audience API

Grupa zainteresowań interfejsu Protected Audience API to grupa osób o wspólnych zainteresowaniach odpowiadająca liście remarketingowej. Każda grupa zainteresowań interfejsu Protected Audience API ma właściciela.

Właściciele grup zainteresowań to kupujący w aukcji reklam Protected Audience API. Członkostwo w grupie zainteresowań jest przechowywane przez przeglądarkę, na urządzeniu użytkownika i nie jest udostępniane dostawcy przeglądarki ani nikomu innemu.

Funkcje interfejsu API

`joinAdInterestGroup()`

Platforma DSP reklamodawcy lub sam reklamodawca dzwoni do navigator.joinAdInterestGroup(), aby poprosić przeglądarkę o dodanie grupy zainteresowań do listy członków przeglądarki.

Pochodzenie kontekstu wywołania dla elementu joinAdInterestGroup() musi być zgodne z pochodzeniem właściciela grupy zainteresowań, więc funkcja joinAdInterestGroup() musi być wywoływana z elementu iframe (np. z DSP), chyba że źródło właściciela grupy zainteresowań odpowiada pochodzeniu 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ć metody joinAdInterestGroup() w przypadku grupy zainteresowań należącej do dsp.example.com, jeśli nie dsp.example.com udzieli jej uprawnień.

Uprawnienia odwiedzonej witryny

Uprawnienia można przyznać 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 odwiedzona witryna (czyli z tego samego źródła co ramka najwyższego poziomu bieżącej strony).

Przykład użycia

Oto przykład, 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 przekazany do funkcji nie może mieć więcej niż 50 kiB. W przeciwnym razie wywołanie zakończy się niepowodzeniem. Drugi parametr określa czas trwania grupy zainteresowań z ograniczeniem do 30 dni. Kolejne wywołania zastępują wcześniej zapisane wartości.

Ważne: wszystkie adresy URL używane jako parametry metod Protected Audience API muszą pochodzić z bezpiecznych źródeł – wszystkie zasoby muszą być udostępniane przez adresy URL HTTPS. Jak używać protokołu HTTPS na potrzeby programowania lokalnego, wyjaśniamy, jak to zrobić podczas lokalnego uruchamiania interfejsu Protected Audience API. Dodatkowo biddingLogicUrl, decisionLogicUrl i trustedBiddingSignals wymagają nagłówka odpowiedzi HTTP X-Allow-FLEDGE: true.

Właściwości wymagane

Jedyne wymagane właściwości 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: URL na potrzeby ustalania stawek JavaScriptu uruchamianego w workucie.
biddingWasmHelperUrl^{1, 2}: Przykład: https://dsp.example/bid/custom-bikes/bid.wasm; Rola: URL kodu WebAssembly pobrany z biddingLogicUrl.
updateUrl²: Przykład: https://dsp.example/bid/custom-bikes/update; Rola: URL, który zwraca plik JSON w celu aktualizowania atrybutów grupy zainteresowań. (patrz Aktualizowanie danych o odbiorcach i odświeżanie reklam).
trustedBiddingSignalsUrl²: Przykład: https://dsp.example/trusted/bidding-signals; Rola: podstawowy adres URL na potrzeby żądań par klucz-wartość wysyłanych do zaufanej usługi klucz-wartość licytującego.
trustedBiddingSignalsKeys: Przykład: ['key1', 'key2' ...]; Rola: klucze dla żądań do par klucz-wartość zaufanych usług 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ć wyświetlane w przypadku tej grupy zainteresowań.
adComponents: Przykład: [customBike1, customBike2, bikePedal, bikeFrame1, bikeFrame2]; Rola: komponenty reklam składających się z kilku elementów.

¹ Właściwości biddingLogicUrl i ads są opcjonalne, ale wymagane do udziału w aukcji. Grupy zainteresowań mogą się przydać w niektórych sytuacjach: np. właściciel grupy zainteresowań może dodać przeglądarkę do grupy zainteresowań w przypadku nieaktywnej kampanii lub w inny sposób, albo może na razie wyczerpać mu się na pewien czas budżet reklamowy.

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

Określ reklamy dla grupy zainteresowań

Obiekty ads i adComponents zawierają adres URL kreacji reklamy oraz (opcjonalnie) dowolne metadane, które mogą być używane podczas określania stawek.

Na przykład:

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

`leaveAdInterestGroup()`

Właściciel grupy zainteresowań może poprosić przeglądarkę o usunięcie z niej. 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, w której poprosiła przeglądarkę o dodanie grupy zainteresowań, jej właściciel może wywołać funkcję navigator.leaveAdInterestGroup(), aby poprosić przeglądarkę o jej usunięcie.

Kod reklamy może też wywoływać tę funkcję w przypadku jej grupy zainteresowań.

Najczęstsze pytania

Jaka jest maksymalna liczba grup zainteresowań na jednego właściciela grupy?

W Chrome można utworzyć do 1000 grup zainteresowań na właściciela i do 1000 właścicieli grup zainteresowań. Ograniczenia te mają charakter barierowy i nie należy ich przekraczać w trakcie zwykłego działania.

Jak mogę zmaksymalizować reklamy kierowane na grupy zainteresowań, które osiągają określone progi?

Jak wspomnieliśmy w wyjaśnieniu publicznym, ponieważ w jednej grupie zainteresowań może znajdować się wiele możliwych do wyświetlenia reklam, ta grupa będzie mogła ponownie ustawić stawkę dla innej reklamy, która może pełnić rolę „reklamy zastępczej” za każdym razem, gdy jej preferowana opcja nie przekracza wartości progowej. Oznacza to, że nawet niewielka, specjalistyczna reklama, która nie osiągnie progu k-anonimowości, może nadal brać udział w aukcjach. Jej grupa zainteresowań może wyświetlać reklamy bardziej ogólne, dopóki bardziej specjalistyczna reklama nie zdobędzie odpowiednio dużej grupy odbiorców.

Z punktu widzenia taktyki warto rozważyć te kwestie:

Aby nowa reklama zaczęła się wyświetlać, po prostu zacznij licytować nią w odpowiednich przypadkach. Nie musisz nic więcej robić.
Jeśli nowe reklamy nie są gotowe, możesz utworzyć reklamę zastępczą. Istnieje pewne ryzyko, że sama reklama zastępcza nie będzie satysfakcjonująca, dlatego może się zdarzyć, że po prostu wyznaczysz stawkę dla reklamy zastępczej. Możesz to robić w 1% przypadków, np. jeśli jest to wystarczający poziom, który zapewni, że kreacja zastępcza przekroczy wartość progową.

Ostatnio dyskutowano o innych możliwościach działania tego mechanizmu, więc jeśli znasz jakiś przypadek użycia, w którym ten mechanizm stwarzałby problem, kontynuuj publiczną dyskusję na temat sposobów ulepszenia interfejsu API.

Wszystkie materiały referencyjne interfejsu Protected Audience API

API reference guides are available:

Developer guide for the Protected Audience API.
Ad buyer guide to Protected Audience interest groups and bid generation.
Ad seller guide to Protected Audience ad auctions.
Guide to reporting auction results
Best practices for Protected Audience ad auction latency
Troubleshoot Protected Audience

The Protected Audience API explainer also provides detail about feature support and constraints.