Grundlagen der Private Aggregation API

Schlüsselkonzepte der Private Aggregation API

An wen richtet sich dieses Dokument?

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 ein Entwickler sind, der ein Berichtssystem für websiteübergreifende Analysen erstellt.
  • Für Marketingexperten, Data Scientist oder andere Zusammenfassungsberichte , können Sie mit diesen Mechanismen Entscheidungen zum Abrufen eines optimierten Zusammenfassungsberichts.

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 als Bucket bezeichnet) ist eine vordefinierte Sammlung von Datenpunkten. Sie möchten beispielsweise einen Bucket mit Standortdaten erfassen, in dem der Browser den Landesnamen meldet. 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, ist France eine Dimension im Aggregationsschlüssel und der viewCount von 1 ist der aggregierbare Wert.
  • Zusammenführbare Berichte werden in einem Browser erstellt und verschlüsselt. Für die Private Aggregation API, enthält Daten zu einem einzelnen Ereignis.
  • Der Aggregationsdienst verarbeitet Daten aus aggregierbaren Berichten, um einen Zusammenfassungsbericht 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 mit ihr kommunizieren.

Workflow für die Private Aggregation

Wenn Sie die Private Aggregation API mit einem Aggregationsschlüssel und einem aggregierbaren Wert aufrufen, generiert der Browser einen aggregierbaren Bericht. Die Berichte werden an Ihren Server gesendet, auf dem sie in Batches zusammengefasst werden. Die Batchberichte werden später vom Aggregationsdienst verarbeitet und ein zusammenfassender Bericht generiert.

Die Daten fließen vom Client zum Aggregator und dann zum Aggregationsdienst, um einen Zusammenfassungsbericht zu erstellen.
  1. Wenn Sie die Private Aggregation API aufrufen, generiert und sendet der Client (Browser) den aggregierbaren Bericht zur Erfassung an Ihren Server.
  2. Ihr Server sammelt die Berichte von den Clients und sendet sie in Batches an den Aggregationsdienst.
  3. Sobald Sie genügend Berichte erfasst haben, werden sie in einem Batch an den Aggregationsdienst gesendet, der in einer vertrauenswürdigen Ausführungsumgebung ausgeführt wird, um einen Zusammenfassungsbericht zu generieren.

Der in diesem Abschnitt beschriebene Workflow ähnelt der Attribution Reporting API. Die Attribution In der Berichterstellung werden die über ein Impressionsereignis und eine Conversion erfassten Daten verknüpft. die zu unterschiedlichen Zeiten stattfinden. Bei der privaten Aggregation wird ein einzelnes websiteübergreifendes Ereignis erfasst.

Aggregationsschlüssel

Ein Aggregationsschlüssel (kurz „Schlüssel“) steht für den Bucket, in dem die aggregierbaren Werte erfasst werden. Mindestens eine Dimension kann in den Schlüssel codiert werden. Eine Dimension stellt einen Aspekt dar, mit dem Sie Informationen über die Altersgruppe der Nutzer oder die Anzahl an Impressionen einer Anzeige Kampagne.

Angenommen, Sie haben ein Widget, das auf mehreren Websites eingebettet ist, und möchten das Land der Nutzer analysieren, die Ihr Widget gesehen haben. Sie möchten beispielsweise wissen, wie viele der Nutzer, die mein Widget gesehen haben, aus Land X stammen. Wenn Sie Berichte zu dieser Frage erstellen möchten, können Sie einen Aggregationsschlüssel einrichten, der zwei Dimensionen codiert: „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 vier Ziffern lang sein, z. B. 1234. Jedem Land wird in alphabetischer Reihenfolge eine Zahl zugewiesen, z. B. 1 für Afghanistan, 61 für Frankreich und 195 für Simbabwe. Der aggregierte Schlüssel wäre daher 7 Ziffern lang, wobei die ersten 4 Ziffern Zeichen sind für WidgetID reserviert; die letzten 3 Zeichen sind für CountryID reserviert.

