Przewodnik po interfejsie API dla sprzedawców i materiały referencyjne na temat aukcji reklam w interfejsie Protected Audience API.
W tym artykule znajdziesz dokumentację techniczną dotyczącą aukcji reklam używaną w obecnej wersji eksperymentalnej 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 dowiedzieć się, jak sprzedawcy przeprowadzają aukcje na urządzeniu.
Nie jesteś programistą? Więcej informacji znajdziesz w artykule Omówienie interfejsu Protected Audience API.
Czym jest aukcja reklam w ramach Protected Audience API?
Aukcja reklam w ramach Protected Audience API to zbiór małych programów JavaScript, które przeglądarka uruchamia na urządzeniu użytkownika, aby wybrać reklamę. Ze względu na ochronę prywatności cały kod aukcji reklam generowany przez sprzedawcę i kupujących jest uruchamiany w osobnych workletach JavaScriptu, które nie komunikują się z osobami z zewnątrz.
![6 etapów aukcji reklam Protected Audience API](https://developers.google.cn/static/privacy-sandbox/assets/images/six-stages-a-protected-a-3e1dd6fdeddbe.png?authuser=3&hl=pl)
- Użytkownik odwiedza witrynę, która wyświetla reklamy.
- Kod sprzedawcy jest uruchamiany
navigator.runAdAuction()
. Określa, która przestrzeń reklamowa jest na sprzedaż i kto może licytować. Sprzedawcy muszą też uwzględnić skrypt, który przyznaje punkty każdej stawce, czyliscoreAd()
. - Kod zaproszonego kupującego jest uruchamiany, aby wygenerować stawkę, adres URL odpowiedniej kreacji reklamy i inne dane. Skrypt ustalania stawek może wysyłać zapytania o dane w czasie rzeczywistym, takie jak pozostały budżet kampanii reklamowej, z usługi klucz-wartość kupującego.
- Kod sprzedawcy nadaje punkty każdej stawce i wybiera zwycięzcę. Ta logika wykorzystuje wartość stawki i inne dane zwracają oczekiwaną wartość stawki. Reklamy, które nie będą lepsze od zwycięskiej kontekstowej, są odrzucane. Sprzedawca może używać własnej usługi kluczy/wartości do obsługi danych w czasie rzeczywistym.
- Zwycięska reklama jest zwracana jako wartość nieprzezroczysta, która pojawia się w ramce otoczonej ramką. Ani sprzedawca, ani wydawca nie będą mogli zobaczyć tej wartości.
- Informacje o aukcji są przekazywane sprzedawcy i kupującym, którzy wygrają.
Kiedy odbywa się aukcja?
Interfejs Protected Audience API można uruchamiać samodzielnie 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ą dla dostępnego boksu reklamowego.
- Trwa aukcja interfejsu Protected Audience API.
scoreAd()
porównuje stawki kupującego z wynikami pierwszej aukcji,
Stawki, które nie mogą przebić zwycięskiego wariantu kontekstowego, są odrzucane.
Kto przeprowadza aukcję reklam w ramach Protected Audience API?
Istnieje wiele podmiotów, które mogą przeprowadzać aukcje dotyczące sprzedaży przestrzeni reklamowej.
Na przykład:
- Wydawca treści: hostowanie treści reklamy w swojej witrynie.
- Platforma dostawców reklam (SSP): współpraca z wydawcą i świadczenie innych usług.
- Skrypt firmy zewnętrznej: działanie na zlecenie wydawcy, umożliwiające udział w aukcjach reklam.
W interfejsie Protected Audience API sprzedawca ma 3 zadania:
- Egzekwowanie reguł wydawcy: które kupujących i stawki są odpowiednie.
- Uruchom logikę aukcji: kod JavaScript jest uruchamiany w workletach, aby obliczyć wynik trafności dla każdej stawki.
- Raportowanie wyniku aukcji
Zadania te są wykonywane w sposób zautomatyzowany w kodzie udostępnionym przez sprzedawcę, gdy wywołuje on 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 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ę, która prowadzi do wartości URN (urn:uuid:<something>
) wskazującej wynik aukcji reklam. Wartość może zostać dekodowana przez przeglądarkę tylko po przekazaniu do chronionej ramki na potrzeby renderowania: strona wydawcy nie może sprawdzić zwycięzcy reklamy.
Skrypt decisionLogicUrl
sprawdza po kolei każdą reklamę wraz z powiązaną z nią stawką i metadanymi, a potem przypisuje jej numeryczny wynik celowy.
auctionConfig
miejsca zakwaterowania
seller
- Wymagane
- Przykład:
'https://ssp.example'
- Rola: pochodzenie sprzedawcy.
decisionLogicUrl
- Wymagany
- Przykład:
'https://ssp.example/auction-decision-logic.js'
- Rola: URL dla kodu JavaScript workletu aukcji.
trustedScoringSignalsUrl
- Opcjonalny
- Przykład:
'https://ssp.example/scoring-signals'
- Rola: URL zaufanego serwera sprzedawcy.
interestGroupBuyers
- Wymagane
- Przykład:
['https://dsp.example', 'https://buyer2.example', ...]
- Rola: źródła wszystkich właścicieli grup zainteresowań, którzy brali udział w aukcji.
- Uwagi: sprzedawca może wybrać
interestGroupBuyers:
, aby zezwolić na ustalanie stawek wszystkim grupom zainteresowań. Reklamy są następnie akceptowane lub odrzucane na podstawie innych kryteriów niż uwzględnienie właściciela grupy zainteresowań. Sprzedawca może na przykład sprawdzać kreacje, aby potwierdzić ich zgodność z zasadami. auctionSignals
- Opcjonalny
- Przykład:
{...}
- Rola: informacje o sprzedawcy o kontekście strony, typie aukcji itp.
sellerSignals
- Opcjonalny
- Przykład:
{...}
- Rola: informacje na podstawie ustawień wydawcy, wysyłanie kontekstowych żądań reklamy itp.
sellerTimeout
- Opcjonalny
- Przykład:
100
- Rola: Maksymalny czas działania (ms) skryptu
scoreAd()
sprzedawcy. perBuyerSignals
- Opcjonalny
- Przykład:
{'https://dsp.example': {...}, 'https://another-buyer.example': {...}, ... }
- Rola: sygnały kontekstowe dotyczące strony każdego kupującego pochodzące z ich serwera.
perBuyerTimeouts
- Opcjonalnie
- Przykład:
50
- Rola: maksymalny czas działania (ms) skryptów
generateBid()
określonego kupującego. componentAuctions
- Opcjonalny
- Przykład:
[{'seller': 'https://www.some-other-ssp.com', 'decisionLogicUrl': ..., ...}, ...]
- Rola: dodatkowe konfiguracje aukcji komponentów.
decisionLogicUrl
decisionLogicUrl
to właściwość obiektu konfiguracji aukcji przekazywana do runAdAuction()
. Ten adres URL musi zawierać skrypt funkcji scoreAd()
. Ta logika jest uruchamiana raz dla każdej reklamy, aby określić jej celowość.
scoreAd(adMetadata, bid, auctionConfig, trustedScoringSignals, browserSignals) {
...
return desirabilityScoreForThisAd;
}
browserSignals
browserSignals
to tworzony przez przeglądarkę obiekt zawierający informacje, które przeglądarka zna i które skrypt aukcji sprzedawcy może chcieć zweryfikować:
{
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 dostępnego boksu reklamowego. Zasada scoreAd()
odrzuca każdą reklamę, która nie może pokonać zwycięskiej reklamy kontekstowej.
scoreAd()
Funkcja scoreAd()
przyjmuje te argumenty:
Argument | Rola |
---|---|
adMetadata |
Dowolne metadane dostarczone przez kupującego. |
auctionConfig |
Obiekt konfiguracji aukcji został przekazany do navigator.runAdAuction() . |
bid |
Liczbowa wartość stawki. |
trustedScoringSignals |
Wartości pobrane w czasie aukcji z zaufanego serwera sprzedawcy, które reprezentują opinię sprzedawcy o reklamie. |
Najczęstsze pytania
Jak jest wybierany zwycięzca aukcji i kto go wybiera?
Sprzedawca określa logikę punktową, aby określić odpowiedni wynik dla każdej reklamy, a przeglądarka wybiera najwyższy wynik jako zwycięską reklamę.
Sprzedawca uwzględnił logikę w funkcji scoreAd()
, a przeglądarka wykonuje tę funkcję w Workletu, który ma ograniczoną komunikację z kodem poza nim. Sama przeglądarka nie ocenia reklam. Przeglądarka odpowiada wyłącznie za realizację logiki punktacji i wybieranie stawki z najwyższym wynikiem.
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.