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 wielu witryn. Omówione tu zagadnienia są ważne dla programistów tworzących funkcje raportowania w Shared Storage i interfejsie Protected Audience API.

• Jeśli jesteś programistą i tworzysz system raportowania do obsługi w wielu witrynach pomiar skuteczności.
• Jeśli jesteś marketerem, analitykiem danych lub innym użytkownikiem raportów zbiorczych, zrozumienie tych mechanizmów pomoże Ci podejmować decyzje projektowe, aby pobierać zoptymalizowane raporty zbiorcze.

Kluczowe terminy

Zanim zaczniesz czytać ten dokument, zapoznaj się z kluczowymi terminami i pojęciami. Poniżej szczegółowo omówimy każdy z tych warunków.

• Klucz agregacji (zwany też zbiorem) to z góry określona kolekcja punktów danych. Możesz na przykład zbierać zbiorczy zestaw danych o lokalizacji, w którym przeglądarka podaje nazwę kraju. Klucz agregacji może zawierać więcej niż 1 wymiar (np. kraj i identyfikator widgeta treści).
• Wartość możliwa do zsumowania to pojedynczy punkt danych zebrany w kluczu agregacji. Jeśli chcesz sprawdzić, ilu użytkowników z Francji, zobaczyli Twoje treści, France jest wymiarem w klucz agregacji, a viewCount ciągu 1 to wartość agregowalna.
• Raporty zbiorcze są generowane i szyfrowane w przeglądarce. W przypadku wartości Interfejs Private Aggregation API zawierający dane o jednym zdarzeniu.
• Usługa agregacji przetwarza dane z raportów, które można agregować, aby utworzyć raport podsumowujący.
• Raport podsumowujący to końcowy wynik usługi agregacji. Zawiera on niespójny zbiorczy zbiór danych o użytkownikach i szczegółowe dane o konwersjach.
• Worklet to element infrastruktury, który umożliwia uruchamianie określonych funkcji JavaScript i zwracanie informacji do osoby, która je zażądała. W ramach workleta możesz wykonywać instrukcje JavaScript, ale nie możesz wchodzić w interakcje z zewnętrzną stroną ani z nią komunikować.

Procedura prywatnej agregacji

Gdy wywołujesz interfejs Private Aggregation API z kluczem agregacji i atrybutem , to przeglądarka generuje raport agregowany. Raporty są wysyłane na serwer, który tworzy ich zbiorcze zestawienie. Raporty zbiorcze są przetworzone później przez usługę agregacji – zostaje wygenerowany raport podsumowujący.

1. Gdy wywołujesz interfejs Private Aggregation API, klient (przeglądarka) generuje i wysyła na serwer raport agregowany w celu zebrania.
2. Twój serwer zbiera raporty od klientów i przesyła je zbiorczo do usługi agregacji.
3. Po zebraniu wystarczającej liczby raportów możesz je grupować i wysyłać usługa agregacji, działająca w zaufanym środowisku wykonawczym, w celu wygenerowania raport podsumowujący,

.

Kluczowy termin: zaufane środowisko wykonawcze to specjalna konfiguracja sprzętu i oprogramowania komputerowego, która umożliwia zewnętrznych firm, aby umożliwić weryfikację dokładnych wersji oprogramowania działającego na danym komputera. TEE umożliwia stronom zewnętrznym sprawdzenie, czy oprogramowanie zgodnie z tym, co robi producent oprogramowania – i nic więcej ani mniej.

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. Agregacja prywatna służy do pomiaru i zdarzenia w wielu witrynach.

Klucz agregacji

Klucz agregacji (w skrócie „klucz”) reprezentuje zbiornik, w którym będą gromadzone wartości podlegające agregacji. Co najmniej jeden wymiar można zakodować do klucza. Wymiar reprezentuje pewien aspekt, na temat którego chcesz uzyskać więcej statystyk, np. grupę wiekową użytkowników lub liczbę wyświetleń w kampanii reklamowej.

