Przewodnik po interfejsie API dla sprzedawców i materiały referencyjne dotyczące aukcji reklam w ramach Protected Audience API.
W tym artykule znajdziesz dokumentację techniczną aukcji reklam używaną w bieżącej wersji eksperymentalnej interfejsu Protected Audience API.
Całe życie przeczytaj przewodnik dla programistów Protected Audience API. Aby dowiedzieć się więcej o tym, jak działa interfejs Protected Audience API, jak sprzedawcy przeprowadzają aukcje na urządzeniu.
Nie jesteś programistą? Zapoznaj się z omówieniem interfejsu Protected Audience API.
Czym jest aukcja reklam w ramach Protected Audience API?
Aukcja reklam interfejsu Protected Audience API to zbiór małych programów JavaScript, przeglądarka działa na urządzeniu użytkownika, aby wybrać reklamę. Aby chronić prywatność, wszystkie reklamy kod aukcji od sprzedawcy i kupującego jest uruchamiany w osobnym kodzie JavaScript. worklety, które nie mogą komunikować się z poza światem.
![6 etapów aukcji reklam w ramach Protected Audience API](https://developers.google.cn/static/privacy-sandbox/assets/images/six-stages-a-protected-a-3e1dd6fdeddbe.png?authuser=9&hl=pl)
- Użytkownik odwiedza witrynę, w której wyświetlane są reklamy.
- Kod sprzedawcy wykonuje kod
navigator.runAdAuction()
. Wskazuje on, przestrzeń reklamową jest na sprzedaż i kto może ustalać stawki. Sprzedawcy muszą też dodać skrypt , który zdobywa punkty dla każdej stawki,scoreAd()
. - Kod zaproszonego kupującego jest uruchamiany, by wygenerować stawkę, adres URL odpowiedniej reklamy kreacji i innych danych. Skrypt określania stawek może wysyłać zapytania o dane w czasie rzeczywistym, np. pozostały budżet kampanii Usługa kluczy-wartości.
- Kod sprzedawcy podaje ocenę w przypadku każdej stawki i wybiera zwycięzcę. Ta logika wykorzystuje wartość stawki i inne dane zwracają atrakcyjność stawki. Reklamy bezkonkurencyjne zwycięzca wyszukiwania kontekstowego jest odrzucany. Sprzedawca może użyć własnej Usługa kluczy-wartości na potrzeby danych w czasie rzeczywistym.
- Zwycięska reklama jest zwracana jako wartość nieprzezroczysta, która wyświetla się w chroniona ramka. Zarówno sprzedawca, jak i wydawca nie będzie mógł wyświetlić tej wartości.
- Aukcja jest zgłaszana sprzedawcy i zwycięskiemu kupującym.
Kiedy odbywa się aukcja?
Interfejs Protected Audience API można uruchamiać niezależnie lub w ramach aukcji automatycznych. W przypadku wielu sprzedawców aukcja automatyczna:
- Użytkownik odwiedza witrynę uczestniczącą w programie.
- Inny sprzedawca przeprowadza aukcję automatyczną, aby znaleźć reklamę kontekstową związaną z dostępnym boksem reklamowym.
- Trwa aukcja interfejsu Protected Audience API.
scoreAd()
porównuje stawki kupującego z wynikami pierwszej aukcji.
Stawki, które nie mogą przebić zwycięzcy reklam kontekstowych, są odrzucane.
Kto prowadzi aukcję reklam w ramach Protected Audience API?
Wiele podmiotów może wziąć udział w aukcji dotyczącej sprzedaży przestrzeni reklamowej.
Na przykład:
- Wydawca treści: samoczynnie hostujący treści reklamy w swojej witrynie.
- Platforma dostawców (SSP): współpraca z wydawcą i świadczenie innych usług.
- Skrypt firmy zewnętrznej: działa w imieniu wydawcy, by umożliwić udział w aukcjach reklam.
W interfejsie Protected Audience API sprzedawca ma 3 zadania:
- Egzekwować reguły dotyczące wydawców, określając, którzy kupujący i które stawki spełniają wymagania.
- Logika aukcji: uruchamianie kodu JavaScript w worklety do obliczania docelowego wyniku dla każdej stawki.
- Zgłosić wynik aukcji.
Te zlecenia są realizowane automatycznie za pomocą kodu dostarczonego przez sprzedawcę, gdy
inicjuje aukcję reklam przez wywołanie funkcji JavaScript
navigator.runAdAuction()
Funkcje interfejsu API
runAdAuction()
Sprzedawca wysyła do przeglądarki użytkownika żądanie rozpoczęcia aukcji reklam, wywołując funkcję navigator.runAdAuction()
.
Na przykład:
const auctionConfig = {
seller: 'https://ssp.example',
decisionLogicUrl: ...,
trustedScoringSignalsUrl: ...,
interestGroupBuyers: ['https://dsp.example', 'https://buyer2.example', ...],
auctionSignals: {...},
sellerSignals: {...},
sellerTimeout: 100,
perBuyerSignals: {
'https://dsp.example': {...},
'https://another-buyer.example': {...},
...
},
perBuyerTimeouts: {
'https://dsp.example': 50,
'https://another-buyer.example': 200,
'*': 150,
...
},
componentAuctions: [
{
'seller': 'https://some-other-ssp.example',
'decisionLogicUrl': ...,
...
},
...
]
};
try {
const auctionResultPromise = navigator.runAdAuction(auctionConfig);
} catch (error) {
// Handle error.
}
runAdAuction()
zwraca obietnicę przechodzącą do URN (urn:uuid:<something>
), który reprezentuje
wyniku aukcji reklam. Przeglądarka może go odkodować tylko wtedy, gdy jest przekazywana do chronionej ramki
do renderowania: strona wydawcy nie może sprawdzać zwycięskiej reklamy.
Skrypt decisionLogicUrl
uwzględnia każdą reklamę i jej
powiązanych stawek i metadanych, a następnie przypisuje do nich wartości liczbowe
oczekiwaną część.
auctionConfig
miejsca zakwaterowania
seller
- Wymagany
- Przykład:
'https://ssp.example'
- Rola: pochodzenie sprzedawcy.
decisionLogicUrl
- Wymagany
- Przykład:
'https://ssp.example/auction-decision-logic.js'
- Rola: adres URL JavaScriptu Workleta aukcji.
trustedScoringSignalsUrl
- Opcjonalnie
- Przykład:
'https://ssp.example/scoring-signals'
- Rola: adres URL zaufanego serwera sprzedawcy.
interestGroupBuyers
- Wymagany
- Przykład:
['https://dsp.example', 'https://buyer2.example', ...]
- Rola: źródła wszystkich właścicieli grup zainteresowań, którzy poprosili o udział w aukcji. .
- Uwaga: sprzedawca może określić
interestGroupBuyers:
, aby umożliwić licytowanie wszystkim grupom zainteresowań. Reklamy są następnie akceptowane lub odrzucane na podstawie kryteriów innych niż uwzględnienie właściciela grupy zainteresowań. Sprzedawca może na przykład sprawdzać kreacje, aby potwierdzić ich zgodność z zasadami. auctionSignals
- Opcjonalnie
- Przykład:
{...}
- Rola: informacje o sprzedawcy o kontekście strony, typie aukcji itp.
sellerSignals
- Opcjonalnie
- Przykład:
{...}
- Rola: informacje zależne od ustawień wydawcy, przesyłanie kontekstowego żądania reklamy itp.
sellerTimeout
- Opcjonalnie
- Przykład:
100
- Rola: maksymalny czas działania skryptu
scoreAd()
sprzedawcy (w milisekundach). perBuyerSignals
- Opcjonalnie
- Przykład:
{'https://dsp.example': {...}, 'https://another-buyer.example': {...}, ... }
- Rola: sygnały kontekstowe dotyczące strony dla każdego kupującego pochodzące z jego serwera.
perBuyerTimeouts
- Opcjonalnie
- Przykład:
50
- Rola: maksymalny czas działania (w milisekundach) skryptów
generateBid()
kupującego. componentAuctions
- Opcjonalnie
- Przykład:
[{'seller': 'https://www.some-other-ssp.com', 'decisionLogicUrl': ..., ...}, ...]
- Rola: dodatkowe konfiguracje dla aukcji komponentów.
decisionLogicUrl
decisionLogicUrl
to właściwość obiektu konfiguracji aukcji,
przekazano do: runAdAuction()
. Ten adres URL musi zawierać skrypt dla funkcji
scoreAd()
. Mechanizm działania tej funkcji jest uruchamiany raz dla każdej reklamy,
określić jej opłacalność.
scoreAd(adMetadata, bid, auctionConfig, trustedScoringSignals, browserSignals) {
...
return desirabilityScoreForThisAd;
}
browserSignals
browserSignals
to obiekt utworzony przez przeglądarkę, w tym informacje
znanej przeglądarce i skryptowi aukcji sprzedawcy
weryfikuj:
{
topWindowHostname: 'publisher.example',
interestGroupOwner: 'https://dsp.example',
renderUrl: 'https://cdn.example/render',
adComponents: ['https://cdn.com/ad-component-1', ...],
biddingDurationMsec: 12,
dataVersion: 1 /* DValue from the seller's Key/Value service response. */
}
Przed rozpoczęciem aukcji sprzedawca znajduje najlepszą reklamę kontekstową dla danego zapytania
dostępnego boksu reklamowego. Część logiki scoreAd()
odrzuca wszystkie reklamy, których nie można
niż zwycięzca kontekstu.
scoreAd()
Funkcja scoreAd()
przyjmuje następujące argumenty:
Argument | Rola |
---|---|
adMetadata |
Dowolne metadane podane przez kupującego. |
auctionConfig |
Obiekt konfiguracji aukcji przekazany do navigator.runAdAuction() . |
bid |
Numeryczna wartość stawki. |
trustedScoringSignals |
Wartości pobrane w czasie aukcji z zaufanego serwera sprzedawcy, odzwierciedlające opinię sprzedawcy o reklamie. |
Najczęstsze pytania
Jak jest ustalany zwycięzca aukcji i kto wybiera?
Sprzedawca używa mechanizmu punktacji, aby określić wynik atrakcyjności każdej reklamy, a przeglądarka wybiera najlepszy wynik jako zwycięską reklamę.
Sprzedawca umieszcza logikę w funkcji scoreAd()
, a przeglądarka wykonuje ją w urządzeniu, który ma ograniczoną komunikację z kodem spoza niej. Sama przeglądarka nie ocenia reklam. Przeglądarka odpowiada wyłącznie za wykonanie procedury punktacji i wybór stawki o najwyższym wyniku.
Wszystkie pliki 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.