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 danych zbiorczych z workletów z dostępem do danych z różnych witryn. Omówione tu koncepcje są ważne dla deweloperów tworzących raporty w ramach Shared Storage i Protected Audience API.

• Jeśli jesteś programistą i tworzysz system raportowania do obsługi w wielu witrynach pomiar skuteczności.
• Jeśli jesteś marketerem, badaczem danych lub innym raportem podsumowującym konsumentom, poznanie tych mechanizmów pomoże decyzji, aby pobrać zoptymalizowany raport podsumowujący.

Kluczowe terminy

Przed przeczytaniem tego dokumentu warto zapoznać się z kluczowych terminach i koncepcjach. Poniżej znajdziesz szczegółowe omówienie każdego z tych warunków.

• Klucz agregacji (nazywany też zasobnikiem) to wstępnie zdefiniowanego zbierania punktów danych. Możesz na przykład: zbierają dane o lokalizacji, w których przeglądarka zgłasza kraj; imię i nazwisko. 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 zebrane do klucza 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 atrybutu Interfejs Private Aggregation API zawierający dane o jednym zdarzeniu.
• usługa agregacji, przetwarza dane z raportów agregowanych w celu utworzenia raportu podsumowującego.
• Raport podsumowujący to ostateczne dane wyjściowe usługi agregacji. zawiera zbiorcze dane o użytkownikach i szczegółowe dane o konwersjach.
• Praca to fragment infrastruktury, która umożliwia uruchamianie określonych funkcji JavaScriptu zwrócić informacje osobom zgłaszającym prośbę. W obrębie Worklet możesz wykonać JavaScript, ale nie możesz wchodzić w interakcję ze stroną zewnętrzną ani się z nią komunikować.

Przepływ pracy agregacji prywatnej

Gdy wywołujesz interfejs Private Aggregation API z kluczem agregacji i atrybutem lub wartości agregowanej, przeglądarka generuje raport agregowany. Raporty są wysyłane na Twój serwer, który grupuje raporty. 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. Serwer zbiera raporty od klientów i grupuje je w celu wysyłane 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.

Przepływ pracy opisany w tej sekcji jest podobny do raportowania atrybucji API. Atrybucja Raportowanie łączy dane zebrane ze zdarzenia wyświetlenia i konwersji które mają miejsce w różnych momentach. Agregacja prywatna służy do pomiaru zdarzenia w wielu witrynach.

Klucz agregacji

Klucz agregacji (w skrócie „klucz”) reprezentuje zasobnik, w którym agregowane wartości będą kumulowane. Co najmniej jeden wymiar można zakodować do klucza. Wymiar reprezentuje jakiś aspekt, który warto zwiększyć np. o grupie wiekowej użytkowników czy liczbie wyświetleń reklamy kampanii.

Możesz na przykład mieć widżet umieszczony w wielu witrynach, chcemy przeanalizować kraj użytkowników, którzy widzieli Twój widżet. 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óra składa się z wielu wymiarów. W tym przykładzie wymiary to widżetu i kraju. Załóżmy, że identyfikator widżetu może mieć maksymalnie 4 cyfry tak jak 1234, a każdy kraj jest przyporządkowany do liczby w zapisie alfabetycznym zamówienie takie jak Afganistan to 1, Francja – 61, a Zimbabwe – „195”. Dlatego klucz agregacyjny miałby 7 cyfr, przy czym pierwsze 4 znaki są zarezerwowane dla WidgetID, a ostatnie 3 to znaki zarezerwowany dla domeny CountryID.

Załóżmy, że klucz reprezentuje liczbę użytkowników z Francji (identyfikator kraju: 061). dla osób, które widziały identyfikator widżetu 3276, klucz agregacji to 3276061.

Klucz agregacji
Identyfikator widżetu	Identyfikator kraju
3276	061

Przykład: jeśli wymiar ma dostępną przestrzeń kluczy dla wielu cyfr, ale wartość ma ich mniej, dodaj początkowe zera. Przykład: jeśli identyfikator kraju składa się z 3 cyfr, identyfikatorem kraju w przypadku Algierii jest 003.

