Raporty o aukcjach w ramach Protected Audience API

Zadbaj o dobrą organizację dzięki kolekcji Zapisuj i kategoryzuj treści zgodnie ze swoimi preferencjami.

Pomiar danych i wyników aukcji Protected Audience API

Z tego artykułu dowiesz się, jak zgłaszać na serwer dane aukcji interfejsu Protected Audience API, a także jakie mechanizmy przejściowe możesz obecnie stosować podczas migracji, dopóki nie udostępnimy alternatywnych rozwiązań.

Aby generować raporty o ważnych danych pochodzących z aukcji reklam, Protected Audience API współpracuje z:

• Private Aggregation, który zbiera sygnały i wyniki aukcji, aby generować raporty podsumowujące.
• Interfejs Ads Reporting API do obsługi ramek odizolowanych i ramek iframe, które stanowią kanał w ramach ramek do komunikacji z modułami 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 jest mechanizmem przejściowym, dopóki nie zostanie opracowany bardziej prywatny mechanizm raportowania.
• Raporty atrybucji, które umożliwiają powiązanie danych o konwersjach z sygnałami aukcji.
• Shared Storage, która umożliwia zapisywanie sygnałów aukcji w przechowywaniu danych z wielu witryn, a potem raportowanie tych danych za pomocą Private Aggregation.

Omówienie raportowania w interfejsie Protected Audience API

Dane z przebiegu aukcji Protected Audience API mogą być przesyłane na serwer w 3 głównych okresach: w czasie aukcji, gdy aukcja jest przeprowadzana w witrynie wydawcy; w czasie renderowania, gdy reklama jest renderowana w ramce odizolowanej lub ramce osadzonej w witrynie wydawcy; oraz w czasie konwersji, gdy użytkownik wykonuje w innej witrynie działanie, które można przypisać do aukcji.

W czasie aukcji możesz raportować dane aukcji za pomocą elementów roboczych raportowania. Podczas renderowania możesz zgłaszać dane o zaangażowaniu z ramki iframe lub wydzielonej ramki. W czasie konwersji możesz zgłaszać dane atrybucji z strony docelowej za pomocą interfejsu Attribution Reporting API.

Lokalizacje do raportowania

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

W każdym z wymienionych okresów kupujący i sprzedający mają dostęp do różnych interfejsów API do 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 z interfejsu Protected Audience API można raportować te dane:

Sygnały

Sygnały to dane kontekstowe aukcji, dane o użytkownikach, dane w czasie rzeczywistym i dane przeglądarki dostępne dla kupujących i sprzedawców w ramach workletu, które umożliwiają generowanie stawek, obliczanie oceny reklamy i raportowanie wyników aukcji.

Obiekt konfiguracja aukcji jest głównym źródłem danych, które są udostępniane jako sygnały w elementach roboczych. Wydawca i sprzedawca mogą dostarczać dane kontekstowe i własne w konfiguracji aukcji. Te sygnały można wzbogacić o dane o grupach zainteresowań od kupującego, dane na poziomie zdarzenia z ramki renderowania reklamy oraz dane atrybucji ze strony kliknięcia. Dane te można wykorzystać do generowania raportów o kupujących i sprzedawcach, do rozliczeń, budżetowania, trenowania modeli ML i do innych celów.

Inne dostępne dane

• Dane wyników dotyczące danych o wygranych i przegranych aukcjach, takich jak cena zwycięskiej stawki i powody odrzucenia stawki.
• Dane o skuteczności zawierające informacje o opóźnieniach, np. o czasie pobierania i wykonania workleta ustalania stawek.

Dane dostępne poza aukcją Protected Audience API

Poza aukcją Protected Audience API są 2 okresy, w których można raportować dane.

Podczas renderowania, gdy reklama jest renderowana w witrynie wydawcy, dane na poziomie zdarzenia z ramki iframe lub ramki odizolowanej mogą zostać powiązane z danymi aukcji Protected Audience API i przesłane do Twojego serwera. Przykładowe dane na poziomie zdarzenia obejmują wyświetlenie reklamy, kliknięcie reklamy, najechanie kursorem i wszystkie inne zdarzenia występujące w ramce.

