Usługi określania stawek i usługi aukcyjne to zestaw usług dla kupujących i sprzedawców reklam, który działa w zaufanym środowisku wykonawczym (TEE), aby ułatwić przeprowadzanie aukcji Protected Audience (PA). Z tego przewodnika dla deweloperów dowiesz się, jak kupujący może zintegrować się z aukcją B&A PA w Chrome.
Omówienie
Aby wziąć udział w aukcji Protected Audience z użyciem usług B&A, kupujący aktualizuje grupę zainteresowań (GA), aby zoptymalizować ładunek danych pod kątem skrócenia czasu oczekiwania na wynik aukcji.
Kupujący musi wykonać te zadania związane z optymalizacją ładunku:
joinAdInterestGroup()
zadaniegenerateBid()
zadanie
Grupa zainteresowań dla B&A
Oto przykład konfiguracji grupy zainteresowań w aukcji B&A PA z zaimplementowaną optymalizacją ładunku:
navigator.joinAdInterestGroup({
name: 'example-ig',
owner: 'https://dsp.example',
// An ID is mapped to each render URL
ads: [
{
renderURL: 'https://dsp.example/ad.html',
adRenderId: '12345678' // 12 characters max,
buyerReportingId: 'brid123', // Optional
buyerAndSellerReportingId: 'bsrid123', // Optional
selectableBuyerAndSellerReportingId: ['sbsrid123', 'sbsrid456'], // Optional
},
],
adComponents: [
{
renderURL: 'https://dsp.example/ad-component.html',
adRenderId: 'abcdefgh'
},
],
// Flags are set to omit data in the B&A auction payload
auctionServerRequestFlags: ['omit-ads', 'omit-user-bidding-signals'],
// Data not included in the B&A auction payload can be fetched as trusted signals
// The following is an example of how the keys could look, but the actual
// implementation is up to the ad tech
trustedBiddingSignalsKeys: [
'exampleUserBiddingSignalsKey',
'exampleAdRenderIdKey',
'exampleAdMetadataKey',
'exampleAdReportingIdKey',
],
// Optionally, interest groups can be prioritized
priority: 0.0,
});
Różnice między konfiguracją grup odbiorców na podstawie zainteresowań w wersji B&A a konfiguracją grup odbiorców na podstawie zainteresowań na urządzeniu:
Pola | B&A IG | IG na urządzeniu | Dołączone do danych aukcji B&A |
auctionServerRequestFlags |
Używany | Nieużywane | Nie |
userBiddingSignals |
Niezalecane | Używany | Nie, jeśli ustawiona jest flaga omit-user-bidding-signals |
adRenderId w ads i adComponents |
Używany | Nieużywane | Jeśli ustawiona jest flaga omit-ads , element adRenderId w elementach ads jest dostępny tylko w elementach browserSignals.prevWins ładunku. Parametr adRenderId zdefiniowany w pliku adComponents nie jest uwzględniany w ładunku.Jeśli flaga |
renderURL w ads i adComponents |
Używany | Używany | Nie |
metadata w ads i adComponents |
Nieużywane | Używany | Nie |
Identyfikatory w raportach w usłudze ads |
Używany | Używany | Nie |
- Pole
auctionServerRequestFlags
umożliwia ustawienie flag, które informują przeglądarkę o pomijaniu niektórych danych w danych licytacji B&A. - Wartość
userBiddingSignals
można zdefiniować w grupie zainteresowań, ale zalecamy pominięcie tych wartości za pomocą flagiomit-user-bidding-signals
. Pomijane sygnały można przesyłać za pomocą usługi K/V. - Pole
adRenderId
jest ustawiane razem z powiązanym polemrenderURL
, ale tylko poleadRenderId
będzie częścią ładunku aukcji B&A. Adres URL renderowania zwracany przezgenerateBid()
później w czasie aukcji musi odpowiadać adresowi URL renderowania zdefiniowanemu w IG. - Identyfikatory raportowania są definiowane w interfejsie Google Ads, ale nie są uwzględniane w pliku danych aukcji B&A. Identyfikator raportowania zwrócony przez
generateBid()
później w czasie aukcji musi odpowiadać adresowi URL renderowania określonemu w IG. - Identyfikatory
ad.metadata
i raportowania nie są uwzględniane w pliku danych aukcji B&A. Zamiast tego są dostępne dzięki korzystaniu z usługi zaufanego klucza/wartości.
Pamiętaj, że adresy renderURL
i identyfikatory raportowania w funkcji ads
są nadal zdefiniowane w konfiguracji grupy zainteresowań, ale nie są uwzględniane w danych żądania aukcji, ponieważ przeglądarka sprawdza, czy adres URL renderowania i identyfikatory raportowania zwracane przez funkcję generateBid()
usługi ustalania stawek są zgodne z wartościami zdefiniowanymi w grupie zainteresowań.
joinAdInterestGroup()
zadanie
W przypadku spotkania joinAdInterestGroup()
należy wykonać te czynności.
Ustawianie flag żądania serwera
Pole auctionServerRequestFlags
w konfiguracji joinAdInterestGroup()
akceptuje te flagi:
Flaga | Opis |
omit-user-bidding-signals |
Flaga omit-user-bidding-signals pomija obiekt userBiddingSignals w pliku danych aukcji.
Jeśli flaga nie jest ustawiona, wartość |
omit-ads |
Flaga omit-ads informuje przeglądarkę, aby pomijała obiekty ads i adComponents w ładunku aukcji.Usługa Jeśli flaga nie jest ustawiona, pola Zdecydowanie zalecamy, aby kupujący wybrali flagę |
Pomijane dane są przetwarzane przez udostępnienie odpowiednich informacji w trustedBiddingSignals
. Flagi można używać osobno, nie muszą być używane razem.
Przykład użycia:
navigator.joinAdInterestGroup({
auctionServerRequestFlags: ['omit-user-bidding-signals', 'omit-ads'],
});
Ustawianie identyfikatorów renderowania reklam
Aby zmniejszyć rozmiar ładunku aukcji B&A, pomijamy obiekty ads
i adComponents
grupy zainteresowań. W związku z tym te obiekty nie są dostępne w ramach funkcji generateBid()
działającej w usłudze ustalania stawek.
Aby obsłużyć brakujące informacje o reklamach, kupujący zachowuje identyfikator (adRenderId
i adComponentRenderId
) powiązany z każdą reklamą w konfiguracji grupy zainteresowań. Identyfikator musi być ciągiem znaków DOM o długości nie większej niż 12 bajtów. Jeśli identyfikator jest zakodowany w formacie Base64, jego długość nie może przekraczać 12 bajtów.
Przykład grupy zainteresowań z identyfikatorami renderowania reklamy:
navigator.joinAdInterestGroup({
ads: [
{
renderURL: 'https://dsp.example/ad.html',
adRenderId: '12345678' // 12 characters max
},
],
adComponents: [
{
renderURL: 'https://dsp.example/ad-component.html',
adComponentRenderId: 'abcdefgh'
},
],
});
adRenderId
powiązane z reklamami staną się dostępne w prevWins.browserSignals
w generateBid()
.
Chociaż renderURL
nie jest uwzględniony w ładunku żądania, zwrócony adres URL renderowania z generateBid()
musi być zgodny z adresem URL renderowania zdefiniowanym w konfiguracji grupy zainteresowań. Firmy technologiczne zajmujące się reklamami mogą przesyłać metadane reklamy i inne informacje w ramach trustedBiddingSignals
, aby podczas wykonywania generateBid()
można było wygenerować adres URL renderowania reklamy i adres URL renderowania komponentu reklamy.
Ustawianie priorytetów grup zainteresowań
Chrome umożliwia kupującym ustalanie priorytetów grup zainteresowań. Jeśli zostanie osiągnięty limit rozmiaru danych dla kupującego ustawiony przez sprzedawcę, podczas generowania danych dla aukcji B&A dla sprzedawcy wartości priorytetów grup zainteresowań są używane do usuwania grup zainteresowań o niższym priorytecie dla pojedynczego kupującego. W przypadku grup zainteresowań między różnymi kupcami przeglądarka podejmuje decyzję na podstawie rozmiaru serializowanego ładunku. Domyślnie każdy kupujący ma przypisany ten sam rozmiar. Pamiętaj, że faktyczne ustalanie priorytetów odbywa się na serwerach B&A, a nie podczas generowania ładunku żądania.
Priorytet jest obliczany w momencie aukcji za pomocą wektorów priorytetów kupującego (priorityVector
) i sygnałów priorytetów sprzedawcy (prioritySignals
). Kupujący może zastąpić sygnały priorytetów sprzedawcy.
Właściwość | Opis |
Wektor priorytetów | Kupujący podaje wektory jako wartość klucza priorityVector z usługi K/V. |
Sygnały priorytetowe | Sprzedawca dostarcza sygnały, ustawiając priority_signals konfiguracji aukcji |
Zastąpienia sygnałów priorytetowych | Kupujący podaje zastąpienie w polu priority_signals_overrides w elementach PerBuyerConfig w konfiguracji aukcji. |
Podczas aukcji przeglądarka oblicza rzadki iloczyn punktowy kluczy dopasowujących w elementach priorityVector
i prioritySignals
, aby określić priorytet. Na diagramie poniżej priorytet jest obliczany na podstawie wartości (4 * 2) + (3 * -1)
, która jest zmniejszana do 8 + -3
, więc priorytet tej grupy zainteresowań w momencie aukcji wynosi 5
.

