Podstawy interfejsu Private Aggregation API

Najważniejsze pojęcia związane z interfejsem Private Aggregation API

Dla kogo jest ten dokument?

Private Aggregation API umożliwia zbieranie zagregowanych danych z workletów, które mają dostęp do danych z różnych witryn. Koncepcje przedstawione w tym artykule są ważne dla deweloperów tworzących funkcje raportowania w interfejsach Shared Storage API i Protected Audience API.

• Jeśli jesteś deweloperem, który tworzy system raportowania do pomiarów w wielu witrynach.
• Jeśli jesteś specjalistą ds. marketingu, analitykiem danych lub innym użytkownikiem raportów podsumowujących, zrozumienie tych mechanizmów pomoże Ci podejmować decyzje dotyczące projektowania, aby uzyskiwać zoptymalizowane raporty podsumowujące.

Kluczowe terminy

Zanim przeczytasz ten dokument, zapoznaj się z kluczowymi terminami i pojęciami. Każde z tych pojęć zostanie tutaj szczegółowo opisane.

• Klucz agregacji (nazywany też koszykiem) to z góry określony zbiór punktów danych. Możesz na przykład zbierać dane o lokalizacji, w których przeglądarka podaje nazwę kraju. Klucz agregacji może zawierać więcej niż 1 wymiar (np. kraj i identyfikator widżetu treści).
• Wartość podlegająca agregacji to pojedynczy punkt danych zebrany w kluczu agregacji. Jeśli chcesz zmierzyć, ilu użytkowników z Francji widziało Twoje treści, France jest wymiarem w kluczu agregacji, a viewCount 1 jest wartością podlegającą agregacji.
• Raporty z możliwością agregacji są generowane i szyfrowane w przeglądarce. W przypadku interfejsu Private Aggregation API zawiera dane o pojedynczym zdarzeniu.
• Usługa do agregacji przetwarza dane z raportów z możliwością agregacji, aby utworzyć raport podsumowujący.
• Raport podsumowujący to końcowy wynik działania usługi do agregacji. Zawiera on zaszumione zagregowane dane użytkownika i szczegółowe dane o konwersjach.
• Worklet to element infrastruktury, który umożliwia uruchamianie określonych funkcji JavaScriptu i przesyłanie informacji z powrotem do osoby wysyłającej żądanie. W ramach workletu możesz wykonywać kod JavaScript, ale nie możesz wchodzić w interakcje ze stroną zewnętrzną ani się z nią komunikować.

Przepływ pracy Private Aggregation

Gdy wywołasz interfejs Private Aggregation API z kluczem agregacji i wartością podlegającą agregacji, przeglądarka wygeneruje raport podlegający agregacji. Raporty są wysyłane na serwer, który je grupuje. Raporty w partiach są później przetwarzane przez usługę do agregacji, która generuje raport podsumowujący.

1. Gdy wywołasz interfejs Private Aggregation API, klient (przeglądarka) wygeneruje i wyśle raport z możliwością agregacji na Twój serwer w celu zebrania.
2. Serwer zbiera raporty od klientów i grupuje je w partie, które są wysyłane do usługi do agregacji.
3. Gdy zbierzesz wystarczającą liczbę raportów, pogrupuj je i wyślij do usługi do agregacji działającej w zaufanym środowisku wykonawczym, aby wygenerować raport podsumowujący.

Proces opisany w tej sekcji jest podobny do interfejsu Attribution Reporting API. Raportowanie atrybucji łączy jednak dane zebrane ze zdarzenia wyświetlenia i zdarzenia konwersji, które występują w różnych momentach. Prywatna agregacja mierzy pojedyncze zdarzenie w wielu witrynach.

Klucz agregacji

Klucz agregacji (w skrócie „klucz”) reprezentuje zasobnik, w którym będą gromadzone wartości podlegające agregacji. W kluczu można zakodować co najmniej 1 wymiar. Wymiar to aspekt, o którym chcesz uzyskać więcej informacji, np. grupa wiekowa użytkowników lub liczba wyświetleń kampanii reklamowej.

Możesz np. mieć widżet umieszczony w wielu witrynach i chcieć analizować kraj użytkowników, którzy go widzieli. Chcesz uzyskać odpowiedzi na pytania takie jak „Ilu użytkowników, którzy widzieli mój widżet, pochodzi z kraju X?”. Aby uzyskać raport dotyczący tego pytania, możesz skonfigurować klucz agregacji, który koduje 2 wymiary: identyfikator widżetu i identyfikator kraju.

