Przewodnik dla sprzedawców: prowadzenie aukcji reklam

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

  1. Użytkownik odwiedza witrynę uczestniczącą w programie.
  2. Inny sprzedawca przeprowadza aukcję automatyczną, aby znaleźć reklamę kontekstową związaną z dostępnym boksem reklamowym.
  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ę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:

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