Przewodnik dla sprzedawców: prowadzenie aukcji reklam

Przewodnik i materiały referencyjne dotyczące interfejsu Seller API w przypadku aukcji reklam z użyciem Protected Audience API.

W tym artykule znajdziesz informacje techniczne o aukcji reklam, która jest używana w obecnej wersji eksperymentalnego interfejsu Protected Audience API.

Pełny cykl życia interfejsu Protected Audience API znajdziesz w przewodniku dla programistów. Szczegółowe omówienie tego, jak sprzedawcy przeprowadzają aukcje na urządzeniu, znajdziesz w wyjaśnieniu dotyczącym interfejsu Protected Audience API.

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

Czym jest aukcja reklamowa z użyciem interfejsu Protected Audience API?

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

6 etapów aukcji reklamowej z użyciem Protected Audience API
6 etapów aukcji reklamowej z użyciem interfejsu Protected Audience API
Ten diagram przedstawia poszczególne etapy aukcji reklamowej z użyciem interfejsu Protected Audience API.
  1. Użytkownik odwiedza witrynę, w której wyświetlają się reklamy.
  2. Kod sprzedawcy jest wykonywanynavigator.runAdAuction(). Określa, która przestrzeń reklamowa jest na sprzedaż i kto może składać oferty. Sprzedawcy muszą też dodać skrypt, który ocenia każdą stawkę, scoreAd().
  3. Kod zaproszonego kupującego jest wykonywany w celu wygenerowania stawki, adresu URL odpowiedniego kreacji reklamy i innych danych. Skrypt określania stawek może wysyłać zapytania o dane w czasie rzeczywistym, takie jak pozostały budżet kampanii reklamowej, do usługi 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ć, jak pożądana jest stawka. Reklamy, które nie mogą pokonać zwycięzcy kontekstowego, są odrzucane. Sprzedawca może używać własnej usługi klucz/wartość do przesyłania danych w czasie rzeczywistym.
  5. Zwycięska reklama jest zwracana jako nieprzezroczysta wartość, która wyświetla się w ramce ograniczonej. Ani sprzedawca, ani wydawca nie będą mogli wyświetlić tej wartości.
  6. Informacja o aukcji jest przekazywana sprzedawcy i kupującym, którzy wygrali.

Kiedy odbędzie się aukcja?

Interfejs Protected Audience API może działać samodzielnie lub w połączeniu z aukcjami automatyzowanymi. Na aukcji automatycznej z udziałem wielu sprzedawców:

  1. Użytkownik odwiedza witrynę uczestniczącą w programie.
  2. Inny sprzedawca przeprowadza aukcję automatyzowaną, aby znaleźć reklamę kontekstową do dostępnego miejsca na reklamę.
  3. Przeprowadzana jest aukcja z użyciem interfejsu Protected Audience API.
  4. scoreAd()porównuje stawki kupującego z wynikami pierwszej aukcji.

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

Kto przeprowadza aukcję reklam w interfejsie Protected Audience API?

Aukcję sprzedaży miejsca na reklamę może przeprowadzić wiele podmiotów.

Na przykład:

  • Wydawca treści: działa we własnym imieniu, aby hostować treści reklamowe w swojej witrynie.
  • Platforma dostawców reklam (SSP): współpracuje z wydawcą i świadczy inne usługi.
  • Skrypt firmy zewnętrznej: działa w imieniu wydawcy, aby umożliwić mu udział w aukcjach reklam.

W przypadku interfejsu Protected Audience API sprzedawca ma 3 zadania:

  • Wymuszanie reguł wydawcy: którzy kupujący i które stawki są kwalifikowane.
  • Uruchomienie logiki aukcji: JavaScript uruchamiany w workletach w celu obliczenia wyniku atrakcyjności każdej stawki.
  • Raportowanie wyniku aukcji.

Te zadania są wykonywane automatycznie w kodzie dostarczonym przez sprzedawcę, gdy rozpoczyna on aukcję reklamową, wywołując funkcję JavaScript navigator.runAdAuction().

Funkcje interfejsu API

runAdAuction()

Sprzedawca wysyła do przeglądarki użytkownika żądanie rozpoczęcia aukcji reklamowej, 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ę, która jest rozwiązywana jako URN (urn:uuid:<something>) reprezentujący wynik aukcji reklam. Może być ona dekodowana tylko przez przeglądarkę po przekazaniu do ramki ograniczonej w celu renderowania: strona wydawcy nie może sprawdzić zwycięskiej reklamy.

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

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: URL JavaScriptu roboczego elementu aukcji.
trustedScoringSignalsUrl
Opcjonalnie
Przykład: 'https://ssp.example/scoring-signals'
Rola: adres URL zaufanego serwera sprzedawcy.
interestGroupBuyers
Wymagane
Przykład: ['https://dsp.example', 'https://buyer2.example', ...]
Rola: pochodzenie wszystkich właścicieli grup zainteresowań, którzy zostali poproszeni o licytowanie w aukcji.
Uwagi: sprzedawca może określić interestGroupBuyers:, aby zezwolić wszystkim grupom zainteresowań na licytowanie. 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 reklamowe, aby potwierdzić ich zgodność z zasadami.
auctionSignals
Opcjonalnie
Przykład: {...}
Rola: informacje o sprzedawcy dotyczące kontekstu strony, typu aukcji itp.
sellerSignals
Opcjonalne
Przykład: {...}
Rola: informacje na podstawie ustawień wydawcy, wysyłanie kontekstowego żądania 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 dla każdego konkretnego kupującego, pochodzące z jego serwera.
perBuyerTimeouts
Opcjonalny
Przykład: 50
Rola: maksymalny czas działania (ms) skryptów danego kupującego.generateBid()
componentAuctions
Opcjonalny
Przykład: 
[{'seller': 'https://www.some-other-ssp.com', 'decisionLogicUrl': ..., ...}, ...]
Rola: dodatkowe konfiguracje aukcji komponentów.



decisionLogicUrl

decisionLogicUrl jest właściwością obiektu konfiguracji aukcji przekazywaną do funkcji runAdAuction(). Ten adres URL musi zawierać skrypt funkcji scoreAd(). Ta logika jest uruchamiana raz dla każdej reklamy, aby określić jej atrakcyjność.

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

browserSignals

browserSignals to obiekt utworzony przez przeglądarkę, który zawiera informacje znane przeglądarce 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. */
}

Zanim rozpocznie się aukcja, 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 w kontekście.

scoreAd()

scoreAd() przyjmuje te argumenty:

Argument Rola
adMetadata Dowolne metadane podane przez kupującego.
auctionConfig Obiekt konfiguracji aukcji przekazany do funkcji navigator.runAdAuction().
bid Wartość stawki w postaci liczbowej.
trustedScoringSignals Wartości pobierane w momencie aukcji z zaufanego serwera sprzedawcy, które odzwierciedlają opinię sprzedawcy o reklamie.

Najczęstsze pytania

Jak wybierany jest zwycięzca aukcji i kto go wybiera?

Sprzedawca udostępnia logikę punktacji, aby określić wynik atrakcyjności każdej reklamy, a przeglądarka wybiera reklamę o najwyższym wyniku.

Sprzedawca umieszcza logikę w funkcji scoreAd(), a przeglądarka wykonuje tę funkcję w worklecie, który ma ograniczoną komunikację z kodem poza nim. Przeglądarka nie ocenia reklam. Za wykonanie logiki oceny i wybranie stawki o najwyższym wyniku odpowiada wyłącznie przeglądarka.

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