Do ustalania priorytetów w sekcji Pytania i odpowiedzi można też używać dodatkowych sygnałów:
Sygnał | Opis |
deviceSignals.one |
Ta wartość zawsze wynosi 1 i jest przydatna do dodawania stałej do iloczynu skalarnego. |
deviceSignals.ageInMinutes |
Wartość określa wiek grupy zainteresowań (czas od ostatniego dołączenia do grupy) w minutach jako liczbę całkowitą z zakresu 0–43 200. |
deviceSignals.ageInMinutesMax60 |
Wartość ta jest taka sama jak sygnał ageInMinutes , ale nie przekracza 60. Jeśli grupa ma więcej niż 1 godzinę, zwracana jest wartość 60. |
deviceSignals.ageInHoursMax24 |
Wartość ta określa wiek grupy zainteresowań w godzinach (maksymalnie 24 godziny). Jeśli grupa ma więcej niż 1 dzień, zwracana jest wartość 24. |
deviceSignals.ageInDaysMax30 |
Ta wartość określa wiek grupy zainteresowań w dniach (maksymalnie 30 dni). Jeśli grupa ma więcej niż 30 dni, zwracana jest wartość 30. |
Więcej informacji znajdziesz w artykule na GitHub.
Konfigurowanie zaufanych sygnałów ustalania stawek
Ponieważ niektóre dane zostaną pominięte w pliku danych aukcji B&A, możesz użyć usługi klucza/wartości, aby przesłać pomijane dane jako wiarygodne sygnały określania stawek do funkcji generateBid()
.
Usługa K/V może dostarczyć następujące pomijane dane:
userBiddingSignals
jeśli kupujący używał produktu;metadata
powiązane z każdą reklamąadRenderId
powiązane z każdą reklamą- Identyfikator raportu

