Umowy w ramach Protected Audience API

wdrażanie umów, zwanych też prywatnym rynkiem reklamowym (PMP), w ramach aukcji z Protected Audience API;

Omówienie

Umowy, zwane też prywatnym rynkiem (Private Marketplace, PMP), zapewniają dostęp do wybranych zasobów reklamowych lub preferencyjne ceny dla kupujących. 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 umowy między kupującym a sprzedawcą. Identyfikator umowy może obejmować m.in. takie właściwości jak koszt/cena, zobowiązanie dotyczące liczby odbiorców, 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 umożliwiają firmom udostępniającym technologie reklamowe otrzymywanie tych identyfikatorów umów i miejsc docelowych w raportach dotyczących Protected Audience po aukcji, aby mogły one przeprowadzać transakcje umów i organizować działania związane z rozliczeniami. Oczekujemy, że kupujący, sprzedawcy, agencje i reklamodawcy mogą mieć własne strategie interpretowania i rozumienia otrzymanych identyfikatorów umów i miejsc docelowych.

Przewodnik

Aby ułatwić zawieranie umów w ramach aukcji Protected Audience, wykonaj te czynności:

  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żna go ustawić w polu buyerAndSellerReportingId, a identyfikatory umów można ustawić w polu identyfikatorów raportowania (selectableBuyerAndSellerReportingIds), które można wybrać.
  2. Podczas generowania stawek identyfikatory umów i stanowisk stają się dostępne. Kupujący wybiera identyfikator umowy z listy 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 umowy i miejsca stają się dostępne w funkcjach raportowania kupującego.

1. Rejestracja identyfikatorów ofert i stanowisk

Przed rozpoczęciem aukcji kupujący rejestruje umowy i identyfikatory miejsc w konfiguracji grupy zainteresowań. Identyfikatory umowy i miejsca są ustawiane w selectableBuyerAndSellerReportingIds jako tablica ciągów znaków. Jeśli identyfikator miejsca jest taki sam we wszystkich umowach i nie trzeba go powtarzać, możesz 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
      buyerReportingId: '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 stanowisk 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. Stawka zostanie odrzucona, jeśli wybrany identyfikator umowy nie znajduje się w tablicy selectableBuyerAndSellerReportingIds.

function generateBid(interestGroup, ...) {
  const [{
    buyerAndSellerReportingId, // 'seat123'
    selectableBuyerAndSellerReportingIds // ['deal123', 'deal456', 'deal789']
    buyerReportingId // 'brid123' - Not used for deals, but the value is available
  }] = interestGroup.ads;

  // ...

  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 atrakcyjności zwycięskiej stawki z uwzględnieniem identyfikatora umowy i wszelkich warunków specjalnych. Jeśli sprzedawca uważa, że wybrany przez kupującego identyfikator umowy nie ma zastosowania, odrzuca stawkę, nadając jej zerowy lub ujemny wynik atrakcyjności.

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 selectedBuyerAndSellerReportingId, buyerAndSellerReportingId (jeśli występuje) i buyerReportingId (jeśli występuje) są k-anonimiczne w stosunku do właściciela grupy zainteresowań, adresu URL skryptu ustalania stawek, adresu URL renderowania i rozmiaru reklamy (rozmiar reklamy jest wykluczony z tej kontroli co najmniej do pierwszego 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 mimo że buyerReportingId jest zaznaczone w celu zapewnienia k-anonimowości, ta wartość jest dostępna tylko dla funkcji raportowania dla kupującego, a nie dla funkcji raportowania dla sprzedawcy.

function reportResult(..., browserSignals, ...) {
  const {
    buyerAndSellerReportingId, // 'seat123'
    selectedBuyerAndSellerReportingIds // 'deal456'
  } = browserSignals;

  // ...
}

5. Identyfikatory umowy i stanowiska na potrzeby raportowania dla kupującego

Raportowanie kupujących działa na tej samej zasadzie co raportowanie sprzedawców. 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 reportWin().

function reportWin(..., browserSignals, ...) {
  const {
    buyerAndSellerReportingId, // 'seat123'
    selectedBuyerAndSellerReportingId // 'deal456'
    buyerReportingId // 'brid123' - Not used for deals, but the value is available
  } = browserSignals;
}

Uzyskiwanie opinii i ich udostępnianie