Definiowanie danych odbiorców

Dowiedz się, jak zdefiniować odbiorców, tworząc grupę zainteresowań za pomocą interfejsu Protected Audience API. Zapoznaj się z przewodnikiem dla programistów, aby poznać pełny cykl życia interfejsu Protected Audience API, oraz z wyjaśnieniem dotyczącym interfejsu Protected Audience API, aby dowiedzieć się, jak przeglądarki rejestrują grupy zainteresowań.

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

Grupy zainteresowań Protected Audience API

Grupa zainteresowań Protected Audience API to grupa osób o wspólnych zainteresowaniach, która odpowiada liście remarketingowej. Każda grupa zainteresowań Protected Audience API ma właściciela.

Właściciele grup zainteresowań występują w roli kupujących na aukcji reklam z interfejsem Protected Audience API. Informacja o przynależności do grupy zainteresowań jest zapisywana przez przeglądarkę na urządzeniu użytkownika i nie jest udostępniana dostawcy przeglądarki ani nikomu innemu.

Funkcje interfejsu API

joinAdInterestGroup()

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

Pochodzenie kontekstu wywołania funkcji joinAdInterestGroup() musi być zgodne z pochodzeniem właściciela grupy zainteresowań, więc funkcja joinAdInterestGroup() musi być wywoływana z elementu iframe (np. z platformy DSP), chyba że pochodzenie właściciela grupy zainteresowań jest zgodne z pochodzeniem bieżącego dokumentu (np. witryny z własnymi grupami zainteresowań).

joinAdInterestGroup() wymaga uprawnień od:

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

Zezwolenie z odwiedzanej witryny

Uprawnienia można przyznać w ramach tej samej domeny lub w ramach różnych domen. Domyślnie uprawnienia są przyznawane w przypadku wywołań 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, jak można zdefiniować grupę zainteresowań i poprosić przeglądarkę o dołączenie do niej.

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 zakończy się niepowodzeniem. Drugi parametr określa czas trwania grupy zainteresowań, który nie może przekraczać 30 dni. Kolejne wywołania zastępują wcześniej zapisane wartości.

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:

biddingLogicUrl1, 2
Przykład: https://dsp.example/bid/custom-bikes/bid.js
Rola: URL do JavaScriptu do określania stawek, który jest uruchamiany w worklecie.
biddingWasmHelperUrl1, 2
Przykład: https://dsp.example/bid/custom-bikes/bid.wasm
Rola: adres URL kodu WebAssembly pochodzący z biddingLogicUrl.
updateUrl2
Przykład: https://dsp.example/bid/custom-bikes/update
Rola: adres URL, który zwraca JSON do aktualizowania atrybutów grupy zainteresowań. (Patrz Aktualizowanie danych o odbiorcach i odświeżanie reklam).
trustedBiddingSignalsUrl2
Przykład: https://dsp.example/trusted/bidding-signals
Rola: podstawowy adres URL żądań klucz-wartość wysyłanych do zaufanej usługi klucz-wartość reklamodawcy.
trustedBiddingSignalsKeys
Przykład: ['key1', 'key2' ...]
Rola: klucze do żądań wysyłanych do zaufanej usługi klucz/wartość.
userBiddingSignals
Przykład: {...}
Rola: dodatkowe metadane, których właściciel może używać podczas określania stawek.
ads1
Przykład: [bikeAd1, bikeAd2, bikeAd3]
Rola: reklamy, które mogą być wyświetlane w tej grupie zainteresowań.
adComponents
Przykład: [customBike1, customBike2, bikePedal, bikeFrame1, bikeFrame2]
Rola: komponenty reklam składających się z wielu elementów.

1 Właściwości biddingLogicUrl i ads są opcjonalne, ale wymagane, aby wziąć udział w aukcji. Może się zdarzyć, że właściciel grupy zainteresowań będzie chciał utworzyć grupę bez tych właściwości, np. dodać przeglądarkę do grupy zainteresowań na potrzeby kampanii, która jeszcze nie jest uruchomiona, lub na potrzeby innego przyszłego zastosowania. Może też tymczasowo nie mieć budżetu na reklamę.

2 W obecnej implementacji interfejsu Protected Audience API adresy biddingLogicUrl, biddingWasmHelperUrl, updateUrl i trustedBiddingSignalsUrl muszą mieć ten sam początek co właściciel. Może to nie być ograniczenie długoterminowe, a adresy URL ads i adComponents nie mają takiego ograniczenia.

Określanie reklam dla grupy zainteresowań

Obiekty ads i adComponents zawierają adres URL kreacji reklamy oraz opcjonalnie dowolne metadane, które można wykorzystać w momencie określania 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 przeglądarki z grupy zainteresowań. Przeglądarka usuwa grupę zainteresowań z listy jej członków.

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

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

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

Najczęstsze pytania

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

Chrome zezwala na maksymalnie 1000 grup zainteresowań na właściciela i maksymalnie 1000 właścicieli grup zainteresowań. Te limity mają charakter ochronny i nie powinny być osiągane podczas normalnej pracy.

Jak mogę zmaksymalizować skuteczność reklam kierowanych na grupy zainteresowań, które spełniają progi k-anonimowości?

Jak zauważono w wyjaśnieniu publicznym, pojedyncza grupa zainteresowań może zawierać wiele możliwych reklam, które mogą się wyświetlać. W związku z tym grupa będzie miała możliwość ponownego zgłoszenia innej reklamy jako „reklamy rezerwowej”, gdy jej najbardziej preferowany wybór będzie poniżej progu. Oznacza to, że mała, specjalistyczna reklama, która nadal nie osiągnęła progu k-anonimowości, może nadal brać udział w aukcjach, a jej grupa zainteresowań może powrócić do bardziej ogólnej reklamy, dopóki bardziej specjalistyczna reklama nie będzie miała wystarczająco dużej grupy odbiorców.

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

  • Aby nowa reklama zaczęła się wyświetlać, zacznij w jej przypadku określać stawki w sytuacjach, w których chcesz, aby się wyświetlała. Nie musisz robić nic więcej.
  • Możesz mieć reklamę zastępczą, której będziesz używać, gdy nowe reklamy nie będą miały atrybutu 𝑘-anon. Istnieje pewne ryzyko, że reklama rezerwowa nie będzie anonimowa w stopniu 𝑘, więc możesz rozważyć składanie ofert tylko na reklamę rezerwową. Możesz to robić np. w 1% przypadków, jeśli taki poziom zapewnia, że wartość rezerwowa pozostanie powyżej progu.

Ostatnio pojawiły się dyskusje na temat innych sposobów działania, więc jeśli masz przypadek użycia, w którym ten mechanizm stanowiłby problem, kontynuuj udział w publicznej dyskusji o tym, jak można ulepszyć interfejs API.

Wszystkie odwołania do interfejsu Protected Audience API

Dostępne są przewodniki po interfejsach API:

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