Umowy w ramach Protected Audience API

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:

  1. 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).
  2. 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ń.
  3. Podczas punktacji reklamy wybrane identyfikatory umów i stanowisk stają się dostępne dla sprzedawcy.
  4. Identyfikatory umowy i miejsca stają się dostępne w funkcjach raportowania sprzedawcy.
  5. 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