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