Raporty o aukcjach w ramach Protected Audience API

Pomiar danych i wyników aukcji z użyciem Protected Audience API

Z tego artykułu dowiesz się, jak ogólnie działają różne mechanizmy, za pomocą których możesz przesyłać dane aukcji interfejsu Protected Audience API na swój serwer, a także jakie mechanizmy przejścia są obecnie dostępne do wykorzystania podczas migracji, dopóki nie będą gotowe alternatywne rozwiązania.

Aby raportować ważne dane, które zbierasz podczas aukcji reklam, interfejs Protected Audience API współpracuje z:

• Private Aggregation, która zbiera sygnały i wyniki aukcji, aby generować raporty podsumowujące.
• Interfejs Ads Reporting API dla ramek ograniczonych i elementów iframe, który jest kanałem w ramkach do komunikacji z procesami roboczymi Protected Audience API. Interfejs API umożliwia powiązanie danych na poziomie zdarzenia z sygnałami aukcji. Raportowanie na poziomie zdarzenia w interfejsie Ads Reporting API to mechanizm przejściowy, dopóki nie zostanie opracowany bardziej prywatny mechanizm raportowania.
• Raportowanie atrybucji, które umożliwia powiązanie danych o konwersjach z sygnałami aukcji.
• Shared Storage, który umożliwia zapisywanie sygnałów aukcji w pamięci z różnych domen, a następnie raportowanie tych danych za pomocą Private Aggregation.

Omówienie raportowania w ramach Protected Audience API

Dane z procesu aukcji Protected Audience API można przesyłać na serwer w 3 głównych okresach: w czasie aukcji, gdy jest ona przeprowadzana w witrynie wydawcy, w czasie renderowania, gdy reklama jest renderowana w ramce ograniczonej lub w ramce iframe w witrynie wydawcy, oraz w czasie konwersji, gdy użytkownik podejmuje w innej witrynie działanie, które można przypisać do aukcji.

Podczas aukcji możesz raportować dane o aukcji za pomocą elementów roboczych raportowania. Podczas renderowania możesz przesyłać dane o zaangażowaniu z elementu iframe lub fenced frame. W momencie konwersji możesz raportować dane atrybucji ze strony docelowej za pomocą interfejsu Attribution Reporting API.

Lokalizacje raportowania

W ramach aukcji kupujący mogą zgłaszać sygnały dostępne w elementach generateBid() i reportWin(), a sprzedawcy – sygnały dostępne w elementach scoreAd() i reportResult(). Poza aukcją kupujący i sprzedawcy mogą raportować dane z ramki, w której wyświetliła się reklama, oraz z witryny, w której nastąpiła konwersja.

W każdym z wymienionych okresów kupujący i sprzedawcy będą mieć dostęp do różnych interfejsów API raportowania, które umożliwiają raportowanie danych takich jak sygnały aukcji, dane na poziomie zdarzenia i dane o konwersjach.

Dane dostępne w ramach aukcji Protected Audience API

Podczas aukcji w ramach Protected Audience API w worklecie dostępne są te dane, które można uwzględnić w raporcie.

Sygnały

Sygnały to dane kontekstowe aukcji, dane użytkownika, dane w czasie rzeczywistym i dane przeglądarki dostępne dla kupujących i sprzedających w ramach workletu, które służą do generowania stawki, oceniania reklamy i raportowania wyników aukcji.

Obiekt auction config jest głównym źródłem danych, które są udostępniane jako sygnały w workletach. Wydawca i sprzedawca mogą podać w konfiguracji aukcji dane kontekstowe i dane własne. Sygnały te można wzbogacić o dane grupy zainteresowań od kupującego, dane na poziomie zdarzenia z ramki renderowania reklamy i dane atrybucji ze strony po kliknięciu. Dane z raportu można wykorzystać do raportowania po stronie kupującego lub sprzedawcy, rozliczeń, budżetowania, trenowania modeli ML i innych celów.

Inne dostępne dane

• Dane o wynikach, które odnoszą się do danych o wygranych i przegranych aukcjach, takich jak cena zwycięskiej stawki i powód odrzucenia stawki.
• Dane o skuteczności, które zawierają informacje o opóźnieniach, np. czas pobierania i wykonywania roboczego elementu do ustalania stawek.

