Omówienie interfejsu Private Aggregation API

Generowanie raportów zbiorczych przy użyciu danych pochodzących z Protected Audience API i danych z różnych witryn z pamięci współdzielonej.

Aby zapewnić kluczowe funkcje, na których zależy internet, agregacja prywatna Interfejs API został stworzony do agregacji i raportowania danych z różnych witryn w w sposób zapewniający ochronę prywatności.

Stan wdrożenia

Propozycja Stan
Zapobieganie nieprawidłowym raportom interfejsu Private Aggregation API dzięki weryfikacji raportów z Udostępnionego miejsca na dane
Objaśnienie		 Dostępne w Chrome
Dostępność trybu debugowania agregacji prywatnej zależy od możliwości korzystania z komputerów zewnętrznych
Problem z GitHubem		 Funkcja dostępna w Chrome M119
Skrócenie opóźnienia raportu
Wyjaśnienie		 Funkcja dostępna w Chrome M119
Obsługa interfejsu Private Aggregation API i usługi agregacji dla Google Cloud
Wyjaśnienie		 Dostępne w Chrome M121
Wypełnianie danych w przypadku zbiorczych ładunków raportu
Opis		 Dostępne w Chrome M119
Tryb debugowania prywatnej agregacji dostępny w raportach auctionReportBuyers
Opis		 Dostępne w Chrome M123
Obsługa identyfikatora filtrowania
Wyjaśnienie		 Dostępne w Chrome M128
Łączenie wkładu po stronie klienta
Wprowadzenie		 Dostępne w Chrome M129

Czym jest interfejs Private Aggregation API

Interfejs Private Aggregation API umożliwia deweloperom generowanie raportów zbiorczych z danymi z interfejsu Protected Audience API oraz danymi z różnych witryn z interfejsu Shared Storage.

Główna funkcja tego interfejsu API jest nazywana contributeToHistogram(). Histogram umożliwia agregowanie danych między użytkownikami w każdym zdefiniowanym zasobniku (nazywanym w interfejsie API kluczem agregacji). Wywołanie histogramu gromadzi wartości i zwraca zagregowany wynik w funkcji ma postać raportu podsumowującego. Raport może na przykład pokazywać liczbę witryn, w których każdy użytkownik widział Twoje treści lub natknął się na błąd w skrypcie innej firmy. Ta operacja jest wykonywana w workletze innego interfejsu API.

Jeśli na przykład masz już zarejestrowane dane demograficzne i geograficzne w Shared Storage, możesz użyć interfejsu Private Aggregation API do stworzenia histogramu, który pokaże przybliżoną liczbę użytkowników w Nowym Jorku, którzy wyświetlili Twoje treści w różnych witrynach. Aby agregować dane na potrzeby tego pomiaru, możesz zakodować wymiar geograficzny w kluczu agregacji i zaliczyć użytkowników do wartości agregowanej.

Kluczowych pojęć

Gdy wywołasz interfejs Private Aggregation API z kluczem agregacji i wartością agregującą, przeglądarka wygeneruje raport agregowany.

Raporty agregujące są wysyłane na Twój serwer w celu zbierania i grupowania. Raporty zbiorcze są później przetwarzane przez usługę agregacji i generowany jest raport z podsumowaniem.

Więcej informacji o kluczowych pojęciach związanych z Private Aggregation API znajdziesz w dokumentacji Private Aggregation API – podstawy.

Różnice w stosunku do raportów atrybucji

Interfejs Private Aggregation API ma wiele podobieństw do interfejsu Attribution Reporting API. Attribution Reporting to samodzielny interfejs API służący do pomiaru konwersji, natomiast agregacja prywatna służy do pomiarów w różnych witrynach w połączeniu z interfejsami API, takimi jak Protected Audience API i Shared Storage. Oba interfejsy API tworzą agregowane raporty, które są wykorzystywane przez backend usługi agregacji do generowania raportów podsumowujących.

