Omówienie interfejsu Private Aggregation API

Generuj raporty zbiorcze na podstawie danych z Protected Audience i danych z różnych witryn z pamięci współdzielonej.

Aby zapewnić dostęp do kluczowych funkcji, z których korzysta sieć, opracowaliśmy interfejs Private Aggregation API służący do agregacji i raportowania danych z różnych witryn w sposób zapewniający ochronę prywatności.

Stan implementacji

Propozycja Stan
Zapobieganie nieprawidłowym raportom interfejsu Private Aggregation API dzięki weryfikacji raportów dotyczących pamięci współdzielonej
Wyjaśnienie		 Dostępne w Chrome
Dostępność trybu debugowania agregacji prywatnej zależy od wymagań dotyczących urządzeń 3PC
Problem z GitHubem		 Dostępne w Chrome M119
Zmniejszanie opóźnienia zgłoszenia
Wyjaśnienie		 Dostępne w Chrome M119
Obsługa interfejsu Private Aggregation API i usługi agregacji w Google Cloud
Wyjaśnienie		 Dostępne w Chrome M121
Dopełnienie ładunków raportów agregowanych
Wyjaśnienie		 Dostępne w Chrome M119
Tryb debugowania agregacji prywatnej dostępny w raportach służących do raportowania agregacji aukcji
Wyjaśnienie		 Zaplanowane w Chrome M123
Obsługa identyfikatora filtrowania
Wyjaśnienie		 Początkowo planujemy wprowadzić ją w Chrome w II kwartale 2024 roku.

Czym jest interfejs Private Aggregation API

Interfejs Private Aggregation API umożliwia deweloperom generowanie raportów zbiorczych na podstawie danych z interfejsu Protected Audience API i danych z różnych witryn pochodzących z Shared Storage.

Obecnie ten interfejs API udostępnia jedną operację – sendHistogramReport(), ale w przyszłości może być obsługiwanych więcej. Operacja histogramu umożliwia agregowanie danych o użytkownikach w każdym zdefiniowanym przez Ciebie zasobniku (nazywanym w interfejsie API kluczem agregacji). Wywołanie histogramu gromadzi wartości i zwraca zaszumiony wynik zagregowany w formie raportu podsumowującego. Może on np. wskazywać liczbę witryn, w których każdy użytkownik widział Twoje treści, lub natknąć się na błąd w skrypcie zewnętrznym. Ta operacja jest wykonywana w workletze innego interfejsu API.

Jeśli na przykład masz już zarejestrowane dane demograficzne i geograficzne w pamięci współdzielonej, możesz skorzystać z interfejsu Private Aggregation API, aby wygenerować histogram pokazujący w przybliżeniu, ilu użytkowników w Nowym Jorku zobaczyło Twoje treści w różnych witrynach. Aby zagregować dane na potrzeby tego pomiaru, możesz zakodować wymiar geograficzny w kluczu agregacji i zliczyć użytkowników w wartości zbiorczej.

Kluczowe pojęcia

Gdy wywołujesz interfejs Private Aggregation API z kluczem agregacji i wartością agregowaną, przeglądarka generuje raport możliwy do zagregowania.

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

Aby dowiedzieć się więcej o kluczowych pojęciach związanych z interfejsem Private Aggregation API, zapoznaj się z podstawowymi informacjami na temat interfejsu Private Aggregation API.

Różnice w stosunku do raportów atrybucji

Interfejs Private Aggregation API jest pod wieloma względami podobny do interfejsu Attribution Reporting API. Attribution Reporting to osobny interfejs API przeznaczony do pomiaru konwersji, natomiast agregacja prywatna jest przeznaczona do pomiarów w witrynach w połączeniu z interfejsami API takimi jak Protected Audience API i pamięci współdzielone. Oba interfejsy API generują raporty zbiorcze, które są wykorzystywane przez backend usługi agregacji do generowania raportów podsumowujących.

Raportowanie atrybucji wiąże dane zebrane ze zdarzenia wyświetlenia i zdarzenia konwersji, które następują w różnych momentach. Agregacja prywatna mierzy pojedyncze zdarzenie w różnych witrynach.