W czasie konwersji, gdy użytkownik wykonuje na stronie przejścia po kliknięciu działanie, które jest przypisywane aukcji, dane na poziomie zdarzenia z tej strony mogą zostać powiązane z danymi aukcji z Protected Audience API i przesłane do Twojego serwera.

Raporty na poziomie zdarzenia

Raporty na poziomie zdarzenia zawierają szczegółowe informacje z jednego lub większej liczby zdarzeń. Zdarzenie może być wygraną aukcji, wyświetleniem reklamy lub konwersją. Co najmniej do 2026 r. raportowanie wygranych aukcji na poziomie zdarzenia pozostanie w użyciu, a do renderowania reklamy w ramach Protected Audience nie będą wymagane ramki odizolowane. Do raportowania na poziomie zdarzenia można używać ramki iframe z nieograniczonym dostępem do sieci. Interfejs Ads Reporting API jest też dostępny w ramkach wydzielonych i ramkach osadzonych, aby umożliwić Ci powiązanie danych o aukcji i konwersjach z danymi na poziomie zdarzenia pochodzącymi z ramki. Dzięki temu ekosystem będzie miał łatwiejszy dostęp do migracji, ponieważ będziesz mieć możliwość dalszego korzystania z obecnej infrastruktury raportowania co najmniej do 2026 roku, podczas gdy będziesz migrować swój system na Protected Audience.

Raporty o wygrywaniu aukcji na poziomie zdarzenia z użyciem sendReportTo()

Mechanizmem umożliwiającym raportowanie danych na poziomie zdarzenia w ramach aukcji Protected Audience jest sendReportTo() function w przypadku wygranej aukcji. Funkcja jest dostępna w elementach roboczych raportowania dla kupujących i sprzedawców, a przeglądarka wysyła żądanie GET do podanego ciągu adresu URL, gdy rozpoczyna się renderowanie reklamy. Jako parametry zapytania w adresie URL możesz zakodować dowolny sygnał dostępny w Twoich workletach.

Na przykład kupujący może podać kwotę wygrywającej stawki z workletu reportWin() 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 wygraniu dla sprzedawcy, gdy wywołanie pochodzi z reportResult(), oraz raportu o wygraniu dla kupującego, gdy wywołanie pochodzi z reportWin(). Funkcja sendReportTo() będzie dostępna co najmniej do 2026 r.

Raport Zaangażowanie

Raport o zaangażowaniu zawiera dane na poziomie zdarzenia z kreacji reklamy, np. dane o wyświetleniach lub kliknięciach, które są powiązane z sygnałami aukcji Protected Audience API, która renderowała reklamę. Reklama jest renderowana po zakończeniu aukcji, więc sygnały aukcji nie są dostępne w ramce, która renderuje reklamę. Aby umożliwić Ci łączenie danych z różnych okresów, udostępniamy 2 mechanizmy przejściowe do generowania raportów zaangażowania.

Opisane powyżej działanie sendReportTo() można wykorzystać do powiązania danych aukcji z danymi na poziomie zdarzenia z elementu iframe, ale nie działa ono w przypadku ramki odizolowanej, ponieważ nie można przekazać unikalnego identyfikatora od osoby umieszczającej element, ponieważ komunikacja między nią a ramką odizolowaną jest ograniczona. Do kojarzenia danych aukcji z danymi na poziomie zdarzenia pochodzącymi z reklamy w ramce wydzielonej możesz używać interfejsu Ads Reporting API.

Interfejs Ads Reporting API do obsługi odizolowanych ramek i ramek iframe

Interfejs Ads Reporting API przeznaczony do obsługi chronionych ramek i ramek iframe udostępnia mechanizm umożliwiający powiązanie danych na poziomie zdarzenia użytkownika z ramki reklamy z sygnałami w ramach aukcji Protected Audience.

