Kurzanleitung zur Implementierung von freigegebenem Speicher und privater Aggregation

In diesem Dokument finden Sie eine Kurzanleitung für die Verwendung von freigegebenem Speicher und privater Aggregation. Sie müssen beide APIs kennen, da die Werte im gemeinsamen Speicher gespeichert und die aggregierbaren Berichte mit der privaten Aggregation erstellt werden.

Zielgruppe:Anbieter von Anzeigentechnologien und Analysetools

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 Speicherplatz erforderlich ist. Die Shared Storage API bietet unbegrenzten Schreibzugriff auf verschiedene Websites der obersten Ebene mit datenschutzfreundlichem Lesezugriff.

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

Der gemeinsame Speicherplatz hat eine Kapazitätsbeschränkung pro Ursprung. Jeder Eintrag ist auf eine maximale Anzahl von Zeichen beschränkt. Ist das Limit erreicht, werden keine weiteren Eingaben gespeichert. Die Beschränkungen für die Datenspeicherung werden im Hilfeartikel Freigegebener Speicher erläutert.

Shared Storage aufrufen

Anbieter von Anzeigentechnologien können mit JavaScript oder Antwort-Headern in den freigegebenen Speicher schreiben. Das Lesen aus Shared Storage 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.

• Mit JavaScript können Anbieter von Anzeigentechnologien bestimmte Funktionen des gemeinsamen Speichers ausführen, z. B. Werte außerhalb eines JavaScript-Worklets festlegen, anhängen und löschen. Funktionen wie das Lesen des freigegebenen Speichers und die Durchführung 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 im Worklet während eines Vorgangs verwendet werden, finden Sie unter Vorgeschlagene API-Oberfläche – Im Worklet.

• Antwortheader verwenden

  Ähnlich wie bei JavaScript können mit Antwortheadern nur bestimmte Funktionen wie das Festlegen, Anhängen und Löschen von Werten im freigegebenen Speicher ausgeführt werden. Damit Sie mit freigegebenem Speicher in einem Antwortheader arbeiten können, muss Shared-Storage-Writable: ?1 im Anfrageheader enthalten sein.

  Führe je nach gewählter Methode den folgenden Code aus, um eine Anfrage vom Client zu starten:

  • 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.

Schreiben in Shared Storage

Wenn Sie in Shared Storage schreiben möchten, rufen Sie sharedStorage.set() innerhalb oder außerhalb eines JavaScript-Worklets auf. Wenn der Aufruf von außerhalb des Worklets erfolgt, werden die Daten an den Ursprung des Browser-Kontexts geschrieben, von dem aus der Aufruf erfolgt ist. Wenn die Funktion von innerhalb des Worklets aufgerufen wird, werden die Daten an den Ursprung des Browser-Kontexts geschrieben, in dem das Worklet geladen wurde. Die festgelegten Schlüssel haben ein Ablaufdatum von 30 Tagen nach der letzten Aktualisierung.

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

Wenn beim Laden derselben Seite mehrmals mit demselben Schlüssel auf den freigegebenen Speicher zugegriffen wird, wird der Wert für den Schlüssel überschrieben. Verwenden Sie sharedStorage.append(), wenn der Schlüssel den vorherigen Wert beibehalten soll.

• 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'}
  

  Im Worklet gilt Folgendes:

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

• Antwortheader verwenden

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

  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 und set, append, delete und clear kombiniert werden.

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

Wert anhängen

Mit der append-Methode können Sie einem vorhandenen Schlüssel einen Wert anhängen. Wenn der Schlüssel nicht vorhanden ist, wird er durch Aufrufen von append() erstellt und der Wert festgelegt. Dies kann mit JavaScript oder Antwortheadern erfolgen.

• JavaScript verwenden

  Wenn Sie die Werte vorhandener Schlüssel aktualisieren möchten, verwenden Sie sharedStorage.append() entweder 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 Inhalte in das Worklet ein:

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

• Antwortheader verwenden

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

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

Lesen aus freigegebenem Speicher

Sie können nur innerhalb eines Worklets aus Shared Storage lesen.

