wdrażanie umów (nazywanych też prywatną platformą handlową) w ramach aukcji z Protected Audience API.
Omówienie
Umowy, nazywane też prywatną platformą handlową (PMP), oferują kupującym wyselekcjonowany dostęp do określonych zasobów reklamowych lub preferowane ceny. Aby ułatwić transakcje automatyczne, są używane identyfikatory stanowisk i umów:
- Identyfikator stanowiska pochodzi od kupującego i wskazuje jego klienta. Identyfikator miejsca może mieć wpływ na płatności, np. jeśli miejsce ma rabat u danego sprzedawcy.
- Identyfikator umowy pochodzi od kupującego lub sprzedawcy i jest identyfikatorem, który reprezentuje umowę między kupującym a sprzedawcą. Identyfikator umowy może zawierać właściwości takie jak koszt/cena, zobowiązanie dotyczące wielkości, informacje o odbiorcach, wyłączność itp.
Funkcja Protected Audience API ułatwia umowy, ponieważ korzysta z identyfikatorów raportowania, które umożliwiają udostępnianie identyfikatorów stanowisk i umów na potrzeby ustalania stawek na aukcji, ich punktacji i raportowania. Identyfikatory raportowania dają firmom z branży technologii reklamowych mechanizm otrzymywania identyfikatorów umów i stanowisk w raportach z Protected Audience API po zakończeniu aukcji w celu zawierania umów i organizacji działań związanych z płatnościami. Oczekujemy, że kupujący, sprzedawcy, agencje i reklamodawcy mogą mieć własne strategie interpretowania i interpretowania otrzymywanych identyfikatorów umów i stanowisk.
Przewodnik
Aby ułatwić umowy w ramach aukcji z Protected Audience API:
- Przed rozpoczęciem aukcji kupujący rejestruje umowy i identyfikatory miejsc w konfiguracji grupy zainteresowań.
- Identyfikatory umów i stanowisk można ustawić w polu Identyfikatory raportowania, które można wybrać (
selectableBuyerAndSellerReportingIds
). - Jeśli identyfikator miejsca jest taki sam we wszystkich umowach, możesz go ustawić w polu
buyerAndSellerReportingId
, a identyfikatory umów możesz ustawić w polu do wyboru identyfikatorów na potrzeby raportowania (selectableBuyerAndSellerReportingIds
).
- Identyfikatory umów i stanowisk można ustawić w polu Identyfikatory raportowania, które można wybrać (
- Podczas generowania stawek identyfikatory umów i stanowisk stają się dostępne. Kupujący wybiera identyfikator umowy z
selectableBuyerAndSellerReportingIds
. Kupujący generuje stawkę, która zawiera identyfikator umowy powiązany z tą stawką, zwracając wartośćselectedBuyerAndSellerReportingId
. Stawka może wygrać aukcję tylko wtedy, gdy zwrócony identyfikator umowy jest anonimowy w sposób k, a także inne identyfikatory raportowania i wybrane właściwości grupy zainteresowań. - Podczas punktacji reklamy wybrane identyfikatory umów i stanowisk stają się dostępne dla sprzedawcy.
- Identyfikatory umowy i miejsca stają się dostępne w funkcjach raportowania sprzedawcy.
- Identyfikatory umów i stanowisk stają się dostępne w funkcjach raportowania kupującego.
1. Rejestracja identyfikatorów ofert i miejsc
Przed rozpoczęciem aukcji kupujący rejestruje identyfikatory umowy i miejsca w konfiguracji grupy zainteresowań. Identyfikatory umów i stanowisk są ustawione w polu selectableBuyerAndSellerReportingIds
jako tablica ciągów znaków. Jeśli identyfikator miejsca jest taki sam we wszystkich ofertach i nie trzeba go powtarzać, można go dodać w polu buyerAndSellerReportingId
, które akceptuje ciąg znaków:
const interestGroupConfig = {
owner: 'https://buyer.example',
name: 'example-ig',
ad: [
{
renderURL: 'https://buyer.example/ad.html',
selectableBuyerAndSellerReportingIds: ['deal123', 'deal456', 'deal789'], // Deal IDs
buyerAndSellerReportingId: 'seat123', // Seat ID
// Though it is not used to facilitate deals, the buyer
// reporting ID can be defined with other reporting IDs
buyerAndReportingId: 'brid123'
},
],
};
navigator.joinAdInterestGroup(interestGroupConfig);
Jeśli identyfikator miejsca jest inny w przypadku umów, możesz użyć tej konfiguracji:
const interestGroupConfig = {
owner: 'https://buyer.example',
name: 'example-ig',
ad: [
{
renderURL: 'https://buyer.example/ad.html',
selectableBuyerAndSellerReportingIds: [
'deal123seat123',
'deal456seat456',
'deal789seat456'
], // Deal and Seat IDs
},
],
};
navigator.joinAdInterestGroup(interestGroupConfig);
2. Identyfikatory umów i miejsc dla kupujących podczas generowania stawek
Podczas generowania stawki kupujący decyduje, czy chce ustalać stawkę za dany identyfikator umowy. W systemie generateBid()
kupujący może wybrać identyfikator umowy z listy selectableBuyerAndSellerReportingIds
i zwrócić wartość selectedBuyerAndSellerReportingId
. Jeśli wybranego identyfikatora umowy nie ma w tablicy selectableBuyerAndSellerReportingIds
, stawka jest odrzucana.
function generateBid(..., browserSignals, ...) {
const {
buyerAndSellerReportingId, // 'seat123'
selectableBuyerAndSellerReportingIds // ['deal123', 'deal456', 'deal789']
buyerAndReportingId // 'brid123' - Not used for deals, but the value is available
} = browserSignals;
// ...
return {
bid: 1,
render: 'https://buyer.example/ad.html',
selectedBuyerAndSellerReportingId: 'deal456', // Buyer selects a deal ID
};
}
Oferta z wartością zwracaną dla selectedbuyerAndSellerReportingId
może wygrać aukcję tylko wtedy, gdy wartość selectedbuyerAndSellerReportingId
jest wspólnie k-anonimowa wraz z wartością buyerAndSellerReportingId
(jeśli występuje), buyerReportingId
(jeśli występuje), właścicielem grupy zainteresowań, adresem URL skryptu ustalania stawek, adresem URL renderowania i rozmiarem reklamy (rozmiar reklamy jest wykluczony z tej kontroli do co najmniej I kwartala 2025 r.).
Nawet jeśli tag selectablebuyerAndSellerReportingIds
jest zdefiniowany w konfiguracji grupy zainteresowań, nadal może zostać użyty przez generateBid()
stawkę, która nie zawiera tagu selectedbuyerAndSellerReportingId
; W takim przypadku identyfikatory raportowania przekazane funkcjom raportowania do funkcji raportowania w przypadku wygranej będą działać zgodnie z działaniem, którego nie można wybrać w przypadku identyfikatora raportowania.
W przypadku ponownego uruchomienia funkcji generateBid()
, ponieważ pierwotne wywołanie nie spowodowało uzyskania żadnych stawek dla reklam, które przeszły weryfikację k-anonimowości, elementy selectableBuyerAndSellerReportingIds
, które nie przejdą kontroli pod kątem k-anonimowości, nie zostaną uwzględnione w grupie zainteresowań po ponownym uruchomieniu.
3. Identyfikatory ofert i miejsc dla sprzedawców podczas oceny reklam
Wybrany identyfikator umowy wraz z identyfikatorem miejsca (jeśli występuje) są dostępne dla scoreAd()
. Sprzedawca podaje wynik wartości docelowej zwycięskiej stawki z uwzględnieniem identyfikatora umowy i wszelkich warunków specjalnych. Jeśli sprzedawca uzna, że wybrany przez kupującego identyfikator umowy ma zastosowanie, odrzuca ofertę, przyznając jej wynik zerowy lub ujemny.
function scoreAd(..., browserSignals, ...) {
const {
buyerAndSellerReportingId, // 'seat123'
selectedBuyerAndSellerReportingIds, // 'deal456'
} = browserSignals;
// ...
}
4. Identyfikatory umów i miejsc dla sprzedawców na potrzeby raportowania
Pamiętaj, że stawka może wygrać aukcję tylko wtedy, gdy parametry selectedBuyerAndSellerReportingId
, buyerAndSellerReportingId
(jeśli występują) i buyerReportingId
(jeśli występują) są k-anonimowe z właścicielem grupy zainteresowań, adresem URL skryptu ustalania stawek, URL-em renderowania i rozmiarem reklamy (rozmiar reklamy jest wykluczony z tego sprawdzania co najmniej do I kwartału 2025 r.). Z tego powodu wartości identyfikatora raportowania obejmujące selectedBuyerAndSellerReportingId
będą zawsze dostępne w elemencie reportResult()
. Pamiętaj, że chociaż pole buyerReportingId
jest zaznaczone pod kątem k-anonimowości, wartość jest dostępna tylko dla funkcji raportowania kupującego, a nie dla funkcji raportowania o sprzedawcy.
function reportResult(..., browserSignals, ...) {
const {
buyerAndSellerReportingId, // 'seat123'
selectedBuyerAndSellerReportingIds // 'deal456'
} = browserSignals;
// ...
}
5. identyfikatory umów i stanowisk na potrzeby raportów dotyczących kupujących;
Ten sam mechanizm raportowania sprzedawców obowiązuje w przypadku raportów dotyczących kupujących. Pamiętaj, że stawka może wygrać aukcję tylko wtedy, gdy parametry selectedBuyerAndSellerReportingId
, buyerAndSellerReportingId
(jeśli występują) i buyerReportingId
(jeśli występują) są k-anonimowe z właścicielem grupy zainteresowań, adresem URL skryptu ustalania stawek, URL-em renderowania i rozmiarem reklamy (rozmiar reklamy jest wykluczony z tego sprawdzania co najmniej do I kwartału 2025 r.). Dlatego wartości identyfikatora raportowania, które zawierają selectedBuyerAndSellerReportingId
, będą zawsze dostępne w elementach reportWin()
.
function reportWin(..., browserSignals, ...) {
const {
buyerAndSellerReportingId, // 'seat123'
selectedBuyerAndSellerReportingId // 'deal456'
buyerAndReportingId // 'brid123' - Not used for deals, but the value is available
} = browserSignals;
}
Angażuj odbiorców i dziel się opiniami
- Więcej informacji o tożsamości na potrzeby raportowania znajdziesz w sekcji „Tożsamość na potrzeby raportowania” w artykule wprowadzającym do chronionych list odbiorców.
- GitHub zadawaj pytania i bierz udział w dyskusjach na temat problemów w repozytorium interfejsów API.
- W3C: przedyskutuj przypadki użycia w branży podczas wywołania WICG.
- Ogłoszenia: dołącz do listy adresowej lub dołącz do niej.
- Pomoc dla deweloperów w Piaskownicy prywatności: zadawaj pytania i ucz się na podstawie dyskusji w repozytorium pomocy dla deweloperów w Piaskownicy prywatności.
- Chromium: zgłoś błąd w Chromium, aby zadać pytania dotyczące implementacji, którą można przetestować w Chrome.