Grundlagen der Private Aggregation API

Schlüsselkonzepte der Private Aggregation API

Für wen ist dieses Dokument gedacht?

Die Private Aggregation API ermöglicht die Erfassung aggregierter Daten aus Worklets mit Zugriff auf websiteübergreifende Daten. Die hier vorgestellten Konzepte sind wichtig für Entwickler, die Berichte erstellen im freigegebenen Speicher und in der Protected Audience API.

• Wenn Sie als Entwickler ein Berichtssystem für websiteübergreifende zu messen.
• Für Marketingexperten, Data Scientist oder andere Zusammenfassungsberichte , können Sie mit diesen Mechanismen Entscheidungen zum Abrufen eines optimierten Zusammenfassungsberichts treffen.

Wichtige Begriffe

Bevor Sie dieses Dokument lesen, sollten Sie sich mit Schlüsselbegriffe und Konzepte. Jeder dieser Begriffe wird hier ausführlich beschrieben.

• Ein Aggregationsschlüssel (auch Bucket genannt) ist ein vordefinierte Sammlung von Datenpunkten. Vielleicht möchten Sie Eine Gruppe von Standortdaten erheben, in der der Browser das Land meldet Namen. Ein Aggregationsschlüssel kann mehrere Dimensionen enthalten, z. B. Land und ID Ihres Inhalts-Widgets.
• Ein aggregierbarer Wert ist ein einzelner Datenpunkt. die in einem Aggregationsschlüssel erfasst werden. Wenn Sie messen möchten, wie viele Nutzer aus Frankreich Ihre Inhalte gesehen haben, dann ist "France" eine Dimension im Aggregationsschlüssel und viewCount von 1 ist der aggregierbare Wert.
• Zusammengefasste Berichte werden in einem Browser generiert und verschlüsselt. Für die Private Aggregation API, enthält Daten zu einem einzelnen Ereignis.
• Aggregationsdienst verarbeitet Daten aus aggregierbaren Berichten, um einen zusammenfassenden Bericht zu erstellen.
• Ein Zusammenfassungsbericht ist die endgültige Ausgabe des Aggregationsdiensts. enthält verrauschte aggregierte Nutzerdaten und detaillierte Conversion-Daten.
• Ein Worklet ist ein Stück der Infrastruktur, mit der Sie bestimmte JavaScript-Funktionen und Informationen an den Auftraggeber zurücksenden. Innerhalb eines Worklets können Sie Sie können jedoch nicht mit der Außenseite interagieren oder kommunizieren.

Workflow für die private Aggregation

Wenn Sie die Private Aggregation API mit einem Aggregationsschlüssel und einem aggregiert werden, generiert der Browser einen aggregierten Bericht. Berichte an Ihren Server gesendet, auf dem die Berichte stapelweise erstellt werden. Die Batch-Berichte sind die später vom Zusammenfassungsdienst verarbeitet werden, und es wird ein zusammenfassender Bericht erstellt.

1. Wenn Sie die Private Aggregation API aufrufen, generiert der Client (Browser) und sendet den aggregierten Bericht zur Erfassung an Ihren Server.
2. Ihr Server erfasst die Berichte von den Clients und fasst sie in Batches zusammen, an den Zusammenfassungsdienst gesendet.
3. Sobald Sie genügend Berichte gesammelt haben, können Sie sie als Batches an die Aggregationsdienst, der in einer vertrauenswürdigen Ausführungsumgebung ausgeführt wird, um einen zusammenfassenden Bericht.

Der in diesem Abschnitt beschriebene Workflow ähnelt dem für die Attributionsberichte API hinzu. Die Attribution Bei der Berichterstellung werden Daten, die über ein Impressionsereignis und eine Conversion erfasst wurden, verknüpft. die zu unterschiedlichen Zeiten stattfinden. Die private Aggregation misst eine websiteübergreifendes Ereignis.

Aggregationsschlüssel