Możesz np. mieć widżet umieszczony w kilku witrynach i chcesz analizować kraj użytkowników, którzy go widzieli. Patrzysz o odpowiedzi na pytania, takie jak „Ilu użytkowników, którzy zobaczyli mój widżet, z kraju X?” Aby wygenerować raport dotyczący tego pytania, możesz skonfigurować klucz agregacji kodujący 2 wymiary: identyfikator widżetu oraz identyfikator kraju.

Klucz przekazany do interfejsu Private Aggregation API to BigInt, który składa się z wielu wymiarów. W tym przykładzie wymiarami są identyfikator widgeta i identyfikator kraju. Załóżmy, że identyfikator widżetu może mieć maksymalnie 4 cyfry, np. 1234, a każdy kraj jest przypisany do numeru w kolejności alfabetycznej, np. Afganistan to 1, Francja to 61, a Zimbabwe to „195”. Dlatego klucz do agregacji będzie miał 7 cyfr, z których pierwsze 4 są zarezerwowane dla WidgetID, a ostatnie 3 dla CountryID.

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

Klucz agregacji
Identyfikator widżetu	Identyfikator kraju
3276	061

Przykład: jeśli wymiar ma dostępne miejsce na klucz na kilka cyfr, ale wartość ma ich mniej, dodaj zera na początku. Jeśli np. identyfikator kraju pozwala na 3 cyfry, identyfikatorem kraju Algierii jest003.

Klucz agregacji można też wygenerować za pomocą mechanizmu szyfrowania, np. SHA-256. Na przykład ciąg znaków {"WidgetId":3276,"CountryID":67} można zamienić na wartość BigInt, która jest równa 42943797454801331377966796057547478208888578253058197330928948081739249096287n. Jeśli wartość skrótu ma więcej niż 128 bitów, możesz ją skrócić, aby nie przekracza maksymalną dozwoloną wartość zasobnika wynoszącą 2^128−1.

W ramach Worklet Shared Storage możesz uzyskać dostęp do crypto i Moduły: TextEncoder które mogą pomóc w wygenerowaniu hasza. Aby dowiedzieć się więcej o generowaniu hasha, zapoznaj się z artykułem SubtleCrypto.digest() w MDN.

Przykład poniżej pokazuje, jak wygenerować klucz zasobnika na podstawie zaszyfrowanego wartość:

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: mimo że te pojęcia są podobne, klucz w przypadku interfejsu Private Aggregation API jest zbudowany inaczej niż w przypadku interfejsu Attribution Reporting API. W przypadku agregacji prywatnej pełny klucz zostanie określone jednorazowo w wywołaniu JavaScript.

Wartość agregowalna

Agregowane wartości są sumowane na klucz wielu użytkowników w celu wygenerowania zagregowanych wartości statystyki w formie wartości zbiorczych w raportach podsumowujących.

Wróć teraz do przykładowego pytania, które zostało zadane wcześniej: „Ilu użytkowników, którzy widzieli mój widget, pochodzi z Francji?”. Odpowiedź na to pytanie będzie wyglądać np. „Około 4881 użytkowników, którzy zobaczyli mój identyfikator widżetu 3276, z Francji”. Wartość agregująca wynosi 1 na każdego użytkownika i „4881 użytkowników”. to zagregowana wartość będąca sumą wszystkich agregowanych wartości danego argumentu klucz agregacji.

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

W tym przykładzie zwiększamy wartość o 1 dla każdego użytkownika, który widzi widżet. W praktyce wartość możliwa do zsumowania może być skalowana w celu poprawy stosunku sygnału do szumu.

Budżet darowizn

Każde wywołanie interfejsu Private Aggregation API jest nazywane wkładem. Aby chronić prywatność użytkowników, liczba wkładów, które można zebrać od danej osoby, jest ograniczona.