W worklecie raportowania interfejsu Protected Audience API możesz zarejestrować sygnał reklamy za pomocą funkcji registerAdBeacon() i przekazać adres URL raportowania z dodanymi sygnałami jako parametrami zapytania. Musisz też określić zdarzenie niestandardowe, które chcesz powiązać z adresem URL raportu. Następnie, gdy reklama zostanie wyrenderowana w ramce ogrodzeniowej, możesz wywołać zdarzenie niestandardowe, wywołując funkcję window.fence.reportEvent(). Dane dostępne w ramach wydzielonego obszaru można dodać jako ładunek.

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

W tym przykładzie identyfikator kampanii jest powiązany z ładunkiem na poziomie zdarzenia zawierającym współrzędne 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 interfejs Win Reporting API.

Aby dowiedzieć się więcej, przeczytaj artykuł.

Nieograniczony dostęp do sieci

Ramki ograniczone umożliwiają wczytywanie zasobów sieci w taki sam sposób jak ramka iframe, a w ramkach tych możesz wysyłać na serwer dane na poziomie zdarzenia. Raporty na poziomie zdarzenia możesz generować po stronie serwera, powiązać dane na poziomie zdarzenia z ogrodzonego ramki z danymi aukcji, które zostały wysłane z sendReportTo(), jak opisano w sekcji mechanizm raportowania na poziomie zdarzenia aukcji.

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

Raport atrybucji

Raport o przypisaniu umożliwia powiązanie konwersji w witrynie z reklamą wybraną w aukcji Protected Audience API. Użytkownik może na przykład kliknąć wyświetlaną przez Ciebie reklamę produktu, zostać przekierowany do witryny reklamodawcy i dokonać w niej zakupu. Chcesz przypisać ten zakup do wyświetlonej reklamy. Interfejs Attribution Reporting API zostanie zintegrowany z Protected Audience API, aby połączyć dane aukcji z witryny wydawcy z informacjami o konwersjach z witryny reklamodawcy.

Podczas gdy opracowujemy bardziej trwałe rozwiązanie, możesz używać interfejsu Ads Reporting API w przypadku ramek wydzielonych jako mechanizm przejściowy do generowania raportu na poziomie zdarzenia i raportu możliwych do zgrupowania za pomocą raportowania atrybucji. Pamiętaj, że te raporty służą do pomiaru konwersji i są odrębne od raportów na poziomie zdarzenia i zbiorczych raportów o zaangażowaniu generowanych na podstawie aukcji i ramki reklamowej. Gdy tylko będzie gotowe, opublikujemy wyjaśnienie dotyczące bardziej trwałego rozwiązania.

Mechanizm przejściowy

Podczas rejestrowania sygnału reklamowego możesz użyć słowa kluczowego reserved.top_navigation, które automatycznie doda nagłówek Attribution-Reporting-Eligible, aby sygnał mógł zarejestrować się 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 sygnalizatora, możesz wywołać funkcję setReportEventDataForAutomaticBeacons() z ramki wydzielonej z ładunkiem danych zdarzenia.

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

Więcej informacji znajdziesz w sekcji Atrybucja w raportach API w opisie interfejsu Ads Reporting API.

Przykład raportowania zaangażowania i konwersji

W tym przykładzie przyjrzymy się temu z perspektywy kupującego, który chce powiązać dane z aukcji, ramki reklamowej i witryny konwersji.

W tym procesie kupujący uzgadnia z sprzedawcą wysyłanie do aukcji unikalnego identyfikatora. Podczas aukcji kupujący wysyła ten unikalny identyfikator wraz z danymi aukcji. Podczas renderowania i konwersji dane z ramki odizolowanej lub ramki wbudowanej są też wysyłane z tym samym unikalnym identyfikatorem. Później możesz użyć tego identyfikatora do powiązania tych raportów.

Proces:

