Podstawy interfejsu Private Aggregation API

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

Dla kogo jest ten dokument?

Interfejs Private Aggregation API umożliwia zbieranie danych zbiorczych z workletów z dostępem do danych z różnych witryn. Przedstawione tu koncepcje są ważne dla programistów tworzących funkcje raportowania w ramach interfejsu Shared Storage i Protected Audience API.

• Jeśli jesteś deweloperem i tworzysz system raportowania do pomiarów w witrynach.
• Jeśli jesteś marketerem, badaczem danych lub innym konsumentem raportów podsumowujących, znajomość tych mechanizmów pomoże Ci w podejmowaniu decyzji dotyczących pobierania zoptymalizowanego raportu podsumowującego.

Kluczowe terminy

Przed przeczytaniem tego dokumentu warto zapoznać się z kluczowymi terminami i pojęciami. Poniżej szczegółowo opisujemy każdy z tych warunków.

• Klucz agregacji (nazywany też zasobnikiem) to wstępnie ustalony zbiór punktów danych. Może Ci być np. potrzebne utworzenie grupy danych o lokalizacji, w której przeglądarka zgłasza nazwę kraju. Klucz agregacji może zawierać więcej niż 1 wymiar (np. kraj i identyfikator widżetu treści).
• Wartość agregująca to pojedynczy punkt danych zbierany w kluczu agregacji. Jeśli chcesz sprawdzić, ilu użytkowników z Francji zobaczyło Twoje treści, France jest wymiarem w kluczu agregacji, a viewCount (1) jest wartością zagregowaną.
• Raporty zbiorcze są generowane i szyfrowane w przeglądarce. W przypadku interfejsu Private Aggregation API zawiera dane o pojedynczym zdarzeniu.
• Usługa agregująca przetwarza dane z raportów zbiorczych, aby utworzyć raport podsumowujący.
• Raport podsumowujący to wynik działania usługi agregacji. Zawiera on zagregowane dane zbiorcze oraz szczegółowe dane o konwersjach.
• Worklet to element infrastruktury, który umożliwia uruchamianie określonych funkcji JavaScript i zwracanie informacji z powrotem do żądającego. W workletach można uruchamiać JavaScript, ale nie można korzystać ze strony zewnętrznej ani komunikować się ze stroną.

Przepływ pracy agregacji prywatnej

Gdy wywołujesz interfejs Private Aggregation API z kluczem agregacji i wartością możliwą do agregacji, przeglądarka generuje raport możliwy do zagregowania. Raporty są wysyłane na serwer, który grupuje raporty. Raporty zbiorcze są później przetwarzane przez usługę agregacji i generowane jest raport podsumowujący.

1. Gdy wywołujesz interfejs Private Aggregation API, klient (przeglądarka) generuje i wysyła na Twój serwer raport zbiorczy w celu zebrania danych.
2. Serwer zbiera raporty od klientów i grupuje je w celu wysłania do usługi agregacji.
3. Po zebraniu wystarczającej liczby raportów grupujesz je i wyślesz do usługi agregacji działającej w zaufanym środowisku wykonawczym, aby wygenerować raport podsumowujący.

Kluczowy termin: zaufane środowisko wykonawcze to specjalna konfiguracja sprzętu i oprogramowania komputerowego, która umożliwia podmiotom zewnętrznym sprawdzenie dokładnych wersji oprogramowania działającego na komputerze. TEE pozwalają stronom zewnętrznym sprawdzić, czy oprogramowanie działa dokładnie tak, jak twierdzi jego producent – nie ma niczego więcej ani mniej.

Przepływ pracy opisany w tej sekcji jest podobny do interfejsu Attribution Reporting API. Raportowanie atrybucji wiąże jednak dane zebrane przez zdarzenie wyświetlenia i zdarzenie konwersji, które następują w różnych momentach. Agregacja prywatna mierzy pojedyncze zdarzenie w witrynach.

Klucz agregacji

Klucz agregacji (w skrócie „klucz”) reprezentuje zasobnik, w którym będą gromadzone wartości zbiorcze. W kluczu można zakodować jeden wymiar lub większą ich liczbę. Wymiar to aspekt, który chcesz lepiej poznać, np. grupa wiekowa użytkowników lub liczba wyświetleń w kampanii reklamowej.

Załóżmy, że masz widżet umieszczony w wielu witrynach i chcesz przeanalizować kraj użytkowników, którzy go zobaczyli. Chcesz odpowiedzieć na pytania w rodzaju: „Ilu użytkowników, którzy zobaczyli mój widżet, pochodzi z kraju X?” Aby wygenerować raport o tym pytaniu, możesz skonfigurować klucz agregacji, który koduje 2 wymiary: identyfikator widżetu i identyfikator kraju.