Klucz przekazywany do interfejsu Private Aggregation API to BigInt, który składa się z wielu wymiarów. W tym przykładzie wymiarami są identyfikator widżetu i identyfikator kraju. Załóżmy, że identyfikator widżetu może mieć maksymalnie 4 cyfry, np. 1234, a każdy kraj jest przypisany do liczby w porządku alfabetycznym, np. Afganistan to 1, Francja to 61, a Zimbabwe to 195. Klucz do agregacji będzie więc miał 7 cyfr, z których pierwsze 4 znaki są zarezerwowane dla WidgetID, a ostatnie 3 znaki dla CountryID.

Załóżmy, że klucz reprezentuje liczbę użytkowników z Francji (identyfikator kraju 061), którzy widzieli widżet o identyfikatorze 3276. Klucz agregacji to 3276061.

Klucz agregacji można też wygenerować za pomocą mechanizmu szyfrowania, takiego jak SHA-256. Na przykład ciąg znaków {"WidgetId":3276,"CountryID":67} można zaszyfrować, a następnie przekształcić w wartość BigInt, czyli 42943797454801331377966796057547478208888578253058197330928948081739249096287n. Jeśli wartość skrótu ma więcej niż 128 bitów, możesz ją skrócić, aby nie przekraczała maksymalnej dozwolonej wartości zasobnika wynoszącej 2^128−1.

W module roboczym Pamięci współdzielonej możesz uzyskać dostęp do modułów crypto i TextEncoder, które pomogą Ci wygenerować hash. Więcej informacji o generowaniu skrótu znajdziesz w SubtleCrypto.digest() na stronie MDN.

Przykład poniżej pokazuje, jak wygenerować klucz zasobnika z wartości po haszowaniu:

async function convertToBucket(data) {
  // Encode as UTF-8 Uint8Array
  const encodedData = new TextEncoder().encode(data);

  // Generate SHA-256 hash
  const hashBuffer = await crypto.subtle.digest('SHA-256', encodedData);

  // Truncate the hash
  const truncatedHash = Array.from(new Uint8Array(hashBuffer, 0, 16));

  // Convert the byte sequence to a decimal
  return truncatedHash.reduce((acc, curr) => acc * 256n + BigInt(curr), 0n);
}

const data = {
  WidgetId: 3276,
  CountryID: 67
};

const dataString = JSON.stringify(data);
const bucket = await convertToBucket(dataString);

console.log(bucket); // 126200478277438733997751102134640640264n

Wartość podlegająca agregacji

Wartości podlegające agregacji są sumowane według klucza w przypadku wielu użytkowników, aby generować zbiorcze statystyki w postaci wartości podsumowujących w raportach podsumowujących.

Wróćmy teraz do przykładowego pytania: „Ilu użytkowników, którzy widzieli mój widget, pochodzi z Francji?”. Odpowiedź na to pytanie będzie wyglądać mniej więcej tak: „Około 4881 użytkowników, którzy widzieli mój widżet o identyfikatorze 3276, pochodzi z Francji”. Wartość, którą można agregować, wynosi 1 w przypadku każdego użytkownika, a „4881 użytkowników” to wartość zagregowana, która jest sumą wszystkich wartości, które można agregować, dla danego klucza agregacji.

W tym przykładzie zwiększamy wartość o 1 za każdego użytkownika, który zobaczy widżet. W praktyce wartość podlegającą agregacji można skalować, aby poprawić stosunek sygnału do szumu.

Budżet na wspieranie

Każde wywołanie interfejsu Private Aggregation API jest nazywane wkładem. Aby chronić prywatność użytkowników, ograniczamy liczbę opinii, które możemy zebrać od jednej osoby.

Suma wszystkich wartości podlegających agregacji we wszystkich kluczach agregacji musi być mniejsza od budżetu na udział. Budżet jest określany dla każdego pochodzenia workletu i każdego dnia, a także oddzielnie dla workletów interfejsu Protected Audience API i Shared Storage. Dzień jest określany na podstawie ruchomego okna obejmującego mniej więcej ostatnie 24 godziny. Jeśli nowy raport z możliwością agregacji spowodowałby przekroczenie budżetu, nie zostanie utworzony.

Budżet na udział jest reprezentowany przez parametr L₁ i wynosi 2¹⁶ (65 536) na 10 minut dziennie z limitem 2²⁰ (1 048 576). Więcej informacji o tych parametrach znajdziesz w wyjaśnieniu.

Wartość budżetu na udział jest dowolna, ale szum jest do niej skalowany. Możesz użyć tego budżetu, aby zmaksymalizować stosunek sygnału do szumu w przypadku wartości podsumowujących (więcej informacji znajdziesz w sekcji Szum i skalowanie).

