Kurzanleitung zur Implementierung von freigegebenem Speicher und privater Aggregation

Dieses Dokument ist eine Kurzanleitung für die Verwendung von freigegebenem Speicher und privater Aggregation. Sie sollten die beiden APIs kennen, da die Werte im freigegebenen Speicher gespeichert werden und die aggregierten Berichte über die private Aggregation erstellt werden.

Zielgruppe:Anbieter von Anzeigentechnologien und Analyselösungen.

Zur Demo

Live-Demo ausprobieren Folgen Sie der Anleitung in der Demoanleitung, um die Privacy Sandbox APIs zu aktivieren. Mit den Chrome-Entwicklertools können Sie die Ergebnisse verschiedener Anwendungsfälle visualisieren. In der Demo verfügbare Anwendungsfälle:

• Private Aggregation
  • Unique Reach-Messung
  • Demografische Analyse
  • Frequenzmessung von K+
• Allgemeine Verwendung
  • Mouseover-Ereignis in eingezäunten Frames messen
  • Navigation der obersten Ebene
  • Festlegen, wo Dritte Daten schreiben dürfen

Freigegebenen Speicher aufrufen

Mit den Chrome-Entwicklertools können Sie sehen, was im freigegebenen Speicher gespeichert ist. Gespeicherte Daten finden Sie in Application -> Shared Storage.

Berichte zur privaten Aggregation aufrufen

Rufen Sie chrome://private-aggregation-internals auf, um die gesendeten aggregierten Berichte zu sehen. Wenn der Debug-Modus aktiviert ist, wird ein Bericht sofort (ohne Verzögerung) an [[YOUR_ORIGIN]]/.well-known/private-aggregation/debug/report-shared-storage und der verzögerte Bericht an [[YOUR_ORIGIN]]/.well-known/private-aggregation/report-shared-storage gesendet.

Folgen Sie der Anleitung im Abschnitt Fehlerbehebung, um die Fehlerbehebung zu aktivieren.

Shared Storage API

Um websiteübergreifendes Tracking zu verhindern, haben Browser damit begonnen, alle Arten von Speicher zu partitionieren, einschließlich des lokalen Speichers, Cookies usw. Es gibt jedoch Anwendungsfälle, in denen nicht partitionierter Speicher erforderlich ist. Die Shared Storage API bietet unbegrenzten Schreibzugriff auf verschiedene Top-Level-Websites mit datenschutzfreundlichem Lesezugriff.

Freigegebener Speicher ist auf den Kontextursprung beschränkt (den Aufrufer von sharedStorage).

Freigegebener Speicher hat ein Kapazitätslimit pro Ursprung, wobei jeder Eintrag auf eine maximale Anzahl von Zeichen begrenzt ist. Ist das Limit erreicht, werden keine weiteren Eingaben gespeichert. Die Limits für die Datenspeicherung sind in der Erläuterung zu freigegebenem Speicher erläutert.

Freigegebenen Speicher aufrufen

Anzeigentechnologie-Anbieter können JavaScript oder Antwortheader verwenden, um Daten in freigegebenen Speicher zu schreiben. Das Lesen aus dem freigegebenen Speicher erfolgt nur in einer isolierten JavaScript-Umgebung, die als Worklet bezeichnet wird.

Mit einem Worklet können Sie bestimmte JavaScript-Funktionen ausführen und Informationen an den Anforderer zurückgeben. Innerhalb eines Worklets können Sie JavaScript ausführen, aber nicht mit der externen Seite interagieren oder kommunizieren.

Worklets werden zum Speichern und Extrahieren von Daten mit der Shared Storage API verwendet.

• JavaScript verwenden Anzeigentechnologien können bestimmte Funktionen für freigegebenen Speicher ausführen, wie das Festlegen, Anfügen und Löschen von Werten außerhalb eines JavaScript-Worklets. Funktionen wie das Lesen des freigegebenen Speichers und das Ausführen einer privaten Aggregation müssen jedoch über ein JavaScript-Worklet ausgeführt werden. Methoden, die außerhalb eines JavaScript-Worklets verwendet werden können, finden Sie unter Vorgeschlagene API-Oberfläche – außerhalb des Worklets.

  Methoden, die während eines Vorgangs im Worklet verwendet werden, finden Sie unter Vorgeschlagene API-Oberfläche – Im Worklet.