Przetestuj ten interfejs API

Interfejs Private Aggregation API może być testowany lokalnie. W tym celu włącz flagę eksperymentu z interfejsami API reklam w Piaskownicy prywatności na stronie chrome://flags/#privacy-sandbox-ads-apis.

Aby używać tych interfejsów API, ustaw eksperyment z interfejsami API reklam w Piaskownicy prywatności
Aby używać tych interfejsów API, ustaw eksperyment dotyczący interfejsów API reklam w Piaskownicy prywatności

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

Skorzystaj z wersji demonstracyjnej

Wersja demonstracyjna interfejsu Private Aggregation API for Shared Storage jest dostępna na stronie goo.gle/shared-storage-demo, a kod jest dostępny na GitHub. Demonstracja wdraża operacje po stronie klienta i generuje raport zbiorczy, który jest wysyłany na Twój serwer.

W przyszłości opublikujemy wersję demonstracyjną interfejsu Private Aggregation API przeznaczonego do interfejsu Protected Audience API.

Przykłady zastosowań

Agregacja prywatna to ogólny interfejs API służący do pomiarów w witrynach, który można używać w workletach Shared Storage i Protected Audience API. Pierwszym krokiem jest określenie, 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 innych witryn w bezpiecznym środowisku, co zapobiega wyciekom danych, a interfejs Private Aggregation API umożliwia pomiar danych 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 ich treści. Interfejs Private Aggregation API może wyświetlić odpowiedź, taką jak „Około 317 unikalnych użytkowników zobaczyło identyfikator treści 861”.

W pamięci współdzielonej możesz ustawić flagę wskazującą, czy użytkownik już widział treść. Przy pierwszej wizycie, w przypadku której flaga nie istnieje, następuje wywołanie agregacji prywatnej, a następnie zostaje ustawiona flaga. Podczas kolejnych wizyt użytkownika, w tym wizyt w innych witrynach, możesz zaznaczyć „Pamięć współdzielona” i pominąć przesyłanie raportu do agregacji prywatnej, jeśli flaga jest ustawiona.

Pomiar danych demograficznych

Warto mierzyć 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 jest w wieku od 18 do 45 lat i pochodzi z Niemiec”. Korzystaj z pamięci współdzielonej, aby uzyskiwać dostęp do danych demograficznych z kontekstu innej firmy. Później możesz wygenerować raport z agregacją prywatną, zakodując wymiary grupa wiekowa i kraj w kluczu agregacji.

Pomiar częstotliwości K+

Możesz mierzyć liczbę użytkowników, którzy zobaczyli treść lub reklamę co najmniej tyle razy w danej przeglądarce, dla wcześniej wybranej wartości K.

W przypadku agregacji prywatnej może udzielić takiej odpowiedzi: „Około 89 użytkowników widziało system Content ID 581 co najmniej 3 razy”. Licznik w pamięci współdzielonej może być zwiększony z różnych witryn i można go odczytywać w ramach workletu. Gdy liczba osiągnie wartość K, możesz przesłać raport przez agregację prywatną.

Dzięki interfejsowi Protected Audience API

Interfejs Protected Audience API umożliwia ponowne kierowanie i zastosowanie niestandardowych list odbiorców, a agregacja prywatna umożliwia raportowanie zdarzeń z workletów kupujących i sprzedawców. Interfejs API może być używany do takich zadań jak mierzenie rozkładu stawek w aukcji.

Korzystając z workletu Protected Audience API, możesz agregować dane bezpośrednio za pomocą funkcji sendHistogramReport() i raportować dane na podstawie reguły za pomocą funkcji reportContributionForEvent(), która 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ć funkcję privateAggregation.contributeToHistogram({ bucket: <bucket>, value: <value> }), gdzie klucz agregacji to bucket, a wartość zagregowana jako value. W przypadku parametru bucket wymagana jest wartość BigInt. W przypadku parametru value wymagana jest liczba całkowita.

Oto przykład jej nazwy w pamięci współdzielonej na potrzeby 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 this.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 this.sharedStorage.set(key, true);
  }
}

