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.
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
2- 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
2- 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
1- 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.
1 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.
2 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
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.