Gdy zsumujesz wszystkie wartości podlegające agregacji we wszystkich kluczach agregacji, suma musi być mniejsza od budżetu udziału. Budżet jest ograniczony do konkretnego zbioru zadań origin, dziennie i jest oddzielnie dla Workletów Protected Audience API i Shared Storage. Rolka dla dnia używane jest okno z około ostatnich 24 godzinami. Jeśli nowy raport możliwy do zsumowania spowodowałby przekroczenie budżetu, nie zostanie on utworzony.

Budżet na wkład jest reprezentowany przez parametr L₁ i jest ustawiony na 2¹⁶ (65 536) na 10 minut dziennie z zabezpieczeniem 2²⁰

(1048576). Więcej informacji o tych parametrach znajdziesz w tym artykule.

Wartość budżetu na udział jest dowolna, ale szum jest do niej dostosowywany. Możesz użyć tego budżetu, aby zmaksymalizować stosunek sygnału do szumu w podsumowaniu wartości (te omówione dokładniej w sekcji Szum i skalowanie).

Więcej informacji o budżetach na udział znajdziesz w tym artykule. Więcej wskazówek znajdziesz też w budżecie na wkłady.

Limit darowizn na raport

W zależności od dzwoniącego limit wpłat może się różnić. Obecnie raporty generowane przez wywołujących interfejs API Shared Storage są ograniczone do 20 współtworzonych danych na raport. Z drugiej strony, w przypadku wywołań interfejsu Protected Audience API obowiązuje limit 100 dostaw na raport. Te limity zostały wybrane, aby zachować równowagę między liczbą wkładów, które można osadzić, a rozmiarem ładunku.

W przypadku współdzielonego miejsca na dane w raportach zbiorczych są uwzględniane dane z pojedynczej operacji run() lub selectURL(). W przypadku Protected Audience API publikowane treści według jednego źródła w ramach aukcji są grupowane razem.

Wkłady z wypełnieniem

Wkłady są dodatkowo modyfikowane za pomocą funkcji wypełniania. Dodanie danych do ładunku zabezpiecza informacje o rzeczywistej liczbie wkładów zawartych w raporcie możliwym do zsumowania. Dopełnienie rozszerza ładunek o null elementów (tj.z wartością 0), by osiągnąć stałą długość.

Raporty agregowane

Gdy użytkownik wywoła interfejs Private Aggregation API, przeglądarka wygeneruje agregowane raporty do przetworzenia przez usługę agregacji w późniejszym czasie. w czasie, by wygenerować podsumowanie . Raport możliwy do zsumowania jest w formacie JSON i zawiera zaszyfrowaną listę udziałów, z których każdy jest parą {aggregation key, aggregatable value}. Raporty agregujące są wysyłane z losowym opóźnieniem maksymalnie 1 godziny.

Dane są zaszyfrowane i nieczytelne poza usługą agregacji. Usługa agregacji odszyfrowuje raporty i generuje raport podsumowujący. klucz szyfrowania przeglądarki i klucz odszyfrowywania na potrzeby agregacji Usługa jest udostępniana przez koordynatora, który pełni funkcję usługi zarządzania kluczami. Koordynator przechowuje listę haszy binarnych obrazu usługi do weryfikacji rozmówca może otrzymać klucz odszyfrowywania.

Przykładowy raport agregowany z funkcją debugowania włączony tryb:

  "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:

W celu przetestowania możesz użyć przycisku „Wyślij wybrane raporty”, aby natychmiast wysłać raport na serwer.

Gromadzenie i grupowanie raportów możliwych do zagregowania

Przeglądarka wysyła raporty agregowane do źródła Workletu zawierający wywołanie interfejsu Private Aggregation API przy użyciu wymienionego dobrze znanego ścieżka:

• Shared Storage: /.well-known/private-aggregation/report-shared-storage
• Ochrona odbiorców: /.well-known/private-aggregation/report-protected-audience

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

