Przewodnik dla sprzedawców: prowadzenie aukcji reklam

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
Ten diagram przedstawia każdy etap aukcji reklam w ramach Protected Audience API.
  1. Użytkownik odwiedza witrynę, która wyświetla reklamy.
  2. 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, czyli scoreAd().
  3. 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.
  4. 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.
  5. 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.
  6. 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:

  1. Użytkownik odwiedza witrynę uczestniczącą w programie.
  2. Inny sprzedawca przeprowadza aukcję automatyczną, aby znaleźć reklamę kontekstową dla dostępnego boksu reklamowego.
  3. Trwa aukcja interfejsu Protected Audience API.
  4. 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:

Wyjaśnienie interfejsu Protected Audience API zawiera też szczegółowe informacje o obsłudze i ograniczeniach funkcji.