Dane dostępne poza aukcją z użyciem Protected Audience API

Poza aukcją z użyciem Protected Audience API są 2 okresy, w których dostępne są dane do raportowania.

W czasie renderowania, gdy reklama jest renderowana w witrynie wydawcy, dane na poziomie zdarzenia z ramki iframe lub ramki ograniczonej mogą być powiązane z danymi aukcji Protected Audience API i przesyłane do Twojego serwera. Przykładowe dane na poziomie zdarzenia to wyświetlenie reklamy, kliknięcie, najechanie kursorem i wszelkie inne zdarzenia, które mają miejsce w ramce.

Gdy użytkownik wykona na stronie po kliknięciu działania, które są przypisywane do aukcji, dane na poziomie zdarzenia ze strony konwersji można powiązać z danymi aukcji Protected Audience API i przesłać do Twojego serwera.

Raporty na poziomie zdarzenia

Raporty na poziomie zdarzenia zawierają szczegółowe informacje o co najmniej jednym zdarzeniu. Zdarzeniem może być wygrana aukcja, wyświetlenie reklamy lub konwersja. Co najmniej do 2026 r. raportowanie wygranych aukcji na poziomie zdarzenia pozostanie bez zmian, do renderowania reklam Protected Audience nie będą wymagane ograniczone ramki, a do raportowania na poziomie zdarzenia będzie można używać elementu iframe z nieograniczonym dostępem do sieci. Interfejs Ads Reporting API jest też dostępny w ramkach ograniczonych i ramkach iframe, dzięki czemu możesz powiązywać dane o aukcjach i konwersjach z danymi na poziomie zdarzenia z ramki. Ma to ułatwić przejście na nowe rozwiązanie, ponieważ możesz korzystać z dotychczasowej infrastruktury raportowania co najmniej do 2026 roku, a w tym czasie przenieść system na Protected Audience.

Raportowanie wygranych aukcji na poziomie zdarzenia za pomocą sendReportTo()

Mechanizmem dostępnym do raportowania danych na poziomie zdarzenia w aukcji z użyciem Protected Audience API jest sendReportTo() function po wygraniu aukcji. Funkcja jest dostępna w elementach roboczych raportowania kupującego i sprzedawcy, a przeglądarka wysyła żądanie GET do podanego ciągu adresu URL, gdy rozpoczyna się renderowanie reklamy. Każdy sygnał dostępny w elementach roboczych możesz zakodować jako parametry zapytania adresu URL.

Na przykład kupujący może zgłosić kwotę wygrywającej stawki z reportWin() workletu na potrzeby rozliczeń:

// Buyer reporting worklet
function reportWin(auctionSignals, perBuyerSignals, sellerSignals, browserSignals, directFromSellerSignals) {
  sendReportTo(`https://buyer-reporting-server.example/reporting?bid=${browserSignals.bid}`);
}

Funkcja sendReportTo() może służyć do generowania raportu o wygranej dla sprzedawcy, gdy jest wywoływana z reportResult(), oraz raportu o wygranej dla kupującego, gdy jest wywoływana z reportWin(). Funkcja sendReportTo() jest dostępna co najmniej do 2026 r..

Raport Zaangażowanie

Raport o zaangażowaniu zawiera dane na poziomie zdarzenia z kreacji reklamowej, np. dane o wyświetleniach lub kliknięciach, które są powiązane z sygnałami aukcji Protected Audience API, która wyrenderowała reklamę. Reklama jest renderowana po zakończeniu aukcji, więc sygnały aukcji nie są dostępne w ramce, w której jest renderowana reklama. Aby powiązać te dane z różnych okresów, udostępniamy 2 mechanizmy przejścia, które umożliwiają generowanie raportów o zaangażowaniu.

Opisana powyżej funkcja sendReportTo() może służyć do powiązania danych aukcji z danymi na poziomie zdarzenia z elementu iframe, ale nie działa w przypadku ramki ograniczonej, ponieważ nie można przekazać unikalnego identyfikatora z elementu osadzającego, ponieważ komunikacja między elementem osadzającym a ramką ograniczoną jest ograniczona. Do powiązania danych aukcji z danymi na poziomie zdarzenia z reklamy w ramce z ograniczeniami dostępu możesz użyć interfejsu Ads Reporting API.