1. Przed rozpoczęciem aukcji kupujący wysyła do sprzedawcy unikalny identyfikator w ramach automatycznego określania stawek w czasie rzeczywistym („RTB”) w odpowiedzi na stawkę. Identyfikator można ustawić jako zmienną, np. auctionId. Identyfikator jest przekazywany jako perBuyerSignals w elementach auctionConfig i staje się dostępny w elementach roboczych kupującego.
2. W czasie aukcji kupujący może zarejestrować sygnał reklamowy, który zostanie uruchomiony w momencie wyświetlania reklamy i konwersji (registerAdBeacon()).
   1. Aby powiązać sygnały aukcji z zdarzeniem ramki reklamy, ustaw parametr zapytania auctionId jako parametr zapytania adresu URL sygnału.
   2. Aby powiązać sygnały aukcji ze zdarzeniem konwersji, w adresie URL beacona ustaw wartość auctionId.
3. Podczas renderowania reklam beacony zarejestrowane w czasie aukcji mogą zostać wywołane lub wzbogacone o dane na poziomie zdarzenia.
   1. Uaktywnij zdarzenie frame za pomocą funkcji reportEvent() i przekaż dane na poziomie zdarzenia.
   2. Dodaj ładunek na poziomie zdarzenia do sygnału atrybucji za pomocą funkcji setReportEventDataForAutomaticBeacons()
   3. Zarejestruj reklamę w interfejsie Attribution Reporting API, odpowiadając na żądania sygnału reklamowego za pomocą nagłówka Attribution-Reporting-Register-Source.
4. W czasie konwersji możesz uruchomić źródło zarejestrowane w czasie aukcji.

Po zakończeniu tego procesu kupujący będzie mieć raporty o aukcji, zaangażowaniu i konwersjach, które są ze sobą powiązane za pomocą unikalnego klucza, który umożliwia ich wzajemne łączenie.

Podobny proces dotyczy sprzedawcy, jeśli potrzebuje on dostępu do danych atrybucji. Może on też wysyłać niepowtarzalny identyfikator za pomocą registerAdBeacon(). W ramce wywołania funkcji reportEvent() znajduje się usługa docelowa, której można użyć do wysłania raportu zarówno do kupującego, jak i sprzedawcy. Pamiętaj, że aby można było przypisać wywołanie do źródła, na stronie docelowej musi się też znajdować dostawca usług SSP.

Aggregating Protected Audience data

Interfejs Private Aggregation API to mechanizm służący do raportowania danych Protected Audience na potrzeby generowania raportu zbiorczego, czyli raportu zbiorczego z dużą ilością danych zebranych w grupach. Grupa jest reprezentowana przez klucz agregacji, a w kluczu tym można zakodować pewne informacje.

Na przykład zdarzenie wyświetlenia reklamy może być liczone w różnych zbiornikach, 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. Z raportu na poziomie zdarzenia możesz się dowiedzieć, że użytkownicy A, B i C widzieli kampanię 123. Dzięki raportom podsumowującym możesz mierzyć liczbę użytkowników, którzy widzieli kampanię 123. Aby chronić prywatność użytkowników, dodawany jest szum.

Więcej informacji o tym interfejsie API znajdziesz w artykule Private Aggregation (Prywatna agregacja).

Aggregating auction signals

Za pomocą Private Aggregation możesz agregować sygnały dostępne w workletach na serwerze. Do agregacji sygnałów możesz używać metody privateAggregation.contributeToHistogram() dostępnej w elementach roboczych ustalania stawek przez kupującego, oceniania sprzedawcy i raportowania kupującego/sprzedawcę.

W tym przykładzie stawka zwycięska jest agregowana w grupie 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 artykule na ten temat.

Aggregating auction signals with event data

Możesz agregować sygnały aukcji z ograniczonymi informacjami o wydarzeniu, które występuje w ramce reklamy. Możesz np. zliczać liczbę kliknięć reklamy w danej kampanii, tworząc zbiorczy element, który reprezentuje tę kampanię i zdarzenie kliknięcia. Pamiętaj, że w ramce reklamy możesz określić, które zdarzenie wystąpiło, ale nie możesz dołączyć ładunku danych 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 współczynnik, który ma być zgłaszany po wywołaniu tego zdarzenia. Możesz wywołać metodę z niestandardowym typem zdarzenia, a potem wywołać window.fence.reportEvent(eventType) z ramki reklamy, aby wywołać przesłanie raportu.

