Dowiedz się, jak skonfigurować aukcję w ramach Protected Audience API.
Aukcje na urządzeniu prowadzone przez sprzedawców
W witrynie sprzedającej przestrzenie reklamowe odbywa się aukcja z użyciem Protected Audience API. podmiot, który prowadzi aukcję, jest nazywany sprzedawcą. Wiele stron może potraktować sprzedawców: witryna może prowadzić własną aukcję reklam lub może w niej uczestniczyć skrypt do przeprowadzenia dla niej aukcji lub może użyć platformy SSP, która łączy na aukcji na urządzeniu z innymi działaniami z aukcji reklam po stronie serwera. Sprzedawcy mają 3 podstawowe zadania w aukcji reklam na urządzeniu:
- Sprzedawcy decydują: (a) którzy kupujący mogą uczestniczyć w programie oraz (b) które stawki tych kupujących grupy zainteresowań mogą brać udział w aukcji. Dzięki temu sprzedawca egzekwuje reguły określające, jakie reklamy mogą być wyświetlane stronę.
- Sprzedawcy są odpowiedzialni za logikę biznesową aukcji: JavaScript który uwzględnia cenę i metadane każdej stawki, a następnie oblicza „celowość” Jak. Stawka z najwyższym wynikiem pożądanego zwycięża aukcji.
- Sprzedawcy raportują o wyniku aukcji, w tym podają rozliczeniową i pozostałych płatności. Kupujący, którzy wygrają, a przegrywają, zyskują tworzyć własne raporty.
Z tego dokumentu dowiesz się, jak skonfigurować i zainicjować aukcję na urządzeniu.
Konfigurowanie aukcji reklam w ramach Protected Audience API
Aby przeprowadzić aukcję reklam za pomocą interfejsu Protected Audience API, najpierw musisz wykonać
skonfigurować aukcję. W tym celu należy utworzyć obiekt auctionConfig
.
Oto przykład takiej konfiguracji:
const auctionConfig = {
seller: 'https://seller.example',
decisionLogicUrl: ...,
trustedScoringSignalsUrl: ...,
interestGroupBuyers: ['https://buyer-1.example', 'https://buyer-2.example', ...],
auctionSignals: {...},
sellerSignals: {...},
sellerTimeout: 100,
perBuyerSignals: {
'https://buyer-1.example': {...},
'https://buyer-2.example': {...},
...
},
perBuyerTimeouts: {
'https://buyer-1.example': 50,
'https://buyer-2.example': 200,
'*': 150,
...
},
componentAuctions: [
{
'seller': 'https://component-seller.example',
'decisionLogicUrl': ...,
...
},
...
],
resolveToConfig: [true|false],
};
AuctionConfig
miejsca zakwaterowania
Właściwości wymagane
Jedyne wymagane właściwości auctionConfigs
to seller
,
decisionLogicUrl
i interestGroupBuyers
.
Właściwość | Przykład | Rola |
---|---|---|
seller | https://seller.example | Pochodzenie sprzedawcy. |
decisionLogicUrl | https://seller.example/decision-logic.js | Adres URL arkusza decyzyjnego JavaScriptu na potrzeby aukcji. To pole musi mieć takie samo źródło jak pole sprzedawcy. |
interestGroupBuyers | [https://buyer-1.example.com https://buyer-2.example ...] |
Źródła wszystkich właścicieli grup zainteresowań, którzy poprosili o udział w aukcji |
Właściwości opcjonalne
Pozostałe właściwości obiektu auctionConfigs
są opcjonalne.
Właściwość | Przykład | Rola |
---|---|---|
trustedScoringSignalsUrl | https://seller.example/scoring-signals | Adres URL serwera klucz-wartość sprzedawcy. Zapytania te będą wysyłane w trakcie procesu oceny reklamy z użyciem adresu URL renderowania kreacji jako klucza. To pole musi mieć takie samo źródło jak pole sprzedawcy. |
auctionSignals | {"category":"news"} | Zserializowany obiekt JSON reprezentujący sygnały dostępne dla wszystkich kupujących i sprzedawców uczestniczących w aukcji. |
sellerSignals | {…} | Zserializowany obiekt JSON reprezentujący sygnały dostępne tylko dla sprzedawców. |
perBuyerSignals | {https://dsp.example: {...}, https://another-buyer.example: {...}, ... } |
Sygnały dostępne dla określonego kupującego. Mogą one pochodzić od sprzedawców, a także od samych kupujących. |
perBuyerTimeouts | {https://www.example-dsp.com: 50, https://www.another-buyer.com: 200, *: 150, ...}, |
Maksymalny czas działania skryptu generateBid() przez danego kupującego (w milisekundach). Do każdego kupującego, który nie ma określonego czasu oczekiwania, zostanie zastosowany symbol wieloznaczny. |
sellerTimeout | 100 | Maksymalny czas działania skryptu ScoreAd() sprzedawcy (w milisekundach). |
componentAuctions | [{seller: https://www.some-other-ssp.com, decisionLogicUrl: ..., ...}, ...] | Dodatkowe konfiguracje dla aukcji komponentów. |
resolveToConfig | prawda|fałsz | Wartość logiczna kierująca obietnicę zwróconą przez funkcję runAdAuction() w celu przejścia do FencedFrameConfig (do zastosowania w elemencie <fencedframe>) lub do nieprzejrzystego adresu URL typu urn:uuid w przypadku wartości false (do użycia w elemencie <iframe>). Wartość domyślna to fałsz. |
Asynchroniczne udostępnianie sygnałów
wartości niektórych sygnałów (skonfigurowanych przez auctionSignals
,
sellerSignals
, perBuyerSignals
i perBuyerTimeouts
) mogą
opcjonalnie podawać nie jako konkretne wartości, ale jako wartość Promises. Dzięki temu:
w niektórych częściach aukcji, takich jak wczytywanie skryptów i zaufanych sygnałów,
uruchamianie izolowanych procesów Workletów, aby nakładać na siebie obliczenia (lub sieć
ich pobrania). Skrypty Worklet będą widzieć tylko rozwiązania
wartości; w przypadku odrzucenia którejś z takich obietnic aukcja zostanie przerwana,
które już nie powiodło się lub zostały przerwane w inny sposób.
Konfigurowanie aukcji z kilkoma sprzedawcami
W niektórych przypadkach w aukcji może wziąć udział wielu sprzedawców, przy czym
wygranych w osobnych aukcjach, które są przenoszone do innej aukcji, przeprowadzone przez inną
sprzedawcy. Te oddzielne aukcje są nazywane aukcjami składowymi.
Aby ułatwić tę aukcję komponentów, obiekt componentAuctions
może zawierać
dodatkowe konfiguracje aukcji dla każdego sprzedawcy.
zwycięska stawka w każdej z tych aukcji składowych zostanie przekazana do
„najwyższy poziom” która decyduje o jej ostatecznej aukcji.
auctionConfig
aukcji komponentów może nie mieć własnych
componentAuctions
Jeśli pole componentAuctions
nie jest puste,
Pole interestGroupBuyers
musi być puste. Oznacza to, że w przypadku każdego chronionego
aukcją wśród odbiorców, w przypadku jednego sprzedawcy bez aukcji komponentów albo
w przeciwnym razie wszystkie stawki pochodzą z aukcji składowych, a aukcja najwyższego poziomu może
wybrać jedną z aukcji składowych zwycięzcy.
Przeprowadzenie aukcji
Sprzedawca wysyła do przeglądarki użytkownika żądanie rozpoczęcia aukcji reklam przez
Dzwonię pod navigator.runAdAuction()
.
try {
const auctionResultPromise = navigator.runAdAuction(auctionConfig);
} catch (error) {
// Handle error.
}
Wywołanie runAdAuction()
zwraca obietnicę odnoszącą się do reklamy. Nie
dowolnego kodu na stronie wydawcy do sprawdzenia zwycięskiej reklamy,
w przeciwnym razie uzyska informacje o jego zawartości z wyniku funkcji runAdAuction()
. Jeśli
flaga resolveToConfig
została ustawiona na Prawda w AuctionConfig
,
Zwracany jest FencedFrameConfig
obiekt, który może być renderowany tylko w zabezpieczonym obszarze
ramki. Jeśli flaga ma wartość false (fałsz), zwracany jest nieprzezroczysty numer URN, który może być
renderowanej w elemencie iframe. Możliwe, że runAdAuction zwraca wartość null,
co oznacza, że nie wybrano żadnej reklamy. W takim przypadku sprzedawca może zdecydować się
wyświetlić reklamę kierowaną kontekstowo.