Interfejs Ads Reporting API w przypadku ramek ograniczonych i ramek iframe

Interfejs Ads Reporting API w przypadku ramek ograniczonych i ramek iframe zapewnia mechanizm umożliwiający powiązanie danych na poziomie zdarzenia użytkownika z ramki reklamy z sygnałami w aukcji Protected Audience.

W procesie roboczym raportowania interfejsu Protected Audience API możesz zarejestrować sygnał reklamy za pomocą funkcji registerAdBeacon() i przekazać adres URL raportowania z sygnałami dodanymi jako parametry zapytania. Określasz też zdarzenie niestandardowe, które chcesz powiązać z adresem URL raportowania. Później, gdy reklama będzie renderowana w ramce ograniczonej, możesz wywołać zdarzenie niestandardowe, wywołując funkcję window.fence.reportEvent(). Dane dostępne w ramce ograniczonej można dodać jako ładunek.

Funkcja registerAdBeacon() jest dostępna tylko w funkcjach raportowania, a nie w logice określania stawek kupującego ani w logice oceniania sprzedawcy.

W tym przykładzie identyfikator kampanii jest powiązany z ładunkiem na poziomie zdarzenia ze współrzędnymi kliknięcia:

// Protected Audience API buyer win reporting worklet
function reportWin(auctionSignals) {
  const { campaignId } = auctionSignals

  registerAdBeacon({
    click: `https://buyer-server.example/report/click?campaignId=${campaignId}`
  })
}

// Protected Audience API seller reporting worklet
function reportResult(auctionConfig) {
  const { campaignId } = auctionConfig.auctionSignals;

  registerAdBeacon({
    click: `https://seller-server.example/report/click?campaignId=${campaignId}`
  })
}

// Ad frame
window.fence.reportEvent({
  eventType: 'click',
  eventData: JSON.stringify({'clickX': '123', 'clickY': '456'}),
  destination:['buyer', 'seller']
});

Interfejs Fenced Frames Ads Reporting API będzie też dostępny co najmniej do 2026 r. z tych samych powodów co raportowanie wygranych.

Więcej informacji znajdziesz w wyjaśnieniu.

Nieograniczony dostęp do sieci

Ogrodzone ramki umożliwiają wczytywanie zasobów sieciowych w taki sam sposób jak ramki iframe. W ich obrębie możesz wysyłać dane na poziomie zdarzenia na swój serwer. Raporty na poziomie zdarzenia po stronie serwera możesz wygenerować później, łącząc dane na poziomie zdarzenia z ogrodzonej ramki z danymi aukcji wysłanymi za pomocą sendReportTo(), o których mowa w sekcji Mechanizm raportowania na poziomie zdarzenia aukcji powyżej.

W przyszłości dostęp do sieci będzie ograniczony.

Raport atrybucji

Raport o atrybucji umożliwia powiązanie konwersji w witrynie z reklamą wybraną w ramach aukcji z użyciem Protected Audience API. Na przykład użytkownik może kliknąć wyświetloną przez Ciebie reklamę produktu, zostać przekierowany do witryny reklamodawcy i dokonać tam zakupu. W takiej sytuacji możesz chcieć przypisać ten zakup do wyświetlonej reklamy. Interfejs Attribution Reporting API zostanie zintegrowany z interfejsem Protected Audience API, aby łączyć dane aukcji z witryny wydawcy z danymi o konwersjach z witryny reklamodawcy.

Podczas prac nad trwalszym rozwiązaniem możesz używać interfejsu Ads Reporting API w przypadku ramek z ograniczonym dostępem jako mechanizmu przejściowego do generowania raportu na poziomie zdarzenia i raportu zbiorczego za pomocą interfejsu Attribution Reporting. Pamiętaj, że te raporty służą do pomiaru konwersji i są oddzielone od raportów o zaangażowaniu na poziomie zdarzenia i raportów zbiorczych generowanych na podstawie aukcji i ramki reklamy. Gdy będziemy mieć gotowe trwalsze rozwiązanie, opublikujemy wyjaśnienie.

Mechanizm przejściowy

Podczas rejestrowania sygnału reklamy możesz użyć słowa kluczowego reserved.top_navigation, które automatycznie doda nagłówek Attribution-Reporting-Eligible, aby sygnał kwalifikował się do zarejestrowania jako źródło atrybucji.

