Przewodnik dla sprzedawców: prowadzenie aukcji reklam

Przewodnik po interfejsie API sprzedawcy i dokumenty referencyjne dotyczące aukcji reklam w Protected Audience API.

W tym artykule znajdziesz informacje techniczne dotyczące aukcji reklam, które są używane w bieżącej wersji eksperymentalnej interfejsu Protected Audience API.

Aby poznać pełny cykl życia interfejsu Protected Audience API, przeczytaj przewodnik dla programistów. Informacje o tym, jak sprzedawcy prowadzą aukcje na urządzeniu, znajdziesz w artykule wyjaśniającym Protected Audience API.

Nie jesteś deweloperem? Zapoznaj się z omówieniem Protected Audience API.

Czym jest aukcja reklam z interfejsu Protected Audience API?

Aukcja reklam Protected Audience API to zbiór małych programów JavaScript, które przeglądarka uruchamia na urządzeniu użytkownika, aby wybrać reklamę. Aby chronić prywatność, cały kod aukcji reklam od sprzedawców i kupujących jest uruchamiany w odizolowanych elementach roboczych JavaScriptu, które nie mogą komunikować się ze światem zewnętrznym.

6 etapów aukcji reklamy w Protected Audience API
Ten diagram przedstawia poszczególne etapy aukcji reklam w interfejsie Protected Audience API.
  1. Użytkownik odwiedza witrynę, która wyświetla reklamy.
  2. Kod sprzedawcy jest wykonywany (navigator.runAdAuction()). Określa, która przestrzeń reklamowa jest na sprzedaż i kto może licytować. Sprzedawcy muszą też dołączyć skrypt, który ocenia każdą stawkę (scoreAd()).
  3. Kod zaproszonego kupującego jest wykonywany w celu wygenerowania stawki, adresu URL odpowiedniej kreacji reklamy i innych danych. Skrypt ustalania stawek może wysyłać zapytania o dane w czasie rzeczywistym, np. o pozostały budżet kampanii reklamowej, do usługi par klucz-wartość kupującego.
  4. Kod sprzedawcy ocenia każdą stawkę i wybiera zwycięzcę. Ta logika wykorzystuje wartość stawki i inne dane, aby określić atrakcyjność stawki. Reklamy, które nie mogą pokonać zwycięzcy kontekstowego, są odrzucane. Sprzedawca może używać własnej usługi klucz-wartość do danych w czasie rzeczywistym.
  5. Zwycięska reklama jest zwracana jako nieprzezroczysta wartość, która wyświetla się w ramce ograniczonej. Zarówno sprzedawca, jak i wydawca nie będą mogli wyświetlić tej wartości.
  6. Aukcja jest raportowana sprzedawcy i kupującym, którzy wygrali aukcję.

Kiedy odbywa się aukcja?

Interfejs Protected Audience API może działać samodzielnie lub w ramach aukcji programmaticznych. W aukcji automatycznej z udziałem wielu sprzedawców:

  1. Użytkownik odwiedza witrynę uczestniczącą w programie.
  2. Aukcja programowa jest prowadzona przez innego sprzedawcę w celu znalezienia reklamy kontekstowej dla dostępnego miejsca na reklamę.
  3. Przeprowadzana jest aukcja interfejsu Protected Audience API.
  4. scoreAd()porównuje stawki kupującego z wynikami pierwszej aukcji.

Stawki, które nie mogą pokonać zwycięzcy w ramach kontekstu, są odrzucane.

Kto przeprowadza aukcję reklam w interfejsie Protected Audience API?

Wiele stron może prowadzić aukcję, aby sprzedać miejsce reklamowe.

Na przykład:

  • Wydawca treści: podmiot, który w swojej witrynie hostuje treści reklamowe.
  • Platforma dostawców reklam (SSP): współpraca z wydawcą i świadczenie innych usług.
  • Skrypt firmy zewnętrznej: działa w imieniu wydawcy, aby umożliwić udział w aukcjach reklam.

W ramach interfejsu Protected Audience API sprzedawca musi wykonać 3 działania:

  • egzekwowanie zasad wydawcy: którzy kupujący i które stawki kwalifikują się do wyświetlania reklam;
  • Wykonywanie logiki aukcji: kod JavaScript jest uruchamiany w elementach roboczych w celu obliczenia wyniku atrakcyjności dla każdej stawki.
  • Wyświetl wynik aukcji.