Ein Aggregationsschlüssel (kurz: Schlüssel) stellt den Bucket dar, in dem der aggregierbare Werte aggregiert. Eine oder mehrere Dimensionen können codiert werden. in den Schlüssel ein. Eine Dimension stellt einen Aspekt dar, mit dem Sie Informationen über die Altersgruppe der Nutzer oder die Anzahl an Impressionen einer Anzeige Kampagne.

Beispiel: Sie haben ein Widget, das in mehrere Websites eingebettet ist und möchten Sie das Land der Nutzer analysieren, die Ihr Widget gesehen haben. Sie suchen um Fragen wie „Wie viele der Nutzenden, die mein Widget gesehen haben, aus Land X?“ Wenn du Berichte zu dieser Frage erstellen möchtest, kannst du einen Aggregationsschlüssel einrichten mit der zwei Dimensionen codiert werden: Widget-ID und Länder-ID.

Der an die Private Aggregation API übergebene Schlüssel ist ein BigInt der 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 4 Ziffern umfassen. z. B. 1234, und jedes Land ist einer alphabetischen Zahl Beispiel: Afghanistan ist 1, Frankreich ist 61 und Simbabwe ist 195. Daher wäre der aggregierte Schlüssel 7 Ziffern lang, wobei die ersten 4 Ziffern Zeichen sind für WidgetID reserviert; die letzten drei Zeichen sind für CountryID reserviert.

Angenommen, der Schlüssel steht für die Anzahl der Nutzer aus Frankreich (Länder-ID 061). die die Widget-ID 3276 gesehen haben, lautet der Aggregationsschlüssel 3276061.

Aggregationsschlüssel
Widget-ID	Landes-ID
3276	061

Der Aggregationsschlüssel kann auch mit einem Hash-Mechanismus wie z. B. SHA-256: Beispiel: Der String {"WidgetId":3276,"CountryID":67} kann gehasht und dann in einen Wert BigInt von 42943797454801331377966796057547478208888578253058197330928948081739249096287n Beinhaltet der Hashwert mehr als 128 Bit, können Sie ihn kürzen, damit keine den maximal zulässigen Bucket-Wert von 2^128−1 überschreiten.

Innerhalb eines Shared Storage-Worklets können Sie auf das crypto und TextEncoder Module mit dem Sie einen Hash generieren können. Weitere Informationen zum Generieren eines Hashs finden Sie in SubtleCrypto.digest() an MDN

Im folgenden Beispiel wird beschrieben, wie Sie einen Bucket-Schlüssel aus einem gehashten Wert:

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

Die aggregierten Werte werden pro Schlüssel für viele Nutzer addiert, um aggregierte Informationen in Form von Übersichtswerten in zusammenfassenden Berichten zu gewinnen.

Kehren wir nun zur vorherigen Beispielfrage zurück: „Wie viele der Nutzenden die mein Widget gesehen haben, kommen aus Frankreich?“ Die Antwort auf diese Frage etwa 4881 Nutzer, die meine Widget-ID 3276 gesehen haben, aus Frankreich“. Der aggregierbare Wert beträgt für jeden Nutzer 1 und „4.881 Nutzer“. ist den aggregierten Wert, also die Summe aller aggregierbaren Werte für diesen Wert Aggregationsschlüssel.

Aggregationsschlüssel		Aggregierbarer Wert
Widget-ID	Landes-ID	Anzahl der 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 die Signal-zu-Rausch-Funktion zu verbessern. Seitenverhältnis.

Beitragsbudget

Jeder Aufruf der Private Aggregation API wird als Beitrag bezeichnet. Zum Schutz Datenschutz, die Anzahl der Beiträge, die über ein Einzelpersonen sind begrenzt.

Wenn Sie alle aggregierbaren Werte in allen Aggregationsschlüsseln summieren, muss die Summe unter dem Beitragsbudget liegen. Das Budget bezieht sich auf ein Worklet. origin, pro Tag und ist separat für die Worklets Protected Audience API und freigegebener Speicher. Ein rollierender Für den Tag wird ein Zeitfenster von etwa den letzten 24 Stunden verwendet. Wenn ein neuer Aggregierbarer Bericht dazu führen, dass das Budget überschritten wird. erstellt.