registerAdBeacon({
 'reserved.top_navigation': 'https://adtech.example/click?buyer_event_id=123',
});

Aby dołączyć dane na poziomie zdarzenia do zarejestrowanego sygnału, możesz wywołać funkcję setReportEventDataForAutomaticBeacons() z ograniczonej ramki z ładunkiem zdarzenia.

window.fence.setReportEventDataForAutomaticBeacons({
  eventType: 'reserved.top_navigation',
  eventData: 'data from the frame',
  destination:['seller', 'buyer']
})

Więcej informacji znajdziesz w sekcji poświęconej interfejsowi Attribution Reporting API w wyjaśnieniu interfejsu Ads Reporting API.

Przykład raportowania zaangażowania i konwersji

W tym przykładzie przyjrzymy się temu z perspektywy kupującego, który jest zainteresowany powiązaniem ze sobą danych z aukcji, ramki reklamy i witryny konwersji.

W tym przepływie pracy kupujący współpracuje ze sprzedawcą, aby wysłać na aukcję unikalny identyfikator. Podczas aukcji kupujący przesyła ten unikalny identyfikator wraz z danymi aukcji. Podczas renderowania i konwersji dane z ramki ograniczonej lub elementu iframe są również wysyłane z tym samym niepowtarzalnym identyfikatorem. Później można użyć unikalnego identyfikatora, aby powiązać te raporty.

Przepływ pracy:

1. Przed rozpoczęciem aukcji kupujący wysyła do sprzedawcy niepowtarzalny identyfikator w ramach odpowiedzi na pytanie o stawkę w określaniu stawek w czasie rzeczywistym („RTB”). Identyfikator można ustawić jako zmienną, np. auctionId. Identyfikator jest przekazywany jako perBuyerSignals w parametrze auctionConfig i staje się dostępny w elementach roboczych kupującego.
2. Podczas aukcji kupujący może zarejestrować sygnał reklamy, który będzie wywoływany w momencie renderowania reklamy i w momencie konwersji (registerAdBeacon()).
   1. Aby powiązać sygnały aukcji ze zdarzeniem ramki reklamy, ustaw auctionId jako parametr zapytania w adresie URL sygnału.
   2. Aby powiązać sygnały aukcji ze zdarzeniem konwersji, ustaw parametr auctionId w adresie URL sygnału.
3. Podczas renderowania reklamy sygnały zarejestrowane w czasie aukcji mogą być wywoływane lub wzbogacane o dane na poziomie zdarzenia.
   1. Wywołaj zdarzenie ramki za pomocą funkcji reportEvent() i przekaż dane na poziomie zdarzenia.
   2. Dodawanie ładunku na poziomie zdarzenia do sygnału atrybucji za pomocą parametru setReportEventDataForAutomaticBeacons()
   3. Zarejestruj reklamę w interfejsie Attribution Reporting API, odpowiadając na żądania sygnału reklamy za pomocą nagłówka Attribution-Reporting-Register-Source.
4. W momencie konwersji możesz aktywować źródło zarejestrowane w momencie aukcji.

Po zakończeniu tego procesu kupujący będzie mieć raport z aukcji, raport o zaangażowaniu i raport o konwersjach, które będą powiązane ze sobą za pomocą jednego unikalnego klucza.

Podobny proces dotyczy sprzedawcy, który potrzebuje dostępu do danych o atrybucji. Może on też używać unikalnego identyfikatora do wysyłania z parametrem registerAdBeacon(). Wywołanie reportEvent() w ramce zawiera usługę docelową, której można użyć do wysłania raportu zarówno do kupującego, jak i do sprzedawcy. Pamiętaj, że platforma SSP musi być też obecna na stronie docelowej, aby wywoływanie zostało przypisane do źródła.

Zbieranie danych Protected Audience

Interfejs Private Aggregation API to mechanizm używany do raportowania danych Protected Audience w celu wygenerowania raportu podsumowującego, czyli zaszumionego raportu zbiorczego danych zebranych w grupach. Kosz jest reprezentowany przez klucz agregacji, a niektóre informacje mogą być w nim zakodowane.