Klucz dostarczony do interfejsu Private Aggregation API to BigInt, który składa się z wielu wymiarów. W tym przykładzie są to identyfikator widżetu i identyfikator kraju. Przyjmijmy, że identyfikator widżetu może mieć do 4 cyfr, np. 1234, a każdy kraj jest przypisany do liczby w kolejności alfabetycznej, np. w Afganistanie to 1, Francja to 61, a Zimbabwe to „195”. Dlatego klucz agregacyjny będzie miał 7 cyfr, gdzie pierwsze 4 znaki zostaną zarezerwowane dla WidgetID, a 3 ostatnie znaki są zarezerwowane dla CountryID.

Załóżmy, że klucz reprezentuje liczbę użytkowników z Francji (identyfikator kraju 061), którzy zobaczyli identyfikator widżetu 3276. Kluczem agregacji jest 3276061.

Klucz agregacji
Identyfikator widżetu	Identyfikator kraju
3276	061

Przykład: jeśli wymiar ma dostępną przestrzeń klucza na wiele cyfr, ale wartość ma mniej, dodaj zera wiodące. Jeśli np. identyfikator kraju zawiera 3 cyfry, identyfikatorem kraju w przypadku Algierii jest 003.

Klucz agregacji można też wygenerować za pomocą mechanizmu haszowania, np. SHA-256. Na przykład ciąg {"WidgetId":3276,"CountryID":67} można zaszyfrować, a potem przekonwertować na wartość BigInt o wartości 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 2^128−1.

W workletzie pamięci współdzielonej masz dostęp do modułów crypto i TextEncoder, które pomagają wygenerować hasz. Więcej informacji o generowaniu skrótu znajdziesz w artykule o SubtleCrypto.digest() w MDN.

Ten przykład opisuje, jak wygenerować klucz zasobnika z zahaszowanej wartości:

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

Uwaga: chociaż koncepcje są podobne, klucz dla interfejsu Private Aggregation API jest skonstruowany inaczej niż dla interfejsu Attribution Reporting API. W przypadku agregacji prywatnej cały klucz jest podawany jednorazowo w wywołaniu JavaScriptu.

Skumulowana wartość

Agregowane wartości są sumowane według klucza wielu użytkowników, co pozwala generować zagregowane statystyki w formie wartości podsumowujących w raportach podsumowujących.

Wróćmy do zadanego wcześniej przykładowego pytania: „Ilu użytkowników, którzy zobaczyli mój widżet, pochodzi z Francji?”. Odpowiedź będzie wyglądała mniej więcej tak: „Około 4881 użytkowników, którzy zobaczyli mój identyfikator widżetu 3276, jest z Francji”. Wartość całkowita to 1 na każdego użytkownika, a „4881 użytkowników” to wartość zbiorcza, która jest sumą wszystkich wartości zbiorczych tego klucza agregacji.

Klucz agregacji		Skumulowana wartość
Identyfikator widżetu	Identyfikator kraju	Liczba wyświetleń
3276	061	1

W tym przykładzie zwiększamy wartość o 1 w przypadku każdego użytkownika, który widzi widżet. W praktyce wartość zagregowaną można skalować, by poprawić stosunek sygnału do szumu.

Budżet na wpłatę

Każde wywołanie interfejsu Private Aggregation API jest nazywane treścią. Aby chronić prywatność użytkownika, liczba darowizn, które można zebrać od danej osoby, jest ograniczona.

Gdy sumujesz wszystkie wartości, które można zagregować ze wszystkich kluczy agregacji, suma musi być mniejsza od kwoty wpłat funduszy. Budżet jest ograniczony do elementu origin i danego zasobu roboczego i jest oddzielony w przypadku workletów Protected Audience API i Shared Storage. W ciągu dnia uwzględnia się okno ruchome z ostatnich 24 godzin. Jeśli nowy raport zbiorczy spowodowałby przekroczenie budżetu, raport nie zostanie utworzony.

Budżet darowizn jest reprezentowany przez parametr L₁ i jest ustawiony na 2¹⁶ (65 536) na 10 minut dziennie z okresem wstecznym 2²⁰

(1 048 576). Więcej informacji o tych parametrach znajdziesz w sekcji Wyjaśnienie.

Wartość budżetu darowizny jest dowolna, ale szum jest do niej skalowany. Możesz użyć tego budżetu, aby zmaksymalizować stosunek sygnału do szumu w wartościach podsumowujących (więcej o tym omówiliśmy w sekcji Zaszumienia i skalowanie).

Więcej informacji o budżetach darowizn znajdziesz tutaj. Więcej wskazówek znajdziesz w sekcji Budżet darowizn.

Raporty zbiorcze

Gdy użytkownik wywoła interfejs Private Aggregation API, przeglądarka wygeneruje raporty, które można później przetworzyć przez usługę agregacji w celu wygenerowania raportów podsumowujących. Raport agregacyjny ma format JSON i zawiera zaszyfrowaną listę opublikowanych treści, z których każdy ma postać pary {aggregation key, aggregatable value}. Raporty zbiorcze są wysyłane z losowym opóźnieniem do godziny.

Publikowane treści są zaszyfrowane i nieczytelne poza usługą agregacji. Usługa agregacji odszyfrowuje raporty i generuje raport podsumowujący. Klucz szyfrowania dla przeglądarki i klucz odszyfrowywania dla usługi agregacji są wystawiane 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 element wywołujący może otrzymać klucz odszyfrowywania.