Das Beitragsbudget wird durch den Parameter L₁ dargestellt und ist auf 2¹⁶ (65.536) pro 10 Minuten pro Tag mit einem Backstop-Wert von 2²⁰ festgelegt

(1.048.576). Weitere Informationen finden Sie in der Erklärung um mehr über diese Parameter zu erfahren.

Der Wert des Beitragsbudgets ist beliebig, aber Rauschen wird darauf skaliert. Mit diesem Budget können Sie das Signal-Rausch-Verhältnis der Zusammenfassungswerte maximieren. (wird im Abschnitt Rauschen und Skalierung genauer erläutert).

Weitere Informationen zu Beitragsbudgets finden Sie in der Erklärung. Siehe auch Beitrag Budget .

Aggregierbare Berichte

Sobald der Nutzer die Private Aggregation API aufruft, generiert der Browser aggregierte Berichte, die später vom Zusammenfassungsdienst verarbeitet werden. um rechtzeitig eine Zusammenfassung berichten. Eine Der aggregierte Bericht ist im JSON-Format formatiert und enthält eine verschlüsselte Liste von Beiträge, wobei jeder ein {aggregation key, aggregatable value}-Paar ist. Aggregierte Berichte werden mit einer zufälligen Verzögerung von bis zu einer Stunde gesendet.

Die Beiträge sind verschlüsselt und können außerhalb des Aggregationsdienstes nicht gelesen werden. Der Zusammenfassungsdienst entschlüsselt die Berichte und erstellt einen Zusammenfassungsbericht. Die Verschlüsselungsschlüssel für den Browser und den Entschlüsselungsschlüssel für die Aggregation Der Dienst wird vom Koordinator bereitgestellt, der als Key Management Service fungiert. Der Koordinator führt eine Liste binärer Hashes des Dienst-Images, um zu überprüfen, dass der Aufrufer den Entschlüsselungsschlüssel empfangen darf.

Beispiel für einen aggregierten Bericht mit debug Modus aktiviert haben:

  "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 aggregierten Berichte können auf der chrome://private-aggregation-internals Seite:

Zu Testzwecken bietet die Funktion "Ausgewählte Berichte senden" kann das Ereignis sofort an den Server melden.

Aggregierbare Berichte erfassen und zusammenfassen

Der Browser sendet die aggregierbaren Berichte an den Ursprung des Worklets. mit dem Aufruf der Private Aggregation API unter Verwendung der aufgeführten bekannten Pfad:

• 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. die die aggregierten Berichte empfängt, die von den Clients gesendet wurden.

Der Server sollte dann Batch-Berichte erstellen und den Batch an die Aggregation senden. Dienst. Erstellen Sie Batches basierend auf den in der unverschlüsselten Datei verfügbaren Informationen. Nutzlast des aggregierten Berichts aus, z. B. das Feld shared_info. Idealerweise sollten die Batches mindestens 100 Berichte enthalten.

Du kannst dich für eine tägliche oder wöchentliche Batch-Verarbeitung entscheiden. Diese Strategie ist flexibel, und Sie können Ihre Batch-Strategie für bestimmte Ereignisse ändern, mehr Volumen, z. B. Tage im Jahr, an denen mehr Impressionen erwartet werden. Batches sollten Berichte aus derselben API-Version, derselben Berichtsquelle und zum Planen des Berichts.

Zusammenfassungsdienst

Aggregationsdienst empfängt verschlüsselte, aggregierte Berichte vom Collector und erstellt eine Zusammenfassung Berichte.

Zum Entschlüsseln der Berichtsnutzlast ruft der Aggregationsdienst einen Entschlüsselungsschlüssel ab aus dem Koordinator. Der Dienst wird in einer vertrauenswürdigen Ausführungsumgebung (Trusted Execution Environment, TEE) ausgeführt. die ein gewisses Maß an Sicherheit in Bezug auf Datenintegrität, Datenvertraulichkeit und Codeintegrität. Auch wenn Sie den Dienst besitzen und betreiben, Einblick in die verarbeiteten Daten im TEE.