• Antwortheader verwenden

  Diese Funktion ist seit M119 verfügbar.

  Ähnlich wie bei JavaScript können nur bestimmte Funktionen wie das Festlegen, Anfügen und Löschen von Werten im freigegebenen Speicher mithilfe von Antwortheadern ausgeführt werden. Wenn Sie freigegebenen Speicher in einem Antwortheader verwenden möchten, muss Shared-Storage-Writable: ?1 im Anfrageheader enthalten sein.

  Führen Sie je nach ausgewählter Methode den folgenden Code aus, um eine Anfrage vom Client zu initiieren:

  • fetch() verwenden

    fetch("https://a.example/path/for/updates", {sharedStorageWritable: true});
    

  • iframe- oder img-Tag verwenden

    <iframe src="https://a.example/path/for/updates" sharedstoragewritable></iframe>
    

  • IDL-Attribut mit einem iframe- oder img-Tag verwenden

    let iframe = document.getElementById("my-iframe");
    iframe.sharedStorageWritable = true;
    iframe.src = "https://a.example/path/for/updates";
    

Weitere Informationen finden Sie unter Freigegebener Speicher: Antwortheader.

In freigegebenen Speicher schreiben

Rufen Sie sharedStorage.set() innerhalb oder außerhalb eines JavaScript-Worklets auf, um in freigegebenen Speicher zu schreiben. Bei einem Aufruf von außerhalb des Worklets werden die Daten in den Ursprung des Browsing-Kontexts geschrieben, aus dem der Aufruf stammt. Bei Aufruf aus dem Worklet werden die Daten in den Ursprung des Browserkontexts geschrieben, der das Worklet geladen hat. Die festgelegten Schlüssel laufen 30 Tage nach der letzten Aktualisierung ab.

Das Feld ignoreIfPresent ist optional. Falls vorhanden und auf true gesetzt, wird der Schlüssel nicht aktualisiert, falls er bereits vorhanden ist. Die Ablaufzeit des Schlüssels wird nach dem set()-Aufruf auf 30 Tage verlängert, auch wenn der Schlüssel nicht aktualisiert wird.

Wenn beim selben Seitenaufbau mehrmals auf den freigegebenen Speicher zugegriffen wird, wird der Wert für den Schlüssel überschrieben. Wenn der Schlüssel den vorherigen Wert beibehalten muss, empfiehlt es sich, sharedStorage.append() zu verwenden.

• JavaScript verwenden

  Außerhalb des Worklets:

  window.sharedStorage.set('myKey', 'myValue1', { ignoreIfPresent: true });
  // Shared Storage: {'myKey': 'myValue1'}
  window.sharedStorage.set('myKey', 'myValue2', { ignoreIfPresent: true });
  // Shared Storage: {'myKey': 'myValue1'}
  window.sharedStorage.set('myKey', 'myValue2', { ignoreIfPresent: false });
  // Shared Storage: {'myKey': 'myValue2'}
  

  Ähnlich verhält es sich im Worklet:

  sharedStorage.set('myKey', 'myValue1', { ignoreIfPresent: true });
  

• Antwortheader verwenden

  Sie können auch mithilfe von Antwortheadern in freigegebenen Speicher schreiben. Verwenden Sie dazu Shared-Storage-Write zusammen mit den folgenden Befehlen im Antwortheader:

  Shared-Storage-Write : set;key="myKey";value="myValue";ignore_if_present
  

  Shared-Storage-Write : set;key="myKey";value="myValue";ignore_if_present=?0
  

  Mehrere Elemente können durch Kommas getrennt werden und set, append, delete und clear kombinieren.

  Shared-Storage-Write : 
  set;key="hello";value="world";ignore_if_present, set;key="good";value="bye"
  

Wert anhängen

Mit der Anfügemethode können Sie einen Wert an einen vorhandenen Schlüssel anhängen. Wenn der Schlüssel nicht vorhanden ist, wird durch Aufrufen von append() der Schlüssel erstellt und der Wert festgelegt. Dies kann mithilfe von JavaScript oder Antwortheadern erreicht werden.

• JavaScript verwenden

  Verwenden Sie zum Aktualisieren der Werte vorhandener Schlüssel sharedStorage.append() innerhalb oder außerhalb des Worklets.

  window.sharedStorage.append('myKey', 'myValue1');
  // Shared Storage: {'myKey': 'myValue1'}
  window.sharedStorage.append('myKey', 'myValue2');
  // Shared Storage: {'myKey': 'myValue1myValue2'}
  window.sharedStorage.append('anotherKey', 'hello');
  // Shared Storage: {'myKey': 'myValue1myValue2', 'anotherKey': 'hello'}
  

  So fügen Sie etwas in das Worklet an:

  sharedStorage.append('myKey', 'myValue1');
  

• Antwortheader verwenden

  Ähnlich wie beim Festlegen eines Werts im freigegebenen Speicher können Sie Shared-Storage-Write im Antwortheader verwenden, um das Schlüssel/Wert-Paar zu übergeben.

  Shared-Storage-Write : append;key="myKey";value="myValue2"
  

Aus freigegebenem Speicher lesen