await sharedStorage.get('mykey');

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

Daten aus freigegebenem Speicher löschen

Sie können Elemente aus dem freigegebenen Speicher mit JavaScript entweder innerhalb oder außerhalb des Worklets löschen oder Antwort-Header mit delete() verwenden. Wenn Sie alle Schlüssel auf einmal löschen möchten, verwenden Sie clear() für einen der beiden Schlüssel.

• JavaScript verwenden

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

  window.sharedStorage.delete('myKey');
  

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

  sharedStorage.delete('myKey');
  

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

  window.sharedStorage.clear();
  

  So löschen Sie alle Schlüssel gleichzeitig im Worklet:

  sharedStorage.clear();
  

• Antwortheader verwenden

  Zum Löschen von Werten mithilfe von Antwortheadern 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 aus dem freigegebenen Speicher werden an den Ursprung (z. B. https://beispiel.adtech.com) des Browser-Kontexts geschrieben, von dem aus der Aufruf stammt.

Wenn du den Code des Drittanbieters über ein <script>-Tag lädst, wird er im Browserkontext des Einbettungspartners ausgeführt. Wenn der Drittanbietercode also sharedStorage.set() aufruft, werden die Daten in den freigegebenen Speicher des Embedders geschrieben. Wenn Sie den Code des Drittanbieters in einem iFrame laden, erhält der Code einen neuen Browserkontext und sein Ursprung ist der Ursprung des iFrames. Daher speichert der sharedStorage.set()-Aufruf aus dem iFrame die Daten im freigegebenen Speicher des iFrame-Ursprungs.

Kontext mit selbst erhobenen Daten

Wenn auf einer selbst gehosteten Seite eingebetteter JavaScript-Code von Drittanbietern vorhanden ist, der sharedStorage.set() oder sharedStorage.delete() aufruft, wird das Schlüssel/Wert-Paar im selbst gehosteten Kontext gespeichert.

Drittanbieterkontext

Das Schlüssel/Wert-Paar kann im Kontext der Anzeigentechnologie oder des Drittanbieters gespeichert werden. Dazu müssen Sie einen iFrame erstellen und set() oder delete() im JavaScript-Code innerhalb des iFrames aufrufen.

Private Aggregation API

Wenn Sie aggregierbare Daten messen möchten, die im freigegebenen Speicher gespeichert sind, können Sie die Private Aggregation API verwenden.

Wenn Sie einen Bericht erstellen möchten, rufen Sie contributeToHistogram() in einem Worklet mit einem Bucket und einem 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, während der Übertragung verschlüsselt. Sie kann nur mit dem Aggregationsdienst entschlüsselt und aggregiert werden.

Außerdem wird der Browser die Beiträge einer Website zu einer Ausgabeabfrage einschränken. Das Beitragsbudget begrenzt die Gesamtzahl aller Berichte von einer einzelnen Website für einen bestimmten Browser in einem bestimmten Zeitraum über alle Buckets hinweg. Wenn das aktuelle Budget überschritten wird, wird kein Bericht generiert.

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

Gemeinsamen Speicher und private Aggregation ausführen

Sie müssen ein Worklet erstellen, um auf Daten aus freigegebenem Speicher zuzugreifen. Rufen Sie dazu createWorklet() mit der URL des Worklets auf. Bei der Verwendung von freigegebenem Speicher mit createWorklet() ist der Ursprung der Datenpartition standardmäßig der Ursprung des Browserkontexts, nicht der Ursprung des Worklet-Skripts selbst.

Zum Ändern des Standardverhaltens legst du das Attribut dataOrigin beim Aufrufen von createWorklet fest.

• dataOrigin: "context-origin": (Standard) Die Daten werden im freigegebenen Speicher des Ursprungs des aufgerufenen Browser-Kontexts gespeichert.
• dataOrigin: "script-origin": Die Daten werden im freigegebenen Speicher des Ursprungs des Worklet-Scripts gespeichert. Hinweis: Sie müssen diesen Modus aktivieren.

sharedStorage.createWorklet(scriptUrl, {dataOrigin: "script-origin"});

Wenn du "script-origin" verwenden möchtest, muss der Script-Endpunkt mit dem Header Shared-Storage-Cross-Origin-Worklet-Allowed antworten, um die Funktion zu aktivieren. Für ursprungsübergreifende Anfragen sollte CORS aktiviert sein.

Shared-Storage-Cross-Origin-Worklet-Allowed : ?1

Ab M130 ist das Festlegen von „dataOrigin“ für „createWorklet()“ und das Erstellen von ursprungsübergreifenden Worklets mit „addModule()“ verfügbar.

Cross-Origin-iFrame verwenden

Zum Aufrufen des Worklets für den freigegebenen Speicher ist ein iFrame erforderlich.

Laden Sie im iFrame der Anzeige das Worklet-Modul, indem Sie addModule() aufrufen. Wenn Sie die in der Worklet-Datei sharedStorageWorklet.js registrierte Methode ausführen möchten, rufen Sie im selben JavaScript-Code des Anzeigen-iFrames sharedStorage.run() auf.

const sharedStorageWorklet = await window.sharedStorage.createWorklet(
  'https://any-origin.example/modules/sharedStorageWorklet.js'
);
await sharedStorageWorklet.run('shared-storage-report', {
  data: { campaignId: '1234' },
});

Im Worklet-Script müssen Sie eine Klasse mit einer asynchronen run-Methode erstellen und register sie so konfigurieren, 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,
      value
    });
  }
}
register('shared-storage-report', SharedStorageReportOperation);