Attribution Reporting łączy dane zebrane ze zdarzenia wyświetlenia i zdarzenia konwersji, które mają miejsce w różnych momentach. Agregacja prywatna służy do pomiaru 1 zdarzenia w różnych witrynach.

Przetestuj ten interfejs API

Aby lokalnie przetestować Private Aggregation API, włącz wszystkie interfejsy Ad Privacy API w dokumencie chrome://settings/adPrivacy.

Dowiedz się więcej o testowaniu w eksperymencie i uczestnictwie w nim.

Skorzystaj z wersji demonstracyjnej

Demonstrację interfejsu Private Aggregation API na potrzeby Shared Storage można znaleźć na stronie goo.gle/shared-storage-demo, a kod jest dostępny na GitHub. Wersja demonstracyjna implementuje operacje po stronie klienta i tworzy agregowany raport, który jest wysyłany na Twój serwer.

W przyszłości opublikowana zostanie wersja demonstracyjna interfejsu Private Aggregation API na potrzeby Protected Audience API.

Przypadki użycia

Prywatna agregacja to ogólny interfejs API do pomiarów w wielu witrynach. Można go używać w elementach worklet Shared Storage i Protected Audience API. Najpierw musisz określić, jakie informacje chcesz zbierać. Te punkty danych są podstawą kluczy agregacji.

Z pamięcią współdzieloną

Pamięć współdzielona umożliwia odczytywanie i zapisywanie danych z różnych witryn w bezpiecznym środowisku, co zapobiega wyciekowi danych. Interfejs Private Aggregation API umożliwia pomiar danych z różnych witryn przechowywanych w pamięci współdzielonej.

Pomiar zasięgu wśród unikalnych użytkowników

Możesz chcieć sprawdzić, ilu unikalnych użytkowników obejrzało Twoje treści. Interfejs Private Aggregation API może podać odpowiedź, np. „Ok. 317 unikalnych użytkowników widziało system Content ID 861”.

W pamięci współdzielonej możesz ustawić flagę, aby wskazać, czy użytkownik widział już daną treść. Przy pierwszej wizycie, w której flaga nie istnieje, wysyłane jest wywołanie do agregacji prywatnej, a następnie ustawiana jest flaga. W przypadku kolejnych wizyt użytkownika (w tym wizyt w innych witrynach) możesz zaznaczyć pole „Udostępnione miejsce na dane” i pominąć przesyłanie raportu do prywatnej agregacji, jeśli ta flaga jest ustawiona. Więcej informacji o metodach wdrażania tych pomiarów znajdziesz w naszym raporcie dotyczącym zasięgu.

Pomiar danych demograficznych

Możesz analizować dane demograficzne użytkowników, którzy widzieli Twoje treści w różnych witrynach.

Prywatna agregacja może podać odpowiedź, np. „Około 317 unikalnych użytkowników w wieku 18–45 lat pochodzi z Niemiec”. Korzystaj z pamięci współdzielonej, aby uzyskiwać dostęp do danych demograficznych z kontekstu zewnętrznego. W późniejszym czasie możesz wygenerować raport z konsolidacją prywatną, kodując wymiary grupa wiekowa i kraj w kluczu agregacji.

Pomiar częstotliwości K+

Możesz zmierzyć liczbę użytkowników, którzy zobaczyli fragment treści lub reklamę co najmniej K razy w danej przeglądarce dla wstępnie wybranej wartości K.

Agregacja prywatna może przynieść odpowiedź, np. „Około 89 użytkowników widziało system Content ID 581 co najmniej 3 razy”. Licznik może być zwiększony w pamięci współdzielonej z różnych witryn i może być odczytywany w obrębie workletu. Gdy liczba przekroczy K, raport można przesłać za pomocą agregacji prywatnej.

Atrybucja uwzględniająca różne interakcje

