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, aviewCount
(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.
![Dane przepływają od klienta do kolektora, a następnie do usługi agregacji w celu wygenerowania raportu podsumowującego.](https://developers.google.cn/static/privacy-sandbox/assets/images/data-flows-the-client-t-ebd6f5c55d92f.png?authuser=3&hl=pl)
- Gdy wywołujesz interfejs Private Aggregation API, klient (przeglądarka) generuje i wysyła na Twój serwer raport zbiorczy w celu zebrania danych.
- Serwer zbiera raporty od klientów i grupuje je w celu wysłania do usługi agregacji.
- 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.
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 |
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
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 L1 i jest ustawiony na 216 (65 536) na 10 minut dziennie z okresem wstecznym 220
(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
:
![zrzut ekranu strony interfejsu Private Aggregation API](https://developers.google.cn/static/privacy-sandbox/assets/images/screenshot-the-private-a-132a69aaab759.png?authuser=3&hl=pl)
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 działa w TEE, odszyfrowuje raporty zbiorcze i dodaje szum, aby utworzyć końcowy raport podsumowujący.](https://developers.google.cn/static/privacy-sandbox/assets/images/the-service-runs-a-tee-746adddcc2c6.png?authuser=3&hl=pl)
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ą.
![Szum jest stały niezależnie od wartości zagregowanej.](https://developers.google.cn/static/privacy-sandbox/assets/images/noise-is-constant-regardl-6c311a31c1292.png?authuser=3&hl=pl)
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.
![Przeskaluj wartość agregowaną do budżetu darowizn.](https://developers.google.cn/static/privacy-sandbox/assets/images/scale-aggregatable-value-b7347ae673f12.png?authuser=3&hl=pl)
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.