Sie können Daten aus freigegebenem Speicher nur innerhalb eines Worklets lesen.

await sharedStorage.get('mykey');

Der Ursprung des Browserkontexts, aus dem das Worklet-Modul geladen wurde, bestimmt, wessen freigegebener Speicher gelesen wird.

Löschen aus freigegebenem Speicher

Sie können Löschvorgänge aus dem freigegebenen Speicher mit JavaScript innerhalb oder außerhalb des Worklets oder mithilfe von Antwortheadern mit delete() ausführen. Wenn Sie alle Schlüssel auf einmal löschen möchten, können Sie clear() in beiden verwenden.

• JavaScript verwenden

  So löschen Sie von außerhalb des Worklets aus dem freigegebenen Speicher:

  window.sharedStorage.delete('myKey');
  

  So löschen Sie innerhalb des Worklets aus dem freigegebenen Speicher:

  sharedStorage.delete('myKey');
  

  So löschen Sie alle Schlüssel von außerhalb des Worklet auf einmal:

  window.sharedStorage.clear();
  

  So löschen Sie alle Schlüssel auf einmal aus dem Worklet:

  sharedStorage.clear();
  

• Antwortheader verwenden

  Wenn Sie Werte mithilfe von Antwortheadern löschen möchten, können Sie auch Shared-Storage-Write im Antwortheader verwenden, um den zu löschenden Schlüssel zu übergeben.

  delete;key="myKey"
  

  So löschen Sie alle Schlüssel mit Antwortheadern:

  clear;
  

Kontextwechsel