Ursprungsübergreifende Anfrage verwenden

Mit freigegebenem Speicher und privater Aggregation können ursprungsübergreifende Worklets erstellt werden, ohne dass ursprungsübergreifende iFrames erforderlich sind.

Die Seite mit selbst erhobenen Daten kann auch einen createWorklet()-Aufruf an den plattformübergreifenden JavaScript-Endpunkt auslösen. Sie müssen beim Erstellen des Worklets den Ursprung der Datenpartition des Worklets auf den Ursprung des Scripts festlegen.

async function crossOriginCall() {
  const privateAggregationWorklet = await sharedStorage.createWorklet(
    'https://cross-origin.example/js/worklet.js',
    { dataOrigin: 'script-origin' }
  );
  await privateAggregationWorklet.run('pa-worklet');
}
crossOriginCall();

Der ursprungsübergreifende JavaScript-Endpunkt muss mit den Headern Shared-Storage-Cross-Origin-Worklet-Allowed antworten und CORS ist für die Anfrage aktiviert.

Shared-Storage-Cross-Origin-Worklet-Allowed : ?1

Mit der createWorklet() erstellte Worklets haben selectURL und run(). addModule() ist dafür nicht verfügbar.

Hinweis: addModule() kann zum Erstellen plattformübergreifender Worklets verwendet werden. Die Verwendung von createWorklet() ist jedoch vorzuziehen, da damit eine datenpartitionsübergreifende Datenpartition erstellt werden kann und im Gegensatz zu addModule() mehrere Worklets erstellt werden können.

class CrossOriginWorklet {
  async run(data){
    // Other code goes here.
    bucket = getBucket(...);
    value = getValue(...);
    privateAggregation.contributeToHistogram({
      bucket,
      value
    });
  }
}

Nächste Schritte

Auf den folgenden Seiten werden wichtige Aspekte der Shared Storage API und der Private Aggregation API erläutert.

• Einführung in den freigegebenen Speicher (Chrome für Entwickler)
• Anwendungsfälle für freigegebenen Speicher (Chrome für Entwickler)
• Einführung in die private Aggregation (Chrome für Entwickler)
• Erläuterung zu freigegebenen Speichern (GitHub)
• Erläuterung zur privaten Aggregation (GitHub)
• Demo für freigegebenen Speicher und Private Aggregation API

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.

• Debug-Berichte – 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 aggregierten Berichte zu erhalten.

Feedback geben

Sie können uns Feedback zu den APIs und der Dokumentation auf GitHub geben.

• Shared Storage
• Private Aggregation