Te zadania są wykonywane automatycznie w kodzie dostarczonym przez sprzedawcę, gdy rozpoczyna aukcję reklamy przez wywołanie funkcji JavaScriptnavigator.runAdAuction().

Funkcje interfejsu API

runAdAuction()

Sprzedawca wysyła do przeglądarki użytkownika żądanie navigator.runAdAuction(), aby rozpocząć aukcję reklamy.

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 przekształca się w URN (urn:uuid:<something>) reprezentujący wynik aukcji reklamy. Dane te mogą być dekodowane przez przeglądarkę tylko wtedy, gdy zostaną przekazane do ramki odizolowanej na potrzeby renderowania: strona wydawcy nie może sprawdzić reklamy zwycięskiej.

Skrypt decisionLogicUrl rozpatruje po kolei każdą reklamę wraz z powiązaną stawką i metadanymi, a następnie przypisuje jej liczbową ocenę atrakcyjności.

auctionConfig miejsca zakwaterowania

seller
Wymagany
Przykład: 'https://ssp.example'
Rola: kraj pochodzenia sprzedawcy.
decisionLogicUrl
Wymagany
Przykład: 'https://ssp.example/auction-decision-logic.js'
Rola: URL JavaScriptu workletu 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órych poproszono o ustawienie stawki w aukcji.
Uwagi: sprzedawca może określić wartość interestGroupBuyers:, aby zezwolić na 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 sprawdzić kreacje reklamy, aby potwierdzić zgodność z jego zasadami.
auctionSignals
Opcjonalnie
Przykład: {...}
Rola: informacje sprzedawcy o kontekście strony, typie aukcji itp.
sellerSignals
Opcjonalnie
Przykład: {...}
Rola: informacje na podstawie ustawień wydawcy, wysyłanie żądania reklamy kontekstowej itp.
sellerTimeout
Opcjonalnie
Przykład: 100
Rola: maksymalny czas wykonywania (ms) skryptu scoreAd() sprzedawcy.
perBuyerSignals
Opcjonalnie
Przykład: 
{'https://dsp.example': {...}, 'https://another-buyer.example': {...}, ... }
Rola: sygnały kontekstowe dotyczące strony każdego konkretnego kupującego z jego serwera.
perBuyerTimeouts
Opcjonalnie
Przykład: 50
Rola: maksymalny czas działania (ms) generateBid()skryptów konkretnego 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 przekazana do runAdAuction(). Adres URL musi zawierać skrypt do funkcji scoreAd(). Ta logika jest stosowana raz w przypadku każdej reklamy w celu określenia jej atrakcyjności.

scoreAd(adMetadata, bid, auctionConfig, trustedScoringSignals, browserSignals) {
  ...
  return desirabilityScoreForThisAd;
}

browserSignals

browserSignals to obiekt utworzony przez przeglądarkę, zawierający informacje, które zna przeglądarka 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. Część logiki scoreAd() odrzuca każdą reklamę, która nie może pokonać zwycięzcy kontekstowego.

scoreAd()

Funkcja scoreAd() przyjmuje te argumenty:

Argument Rola
adMetadata dowolne metadane podane przez kupującego;
auctionConfig Obiekt konfiguracji aukcji przekazany do navigator.runAdAuction().
bid Wartość liczbowa stawki.
trustedScoringSignals Wartości pobierane w momencie aukcji z zaufanego serwera sprzedawcy, które odzwierciedlają jego opinię na temat reklamy.

Najczęstsze pytania

Jak określany jest zwycięzca aukcji i kto go wybiera?

Sprzedawca udostępnia logikę punktacji, która określa wynik atrakcyjności każdej reklamy, a przeglądarka wybiera reklamę z najwyższym wynikiem jako reklamę zwycięską.

Sprzedawca umieszcza logikę w funkcji scoreAd(), a przeglądarka wykonuje ją w ramach elementu worklet, który ma ograniczoną komunikację z kodem znajdującym się poza nim. Samą ocenę reklam nie wykonuje przeglądarka. Przeglądarka jest odpowiedzialna za wykonanie logiki punktacji i wybranie stawki z najwyższym wynikiem.

Wszystkie odwołania do 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.