Na przykład zdarzenie wyświetlenia reklamy może być zliczane w różnych segmentach, z których każdy reprezentuje inną kampanię reklamową. Raport podsumowujący różni się od raportu na poziomie zdarzenia tym, że nie ujawnia informacji o poszczególnych zdarzeniach. Dzięki raportowi na poziomie zdarzenia możesz stwierdzić, że użytkownicy A, B i C zobaczyli kampanię 123. Raporty podsumowujące umożliwiają pomiar liczby użytkowników, którzy widzieli kampanię 123, a w celu ochrony prywatności użytkowników dodawany jest szum.

Więcej informacji o tym interfejsie API znajdziesz w artykule Private Aggregation.

Zbieranie sygnałów aukcji

Za pomocą Private Aggregation możesz agregować sygnały dostępne w workletach na serwerze. Do agregacji sygnałów możesz użyć privateAggregation.contributeToHistogram() metody dostępnej w module roboczym dotyczącym określania stawek przez kupującego, module roboczym dotyczącym oceny sprzedawcy oraz modułach roboczych dotyczących raportowania przez kupującego i sprzedawcę.

W tym przykładzie wygrywająca stawka jest agregowana w zasobniku właściciela grupy zainteresowań:

function convertBuyerToBucket(igOwner) {}
function convertWinningBidToValue(winningBid) {}

function reportResult(auctionConfig, browserSignals) {
  privateAggregation.contributeToHistogram({
    bucket: convertBuyerToBucket(browserSignals.interestGroupOwner),
    value: convertWinningBidToValue(browserSignals.bid)
  });
} 

Jest to ogólny mechanizm, którego należy używać, gdy sygnały, które chcesz agregować, nie są powiązane z danymi na poziomie zdarzenia i nie są wywoływane przez zdarzenie poza aukcją. Więcej informacji o raportowaniu sygnałów aukcji znajdziesz w wyjaśnieniu.

Agregowanie sygnałów aukcji z danymi o zdarzeniach

Możesz agregować sygnały aukcji z ograniczonymi informacjami o zdarzeniu, które występuje w ramce reklamy. Możesz na przykład zbiorczo mierzyć liczbę kliknięć reklamy w kampanii, tworząc zasobnik reprezentujący tę kampanię i zdarzenie kliknięcia. Pamiętaj, że w ramce reklamy możesz określić, jakie zdarzenie wystąpiło, ale nie możesz dołączyć ładunku na poziomie zdarzenia.

Aby agregować sygnały aukcji według zdarzeń, możesz użyć funkcji privateAggregation.contributeToHistogramOnEvent(eventType, contribution), która przyjmuje ciąg znaków określający typ zdarzenia i wartość, która ma być raportowana po wywołaniu tego zdarzenia. Możesz wywołać tę metodę z niestandardowym typem zdarzenia, a następnie wywołać window.fence.reportEvent(eventType) z ramki reklamy, aby przesłać raport.

Załóżmy, że chcesz sprawdzić, ile kliknięć uzyskała reklama w kampanii.

// Protected Audience API worklet
function getClickReportBucketForCampaign(campaignId) {
  // return a bucket for the campaign ID and the click event
}

function generateBid(interestGroup) {
  privateAggregation.contributeToHistogramOnEvent('click', {
    bucket: getClickReportBucketForCampaign(interestGroup.ads.metadata.campaignId), 
    value: 1
  });
}

W funkcji generowania stawek możesz zdefiniować przedział jako kombinację identyfikatora kampanii i zdarzenia kliknięcia, a następnie zwiększać wartość tego przedziału o 1 za każdym razem, gdy zdarzenie zostanie wywołane.

// Ad frame
window.fence.reportEvent('click');

Później możesz przesłać zgłoszenie z ramki reklamy, wywołując funkcję reportEvent(eventType):

Więcej informacji o wywoływaniu wkładów Private Aggregation z ramki znajdziesz w wyjaśnieniu.

Raportowanie wyników i skuteczności aukcji

Możesz też agregować wyniki aukcji, gdy są one wywoływane przez zdarzenie wygranej lub przegranej aukcji, za pomocą parametru contributeToHistogramOnEvent(eventType, contribution), jeśli przekazujesz zarezerwowane słowa kluczowe typu zdarzenia (reserved.win, reserved.loss i reserved.always).