Więcej informacji o budżetach na udział znajdziesz w tym wyjaśnieniu. Więcej informacji znajdziesz też w sekcji Budżet na wkład.

Limit udziału w raporcie

W zależności od dzwoniącego limit może być inny. W przypadku pamięci współdzielonej są to limity domyślne, które można zastąpić. Obecnie raporty generowane dla wywołujących interfejs Shared Storage API są ograniczone do 20 wartości w każdym raporcie. Z kolei liczba wkładów w raportach dla podmiotów wywołujących Protected Audience API jest ograniczona do 100. Te limity zostały wybrane tak, aby zachować równowagę między liczbą osadzanych treści a rozmiarem ładunku.

W przypadku pamięci współdzielonej działania wykonane w ramach jednej operacji run() lub selectURL() są łączone w jeden raport. W przypadku Protected Audience API wkłady pochodzące z jednego źródła w ramach aukcji są łączone w pakiety.

Publikacje z dopełnieniem

Wkłady są dodatkowo modyfikowane za pomocą funkcji dopełniania. Dopełnianie ładunku chroni informacje o rzeczywistej liczbie wkładów osadzonych w raporcie podlegającym agregacji. Wypełnienie powiększa ładunek o null (czyli o wartość 0), aby osiągnąć stałą długość.

Raporty, które można agregować

Gdy użytkownik wywoła interfejs Private Aggregation API, przeglądarka wygeneruje raporty możliwe do agregacji, które zostaną później przetworzone przez usługę do agregacji w celu wygenerowania raportów podsumowujących. Raport zbiorczy jest sformatowany w JSON i zawiera zaszyfrowaną listę udziałów, z których każdy jest parą {aggregation key, aggregatable value}. Raporty z możliwością agregacji są wysyłane z losowym opóźnieniem do godziny.

Dane są szyfrowane i nie można ich odczytać poza usługą do agregacji. Usługa do agregacji odszyfrowuje raporty i generuje raport podsumowujący. Klucz szyfrowania przeglądarki i klucz odszyfrowywania usługi agregacji są wydawane przez koordynatora, który pełni funkcję usługi zarządzania kluczami. Koordynator przechowuje listę skrótów binarnych obrazu usługi, aby sprawdzić, czy dzwoniący ma uprawnienia do otrzymania klucza odszyfrowywania.

Przykładowy raport z możliwością agregacji z włączonym trybem debugowania:

  "aggregation_service_payloads": [
    {
      "debug_cleartext_payload": "omRkYXRhgaJldmFsdWVEAAAAgGZidWNrZXRQAAAAAAAAAAAAAAAAAAAE0mlvcGVyYXRpb25paGlzdG9ncmFt",
      "key_id": "2cc72b6a-b92f-4b78-b929-e3048294f4d6",
      "payload": "a9Mk3XxvnfX70FsKrzcLNZPy+00kWYnoXF23ZpNXPz/Htv1KCzl/exzplqVlM/wvXdKUXCCtiGrDEL7BQ6MCbQp1NxbWzdXfdsZHGkZaLS2eF+vXw2UmLFH+BUg/zYMu13CxHtlNSFcZQQTwnCHb"
    }
  ],
  "debug_key": "777",
  "shared_info": "{\"api\":\"shared-storage\",\"debug_mode\":\"enabled\",\"report_id\":\"5bc74ea5-7656-43da-9d76-5ea3ebb5fca5\",\"reporting_origin\":\"https://localhost:4437\",\"scheduled_report_time\":\"1664907229\",\"version\":\"0.1\"}"

Raporty, które można agregować, możesz sprawdzić na stroniechrome://private-aggregation-internals:

Do celów testowych możesz użyć przycisku „Wyślij wybrane raporty”, aby natychmiast wysłać raport na serwer.

Zbieranie i grupowanie raportów, które można agregować

Przeglądarka wysyła raporty podlegające agregacji do źródła workletu zawierającego wywołanie interfejsu Private Aggregation API, korzystając z tej znanej ścieżki:

• W przypadku Shared Storage: /.well-known/private-aggregation/report-shared-storage
• W przypadku Protected Audience:/.well-known/private-aggregation/report-protected-audience

W tych punktach końcowych musisz obsługiwać serwer, który będzie działać jako kolektor i odbierać raporty podlegające agregacji wysyłane przez klientów.

Serwer powinien następnie grupować raporty i wysyłać je do usługi do agregacji. Twórz partie na podstawie informacji dostępnych w niezaszyfrowanym ładunku raportu zbiorczego, np. w polu shared_info. Najlepiej, aby każda partia zawierała co najmniej 100 raportów.