Zusammenfassende Berichte

Zusammenfassungsberichte können Sie die erfassten Daten mit Rauschen sehen. Auf Anfrage Zusammenfassungsberichte für einen bestimmten Schlüsselsatz.

Ein Zusammenfassungsbericht enthält Schlüssel/Wert-Paare im Stil eines JSON-Wörterbuchs. Jedes Paar enthält:

• bucket: der Zusammenfassungsschlüssel als String mit binären Zahlen Wenn die Aggregationsschlüssel „123“, der Bucket „1111011“.
• value: der Zusammenfassungswert für ein bestimmtes Messziel, summiert aus alle verfügbaren aggregierbaren Berichte mit Rauschen hinzugefügt.

Beispiel:

[
  {"bucket":` `"111001001",` `"value":` `"2558500"},
  {"bucket":` `"111101001",` `"value":` `"3256211"},
  {"bucket":` `"111101001",` `"value":` `"6536542"},
]

Rauschen und Skalierung

Um die Privatsphäre der Nutzer zu schützen, fügt der Zusammenfassungsdienst jedem Zusammenfassungswert verwendet, wenn ein zusammenfassender Bericht angefordert wird. Die Rauschwerte sind zufällig aus einer Laplace-Wahrscheinlichkeit Vertrieb. In der Zwischenzeit nicht die direkte Kontrolle darüber haben, wie Geräusche hinzugefügt werden, können Sie die Auswirkungen Rauschen in seine Messdaten einfließen lassen.

Die Rauschverteilung ist unabhängig von der Summe aller aggregierbaren Werte. Je höher die aggregierbaren Werte daher, desto geringer ist das Rauschen. wahrscheinlich haben wird.

Nehmen wir an, die Rauschverteilung hat eine Standardabweichung von 100. und bei Null zentriert. Wenn der erfasste aggregierte Berichtswert (oder „aggregierbarer Wert“) nur 200 beträgt, wäre die Standardabweichung des Rauschens 50% des aggregierten Werts. Wenn der aggregierte Wert jedoch 20.000 beträgt, ist der Wert würde die Standardabweichung des Rauschens nur 0,5% des aggregierten Werts betragen. Die Funktion einen aggregierten Wert von 20.000 hätte ein viel höheres Signal-Rausch-Verhältnis.

Daher kann das Multiplizieren Ihres aggregierbaren Werts mit einem Skalierungsfaktor Geräusche zu reduzieren. Der Skalierungsfaktor gibt an, wie stark ein bestimmter aggregierten Wert.

Wenn Sie die Werte durch Auswählen eines größeren Skalierungsfaktors hochskalieren, verringert sich die relative Lärm. Dies führt jedoch auch dazu, dass die Summe aller Beiträge aller Gruppen um das Beitragsbudget-Limit schneller zu erreichen. Skalieren Sie die Werte um Konstante für einen kleineren Skalierungsfaktor erhöht das relative Rauschen, verringert aber das Risiko, das Budgetlimit zu erreichen.

Um einen geeigneten Skalierungsfaktor zu berechnen, teilen Sie das Beitragsbudget durch die maximale Summe aggregierbarer Werte über alle Schlüssel hinweg.

Siehe Beitragsbudget Dokumentation um mehr zu erfahren.

Interagieren und Feedback geben

Die Private Aggregation API wird derzeit diskutiert und unterliegt Änderungen in in die Zukunft zu führen. Wir würden uns freuen, wenn Sie diese API ausprobieren und uns Feedback geben.

• GitHub: Lesen Sie den Erklärung, Fragen stellen und an Diskussion. * Support für Entwickler: Hier können Sie Fragen stellen und sich an Diskussionen im Privacy Sandbox-Entwicklersupport Repository. * Der Shared Storage API beitreten Gruppe und die Protected Audience API Gruppe finden Sie aktuelle Ankündigungen zur privaten Aggregation.