Załóżmy, że chcesz sprawdzić, ile kliknięć uzyskała reklama w ramach danej 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 potem zwiększać jego wartość o 1 za każdym razem, gdy to zdarzenie zostanie wywołane.

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

Następnie w ramce reklamy możesz wywołać przesłanie zgłoszenia, wywołując funkcję reportEvent(eventType):

Więcej informacji o wyzwalaniu udziału w Private Aggregation z ramki znajdziesz w filmie poglądowym.

Raportowanie wyników i skuteczności aukcji

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

Prywatalna agregacja udostępnia listę wartości podstawowych, na podstawie których możesz obliczyć przedział i wartość swojego wkładu. Dostępne wartości bazowe wyników aukcji to wartość stawki zwycięskiej reklamy, wartość stawki, która została oceniona jako druga najwyższa, oraz powód odrzucenia stawki na aukcji.

Jeśli podana jest wartość podstawowa, np. kwota zwycięskiego stawka, możesz określić, o ile chcesz ją zwiększyć lub zmniejszyć, a potem podać wartość końcową. Jeśli na przykład jako wartość podstawową podano wartość wygranej stawki wynoszącą 5 zł, możesz odjąć swoją stawkę wynoszącą 2 zł, aby obliczyć rzeczywistą wartość 3 zł, o którą przegrałeś aukcję.

Raportowanie wyników aukcji

Rozważmy przykład, w którym tracisz aukcję i chcesz się dowiedzieć, jak bardzo Twoja stawka różni się od ceny licytowanej.

Aby sprawdzić, o ile przegraliśmy aukcję, możemy odjąć cenę stawki od ceny stawki zwycięskiej:

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 
    }
  });
}

Gdy raport zostanie przesłany, rzeczywista wartość raportowana będzie przeskalowaną wartością baseValue przesuniętą o wartość offset. Więcej informacji znajdziesz w tym artykule.

Raportowanie skuteczności

Kupujący i sprzedający mogą zgłaszać, ile czasu zajęło wykonanie skryptu i pobieranie zaufanych sygnałów. Sprzedawcy mogą zbierać czas generowania stawki i czas sygnału zaufanego określania stawek każdego kupującego (z jego zgodą).

Aby dowiedzieć się więcej, zapoznaj się z tym artykułem.

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

Współdzielone miejsce na dane to niepartycjonowane miejsce na dane w wielu domenach, do którego możesz swobodnie zapisywać dane, ale które jest chronione za pomocą bramek podczas odczytu i przetwarzania przechowywanych wartości. Jednym z dostępnych bramek interfejsu Shared Storage API jest Private Aggregation. Wartości w wspólnym magazynie możesz odczytywać tylko z poziomu workletu. Możesz też tworzyć raporty na ich podstawie, korzystając z prywatnej agregacji.

Możesz też zapisywać dane w Shared Storage z workletów ustalania stawek, oceniania i raportowania w Protected Audience API. Później możesz przesłać te wartości ze współdzielonego miejsca na dane na serwer, korzystając z Private Aggregation . Z zapisanych wartości możesz też korzystać w ramach operacji Wybór adresu URL.

Z poziomu workletu Protected Audience API możesz zapisywać dowolne klucze i wartości w shared storage:

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

Później możesz załadować worklet Shared Storage, aby odczytać i wysłać tę wartość 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 Shared Storage znajdziesz w sekcji dotyczącej tego interfejsu w przewodniku dla deweloperów dotyczącym interfejsu Protected Audience API, w artykule, demo na żywo oraz kodzie demo na GitHub.

Co dalej?

Chcemy wspólnie z Tobą rozmawiać, aby mieć pewność, że stworzyliśmy interfejs API dla wszystkich użytkowników.

Omów interfejs API

Podobnie jak inne interfejsy API Piaskownicy prywatności, ten interfejs API jest udokumentowany i omawiany publicznie.

Eksperymentuj z interfejsem API

Możesz eksperymentować i uczestniczyć w rozmowach na temat interfejsu Protected Audience API.