Dowiedz się, jak skonfigurować aukcję interfejsu Protected Audience API.
Aukcje na urządzeniu prowadzone przez sprzedawców
Aukcja Protected Audience API na urządzeniu jest prowadzona w witrynie sprzedającej przestrzeń reklamową. Jako sprzedawcę nazywamy osobę prowadzącą aukcję. Wiele podmiotów może działać jako sprzedawcy: witryna może prowadzić własną aukcję reklam lub zawierać zewnętrzny skrypt, który przeprowadza dla niej aukcję, albo korzystać z platformy SSP, która łączy prowadzenie aukcji na urządzeniu z innymi działaniami związanymi z aukcjami reklam po stronie serwera. W aukcji reklam na urządzeniu sprzedawcy pełnią trzy podstawowe zadania:
- Sprzedawcy decydują, (a) którzy kupujący mogą wziąć udział w aukcji oraz (b) które stawki z grup zainteresowań tych kupujących mogą wziąć udział w aukcji. Dzięki temu sprzedawca może egzekwować w witrynie reguły określające, jakie reklamy mogą pojawiać się na stronie.
- Sprzedawcy są odpowiedzialni za logikę biznesową aukcji: kod JavaScript, który uwzględnia cenę i metadane każdej stawki oraz oblicza wynik „docelowość”. Aukcję wygrywa stawka o najwyższym wyniku zainteresowania.
- Sprzedawcy generują raporty o wynikach aukcji, w tym informacje o cenie rozliczeniowej i wszelkich innych wypłatach. Kupujący, którzy wygrają i przegrywają, mają też własne raporty.
Z tego dokumentu dowiesz się, jak skonfigurować i rozpocząć aukcję na urządzeniu.
Konfigurowanie aukcji reklam w ramach Protected Audience API
Aby przeprowadzić aukcję reklam w ramach Protected Audience API, najpierw musisz ją skonfigurować. W tym celu powstaje obiekt auctionConfig.
Oto przykład jednej z takich 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 | URL dla workletu logiki decyzji JavaScript aukcji. To pole musi mieć takie samo źródło jak pole sprzedawcy. |
| interestGroupBuyers | [https://buyer-1.example, https://buyer-2.example, ...] |
Pochodzenie wszystkich właścicieli grup zainteresowań, którzy poprosili o udział w aukcji |
Właściwości opcjonalne
Pozostałe właściwości auctionConfigs są opcjonalne.
| Właściwość | Przykład | Rola |
|---|---|---|
| trustedScoringSignalsUrl | https://seller.example/scoring-signals | Adres URL serwera klucz-wartość sprzedawcy. Zostanie to wykonane w trakcie procesu oceny reklamy i jako klucz będzie używane URL renderowania kreacji. To pole musi mieć takie samo źródło jak pole sprzedawcy. |
| auctionSignals | {"category":"wiadomości"} | Zserializowany obiekt JSON reprezentujący sygnały dostępne dla wszystkich kupujących i sprzedawców biorących udział 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 konkretnego kupującego. Sygnały mogą 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 (w milisekundach) skryptu generatebid() określonego kupującego. Symbol wieloznaczny zostanie zastosowany w przypadku każdego kupującego, który nie ma określonego czasu oczekiwania. |
| sellerTimeout | 100 | Maksymalny czas działania (w milisekundach) skryptu ScoreAd() sprzedawcy. |
| componentAuctions | [{seller: https://www.some-other-ssp.com, decisionLogicUrl: ..., ...}, ...] | Dodatkowe konfiguracje aukcji komponentów. |
| resolveToConfig | prawda|fałsz | Wartość logiczna kierująca obietnicę zwracaną przez runAdAuction() do klasy FencedFrameConfig (jeśli ma wartość true) (do użycia w <fencedframe>) lub do nieprzezroczystego adresu URL urn:uuid w przypadku wartości false (fałsz). Wartość domyślna to false (fałsz). |
Asynchronicznie dostarczaj sygnały
Wartości niektórych sygnałów (skonfigurowanych za pomocą pól auctionSignals, sellerSignals, perBuyerSignals i perBuyerTimeouts) można opcjonalnie podawać nie jako konkretne wartości, ale jako obietnice. Dzięki temu niektóre części aukcji, takie jak wczytywanie skryptów i zaufanych sygnałów oraz uruchamianie izolowanych procesów Workletów, nakładają się na sposób obliczania (czyli pobieranie przez sieć) tych wartości. Skrypty workletu będą widzieć tylko ustalone wartości. Jeśli któraś z tych obietnic zostanie odrzucona, aukcja zostanie przerwana, chyba że już jej nie uda się lub zostanie przerwana w inny sposób.
Konfigurowanie aukcji z udziałem wielu sprzedawców
W niektórych przypadkach wielu sprzedawców może chcieć wziąć udział w aukcji, w której zwycięzcy osobnych aukcji są organizowane przez innego sprzedawcę. Takie odrębne aukcje są nazywane aukcjami składowymi.
Aby ułatwić obsługę aukcji komponentów, obiekt componentAuctions może zawierać dodatkowe konfiguracje aukcji dla poszczególnych sprzedawców. Zwycięska stawka w każdej z tych aukcji składowych zostanie przekazana na aukcję najwyższego poziomu, co stanowi ostateczny wybór tej aukcji. Element auctionConfig aukcji komponentów może nie mieć własnej wartości componentAuctions. Jeśli pole componentAuctions nie jest puste, pole interestGroupBuyers musi być puste. Oznacza to, że w każdej aukcji w ramach Protected Audience API bierze się pod uwagę 1 sprzedawcę i nie ma żadnych aukcji składowych. W przeciwnym razie wszystkie stawki pochodzą z aukcji składowych, a aukcja najwyższego poziomu może wybrać tylko zwycięzców aukcji komponentów.
Uruchom aukcję
Sprzedawca wysyła do przeglądarki użytkownika żądanie rozpoczęcia aukcji reklam, wywołując navigator.runAdAuction().
try {
const auctionResultPromise = navigator.runAdAuction(auctionConfig);
} catch (error) {
// Handle error.
}
Wywołanie runAdAuction() zwraca obietnicę, która prowadzi do reklamy. Żaden kod na stronie wydawcy nie może sprawdzać zwycięskiej reklamy ani w inny sposób poznać jej treści na podstawie wyniku runAdAuction(). Jeśli flaga resolveToConfig ma w elemencie AuctionConfig wartość prawda, zwracany jest obiekt FencedFrameConfig, który można wyrenderować tylko w objętej ramce. Jeśli flaga ma wartość Fałsz, zwracany jest nieprzezroczysty URN, który może zostać wyrenderowany w elemencie iframe. Możliwe, że runAdAuction zwróci wartość null, co oznacza, że nie została wybrana żadna reklama. W takim przypadku sprzedawca może renderować reklamę kierowaną kontekstowo.