Te wskazówki zostaną opublikowane w witrynie dla programistów, aby specjaliści ds. technologii reklamowych mogli zrozumieć, jak wdrożyć MTA w ramach agregacji współdzielonej pamięci masowej i agregacji prywatnej.

Za pomocą Protected Audience API

Interfejs Protected Audience API umożliwia ponowne kierowanie i niestandardowe przypadki użycia list odbiorców, a agregacja prywatna umożliwia raportowanie zdarzeń z workletów kupujących i sprzedawców. Interfejsu API można używać do wykonywania takich zadań jak pomiar rozkładu stawek aukcji.

Korzystając z workletu Protected Audience API, możesz agregować dane bezpośrednio za pomocą contributeToHistogram() i raportować dane na podstawie reguły za pomocą narzędzia contributeToHistogramOnEvent(), które jest specjalnym rozszerzeniem interfejsu Protected Audience API.

Dostępne funkcje

Poniższe funkcje są dostępne w obiekcie privateAggregation dostępnym w workletach Shared Storage i Protected Audience API.

contributeToHistogram()

Możesz wywołać metodę privateAggregation.contributeToHistogram({ bucket: <bucket>, value: <value> }), gdzie klucz agregacji to bucket, a wartość agregowana jako value. W przypadku parametru bucket wymagana jest właściwość BigInt. W przypadku parametru value wymagana jest liczba całkowita.

Oto przykład użycia tej funkcji w pamięci współdzielonej w celu pomiaru zasięgu:

iframe.js

// Cross-site iframe code

async function measureReach() {
 // Register worklet
 await window.sharedStorage.worklet.addModule('worklet.js');

 // Run reach measurement operation
 await window.sharedStorage.run('reach-measurement', { 
  data: { contentId: '1234' } 
 });
}

measureReach();

worklet.js

// Shared storage worklet code

function convertContentIdToBucket(campaignId){ 
  // Generate aggregation key
}

// The scale factor is multiplied by the aggregatable value to
// maximize the signal-to-noise ratio. See "Noise and scaling" 
// section in the Aggregation Fundamentals document to learn more.
const SCALE_FACTOR = 65536;

class ReachMeasurementOperation {
  async run(data) {
    const key = 'has-reported-content';
    // Read the flag from Shared Storage
    const hasReportedContent = await sharedStorage.get(key) === 'true';

    // Do not send report if the flag is set
    if (hasReportedContent) {
      return;
    }

    // Send histogram report
    // Set the aggregation key in `bucket`
    // Bucket examples: 54153254n or BigInt(54153254)
    // Set the scaled aggregatable value in `value`
    privateAggregation.contributeToHistogram({
      bucket: convertContentIdToBucket(data.contentId), 
      value: 1 * SCALE_FACTOR 
    });

    // Set the flag in Shared Storage
    await sharedStorage.set(key, true);
  }
}

register('reach-measurement', ReachMeasurementOperation);

Powyższy przykładowy kod wywołuje agregację prywatną po każdym wczytaniu treści elementu iframe z innej witryny. Kod iframe wczytuje Worklet, a Worklet wywołuje interfejs Private Aggregation API z identyfikatorem treści przekonwertowanym na klucz agregacji (zasobnik).

contributeToHistogramOnEvent()

Tylko w ramach listów Protected Audience API udostępniamy oparty na aktywatorach mechanizm wysyłania raportu tylko wtedy, gdy wystąpi określone zdarzenie. Ta funkcja pozwala też uzależnić grupę i wartość od sygnałów, które nie są jeszcze dostępne w danym momencie aukcji.