Możesz zdecydować się na przetwarzanie zbiorcze codziennie lub co tydzień. Ta strategia jest elastyczna i możesz zmieniać strategię grupowania w przypadku konkretnych zdarzeń, w których spodziewasz się większej liczby wyświetleń, np. w dniach, w których oczekujesz większej liczby wyświetleń. Partie powinny zawierać raporty z tej samej wersji interfejsu API, pochodzące z tego samego źródła raportowania i wygenerowane o tej samej godzinie.

Identyfikatory filtrów

Interfejs Private Aggregation API i usługa Aggregation Service umożliwiają używanie identyfikatorów filtrowania do przetwarzania pomiarów na bardziej szczegółowym poziomie, np. w przypadku poszczególnych kampanii reklamowych, zamiast przetwarzania wyników w większych zapytaniach.

Aby zacząć korzystać z tej funkcji już dziś, wykonaj te ogólne czynności w przypadku obecnej implementacji.

Kroki dotyczące pamięci współdzielonej

Jeśli w swoim procesie używasz interfejsu Shared Storage API:

1. Określ, gdzie chcesz deklarować i uruchamiać nowy moduł Shared Storage. W tym przykładzie plik modułu ma nazwę filtering-worklet.js i jest zarejestrowany w sekcji filtering-example.

   (async function runFilteringIdsExample () {
   await window.sharedStorage.worklet.addModule('filtering-worklet.js');
   await window.sharedStorage.run('filtering-example', {
     keepAlive: true,
     privateAggregationConfig: {
       contextId: 'example-id',
       filteringIdMaxBytes: 8 // optional
     }
   }});
   })();
   

   Pamiętaj, że wartość filteringIdMaxBytes można skonfigurować w przypadku każdego raportu. Jeśli nie zostanie ustawiona, domyślnie wynosi 1. Ta wartość domyślna zapobiega niepotrzebnemu zwiększaniu rozmiaru ładunku, a tym samym kosztów przechowywania i przetwarzania. Więcej informacji znajdziesz w wyjaśnieniu dotyczącym elastycznego wspierania.

2. W filtering-worklet.js, gdy przekazujesz udział do privateAggregation.contributeToHistogram(...) w ramach workletu Pamięć współdzielona, możesz określić identyfikator filtrowania.

   // Within  filtering-worklet.js
   class FilterOperation {
     async run() {
       let contributions = [{
         bucket: 1234n,
         value: 56,
         filteringId: 3n // defaults to 0n if not assigned, type bigint
       }];
   
       for (const c of contributions) {
         privateAggregation.contributeToHistogram(c);
       }
       …
   }
   });
   
   register('filtering-example', FilterOperation);
   

3. Raporty z możliwością agregacji będą wysyłane do zdefiniowanego przez Ciebie punktu końcowego/.well-known/private-aggregation/report-shared-storage. Aby dowiedzieć się więcej o zmianach, które należy wprowadzić w parametrach zadania usługi Aggregation Service, przejdź do przewodnika po filtrowaniu identyfikatorów.

Po zakończeniu przetwarzania wsadowego i przesłaniu danych do wdrożonej usługi do agregacji przefiltrowane wyniki powinny być widoczne w raporcie końcowym.

Kroki związane z Protected Audience

Jeśli w swoim procesie używasz interfejsu Protected Audience API:

1. W obecnej implementacji Protected Audience możesz skonfigurować te ustawienia, aby korzystać z prywatnej agregacji. W przeciwieństwie do pamięci współdzielonej nie można jeszcze skonfigurować maksymalnego rozmiaru identyfikatorów filtrowania. Domyślnie maksymalny rozmiar identyfikatora filtrowania to 1 bajt, a wartość to 0n. Pamiętaj, że te wartości będą ustawiane w funkcjach raportowania dotyczących ochrony prywatności odbiorców (np.reportResult() lub generateBid()).

   const contribution = {
     ...
     filteringId: 0n
   };
   
   privateAggregation.contributeToHistogram(contribution);
   

2. Raporty z możliwością agregacji będą wysyłane do zdefiniowanego przez Ciebie punktu końcowego/.well-known/private-aggregation/report-protected-audience. Po zakończeniu tworzenia partii i przesłaniu ich do wdrożonej usługi do agregacji przefiltrowane wyniki powinny być widoczne w raporcie końcowym. Dostępne są te materiały wyjaśniające dotyczące interfejsów Attribution Reporting API i Private Aggregation API, a także wstępna propozycja.