Angenommen, der Schlüssel steht für die Anzahl der Nutzer aus Frankreich (Landes-ID 061), die die Widget-ID 3276 gesehen haben. Der Aggregationsschlüssel ist 3276061.

Aggregationsschlüssel
Widget-ID Landes-ID
3276 061

Der Aggregationsschlüssel kann auch mit einem Hash-Mechanismus wie SHA-256 generiert werden. So kann der String {"WidgetId":3276,"CountryID":67} beispielsweise 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 finden Sie in SubtleCrypto.digest() an MDN

Im folgenden Beispiel wird beschrieben, wie Sie einen Bucket-Schlüssel aus einem Hashwert 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

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

Kehren wir nun zur vorherigen Beispielfrage zurück: „Wie viele der Nutzenden die mein Widget gesehen haben, aus Frankreich kommen?“ Die Antwort auf diese Frage sieht 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 das Signal-Rausch-Verhältnis zu verbessern.

Beitragsbudget

Jeder Aufruf der Private Aggregation API wird als Beitrag bezeichnet. Zum Schutz der Privatsphäre der Nutzer ist die Anzahl der Beiträge, die von einer einzelnen Person gesammelt werden können, begrenzt.

Die Summe aller aggregierbaren Werte für alle Aggregationsschlüssel muss unter dem Beitragsbudget liegen. Das Budget gilt pro Worklet, pro Ursprung und pro Tag. Für Protected Audience API- und Shared Storage-Worklets ist es jeweils separat. Ein rollierender Für den Tag wird ein Zeitfenster von etwa den letzten 24 Stunden verwendet. Wenn durch einen neuen aggregierten Bericht das Budget überschritten würde, wird der Bericht nicht erstellt.

Das Beitragsbudget wird durch den Parameter L1 dargestellt und auf 216 (65.536) pro zehn Minuten pro Tag mit einem Backstop von 220 festgelegt.

(1.048.576). Weitere Informationen zu diesen Parametern finden Sie in diesem Hilfeartikel.

Der Wert des Beitragsbudgets ist willkürlich, aber der Rauschenpegel wird daran angepasst. 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 .

Beitragslimit pro Bericht

Je nach Anrufer kann das Beitragslimit variieren. Derzeit sind für Berichte, die für Shared Storage API-Aufrufer generiert werden, maximal 20 Beiträge pro Bericht zulässig. Andererseits gilt für Protected Audience API-Aufrufer eine Obergrenze von 100 Beiträgen pro Bericht. Diese Limits wurden festgelegt, um die Anzahl der Beiträge, die eingebettet werden können, mit der Größe der Nutzlast in Einklang zu bringen.

Bei gemeinsamem Speicher: Beiträge, die innerhalb eines einzelnen run()- oder selectURL()-Elements geleistet wurden in einem Bericht zusammengefasst. Bei Protected Audience werden Beiträge, die von einem einzelnen Ursprung innerhalb einer Auktion stammen, in einem Batch zusammengefasst.

Beiträge mit Abstand

Beiträge werden zusätzlich mit einer Padding-Funktion geändert. Durch das Ausfüllen der Nutzlast werden Informationen zur tatsächlichen Anzahl der Beiträge geschützt, die in den aggregierbaren Bericht eingebettet sind. Durch das Padding wird die Nutzlast mit null-Beiträgen (d. h. mit dem Wert 0) auf eine feste Länge erweitert.

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. Ein aggregierbarer Bericht ist im JSON-Format und enthält eine verschlüsselte Liste von Beiträgen, die jeweils ein {aggregation key, aggregatable value}-Paar sind. 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 Aggregationsdiensts nicht gelesen werden. Der Zusammenfassungsdienst entschlüsselt die Berichte und erstellt einen Zusammenfassungsbericht. Der Verschlüsselungsschlüssel für den Browser und der Entschlüsselungsschlüssel für den Aggregationsdienst werden vom Koordinator ausgegeben, der als Schlüsselverwaltungsdienst 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:

Screenshot der Seite „Private Aggregation API internals“

Zum Testen können Sie über die Schaltfläche „Ausgewählte Berichte senden“ den Bericht sofort an den Server senden.

