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