Daten im freigegebenen Speicher werden in die Quelle (z. B. https://example.adtech.com) des Browserkontexts geschrieben, aus dem der Aufruf stammt.

Wenn du den Drittanbietercode mit einem <script>-Tag lädst, wird der Code im Browser-Kontext des Einbettungsanbieters ausgeführt. Wenn der Drittanbietercode sharedStorage.set() aufruft, werden die Daten daher in den freigegebenen Speicher des Einbettungsgeräts geschrieben. Wenn Sie den Drittanbietercode innerhalb eines iFrames laden, erhält der Code einen neuen Browserkontext und sein Ursprung ist der Ursprung des iFrame. Daher speichert der sharedStorage.set()-Aufruf aus dem iFrame die Daten im freigegebenen Speicher des iFrame-Ursprungs.

Erstanbieterkontext

Wenn auf einer eigenen Seite Drittanbieter-JavaScript-Code eingebettet ist, der sharedStorage.set() oder sharedStorage.delete() aufruft, wird das Schlüssel/Wert-Paar im Erstanbieter-Kontext gespeichert.

Drittanbieterkontext

Das Schlüssel/Wert-Paar kann im Kontext von Anzeigentechnologien oder Drittanbietern gespeichert werden, indem ein iFrame erstellt und set() oder delete() im JavaScript-Code innerhalb des iFrames aufgerufen wird.

Private Aggregation API

Zum Messen aggregierbarer Daten, die im freigegebenen Speicher gespeichert sind, können Sie die Private Aggregation API verwenden.

Rufen Sie zum Erstellen eines Berichts contributeToHistogram() in einem Worklet mit einem Bucket und Wert auf. Der Bucket wird durch eine vorzeichenlose 128-Bit-Ganzzahl dargestellt, die als BigInt an die Funktion übergeben werden muss. Der Wert ist eine positive Ganzzahl.

Aus Datenschutzgründen wird die Nutzlast des Berichts, die den Bucket und den Wert enthält, bei der Übertragung verschlüsselt und kann nur mit dem Aggregationsdienst entschlüsselt und aggregiert werden.

Der Browser schränkt auch die Beiträge ein, die eine Website zu einer Ausgabeabfrage beitragen kann. Das Beitragsbudget begrenzt die Summe aller Berichte einer einzelnen Website für einen bestimmten Browser in einem bestimmten Zeitraum und für alle Buckets. Wird das aktuelle Budget überschritten, wird kein Bericht erstellt.

privateAggregation.contributeToHistogram({
  bucket: BigInt(myBucket),
  value: parseInt(myBucketValue)
});

Freigegebenen Speicher und private Aggregation ausführen

Laden Sie das Worklet-Modul im iFrame der Anzeige, indem Sie addModule() aufrufen. Rufen Sie sharedStorage.run() auf, um die Methode auszuführen, die in der Worklet-Datei sharedStorageWorklet.js im selben Anzeigen-iFrame-JavaScript registriert ist.

await window.sharedStorage.worklet.addModule('modules/sharedStorageWorklet.js');
await window.sharedStorage.worklet.run('shared-storage-report', {
  data: { campaignId: '1234' },
});

Im Worklet-Skript müssen Sie eine Klasse mit der asynchronen run-Methode erstellen. Und register diese Klasse so, dass sie im iFrame der Anzeige ausgeführt wird. In sharedStorageWorklet.js:

class SharedStorageReportOperation {
  async run(data) {
    // Other code goes here.
    bucket = getBucket(...);
    value = getValue(...);
    privateAggregation.contributeToHistogram({
      bucket: bucket,
      value: value
    });
  }
}
register('shared-storage-report',
  SharedStorageReportOperation);

Debugging

Wenn Sie die Fehlerbehebung aktivieren möchten, rufen Sie die JavaScript-Methode enableDebugMode() im selben Kontext auf, in dem der freigegebene Speicher und die private Aggregation verwendet werden. Sie wird auf zukünftige Berichte im selben Kontext angewendet.

privateAggregation.enableDebugMode();

Um die Berichte mit den Kontexten zu verknüpfen, die sie ausgelöst haben, können Sie einen vorzeichenlosen 64-Bit-Debug-Schlüssel für die Ganzzahl festlegen, der an den JavaScript-Aufruf übergeben wird. debugKey ist BigInt.

privateAggregation.enableDebugMode({debugKey: 1234});

Debugging von freigegebenem Speicher

Der freigegebene Speicher gibt eine allgemeine Fehlermeldung zurück:

Promise is rejected without and explicit error message

Sie können Fehler im freigegebenen Speicher beheben, indem Sie die Aufrufe in try-catch-Blöcke umschließen.

try {
  privateAggregation.contributeToHistogram({bucket, value});
} catch (e){
  console.log(e);
}

Private Aggregation debuggen

Berichte werden an /.well-known/private-aggregation/report-shared-storage und /.well-known/private-aggregation/debug/report-shared-storage gesendet. Debugging-Berichte erhalten eine Nutzlast ähnlich der folgenden JSON. Diese Nutzlast definiert das Feld api als "shared-storage".

{
   "aggregation_coordinator_identifier": "aws-cloud",
   "aggregation_service_payloads": [ {
      "debug_cleartext_payload": "omRkYXRhgaJldmFsdWVEAAAAgGZidWNrZXRQAAAAAAAAAAAAAAEfV32BFWlvcGVyYXRpb25paGlzdG9ncmFt",
      "key_id": "9bc4afa7-2934-4779-99ff-999d91b137ec",
      "payload": "bqOFO/cHCdwefU2W4FjMYRMSLoGHPWwZbgVF4aa/ji2YtwFz+jb6v2XCwQUdmvYcZSRPKosGRpKELJ0xAFv+VBYvCiv3FXP6jjAHQD+XAJUz17A39aXijk6JnEAu86+DfTSbXYn1fWhGzIG9xH/Y"
   } ],
   "debug_key": "1234",
   "shared_info": "{\"api\":\"shared-storage\",\"debug_mode\":\"enabled\",\"report_id\":\"93f86829-cdf7-4ecd-b16d-4e415a3ee063\",\"reporting_origin\":\"https://small-free-wealth.glitch.me\",\"scheduled_report_time\":\"1681319668\",\"version\":\"0.1\"}"
}

Fehler im Klartextnutzlast beheben

debug_cleartext_payload ist Base64-CBOR-codiert. Sie können den Bucket und den Wert mit dem Decoder aufrufen oder den JavaScript-Code aus dem Decoder für freigegebenen Speicher verwenden.

Nächste Schritte

Auf den folgenden Seiten werden wichtige Aspekte der APIs für freigegebenen Speicher und Private Aggregation erläutert.

• Einführung in freigegebenen Speicher (Entwickler-Chrome)
• Anwendungsfälle für freigegebenen Speicher (Entwickler-Chrome)
• Einführung in die private Aggregation (Entwickler-Chrome)
• Erklärung zum freigegebenen Speicher (GitHub)
• Erläuterung der privaten Aggregation (GitHub)
• Demo für freigegebenen Speicher und private Aggregation

Sobald Sie mit den APIs vertraut sind, können Sie mit dem Erfassen der Berichte beginnen. Diese werden als POST-Anfrage an die folgenden Endpunkte als JSON im Anfragetext gesendet.

• Fehlerbehebungsberichte – context-origin/.well-known/private-aggregation/debug/report-shared-storage
• Berichte – context-origin/.well-known/private-aggregation/report-shared-storage

Nachdem die Berichte erfasst wurden, können Sie sie mit dem lokalen Testtool testen oder die vertrauenswürdige Ausführungsumgebung für den Aggregationsdienst einrichten, um die zusammengefassten Berichte zu erhalten.

Feedback geben

Du kannst uns Feedback zu den APIs und zur Dokumentation auf GitHub geben.

• Gemeinsam genutzter Speicher
• Private Aggregation