Aggregierbare Berichte erfassen und im Batch zusammenführen

Der Browser sendet die aggregierbaren Berichte an den Ursprung des Worklets, das den Aufruf der Private Aggregation API enthält, und verwendet dabei den aufgeführten bekannten Pfad:

  • Für Shared Storage: /.well-known/private-aggregation/report-shared-storage
  • Für Protected Audience gilt Folgendes: /.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 Informationen in der unverschlüsselten Nutzlast des aggregierbaren Berichts, z. B. im Feld shared_info. Idealerweise sollten die Batches mindestens 100 Berichte enthalten.

Sie können die Batch-Dateien täglich oder wöchentlich erstellen. 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 mit derselben API-Version, demselben Berichts-Ursprung und derselben geplanten Berichtszeit enthalten.

Zusammenfassungsdienst

Der Dienst wird in einem TEE ausgeführt, entschlüsselt die aggregierbaren Berichte und fügt um den abschließenden Bericht „Zusammenfassung“ zu erstellen.

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 für Datenintegrität, Datenvertraulichkeit und Codeintegrität sorgt. Auch wenn Sie den Dienst besitzen und betreiben, Einblick in die verarbeiteten Daten im TEE.

Zusammenfassende Berichte

In Zusammenfassungsberichten sehen Sie die von Ihnen erfassten Daten mit hinzugefügtem Rauschen. Sie können Zusammenfassungsberichte für eine bestimmte Gruppe von Schlüsseln anfordern.

Ein Zusammenfassungsbericht enthält eine Reihe von Schlüssel/Wert-Paaren im JSON-Wörterbuchstil. Jedes Paar enthält Folgendes:

  • bucket: der Aggregationsschlüssel als String mit Binärzahlen. Wenn der verwendete Aggregationsschlüssel „123“ lautet, ist der Bucket „1111011“.
  • value: Der zusammengefasste Wert für ein bestimmtes Analyseziel, der aus allen verfügbaren aggregierbaren Berichten mit hinzugefügtem Rauschen berechnet wird.

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 werden zufällig aus einer Laplace-Wahrscheinlichkeitsverteilung gezogen. Sie können zwar nicht direkt steuern, wie Rauschen hinzugefügt wird, aber Sie können die Auswirkungen von Rauschen auf die Messdaten beeinflussen.

Die Verteilung des Rauschens ist unabhängig von der Summe aller aggregierbaren Werte. Je höher die aggregierten Werte also sind, desto geringer ist die Wahrscheinlichkeit, dass sich das Rauschen auswirkt.

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 aggregierbare Wert jedoch 20.000 beträgt, entspricht die Standardabweichung des Rauschens nur 0,5 % des aggregierten Werts. Der aggregierbare Wert von 20.000 hat also 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, um wie viel Sie einen bestimmten aggregierbaren Wert skalieren möchten.

Der Rauschenpegel ist unabhängig vom aggregierten Wert konstant.

Wenn Sie die Werte durch Auswählen eines größeren Skalierungsfaktors hochskalieren, verringert sich die relative Lärm. Dadurch wird jedoch auch die Summe aller Beiträge in allen Kategorien schneller auf das Beitragsbudgetlimit angerechnet. Wenn Sie die Werte durch Auswahl eines kleineren Skalierungsfaktors verringern, erhöht sich der relative Rauschanteil, aber das Risiko, das Budgetlimit zu erreichen, sinkt.

Skalieren Sie den aggregierbaren Wert auf das Beitragsbudget.

Um einen geeigneten Skalierungsfaktor zu berechnen, teilen Sie das Beitragsbudget durch die maximale Summe der aggregierbaren Werte für alle Schlüssel.

Weitere Informationen finden Sie in der Dokumentation zum Beitragsbudget.

Interagieren und Feedback geben

Die Private Aggregation API befindet sich in der Entwicklungsphase und kann sich in Zukunft ändern. Wenn Sie diese API ausprobieren und Feedback haben, würden wir uns sehr darüber freuen.