Klucz agregacji można też wygenerować za pomocą mechanizmu haszującego, takiego jak SHA-256. Na przykład: {"WidgetId":3276,"CountryID":67} można zaszyfrować, a następnie przekonwertować na BigInt ma wartość 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 skrótu. Więcej informacji o generowaniu hasza: 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: chociaż koncepcje są podobne, najważniejszy dla interfejsu Private Aggregation API jest skonstruowana inaczej niż 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.

Teraz wróć do zajętego wcześniej przykładowego pytania: „Ilu użytkowników kto widział mój widżet, jest 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ść agregowaną można skalować, aby poprawić sygnał do szumu współczynnik proporcji.

Budżet darowizn

Każde wywołanie interfejsu Private Aggregation API jest nazywane contribution. Ochrona prywatności użytkowników, czyli liczbę treści, które można zebrać są ograniczone.

Gdy zsumujesz wszystkie wartości agregujące ze wszystkich kluczy agregacji, suma musi być mniejszy niż budżet darowizny. 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 agregacyjny spowodowałoby przekroczenie budżetu, raport nie jest Utworzono.

Budżet darowizn jest reprezentowany przez parametr L₁ i jest ustaw na 2¹⁶ (65 536) na 10 minut dziennie z przystankiem wstecznym równym 2²⁰

(1 048 576). Zobacz wyjaśnienie .

Wartość budżetu darowizn jest dowolna, ale jest do niej skalowany szum. 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 bazujących na darowiznach znajdziesz w Wyjaśnienie. Zapoznaj się też z sekcją Współpraca Budżet .

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 . An Raport zbiorczy jest w formacie JSON i zawiera zaszyfrowaną listę z których każdy to para {aggregation key, aggregatable value}. Raporty agregowane są wysyłane z losowym opóźnieniem maksymalnie 1 godziny.

Publikowane treści są zaszyfrowane i nie można ich odczytać 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 agregujące można przeglądać w Strona chrome://private-aggregation-internals:

Do celów testowych można użyć opcji „Wyślij wybrane raporty” może służyć do wysłania natychmiast je zgłosić.

Zbieranie i zbiorcze raporty agregujące

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:

• Pamięć współdzielona: /.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óra otrzymuje raporty zbiorcze wysyłane od klientów.

Serwer powinien następnie przesyłać raporty zbiorcze i wysyłać je do agregacji. posprzedażna. Utwórz partie na podstawie informacji dostępnych w niezaszyfrowanych danych ładunku raportu agregowanego, np. pola shared_info. Najlepiej, każda porcja powinna 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 podsumowujące pozwalają zobaczyć dane zebrane z dodanym szumem. Możesz poprosić o raportów podsumowujących dla danego zestawu kluczy.

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

• bucket: klucz agregacji w postaci ciągu liczb binarnych. Jeśli użyty klucz agregacji to „123”, a następnie zasobnik to „1111011”.
• value: łączna wartość dla danego celu pomiarowego, sumowana z wszystkie dostępne raporty agregujące 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żdego z nich. za każdym razem, gdy zażądasz raportu podsumowującego. Wartości szumu to losowo wybrane z prawdopodobieństwa Laplace'a dystrybucji. 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 agregowane, tym mniejszy wpływ na szum co zapewne.

Załóżmy na przykład, że rozkład szumu ma odchylenie standardowe o wartości 100 i jest wyśrodkowany od zera. Jeśli zebrana wartość raportu agregowanego (lub „wartość agregująca”) wynosi tylko 200, to odchylenie standardowe szumu wyniesie 50% wartości zbiorczej. 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.

Skalowanie wartości przez wybranie większego współczynnika skalowania zmniejsza względną hałas. Spowoduje to jednak również sumę wszystkich wkładów we wszystkie segmenty. aby szybciej osiągnąć limit budżetu darowizn. 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.

Zobacz Budżet darowizn dokumentacja aby dowiedzieć się więcej.

Angażuj odbiorców i dziel się opiniami

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

• GitHub: przeczytaj Wyjaśnienie, zadaj pytania i bierz udział w dyskusja. * Pomoc dla deweloperów: zadawaj pytania i dołączaj do dyskusji na Pomoc dla deweloperów w Piaskownicy prywatności repozytorium. * Dołącz do interfejsu Shared Storage API grupa oraz Protected Audience API grupa gdzie znajdziesz najnowsze powiadomienia na temat agregacji prywatnej.