Metoda privateAggregation.contributeToHistogramOnEvent(eventType, contribution) przyjmuje eventType, które określa zdarzenie aktywujące, i tag contribution, który jest przesyłany po jego wywołaniu. Zdarzenie aktywujące może pochodzić z samej aukcji po jej zakończeniu (np. wygranej lub przegranej w aukcji) lub z ogrodzonej ramki, która wyświetliła reklamę. Aby wysyłać raport o zdarzeniach aukcji, możesz użyć 2 zarezerwowanych słów kluczowych: reserved.win, reserved.loss i reserved.always. Aby przesłać raport wywoływany przez zdarzenie z ramki zabezpieczonej, zdefiniuj typ zdarzenia niestandardowego. Aby aktywować zdarzenie z chronionej ramki, użyj metody fence.reportEvent() dostępnej w interfejsie Fenced Frames Ads Reporting API.

Ten przykład wysyła raport o wyświetleniach po wywołaniu zdarzenia wygranej aukcji i raport kliknięć, jeśli zdarzenie click zostanie wywołane z chronionej ramki, która wyświetliła reklamę. Te dwie wartości mogą służyć do obliczania współczynnika klikalności. 

function generateBid(interestGroup, auctionSignals, perBuyerSignals, trustedBiddingSignals, browserSignals) {
  // …
  privateAggregation.contributeToHistogramOnEvent("reserved.win", {
      bucket: getImpressionReportBucket(),
      value: 1
  });
  privateAggregation.contributeToHistogramOnEvent("click", {
      bucket: getClickReportBuckets(), // 128-bit integer as BigInt
      value: 1
  });

Aby dowiedzieć się więcej, przeczytaj wyjaśnienie dotyczące rozszerzonej agregacji prywatnej.

enableDebugMode()

Chociaż pliki cookie innych firm będą nadal dostępne, udostępnimy tymczasowy mechanizm, który po włączeniu trybu debugowania ułatwi debugowanie i testowanie. Raport debugowania przydaje się do porównywania pomiarów opartych na plikach cookie z pomiarami za pomocą agregacji prywatnej. Raport pozwala też szybko sprawdzić integrację interfejsu API.

Wywołanie privateAggregation.enableDebugMode() w Worklet włącza tryb debugowania, który powoduje, że agregowane raporty zawierają niezaszyfrowany ładunek (cleartext). Następnie możesz przetworzyć te ładunki za pomocą lokalnego narzędzia do testowania usługi agregacji.

Tryb debugowania jest dostępny tylko dla elementów wywołujących, które mają dostęp plików cookie innych firm. Jeśli rozmówca nie ma dostępu do plików cookie innych firm, enableDebugMode() spowoduje dyskretną niepowodzenie. Oznacza to, że jeśli firma zewnętrzna Pliki cookie są wycofane, tryb debugowania nie będzie już dostępny.

Klucz debugowania możesz też ustawić, wywołując funkcję privateAggregation.enableDebugMode({ <debugKey: debugKey> }), gdzie jako klucz debugowania można używać elementu BigInt. Klucz debugowania może służyć do powiązania danych z pomiaru z użyciem plików cookie i danych z pomiaru agregacji prywatnej.

W danym kontekście można je wywołać tylko raz. Wszystkie kolejne wywołania będą zgłaszać wyjątek.

// Enables debug mode
privateAggregation.enableDebugMode();

// Enables debug mode and sets a debug key
privateAggregation.enableDebugMode({ debugKey: BigInt(1234) });

Weryfikacja zgłoszenia

W przypadku pamięci współdzielonej możesz sprawdzić, czy otrzymane raporty agregowane są prawidłowe, dodając identyfikator kontekstu do wywołania operacji pamięci współdzielonej. Identyfikator zostanie dołączony do wysłanego raportu, a później możesz go użyć, aby sprawdzić, czy raport został wysłany z operacji pamięci współdzielonej.

Więcej informacji znajdziesz w objaśnieniu dotyczącym weryfikacji na potrzeby raportowania.

Angażuj odbiorców i dziel się opiniami

Interfejs Private Aggregation API jest w trakcie dyskusji i w przyszłości może ulec zmianie. Jeśli wypróbujesz ten interfejs API i chcesz przekazać nam swoją opinię, chętnie poznamy jego opinię.