Agregacja prywatna udostępnia listę wartości podstawowych, na podstawie których możesz obliczyć przedział i wartość swojego wkładu. Dostępne wartości podstawowe wyników aukcji to wartość stawki zwycięskiej reklamy, wartość stawki, która uzyskała drugi najwyższy wynik, oraz przyczyna odrzucenia stawki z aukcji.

Jeśli podana jest jakaś wartość bazowa, np. kwota wygrywającej stawki, możesz określić, ile należy do niej dodać lub od niej odjąć, a następnie zgłosić wartość końcową. Jeśli na przykład zwycięska stawka w wysokości 5 zł jest podana jako wartość bazowa, możesz odjąć od niej swoją stawkę w wysokości 2 zł, aby obliczyć rzeczywistą wartość 3 zł, o którą przegrałeś(-aś) aukcję.

Raportowanie wyników aukcji

Przyjrzyjmy się przykładowi, w którym przegrywasz aukcję i chcesz się dowiedzieć, o ile Twoja stawka różniła się od ceny rozliczeniowej aukcji.

Aby dowiedzieć się, o ile przegrałeś(-aś) aukcję, odejmij swoją cenę od ceny zwycięskiej stawki:

function generateBid() {
  const bid = calculateBidAmount();

  privateAggregation.contributeToHistogramOnEvent('reserved.loss', {
    bucket: getBucketForCampaign(interestGroup.ads.metadata.campaignId),
    value: {
      baseValue: 'winning-bid',
      scale: 1 // Scale the value to minimize noise-to-signal ratio 
      offset: -bid, // Numbers added to browser value after scaling 
    }
  });
}

Po przesłaniu raportu rzeczywista zgłoszona wartość będzie przeskalowaną wartością baseValue przesuniętą o wartość offset. Więcej informacji znajdziesz w wyjaśnieniu.

Raportowanie skuteczności

Kupujący i sprzedawcy mogą zgłaszać, ile czasu zajęło wykonanie skryptu i pobranie zaufanych sygnałów. Sprzedawcy mogą za zgodą kupujących zbierać informacje o czasie generowania stawki i czasie sygnału zaufanego ustalania stawek każdego kupującego.

Więcej informacji znajdziesz w tym wyjaśnieniu.

Przechowywanie sygnałów aukcji w pamięci współdzielonej

Współdzielone miejsce na dane to niepodzielone miejsce na dane, które jest dostępne w różnych domenach. Możesz w nim swobodnie zapisywać dane, ale odczytywanie i przetwarzanie zapisanych wartości jest chronione. Jednym z dostępnych mechanizmów kontroli dostępu do interfejsu Shared Storage API jest Private Aggregation. Wartości w pamięci współdzielonej możesz odczytywać tylko w ramach workletu i możesz je zgłaszać za pomocą prywatnej agregacji z workletu.

Możesz też zapisywać dane w pamięci współdzielonej z poziomu elementów roboczych Protected Audience API służących do ustalania stawek, oceniania i raportowania. W późniejszym czasie możesz zgłosić te wartości w pamięci współdzielonej na serwerze za pomocą Private Aggregation . Możesz też użyć zapisanych wartości w przypadku operacji Wybór adresu URL.

Z poziomu elementu roboczego interfejsu Protected Audience API możesz zapisywać w pamięci współdzielonej dowolne klucze i wartości:

// Protected Audience API worklet
function generateBid() {
  sharedStorage.set('test-bucket', 123);
}

Później możesz wczytać worklet pamięci współdzielonej, aby odczytać tę wartość i wysłać ją za pomocą Private Aggregation:

// Shared Storage worklet
class SendReachReport{
  async run() {
    const testBucket = await this.sharedStorage.get('test-bucket');

    privateAggregation.contributeToHistogram({
      bucket: testBucket,
      value: 1
    });
  }
}

register('send-report', SendReachReport);

Więcej informacji o pamięci współdzielonej znajdziesz w sekcji poświęconej pamięci współdzielonej w przewodniku dla deweloperów dotyczącym raportowania w interfejsie Protected Audience API, w wyjaśnieniu, wersji demonstracyjnej i w kodzie demonstracyjnym w GitHubie.

What's next?

We want to engage in conversations with you to ensure we build an API that works for everyone.

Discuss the API

Like other Privacy Sandbox APIs, this API is documented and discussed publicly.

Experiment with the API

You can experiment and participate in conversation about the Protected Audience API.