register('reach-measurement', ReachMeasurementOperation);

Powyższy przykładowy kod wywołuje funkcję agregacji prywatnej przy każdym wczytaniu zawartości elementu iframe z innej witryny. Kod iframe wczytuje worklet, a potem wywołuje interfejs Private Aggregation API z identyfikatorem treści przekonwertowanym na klucz agregacji (zasobnik).

contributeToHistogramOnEvent()

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

Metoda privateAggregation.reportContributionForEvent(eventType, contribution) pobiera element eventType określający zdarzenie aktywujące, a metodę contribution, który ma zostać przesłany po wywołaniu zdarzenia. Zdarzenie wywołujące może pochodzić z samej aukcji po jej zakończeniu (np. wygranej lub przegranej aukcji) lub może pochodzić z otoczonej ramki, która wyrenderowała reklamę. Aby wysł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 chronionej, określ typ zdarzenia niestandardowego. Aby wywoływać zdarzenie z chronionej ramki, użyj metody fence.reportEvent() dostępnej w interfejsie Fenced Frames Ads Reporting API.

W poniższym przykładzie wysyła się raport o wyświetleniach po wywołaniu zdarzenia zwycięstwa w aukcji oraz raport o kliknięciach, jeśli blokowana ramka, która wyrenderowała reklamę, wywoła zdarzenie click. Te dwie wartości mogą posłużyć do obliczenia 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
  });

Więcej informacji znajdziesz w objaśnieniu dotyczącym rozszerzonego prywatnego raportowania agregacji.

enableDebugMode()

Choć pliki cookie innych firm są nadal dostępne, udostępnimy tryb debugowania, który ułatwi debugowanie i testowanie. Raport debugowania przydaje się do porównywania pomiarów z użyciem plików cookie z pomiarami agregacji prywatnej. Umożliwia też szybką weryfikację integracji z interfejsem API.

Wywołanie privateAggregation.enableDebugMode() w workletcie włącza tryb debugowania, w którym w raportach zbiorczych uwzględniane są niezaszyfrowany tekst (czytelny tekst). Możesz potem przetworzyć te ładunki za pomocą lokalnego narzędzia do testowania usługi agregacji.

Tryb debugowania jest dostępny tylko w przypadku elementów wywołujących, które mają dostęp do plików cookie innych firm. Jeśli element wywołujący nie ma dostępu do plików cookie innych firm, funkcja enableDebugMode() zakończy się niepowodzeniem. Oznacza to, że po wycofaniu plików cookie innych firm tryb debugowania nie będzie dostępny.

Możesz też ustawić klucz debugowania, wywołując privateAggregation.enableDebugMode({ <debugKey: debugKey> }), gdzie BigInt może służyć jako klucz debugowania. Klucz debugowania może służyć do łączenia danych pochodzących z pomiaru opartego na plikach cookie i danych pochodzących z pomiaru agregacji prywatnej. Można je wywoływać tylko raz w danym kontekście. Wszystkie kolejne wywołania będą ignorowane.

// Enables debug mode
privateAggregation.enableDebugMode();

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

Weryfikacja zgłoszenia

Aby sprawdzić, czy otrzymywane raporty zbiorcze są wiarygodne, w przypadku pamięci współdzielonej możesz dodać identyfikator kontekstu do wywołania operacji związanej z pamięcią współdzieloną. Identyfikator zostanie dołączony do wysłanego raportu. W późniejszym czasie możesz użyć tego identyfikatora, aby sprawdzić, czy raport został wysłany z operacji w pamięci współdzielonej.

Ta funkcja jest dostępna do testowania w Chrome od wersji M114. Weryfikacja raportu dotycząca interfejsu Protected Audience API nie jest jeszcze dostępna do testów.

Więcej informacji znajdziesz w objaśnieniu dotyczącym weryfikacji raportu.

Angażuj i dziel się opiniami

Trwa dyskusja na temat interfejsu Private Aggregation API i w przyszłości może on ulec zmianie. Jeśli wypróbujesz ten interfejs API i chcesz przekazać nam swoją opinię, chętnie poznamy Twoją opinię.