Aby dowiedzieć się więcej, przejdź do naszego przewodnika po filtrowaniu identyfikatorów w usłudze Aggregation Service lub do sekcji Interfejs Attribution Reporting API.

Usługa do agregacji

Usługa do agregacji otrzymuje od modułu zbierającego zaszyfrowane raporty z możliwością agregacji i generuje raporty podsumowujące. Więcej strategii dotyczących tworzenia w kolektorze raportów zbiorczych podlegających agregacji znajdziesz w naszym przewodniku po tworzeniu partii.

Usługa działa w zaufanym środowisku wykonawczym (TEE), które zapewnia poziom pewności w zakresie integralności danych, poufności danych i integralności kodu. Jeśli chcesz dowiedzieć się więcej o tym, jak koordynatorzy są używani w połączeniu z TEE, przeczytaj więcej o ich roli i celu.

Raporty podsumowujące

Raporty podsumowujące umożliwiają wyświetlanie zebranych danych z dodatkowym szumem. Możesz poprosić o raporty podsumowujące dla danego zestawu kluczy.

Raport podsumowujący zawiera zbiór par klucz-wartość w formacie słownika JSON. Każda para zawiera:

• bucket: klucz agregacji w postaci ciągu znaków z liczbą binarną. Jeśli użyty klucz agregacji to „123”, zasobnik to „1111011”.
• value: wartość podsumowania dla danego celu pomiarowego, zsumowana ze wszystkich dostępnych raportów, które można agregować, z dodanym szumem.

Na przykład:

[
  {"bucket":` `"111001001",` `"value":` `"2558500"},
  {"bucket":` `"111101001",` `"value":` `"3256211"},
  {"bucket":` `"111101001",` `"value":` `"6536542"},
]

Szum i skalowanie

Aby chronić prywatność użytkowników, usługa do agregacji dodaje szum do każdej wartości podsumowania raz za każdym razem, gdy jest żądany raport podsumowujący. Wartości szumu są losowo pobierane z rozkładu prawdopodobieństwa Laplace’a. Nie masz bezpośredniej kontroli nad sposobami dodawania szumu, ale możesz wpływać na jego wpływ na dane pomiarowe.

Rozkład szumu jest taki sam niezależnie od sumy wszystkich wartości, które można agregować. Im wyższe są wartości podlegające agregacji, tym mniejszy wpływ będzie miał szum.

Załóżmy na przykład, że rozkład szumu ma odchylenie standardowe równe 100 i jest wyśrodkowany na zero. Jeśli zebrana wartość raportu podlegającego agregacji (lub „wartość podlegająca agregacji”) wynosi tylko 200, odchylenie standardowe szumu będzie stanowić 50% wartości zagregowanej. Jeśli jednak wartość podlegająca agregacji wynosi 20 000, odchylenie standardowe szumu będzie stanowić tylko 0,5% wartości zagregowanej. Dlatego wartość podlegająca agregacji wynosząca 20 000 ma znacznie wyższy stosunek sygnału do szumu.

Dlatego pomnożenie wartości podlegającej agregacji przez współczynnik skalowania może pomóc w zmniejszeniu szumu. Współczynnik skalowania określa, o ile chcesz przeskalować daną wartość podlegającą agregacji.

Zwiększenie wartości przez wybranie większego współczynnika skalowania zmniejsza względny szum. Powoduje to jednak szybsze osiągnięcie limitu budżetu na dane przez sumę wszystkich porcji informacji we wszystkich przedziałach. Zmniejszenie wartości przez wybranie mniejszej stałej współczynnika skalowania zwiększa względny szum, ale zmniejsza ryzyko osiągnięcia limitu budżetu.

Aby obliczyć odpowiedni współczynnik skalowania, podziel budżet na wpłaty przez maksymalną sumę wartości, które można agregować we wszystkich kluczach.

Więcej informacji znajdziesz w dokumentacji dotyczącej budżetu na udział w programie.

Angażowanie się i przesyłanie opinii

Interfejs Private Aggregation API jest obecnie przedmiotem dyskusji i w przyszłości może ulec zmianie. Jeśli wypróbujesz ten interfejs API i chcesz podzielić się opinią, chętnie ją poznamy.

• GitHub przeczytaj wyjaśnienie, zadawaj pytania i uczestnicz w dyskusji.
  • Pomoc dla deweloperów: zadawaj pytania i bierz udział w dyskusjach w repozytorium pomocy dla deweloperów Piaskownicy prywatności.
• Dołącz do grupy Shared Storage API i grupy Protected Audience API, aby otrzymywać najnowsze informacje dotyczące interfejsu Private Aggregation.