Serwer powinien następnie przesyłać zbiorcze raporty i przesyłać je do agregacji. posprzedażna. Utwórz partie na podstawie informacji dostępnych w niezaszyfrowanych danych ładunku raportu agregowanego, np. pola shared_info. W idealnej sytuacji partie powinny zawierać co najmniej 100 raportów.

Możesz przesyłać dane codziennie lub co tydzień. Ta strategia jest elastyczna, i możesz zmienić strategię grupowania w przypadku konkretnych zdarzeń tam, gdzie chcesz więcej wyświetleń – na przykład w dniach, w których spodziewana jest większa liczba wyświetleń; Wsady powinny obejmować raporty z tej samej wersji interfejsu API, źródła raportowania zaplanować czas generowania raportu.

Usługa do agregacji

usługa agregacji, odbiera od kolektora zaszyfrowane raporty zbiorcze i generuje podsumowanie raportów.

Aby odszyfrować ładunek raportu, usługa agregacji pobiera klucz odszyfrowywania. od koordynatora. Usługa działa w zaufanym środowisku wykonawczym (TEE), który zapewnia poziom integralności i poufności danych oraz i integralność kodu. Chociaż usługa należy do Ciebie i obsługujesz ją, nie możesz wgląd w dane przetwarzane w TEE.

Raporty podsumowujące

Raporty zbiorcze pozwalają wyświetlić zebrane dane z dodanym hałasem. Możesz poprosić o raporty podsumowania dotyczące danego zbioru kluczy.

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

• bucket: klucz agregacji jako ciąg znaków binarnych. Jeśli użyty klucz agregacji to „123”, a następnie zasobnik to „1111011”.
• value: wartość zbiorcza dla danego celu pomiaru, zsumowana z wszystkich dostępnych raportów możliwych do agregacji z dodatkiem szumu.

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żdego z nich. za każdym razem, gdy zażądasz raportu podsumowującego. Wartości szumu są losowo pobierane z rozkładu prawdopodobieństwa Laplace’a. Gdy jesteś a który nie ma bezpośredniej kontroli nad sposobem dodawania szumu, może wpływać szumu w danych pomiarowych.

Rozkład szumu jest taki sam niezależnie od sumy wszystkich agregowanych danych . Dlatego im wyższe wartości można zsumować, tym mniejszy wpływ będzie miał szum.

Załóżmy na przykład, że rozkład szumu ma odchylenie standardowe 100 i jest scentralizowany wokół zera. Jeśli zebrana wartość raportu możliwa do agregacji (czyli „wartość możliwa do agregacji”) wynosi tylko 200, odchylenie standardowe szumu będzie równe 50% wartości zagregowanej. Jeśli jednak skumulowana wartość to 20 000, odchylenie standardowe szumu wyniesie tylko 0,5% wartości zagregowanej. Dlatego agregowana wartość 20 000 miałaby znacznie wyższy stosunek sygnału do szumu.

Dlatego mnożenie wartości agregacji przez współczynnik skalowania zredukować szum. Współczynnik skalowania reprezentuje rozmiar danej wartości agregującej.

Przeskalowywanie wartości przez wybranie większego współczynnika skalowania zmniejsza względny szum. Spowoduje to jednak, że suma wszystkich udziałów we wszystkich zbiornikach szybciej osiągnie limit budżetu udziałów. Skalowanie wartości w dół o wybór mniejszej stałej współczynnika skalowania zwiększa szum względny, ale zmniejsza może dojść do przekroczenia limitu budżetu.

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

Więcej informacji znajdziesz w dokumentacji dotyczącej budżetu na wkłady.

Zaangażowanie i przesyłanie opinii

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

• GitHub: przeczytaj informacje, zadawaj pytania i ucz się na podstawie dyskusji. * Pomoc dla deweloperów: zadawaj pytania i ucz się na temat Piaskownicy prywatności w repozytorium Pomoc dla deweloperów. * Dołącz do grupy Shared Storage API i Protected Audience API, aby otrzymywać najnowsze informacje dotyczące prywatnej agregacji.