Jednym z możliwych podejść jest uwzględnienie w kluczach sygnałów zaufanego określania stawek unikalnego identyfikatora, a następnie wysłanie powiązanych danych na serwer, aby można je było załadować do usługi klucz-wartość. Ostateczne wdrożenie zależy jednak od firmy technologicznej, a interfejs API nie narzuca żadnych wytycznych.
Ten przykład opisuje jedno z możliwych podejść:
const ad1RenderURL = 'https://dsp.example/ad-1.html';
const ad2RenderURL = 'https://dsp.example/ad-2.html';
const ad1RenderId = 'render-id-1';
const ad2RenderId = 'render-id-2';
const ad1ReportingId = 'reporting-id-1';
const ad2ReportingId = 'reporting-id-2';
// Generate a unique identifier
const id = crypto.randomUUID();
// Define the keys with the unique ID
const trustedSignalsKeyForIG = `interest-group-${id}`
// Set the keys in the interest group
navigator.joinAdInterestGroup({
// …
ads: [
{
renderURL: ad1RenderURL,
adRenderId: ad1RenderId,
buyerReportingId: ad1ReportingId
},
{
renderURL: ad2RenderURL,
adRenderId: ad2RenderId,
buyerReportingId: ad2ReportingId
},
],
trustedBiddingSignalsKeys: [
trustedSignalsKeyForIG
]
});
// Send the associated data to your server to be loaded into the Key/Value Service
fetch('https://dsp.example/kv/load', {
method: 'POST',
body: JSON.stringify({
id,
[trustedSignalsKeyForIG]: {
userBiddingSignals: {
favoriteColor: 'blue'
},
ads: [
{
renderURL: ad1RenderURL,
adRenderId: ad1RenderId,
buyerReportingId: ad1ReportingId,
metadata: {
color: 'red'
}
},
{
renderURL: ad2RenderURL,
adRenderId: ad2RenderId,
buyerReportingId: ad2ReportingId,
metadata: {
color: 'blue'
}
},
]
}
})
});
W tym przykładzie zdefiniowano unikalny identyfikator dla IG, który staje się częścią klucza zaufanych sygnałów. Klucz do IG i powiązane z nim wartości są wysyłane na serwer, aby zostały załadowane do usługi kluczy/wartości. W późniejszym etapie aukcji przeglądarka pobiera zaufane sygnały i udostępnia je w funkcji generateBid()
kupującego.
W razie potrzeby zwracanie sygnału dotyczącego aktualizacji grupy zainteresowań z K/V
Klucz updateIfOlderThanMs
dla zaufanych sygnałów jest używany do aktualizowania grupy zainteresowań wcześniej niż w zwykłym interwale dobowym. Jeśli grupa zainteresowań nie została złączona ani zaktualizowana w czasie przekraczającym wartość zwracaną w milisekundach dla klucza updateIfOlderThanMs
, zostanie zaktualizowana za pomocą mechanizmu updateURL
. Pamiętaj, że Chrome nie będzie aktualizować grup zainteresowań częściej niż raz na 10 minut.
Jeśli aukcja B&A zwróci reklamę, która nie pasuje do żadnej z reklam zdefiniowanych w grupie zainteresowań przechowywanej w przeglądarce, przeglądarka nie przeprowadzi aukcji. Mechanizm updateIfOlderThanMs
może się przydać, aby zapewnić zgodność przeglądarki i aukcji B&A co do zestawu reklam w grupie zainteresowań.
Aby dowiedzieć się więcej, przeczytaj ten artykuł.
generateBid()
zadanie
W przypadku spotkania generateBid()
należy wykonać te czynności.
Odczytywanie sygnałów z przeglądarki
Obiekt browserSignals
przekazany do wywołania usługi B&A generateBid()
ma postać:
{
topWindowHostname: 'advertiser.example',
seller: 'https://ssp.example',
topLevelSeller: 'https://ssp-top.example',
joinCount: 5,
bidCount: 24,
recency: 1684134092,
// prevWins is [timeInSeconds, adRenderId]
prevWins: [
[9342, 'render-id-1'],
[1314521, 'render-id-2']
],
// Compiled WebAssembly code
wasmHelper: WebAssembly.Module
// Data-Version value from K/V response, if available
dataVersion: 1,
}
W elementach browserSignals
dostępne są te zmodyfikowane lub nowe właściwości:
Właściwość | Opis |
prevWins |
prevWins to tablica tuplaków czasu i reklamy. Czas to liczba sekund od ostatniego zwycięstwa powiązanej reklamy w ciągu ostatnich 30 dni.Zamiast obiektu |
wasmHelper |
Kompilowany obiekt kodu dostarczonego z biddingWasmHelperURL . |
dataVersion |
Zaufany serwer może opcjonalnie dołączyć do odpowiedzi nagłówek Data-Version , który jest dostępny w pliku generateBid() .Aby dowiedzieć się więcej, przeczytaj informacje na ten temat na GitHubie. |
Zwraca adres URL renderowania z generateBid()
Obiekt ads
jest pomijany w danych aukcji B&A, dlatego URL renderowania zwracany przez generateBid()
musi zostać ponownie utworzony. Sposób odtwarzania adresu URL renderowania zależy od implementacji, a zwrócony adres URL musi być zgodny z adresem URL renderowania zdefiniowanym w grupie zainteresowań.
Jednym z możliwych podejść jest zachowanie adresu URL podstawowego i wypełnianie szablonu informacjami z elementów interestGroup
i trustedBiddingSignals
.
W tym przykładzie definiujemy 4 reklamy na podstawie koloru i produktu:
await navigator.joinAdInterestGroup({
ads: [
{ renderURL: 'https://dsp.example/red-shirt-ad.html', adRenderId: 'arid1'},
{ renderURL: 'https://dsp.example/blue-shirt-ad.html', adRenderId: 'arid2'},
{ renderURL: 'https://dsp.example/red-pants-ad.html', adRenderId: 'arid3'},
{ renderURL: 'https://dsp.example/blue-pants-ad.html', adRenderId: 'arid4'},
],
trustedBiddingSignalKeys: [
'userBiddingSignals-someUniqueId',
// ...and more
]
})
Następnie wysyłamy ulubiony kolor użytkownika i informacje o produkcie, aby zostały załadowane do usługi klucz-wartość:
fetch('https://dsp.example/kv/load', {
body: JSON.stringify({
'userBiddingSignals-someUniqueId': {
favoriteColor: 'blue',
favoriteProduct: 'shirt'
}
})
})
Później, gdy odbywa się aukcja, sygnały zaufanych stawek są dostępne w generateBid()
. Można ich używać do odtwarzania adresu URL:
function generateBid(..., trustedBiddingSignals, browserSignals) {
const { userBiddingSignals } = trustedBiddingSignals
const { favoriteColor, favoriteProduct } = userBiddingSignals
return {
bid: 1,
render: `https://dsp.example/${favoriteColor}-${favoriteProduct}-ad.html`
}
}
Zwraca identyfikatory raportowania z generateBid()
Identyfikatory raportowania nie są uwzględniane w pliku danych aukcji B&A, dlatego generateBid()
otrzymuje je za pomocą sygnałów zaufanego określania stawek. Po ustaleniu, którego identyfikatora raportowania użyć, wybrany identyfikator raportowania zostanie zwrócony z elementu generateBid()
. Zwrócone identyfikatory muszą być zgodne z identyfikatorami zdefiniowanymi w grupie zainteresowań.
W tym przykładzie wybrano reklamę 1, a jej powiązany identyfikator renderowania jest zwracany z generateBid()
:
generateBid(..., trustedBiddingSignals, …) {
const { ad1ReportingId, ad2reportingId } = trustedBiddingSignals;
// ...
return {
bid: 1,
render: 'https://dsp.example/ad-1.html'
buyerReportingId: ad1reportingId
}
}
Zwrócony identyfikator raportowania jest dostępny w okresie od reportWin()
do buyerReportingSignals
:
reportWin(..., buyerReportingSignals) {
const { buyerReportingId } = buyerReportingSignals;
}
Jeśli zamiast buyerReportingId
zwracana jest wartość generateBid()
, w miejscu buyerReportingId
w elementach buyerReportingSignals
jest dostępna wartość interestGroupName
.
Aby dowiedzieć się więcej, zapoznaj się z przewodnikiem dotyczącym identyfikatorów raportów.
Dalsze kroki
Dostępne są te zasoby
Więcej informacji
- Dowiedz się więcej o konfiguracjach aukcji B&A w Chrome.
- Przeprowadź eksperymenty z interfejsem Protected Audience API z pytaniami i odpowiedziami, korzystając z ćwiczenia z programowania „Kompleksowe testowanie lokalne”.
Masz pytania?
- Jeśli masz pytanie dotyczące usług ustalania stawek i aukcji, otwórz zgłoszenie w repozytorium usług ustalania stawek i aukcji.
- Jeśli masz pytanie na temat Piaskownicy prywatności, otwórz zgłoszenie w repozytorium privacy-sandbox-dev-support.