Przykładowy raport zbiorczy 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 zbiorcze można przeglądać na stronie chrome://private-aggregation-internals:

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

Gromadzenie i zbiorcze raporty zbiorcze

Przeglądarka wysyła raporty zbiorcze do źródła workletu zawierającego wywołanie interfejsu Private Aggregation API, używając wymienionej dobrze znanej ścieżki:

• W przypadku pamięci współdzielonej: /.well-known/private-aggregation/report-shared-storage
• W przypadku Protected Audience API: /.well-known/private-aggregation/report-protected-audience

W takich punktach końcowych musisz obsługiwać serwer – kolektor – który będzie otrzymywać zbiorcze raporty wysyłane od klientów.

Serwer powinien następnie przesyłać raporty zbiorcze i wysyłać je do usługi agregacji. Twórz partie na podstawie informacji dostępnych w niezaszyfrowanym ładunku raportu zbiorczego, np. w polu shared_info. Najlepiej, gdyby wsady mogły zawierać co najmniej 100 raportów na grupę.

Możesz grupować je codziennie lub co tydzień. Ta strategia jest elastyczna i możesz ją zmieniać w przypadku konkretnych zdarzeń, o których spodziewasz się większej liczby wyświetleń, np. dni w roku, w których spodziewana jest większa liczba wyświetleń. Wsady powinny zawierać raporty z tej samej wersji interfejsu API i z tego samego źródła oraz zaplanować czas generowania raportu.

Usługa agregacji

Usługa agregująca otrzymuje od kolektora zaszyfrowane raporty zbiorcze i generuje raporty podsumowujące.

Aby odszyfrować ładunek raportu, usługa agregacji pobiera klucz odszyfrowywania z koordynatora. Usługa działa w zaufanym środowisku wykonawczym (TEE), które zapewnia poziom integralności danych, poufności danych i integralności kodu. Chociaż jesteś właścicielem i obsługą usługi, nie będziesz mieć wglądu w dane przetwarzane w TEE.

Raporty podsumowujące

Raporty podsumowujące umożliwiają sprawdzanie danych zebranych po dodaniu szumu. Możesz poprosić o raporty podsumowania dla danego zestawu kluczy.

Raport podsumowujący zawiera zestaw par klucz-wartość w stylu słownika JSON. Każda para obejmuje:

• bucket: klucz agregacji w postaci binarnego ciągu liczbowego. Jeśli użyty klucz agregacji to „123”, zasobnik będzie miał wartość „1111011”.
• value: podsumowanie wartości danego celu pomiaru, zsumowane ze wszystkich dostępnych raportów zbiorczych 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 agregacji dodaje szum do każdej wartości podsumowania jeden raz przy każdym żądaniu raportu podsumowującego. 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 dane pomiarowe.

Rozkład szumu jest taki sam niezależnie od sumy wszystkich zagregowanych wartości. Dlatego im wyższe wartości zagregowane, tym mniejszy wpływ szumu.

Załóżmy np., że rozkład szumu ma odchylenie standardowe o wartości 100 i jest wyśrodkowany na wartości 0. Jeśli w raporcie zagregowanym (lub „wartość zagregowana”) jest tylko 200, odchylenie standardowe szumu wynosi 50% wartości zbiorczej. Jeśli jednak łączna wartość wynosi 20 000, odchylenie standardowe szumu będzie wynosić tylko 0,5% wartości zbiorczej. Agregowana wartość 20 000 daje więc znacznie wyższy współczynnik sygnału do szumu.

Dlatego mnożenie wartości zagregowanej przez współczynnik skalowania może pomóc w zmniejszeniu szumu. Współczynnik skalowania określa, jak bardzo chcesz skalować daną wartość zagregowaną.

Skalowanie wartości w górę przez wybranie większego współczynnika skalowania zmniejsza względny szum. Sprawia to jednak również, że suma wszystkich darowizn we wszystkich zasobnikach szybciej osiąga limit budżetu darowizn. Skalowanie wartości w dół przez wybranie mniejszej stałej współczynnika skalowania zwiększa szum względny, ale zmniejsza ryzyko przekroczenia limitu budżetu.

Aby obliczyć odpowiedni współczynnik skalowania, podziel budżet darowizn przez maksymalną sumę wartości agregowanych wartości wszystkich kluczy.

Więcej informacji znajdziesz w dokumentacji dotyczącej budżetu darowizn.

Angażuj i dziel się opiniami

Obecnie 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ę.

• GitHub czytaj wyjaśnienie, zadawaj pytania i bierz udział w dyskusji. * Pomoc dla deweloperów: zadawaj pytania i dołączaj do dyskusji w repozytorium pomocy dla deweloperów Piaskownicy prywatności. * Dołącz do grupy Shared Storage API i do grupy Protected Audience API, aby otrzymywać najnowsze ogłoszenia dotyczące agregacji prywatnej.