Umowy w ramach Protected Audience API

Wdrażanie umów, czyli rynku prywatnego, w aukcji z Protected Audience API

Przegląd

Umowy, zwane też rynkiem prywatnym (PMP), zapewniają kupującym wyselekcjonowany dostęp lub preferencyjne ceny w przypadku części zasobów reklamowych. Aby ułatwić transakcje automatyczne, używane są identyfikatory stanowisk i identyfikatory umów:

  • Identyfikator konta pochodzi od kupującego i jest identyfikatorem reprezentującym klienta kupującego. 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 sprzedającego i jest identyfikatorem reprezentującym umowę między kupującym a sprzedającym. Identyfikator umowy może mieć właściwości takie jak koszt lub cena, zobowiązanie dotyczące wolumenu, informacje o odbiorcach, wyłączność i inne.

Protected Audience ułatwia zawieranie umów, korzystając z identyfikatorów raportowania, które umożliwiają udostępnianie identyfikatorów miejsc docelowych i umów na potrzeby określania stawek, oceniania i raportowania na aukcjach. Identyfikatory raportowania umożliwiają firmom technologicznym otrzymywanie tych identyfikatorów umów i kont w raportach o aukcjach z użyciem Protected Audience API, aby zawierać transakcje i organizować płatności. Oczekujemy, że kupujący, sprzedawcy, agencje i reklamodawcy mogą mieć własne strategie interpretowania i rozumienia otrzymywanych identyfikatorów transakcji i miejsc.

Przewodnik

Aby ułatwić zawieranie transakcji na aukcji Protected Audience API:

  1. Kupujący rejestruje identyfikatory umowy i miejsca w konfiguracji grupy zainteresowań przed rozpoczęciem aukcji.
    • Identyfikatory transakcji i miejsca możesz ustawić w polu Identyfikatory raportowania do wyboru (selectableBuyerAndSellerReportingIds).
    • Jeśli identyfikator miejsca jest taki sam w przypadku wszystkich umów, można go ustawić w parametrze buyerAndSellerReportingId, a identyfikatory umów można ustawić w polu identyfikatorów raportowania do wyboru (selectableBuyerAndSellerReportingIds).
  2. Podczas generowania stawki dostępne stają się identyfikatory umowy i stanowiska. 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 transakcji jest k-anonimowy wraz z innymi identyfikatorami raportowania i wybranymi właściwościami grupy zainteresowań.
  3. Podczas oceniania reklam wybrane identyfikatory umowy i miejsca stają się dostępne dla sprzedawcy.
  4. Identyfikatory umowy i miejsca stają się dostępne w funkcjach raportowania sprzedawcy.
  5. Identyfikatory umowy i miejsca reklamowego stają się dostępne w funkcjach raportowania kupującego.

1. Rejestracja identyfikatorów umowy i stanowiska

Kupujący rejestruje identyfikatory umowy i miejsca w konfiguracji grupy zainteresowań przed przeprowadzeniem aukcji. Identyfikatory umowy i miejsca są ustawione w parametrze selectableBuyerAndSellerReportingIds jako tablica ciągów znaków. Jeśli identyfikator miejsca jest taki sam w przypadku wszystkich transakcji 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
      buyerReportingId: 'brid123'
    },
  ],
};

navigator.joinAdInterestGroup(interestGroupConfig);

Jeśli identyfikator miejsca docelowego 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 umowy i stanowiska kupujących podczas generowania ofert

Podczas generowania stawki kupujący decyduje, czy chce złożyć ofertę w ramach identyfikatora umowy. W generateBid() kupujący może wybrać identyfikator umowy z selectableBuyerAndSellerReportingIds i zwrócić wartość jako 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
  };
}

Stawka z wartością zwróconą dla parametru selectedbuyerAndSellerReportingId może wygrać aukcję tylko wtedy, gdy wartość parametru selectedbuyerAndSellerReportingId jest wspólnie k-anonimowa z parametrem 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 tego sprawdzania co najmniej do I kwartału 2025 r.).

Nawet jeśli w konfiguracji grupy zainteresowań zdefiniowano parametr selectablebuyerAndSellerReportingIds, funkcja generateBid() może zwrócić stawkę, która nie zawiera parametru selectedbuyerAndSellerReportingId. W takim przypadku identyfikatory raportowania przekazywane do funkcji raportowania, jeśli ta stawka wygra aukcję, będą zgodne z zachowaniem identyfikatora raportowania, którego nie można wybrać.

Jeśli funkcja generateBid() zostanie uruchomiona ponownie, ponieważ początkowe wywołanie nie wygenerowało żadnych stawek z reklamami, które przeszły weryfikację k-anonimowości, to w ponownym uruchomieniu w grupie zainteresowań nie będą obecne selectableBuyerAndSellerReportingIds, które nie przeszły weryfikacji k-anonimowości.

3. Identyfikatory umowy i stanowiska sprzedawców podczas oceniania reklam

Wybrany identyfikator umowy wraz z identyfikatorem stanowiska (jeśli jest dostępny) są udostępniane scoreAd(). Sprzedawca podaje ocenę atrakcyjności zwycięskiej stawki, biorąc pod uwagę identyfikator umowy i wszelkie warunki specjalne. Jeśli sprzedawca uważa, że wybrany przez kupującego identyfikator umowy nie ma zastosowania, odrzuca stawkę, przyznając jej zerową lub ujemną ocenę atrakcyjności.

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

  // ...
}

4. Identyfikatory umów i stanowisk na potrzeby raportowania przez sprzedawców

Pamiętaj, że stawka może wygrać aukcję tylko wtedy, gdy parametry selectedBuyerAndSellerReportingId, buyerAndSellerReportingId (jeśli występuje) i buyerReportingId (jeśli występuje) są k-anonimowe w stosunku do właściciela grupy zainteresowań, adresu URL skryptu ustalania stawek, adresu URL renderowania i rozmiaru reklamy (rozmiar reklamy jest wykluczony z tego sprawdzania co najmniej do I kwartału 2025 r.). Dlatego wartości identyfikatorów raportowania zawierające znak selectedBuyerAndSellerReportingId będą zawsze dostępne w usłudze reportResult(). Pamiętaj, że chociaż w przypadku k-anonimizacji zaznaczono pole wyboru buyerReportingId, wartość jest dostępna tylko dla funkcji raportowania kupującego, a nie dla funkcji raportowania sprzedawcy.

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

  // ...
}

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

Ta sama koncepcja raportowania przez sprzedawców dotyczy raportowania przez kupujących. Pamiętaj, że stawka może wygrać aukcję tylko wtedy, gdy parametry selectedBuyerAndSellerReportingId, buyerAndSellerReportingId (jeśli występuje) i buyerReportingId (jeśli występuje) są k-anonimowe w stosunku do właściciela grupy zainteresowań, adresu URL skryptu ustalania stawek, adresu URL renderowania i rozmiaru reklamy (rozmiar reklamy jest wykluczony z tego sprawdzania co najmniej do I kwartału 2025 r.). Dlatego wartości identyfikatorów raportowania, które zawierają znak selectedBuyerAndSellerReportingId, będą zawsze dostępne w reportWin().

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

Angażowanie się i przesyłanie opinii