Schlüsselkonzepte der Private Aggregation API
An wen richtet sich dieses Dokument?
Die Private Aggregation API ermöglicht die aggregierte Datenerhebung aus Worklets mit Zugriff auf websiteübergreifende Daten. Die hier vorgestellten Konzepte sind für Entwickler wichtig, die Berichtsfunktionen im freigegebenen Speicher und in der Protected Audience API erstellen.
- Sie sind Entwickler und erstellen ein Berichtssystem für die websiteübergreifende Messung.
- Wenn Sie Marketingexperte, Data Scientist oder andere Nutzer von zusammenfassenden Berichten sind, hilft Ihnen das Verständnis dieser Mechanismen bei Designentscheidungen zum Abrufen eines optimierten zusammenfassenden Berichts.
Wichtige Begriffe
Bevor Sie dieses Dokument lesen, sollten Sie sich mit den wichtigsten Begriffen und Konzepten vertraut machen. Jeder dieser Begriffe wird hier ausführlich beschrieben.
- Ein Aggregationsschlüssel (auch als Bucket bezeichnet) ist eine vordefinierte Sammlung von Datenpunkten. Angenommen, Sie möchten einen Bucket mit Standortdaten erfassen, wenn der Browser den Ländernamen meldet. Ein Aggregationsschlüssel kann mehr als eine Dimension enthalten, z. B. Land und ID Ihres Inhalts-Widgets.
- Ein aggregierbarer Wert ist ein einzelner Datenpunkt, der in einem Aggregationsschlüssel erfasst wird. Wenn Sie erfassen möchten, wie viele Nutzer aus Frankreich Ihre Inhalte gesehen haben, ist
Franceeine Dimension im Aggregationsschlüssel und derviewCountvon1der aggregierbare Wert. - Aggregierte Berichte werden in einem Browser generiert und verschlüsselt. Bei der Private Aggregation API enthält es Daten zu einem einzelnen Ereignis.
- Der Aggregationsdienst verarbeitet Daten aus aggregierten Berichten, um einen zusammenfassenden Bericht zu erstellen.
- Ein zusammenfassender Bericht ist die endgültige Ausgabe des Aggregation Service. Er enthält verrauschte aggregierte Nutzerdaten und detaillierte Conversion-Daten.
- Ein Worklet ist eine Infrastruktur, mit der Sie bestimmte JavaScript-Funktionen ausführen und Informationen an den Anforderer zurückgeben können. Innerhalb eines Worklet können Sie JavaScript ausführen, aber nicht mit der externen Seite interagieren oder mit ihr kommunizieren.
Workflow für private Aggregation
Wenn Sie die Private Aggregation API mit einem Aggregationsschlüssel und einem aggregierbaren Wert aufrufen, generiert der Browser einen zusammengefasste Bericht. Die Berichte werden an Ihren Server gesendet, auf dem die Berichte als Batch zusammengefasst werden. Die Batch-Berichte werden später vom Aggregation Service verarbeitet und ein zusammenfassender Bericht wird generiert.
- Wenn Sie die Private Aggregation API aufrufen, generiert der Client (Browser) den aggregierbaren Bericht und sendet ihn an Ihren Server, um ihn zu erfassen.
- Ihr Server erfasst die Berichte von den Clients und fasst sie in Batches zusammen, um sie an den Aggregationsdienst zu senden.
- Sobald Sie genügend Berichte erfasst haben, senden Sie sie im Batch an den Aggregationsdienst, der in einer vertrauenswürdigen Ausführungsumgebung ausgeführt wird, um einen zusammenfassenden Bericht zu generieren.
Der in diesem Abschnitt beschriebene Workflow ähnelt der Attribution Reporting API. In Attribution Reporting werden jedoch Daten aus einem Impressionsereignis und einem Conversion-Ereignis zugeordnet, die zu unterschiedlichen Zeiten stattfinden. Bei der privaten Aggregation wird ein einzelnes, websiteübergreifendes Ereignis erfasst.
Aggregationsschlüssel
Ein Aggregationsschlüssel ("key") steht für den Bucket, in dem die aggregierbaren Werte akkumuliert werden. Im Schlüssel können eine oder mehrere Dimensionen codiert werden. Eine Dimension repräsentiert einen Aspekt, über den Sie mehr Einblicke erhalten möchten, z. B. die Altersgruppe der Nutzer oder die Anzahl der Impressionen einer Kampagne.
Angenommen, Sie haben ein Widget, das in mehrere Websites eingebettet ist, und möchten das Land der Nutzer analysieren, die Ihr Widget gesehen haben. Sie möchten Fragen wie „Wie viele Nutzer, die mein Widget gesehen haben, aus Land X stammen?“ Für Berichte zu dieser Frage können Sie einen Aggregationsschlüssel einrichten, der zwei Dimensionen codiert: Widget-ID und Länder-ID.
Der der Private Aggregation API bereitgestellten Schlüssel ist BigInt, das aus mehreren Dimensionen besteht. In diesem Beispiel sind die Dimensionen die Widget-ID und die Länder-ID. Angenommen, die Widget-ID kann bis zu vier Ziffern lang sein, z. B. 1234. Jedes Land wird einer Zahl in alphabetischer Reihenfolge zugeordnet, z. B. „1“ für Afghanistan, für „Frankreich“ „61“ und für „Simbabwe“ „195“.
Daher ist der aggregierbare Schlüssel 7 Ziffern lang, wobei die ersten 4 Zeichen für WidgetID und die letzten 3 Zeichen für CountryID reserviert sind.
Nehmen wir an, der Schlüssel steht für die Anzahl der Nutzer aus Frankreich (Landes-ID 061), die die Widget-ID 3276 gesehen haben. Der Zusammenfassungsschlüssel lautet 3276061.
| Aggregationsschlüssel | |
| Widget-ID | Landes-ID |
| 3276 | 061 |
Der Aggregationsschlüssel kann auch mit einem Hash-Mechanismus wie SHA-256 generiert werden. Beispielsweise kann der String {"WidgetId":3276,"CountryID":67} gehasht und dann in einen BigInt-Wert von 42943797454801331377966796057547478208888578253058197330928948081739249096287n umgewandelt werden.
Wenn der Hashwert mehr als 128 Bit hat, können Sie ihn kürzen, damit er den maximal zulässigen Bucket-Wert von 2^128−1 nicht überschreitet.
In einem Worklet für freigegebenen Speicher können Sie auf die Module crypto und TextEncoder zugreifen, mit denen Sie einen Hash generieren können. Weitere Informationen zum Generieren eines Hashs findest du unter SubtleCrypto.digest() auf der MDN-Website.
Im folgenden Beispiel wird beschrieben, wie Sie einen Bucket-Schlüssel aus einem Hash-Wert generieren:
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
Aggregierbarer Wert
Aggregierbare Werte werden pro Schlüssel über viele Nutzer hinweg summiert, um zusammengefasste Informationen in Form von Zusammenfassungswerten in Zusammenfassungsberichten zu generieren.
Kehren wir nun zu der zuvor gestellten Beispielfrage zurück: „Wie viele Nutzer, die mein Widget gesehen haben, kommen aus Frankreich?“ Die Antwort auf diese Frage sieht in etwa so aus: „Ungefähr 4.881 Nutzer, die meine Widget-ID 3276 gesehen haben, stammen aus Frankreich.“ Der aggregierbare Wert ist für jeden Nutzer 1 und "4881 Nutzer" der aggregierte Wert, der der Summe aller aggregierbaren Werte für diesen Aggregationsschlüssel entspricht.
| Aggregationsschlüssel | Aggregierbarer Wert | |
| Widget-ID | Landes-ID | Aufrufe |
| 3276 | 061 | 1 |
In diesem Beispiel erhöhen wir den Wert für jeden Nutzer, der das Widget sieht, um 1. In der Praxis kann der aggregierbare Wert skaliert werden, um das Signal-Rausch-Verhältnis zu verbessern.
Beitragsbudget
Jeder Aufruf der Private Aggregation API wird als Beitrag bezeichnet. Aus Datenschutzgründen ist die Anzahl der Beiträge, die von einer Person erhoben werden können, begrenzt.
Wenn Sie alle aggregierbaren Werte aller Aggregationsschlüssel summieren, muss die Summe kleiner als das Beitragsbudget sein. Das Budget wird pro Worklet Ursprung und Tag definiert und wird für die Protected Audience API- und Shared Storage-Worklets getrennt. Für den Tag wird ein rollierendes Fenster von etwa 24 Stunden verwendet. Wenn ein neuer zusammengefasste Bericht zu einer Budgetüberschreitung führen würde, wird der Bericht nicht erstellt.
Das Beitragsbudget wird durch den Parameter L1 dargestellt und auf 216 (65.536) pro 10 Minuten und Tag mit einem Backstop von 220 festgelegt.
(1.048.576). Weitere Informationen zu diesen Parametern finden Sie in der Erläuterung.
Der Wert des Beitragsbudgets ist beliebig, aber das Rauschen wird entsprechend skaliert. Sie können dieses Budget verwenden, um das Signal-Rausch-Verhältnis in den zusammengefassten Werten zu maximieren (weitere Informationen im Abschnitt Rauschen und Skalierung).
Weitere Informationen zu Beitragsbudgets findest du in der Erläuterung. Weitere Informationen findest du unter Beitragsbudget.
Aggregierbare Berichte
Sobald der Nutzer die Private Aggregation API aufruft, generiert der Browser zusammengefasste Berichte, die vom Aggregationsdienst zu einem späteren Zeitpunkt verarbeitet werden, um zusammenfassende Berichte zu generieren. Ein aggregierbarer Bericht ist im JSON-Format formatiert und enthält eine verschlüsselte Liste von Beiträgen, die jeweils ein {aggregation key, aggregatable value}-Paar sind.
Aggregierbare Berichte werden mit einer zufälligen Verzögerung von bis zu einer Stunde gesendet.
Die Beiträge sind verschlüsselt und außerhalb des Aggregation Service nicht lesbar. Der Aggregationsdienst entschlüsselt die Berichte und erstellt einen zusammenfassenden Bericht. Der Verschlüsselungsschlüssel für den Browser und der Entschlüsselungsschlüssel für den Aggregation Service werden vom Koordinator ausgegeben, der als Schlüsselverwaltungsdienst fungiert. Der Koordinator führt eine Liste der binären Hashes des Dienst-Images, um zu überprüfen, ob der Aufrufer den Entschlüsselungsschlüssel empfangen darf.
Hier sehen Sie ein Beispiel für einen aggregierbaren Bericht mit aktiviertem Debug-Modus:
"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\"}"
Die aggregierbaren Berichte können auf der Seite chrome://private-aggregation-internals eingesehen werden:
Zu Testzwecken kann die Schaltfläche „Ausgewählte Berichte senden“ verwendet werden, um den Bericht sofort an den Server zu senden.
Aggregierbare Berichte sammeln und im Batch verarbeiten
Der Browser sendet die aggregierten Berichte unter Verwendung des aufgeführten bekannten Pfads an den Ursprung des Worklets, das den Aufruf an die Private Aggregation API enthält:
- Für freigegebenen Speicher:
/.well-known/private-aggregation/report-shared-storage - Für Protected Audience:
/.well-known/private-aggregation/report-protected-audience
An diesen Endpunkten müssen Sie einen Server betreiben, der als Collector fungiert und die aggregierten Berichte empfängt, die von den Clients gesendet werden.
Der Server sollte dann Berichte in Batches zusammenfassen und an den Aggregation Service senden. Erstellen Sie Batches anhand der Informationen, die in der unverschlüsselten Nutzlast des aggregierten Berichts verfügbar sind, z. B. im Feld shared_info. Idealerweise sollten die Batches 100 oder mehr Berichte pro Batch enthalten.
Sie können sich für eine tägliche oder wöchentliche Batch-Verarbeitung entscheiden. Diese Strategie ist flexibel und Sie können die Batch-Strategie für bestimmte Ereignisse ändern, an denen Sie ein höheres Volumen erwarten, z. B. an Tagen im Jahr, an denen mehr Impressionen zu erwarten sind. Batches sollten Berichte aus derselben API-Version, demselben Berichtsursprung und demselben geplanten Berichtszeitraum enthalten.
Aggregationsdienst
Der Aggregation Service empfängt verschlüsselte aggregierte Berichte vom Collector und erstellt zusammenfassende Berichte.
Zum Entschlüsseln der Berichtsnutzlast ruft der Aggregation Service einen Entschlüsselungsschlüssel vom Koordinator ab. Der Dienst wird in einer vertrauenswürdigen Ausführungsumgebung (Trusted Execution Environment, TEE) ausgeführt, die ein Maß an Sicherheit in Bezug auf Datenintegrität, Datenvertraulichkeit und Codeintegrität bietet. Auch wenn Sie der Dienst sind und diesen betreiben, haben Sie keinen Einblick in die Daten, die im TEE verarbeitet werden.
Zusammenfassende Berichte
In Zusammenfassungsberichten sehen Sie die Daten, die Sie mit hinzugefügtem Rauschen erfasst haben. Sie können Zusammenfassungsberichte für einen bestimmten Satz von Schlüsseln anfordern.
Ein Zusammenfassungsbericht enthält eine Reihe von Schlüssel/Wert-Paaren im Stil eines JSON-Wörterbuchs. Jedes Paar enthält Folgendes:
bucket: Der Aggregationsschlüssel als String mit Binärzahl. Wenn der verwendete Aggregationsschlüssel „123“ ist, ist der Bucket „1111011“.value: der Gesamtwert für ein bestimmtes Messziel, der aus allen verfügbaren aggregierten Berichten mit Rauschen addiert wurde.
Beispiel:
[
{"bucket":` `"111001001",` `"value":` `"2558500"},
{"bucket":` `"111101001",` `"value":` `"3256211"},
{"bucket":` `"111101001",` `"value":` `"6536542"},
]
Rauschen und Skalierung
Aus Datenschutzgründen fügt der Aggregationsdienst jedem Zusammenfassungswert bei jeder Anforderung eines zusammenfassenden Berichts einmal verrauscht hinzu. Die Rauschwerte werden zufällig aus einer Laplace-Wahrscheinlichkeitsverteilung bezogen. Sie haben zwar keine direkte Kontrolle darüber, wie Rauschen hinzugefügt wird, können aber die Auswirkungen von Rauschen auf die Messdaten beeinflussen.
Die Rauschverteilung ist unabhängig von der Summe aller aggregierbaren Werte gleich. Daher gilt: Je höher die aggregierbaren Werte, desto weniger Auswirkungen hat das Rauschen wahrscheinlich.
Angenommen, die Rauschverteilung hat eine Standardabweichung von 100 und ist auf null zentriert. Wenn der erfasste aggregierte Berichtswert (oder „aggregierbarer Wert“) nur 200 beträgt, beträgt die Standardabweichung des Rauschens 50% des aggregierten Werts. Wenn der aggregierbare Wert jedoch 20.000 ist, beträgt die Standardabweichung des Rauschens nur 0,5% des aggregierten Werts. Der aggregierte Wert 20.000 hätte also ein viel höheres Signal-Rausch-Verhältnis.
Daher kann das Multiplizieren des aggregierbaren Werts mit einem Skalierungsfaktor dazu beitragen, das Rauschen zu reduzieren. Der Skalierungsfaktor gibt an, wie stark ein bestimmter aggregierter Wert skaliert werden soll.
Wenn Sie die Werte durch Auswahl eines größeren Skalierungsfaktors skalieren, wird das relative Rauschen reduziert. Dies führt jedoch auch dazu, dass die Summe aller Beiträge in allen Buckets das Limit für das Beitragsbudget schneller erreicht. Wenn Sie die Werte durch Auswahl eines kleineren Skalierungsfaktors verkleinern, erhöht sich das relative Rauschen, aber das Risiko, das Budgetlimit zu erreichen, wird verringert.
Um einen geeigneten Skalierungsfaktor zu berechnen, teilen Sie das Beitragsbudget durch die maximale Summe der aggregierbaren Werte über alle Schlüssel hinweg.
Weitere Informationen findest du in der Dokumentation zum Beitragsbudget.
Reagieren und Feedback geben
Die Private Aggregation API wird derzeit diskutiert und kann sich in Zukunft ändern. Wenn Sie diese API testen und Feedback haben, freuen wir uns darauf, sie zu hören.
- GitHub Lesen Sie die Erklärung, stellen Sie Fragen und beteiligen Sie sich an Diskussionen. * Entwicklersupport: Im Privacy Sandbox-Entwickler-Support-Repository kannst du Fragen stellen und an Diskussionen teilnehmen. * Treten Sie der Shared Storage API-Gruppe und der Protected Audience API-Gruppe bei, um aktuelle Ankündigungen zur privaten Aggregation zu erhalten.