Private Aggregation API – Übersicht

Aggregierte Datenberichte mit Daten aus Protected Audience und websiteübergreifenden Daten aus Shared Storage erstellen

Die Private Aggregation API wurde entwickelt, um websiteübergreifende Daten auf datenschutzfreundliche Weise zu aggregieren und zu melden. Sie bietet wichtige Funktionen, auf die das Web angewiesen ist.

Implementierungsstatus

Was ist die Private Aggregation API?

Mit der Private Aggregation API können Entwickler aggregierte Datenberichte mit Daten aus der Protected Audience API und websiteübergreifenden Daten aus Shared Storage erstellen.

Die Hauptfunktion dieser API wird als contributeToHistogram() bezeichnet. Mit dem Histogramm-Vorgang können Sie Daten für Nutzer in jedem Bucket (in der API als Aggregationsschlüssel bezeichnet) aggregieren, den Sie definieren. Bei Ihrem Histogrammaufruf werden Werte zusammengefasst und ein zusammengefasstes Ergebnis mit Rauschen in Form eines Übersichtsberichts zurückgegeben. Der Bericht kann beispielsweise die Anzahl der Websites enthalten, auf denen Nutzer Ihre Inhalte gesehen haben, oder einen Fehler in Ihrem Drittanbieter-Script. Dieser Vorgang wird im Worklet einer anderen API ausgeführt.

Wenn Sie beispielsweise demografische und geografische Daten in Shared Storage gespeichert haben, können Sie mit der Private Aggregation API ein Histogramm erstellen, das Ihnen ungefähr zeigt, wie viele Nutzer in New York City Ihre Inhalte websiteübergreifend gesehen haben. Um die Daten für diese Messung zu aggregieren, können Sie die Dimension „Standort“ im Aggregationsschlüssel codieren und die Nutzer im aggregierbaren Wert zählen.

Wichtige Konzepte

Wenn Sie die Private Aggregation API mit einem Aggregationsschlüssel und einem aggregierbaren Wert aufrufen, generiert der Browser einen aggregierbaren Bericht.

Aggregierbare Berichte werden an Ihren Server gesendet, damit sie dort erfasst und in Batches zusammengefasst werden. Die Batchberichte werden später vom Aggregationsdienst verarbeitet und ein Zusammenfassungsbericht wird generiert.

Weitere Informationen zu den wichtigsten Konzepten der Private Aggregation API finden Sie im Dokument Grundlagen der Private Aggregation API.

Unterschiede zum Attribution Reporting

Die Private Aggregation API weist viele Ähnlichkeiten mit der Attribution Reporting API auf. Attribution Reporting ist eine eigenständige API, die für die Analyse von Conversions entwickelt wurde. Private Aggregation ist für websiteübergreifende Analysen in Verbindung mit APIs wie der Protected Audience API und Shared Storage konzipiert. Mit beiden APIs werden aggregierbare Berichte erstellt, die vom Aggregation Service-Backend verwendet werden, um Zusammenfassungsberichte zu generieren.

Bei Attribution Reporting werden Daten aus einem Impressionsereignis und einem Conversion-Ereignis, die zu unterschiedlichen Zeiten stattfinden, miteinander verknüpft. Bei der privaten Aggregation wird ein einzelnes websiteübergreifendes Ereignis analysiert.

Diese API testen

Wenn Sie die Private Aggregation API lokal testen möchten, aktivieren Sie alle APIs zum Datenschutz bei Werbung unter chrome://settings/adPrivacy.

Weitere Informationen zum Testen

Demo verwenden

Die Demo der Private Aggregation API für Shared Storage ist unter goo.gle/shared-storage-demo verfügbar. Der Code ist auf GitHub verfügbar. In der Demo werden die clientseitigen Vorgänge implementiert und ein aggregierbarer Bericht erstellt, der an Ihren Server gesendet wird.

Eine Demo der Private Aggregation API für die Protected Audience API wird in Zukunft veröffentlicht.

Anwendungsfälle

Private Aggregation ist eine API für allgemeine Zwecke für die websiteübergreifende Analyse. Sie kann in Shared Storage- und Protected Audience API-Worklets verwendet werden. Im ersten Schritt müssen Sie festlegen, welche Informationen Sie genau erfassen möchten. Diese Datenpunkte bilden die Grundlage für Ihre Aggregationsschlüssel.

Mit gemeinsamem Speicher

Mit Shared Storage können Sie websiteübergreifende Daten in einer sicheren Umgebung lesen und schreiben, um Datenlecks zu verhindern. Mit der Private Aggregation API können Sie websiteübergreifende Daten messen, die in Shared Storage gespeichert sind.

Unique Reach-Messung

Sie möchten vielleicht messen, wie viele einzelne Nutzer Ihre Inhalte gesehen haben. Die Private Aggregation API kann eine Antwort wie „Ungefähr 317 einzelne Nutzer haben die Content-ID 861 gesehen“ liefern.

Sie können ein Flag in Shared Storage festlegen, um anzugeben, ob der Nutzer die Inhalte bereits gesehen hat oder nicht. Beim ersten Besuch, bei dem das Flag nicht vorhanden ist, wird ein Aufruf an Private Aggregation gesendet und dann das Flag gesetzt. Bei nachfolgenden Besuchen des Nutzers, auch websiteübergreifend, können Sie Shared Storage prüfen und das Senden eines Berichts an Private Aggregation überspringen, wenn das Flag gesetzt ist. Weitere Informationen zu Methoden zur Implementierung dieser Messwerte finden Sie in unserem Whitepaper zur Reichweite.

Messung demografischer Merkmale

Möglicherweise möchten Sie die demografischen Merkmale der Nutzer erfassen, die Ihre Inhalte auf verschiedenen Websites gesehen haben.

Mit der privaten Aggregation kann eine Antwort wie „Ungefähr 317 einzelne Nutzer im Alter von 18 bis 45 Jahren stammen aus Deutschland“ bereitgestellt werden. Mit Shared Storage können Sie auf demografische Daten aus einem Drittanbieterkontext zugreifen. Später können Sie einen Bericht mit Private Aggregation erstellen, indem Sie die Dimensionen „Altersgruppe“ und „Land“ im Aggregationsschlüssel codieren.

Messung der Häufigkeit von mindestens K

Sie möchten vielleicht die Anzahl der Nutzer messen, die einen Inhalt oder eine Anzeige in einem bestimmten Browser mindestens K Mal gesehen haben, wobei K ein von Ihnen festgelegter Wert ist.

Die private Aggregation kann eine Antwort wie „Ungefähr 89 Nutzer haben die Content-ID 581 mindestens dreimal gesehen“ liefern. Ein Zähler kann in Shared Storage von verschiedenen Websites aus erhöht und in einem Worklet gelesen werden. Wenn die Anzahl K erreicht hat, kann ein Bericht mit Private Aggregation eingereicht werden.

Multi-Touchpoint-Attribution

Die Marketing-Attribution ist eine Methode, mit der Werbetreibende den Beitrag von Marketingstrategien und nachfolgenden Anzeigeninteraktionen zu Verkäufen oder Conversions ermitteln.

Mit der Protected Audience API

Die Protected Audience API ermöglicht Retargeting und Anwendungsfälle für benutzerdefinierte Zielgruppen. Mit Private Aggregation können Sie Ereignisse aus Käufer- und Verkäufer-Worklets melden. Die API kann für Aufgaben wie die Messung der Verteilung von Auktionsgeboten verwendet werden.

In einem Protected Audience API-Worklet können Sie Ihre Daten direkt mit contributeToHistogram() aggregieren und Ihre Daten basierend auf einem Trigger mit contributeToHistogramOnEvent() melden. contributeToHistogramOnEvent() ist eine spezielle Erweiterung für die Protected Audience API.

Verfügbare Funktionen

Die folgenden Funktionen sind im privateAggregation-Objekt verfügbar, das in Shared Storage- und Protected Audience API-Worklets verfügbar ist.

contributeToHistogram()

Sie können privateAggregation.contributeToHistogram({ bucket: <bucket>, value: <value> }) aufrufen, wobei der Aggregationsschlüssel bucket und der aggregierbare Wert value ist. Für den Parameter bucket ist ein BigInt erforderlich. Für den Parameter value ist eine Ganzzahl erforderlich.

Hier ist ein Beispiel dafür, wie sie im Shared Storage für Reichweitenmessungen aufgerufen werden kann:

iframe.js

// Cross-site iframe code

async function measureReach() {
 // Register worklet
 await window.sharedStorage.worklet.addModule('worklet.js');

 // Run reach measurement operation
 await window.sharedStorage.run('reach-measurement', {
  data: { contentId: '1234' }
 });
}

measureReach();

worklet.js

// Shared storage worklet code

function convertContentIdToBucket(campaignId){
  // Generate aggregation key
}

// The scale factor is multiplied by the aggregatable value to
// maximize the signal-to-noise ratio. See "Noise and scaling"
// section in the Aggregation Fundamentals document to learn more.
const SCALE_FACTOR = 65536;

class ReachMeasurementOperation {
  async run(data) {
    const key = 'has-reported-content';
    // Read the flag from Shared Storage
    const hasReportedContent = await sharedStorage.get(key) === 'true';

    // Don't send report if the flag is set
    if (hasReportedContent) {
      return;
    }

    // Send histogram report
    // Set the aggregation key in `bucket`
    // Bucket examples: 54153254n or BigInt(54153254)
    // Set the scaled aggregatable value in `value`
    privateAggregation.contributeToHistogram({
      bucket: convertContentIdToBucket(data.contentId),
      value: 1 * SCALE_FACTOR
    });

    // Set the flag in Shared Storage
    await sharedStorage.set(key, true);
  }
}

register('reach-measurement', ReachMeasurementOperation);

Im vorherigen Codebeispiel wird die Private Aggregation immer dann aufgerufen, wenn die websiteübergreifenden iframe-Inhalte geladen werden. Der Iframe-Code lädt das Worklet und das Worklet ruft die Private Aggregation API mit der in einen Aggregationsschlüssel (Bucket) umgewandelten Inhalts-ID auf.

contributeToHistogramOnEvent()

Nur in Protected Audience API-Worklets bieten wir einen triggerbasierten Mechanismus zum Senden eines Berichts, wenn ein bestimmtes Ereignis eintritt. Mit dieser Funktion können Bucket und Wert auch von Signalen abhängen, die zu diesem Zeitpunkt der Auktion noch nicht verfügbar sind.

Die Methode privateAggregation.contributeToHistogramOnEvent(eventType, contribution) akzeptiert ein eventType, das das auslösende Ereignis angibt, und das contribution, das gesendet werden soll, wenn das Ereignis ausgelöst wird. Das Auslöseereignis kann nach Auktionsende aus der Auktion selbst stammen, z. B. ein Auktionsgewinn- oder ‑verlustereignis, oder von einem eingegrenzten Frame, in dem die Anzeige gerendert wurde.

Wenn Sie einen Bericht für Auktionsereignisse senden möchten, können Sie die beiden reservierten Keywords reserved.win, reserved.loss und reserved.always verwenden. Wenn Sie einen Bericht senden möchten, der durch ein Ereignis aus einem eingezäunten Frame ausgelöst wird, definieren Sie einen benutzerdefinierten Ereignistyp. Um das Ereignis über einen Fenced Frame auszulösen, verwenden Sie die Methode fence.reportEvent(), die über die Fenced Frames Ads Reporting API verfügbar ist.

Im folgenden Beispiel wird ein Impressionsbericht gesendet, wenn das Ereignis „Auktionsgewinn“ ausgelöst wird, und ein Klickbericht, wenn ein click-Ereignis aus dem Fenced Frame ausgelöst wird, in dem die Anzeige gerendert wurde. Anhand dieser beiden Werte lässt sich die Klickrate berechnen.

function generateBid(interestGroup, auctionSignals, perBuyerSignals, trustedBiddingSignals, browserSignals) {
  // …
  privateAggregation.contributeToHistogramOnEvent("reserved.win", {
      bucket: getImpressionReportBucket(),
      value: 1
  });
  privateAggregation.contributeToHistogramOnEvent("click", {
      bucket: getClickReportBuckets(), // 128-bit integer as BigInt
      value: 1
  });

Weitere Informationen finden Sie im Dokument zu erweiterten Berichten zur privaten Aggregation.

enableDebugMode()

Solange Drittanbieter-Cookies noch verfügbar sind, stellen wir einen temporären Mechanismus bereit, der das Debuggen und Testen durch Aktivieren des Debug-Modus erleichtert. Ein Debug-Bericht ist nützlich, um Ihre Cookie-basierten Messungen mit Ihren Private Aggregation-Messungen zu vergleichen. Außerdem können Sie damit Ihre API-Integration schnell validieren.

Wenn Sie privateAggregation.enableDebugMode() im Worklet aufrufen, wird der Debug-Modus aktiviert. Dadurch enthalten aggregierbare Berichte die unverschlüsselte Nutzlast (Klartext). Anschließend können Sie diese Nutzlasten mit dem lokalen Testtool des Aggregation Service verarbeiten.

Der Debug-Modus ist nur für Aufrufer verfügbar, die auf Drittanbieter-Cookies zugreifen dürfen. Wenn der Aufrufer keinen Zugriff auf Drittanbieter-Cookies hat, schlägt enableDebugMode() fehl.

Sie können den Debug-Schlüssel auch festlegen, indem Sie privateAggregation.enableDebugMode({ <debugKey: debugKey> }) aufrufen. Dabei kann ein BigInt als Debug-Schlüssel verwendet werden. Mit dem Debug-Schlüssel können Daten aus einer cookiebasierten Analyse und Daten aus einer Analyse mit privater Aggregation verknüpft werden.

Diese können nur einmal pro Kontext aufgerufen werden. Bei allen nachfolgenden Aufrufen wird eine Ausnahme ausgelöst.

// Enables debug mode
privateAggregation.enableDebugMode();

// Enables debug mode and sets a debug key
privateAggregation.enableDebugMode({ debugKey: BigInt(1234) });

Bericht überprüfen

Die Private Aggregation API ermöglicht websiteübergreifende Messungen und schützt gleichzeitig die Privatsphäre der Nutzer. Böswillige Akteure können jedoch versuchen, die Genauigkeit dieser Messungen zu manipulieren. Um dies zu verhindern, können Sie eine Kontext-ID verwenden, um die Authentizität von Berichten zu bestätigen.

Wenn Sie eine Kontext-ID festlegen, tragen Sie dazu bei, dass die Daten korrekt sind, wenn sie zu den endgültigen aggregierten Ergebnissen beitragen. Dies wird durch Folgendes erreicht:

• Verhindern unrechtmäßiger oder gefälschter Berichte:Prüfen Sie, ob Berichte durch rechtmäßige und authentische API-Aufrufe generiert werden. Dadurch wird es böswilligen Akteuren erschwert, Berichte zu fälschen.
• Wiederholung von Berichten verhindern:Alle Versuche, alte Berichte wiederzuverwenden, werden erkannt und abgelehnt. So trägt jeder Bericht nur einmal zu den aggregierten Ergebnissen bei.

Shared Storage

Wenn Sie Shared Storage verwenden, um einen Vorgang auszuführen, bei dem ein aggregierbarer Bericht gesendet werden kann, können Sie eine unvorhersehbare ID außerhalb des Worklets festlegen.

Diese ID ist in den Bericht eingebettet, der aus dem Worklet erstellt wurde. Sie können sie beim Aufrufen der Shared Storage-Methoden run() oder selectURL() im Optionenobjekt unter dem Schlüssel privateAggregationConfig angeben.

Beispiel:

sharedStorage.run('measurement-operation', {
  privateAggregationConfig: {
    contextId: 'exampleId123456789abcdeFGHijk'
  }
});

Nachdem diese ID festgelegt wurde, können Sie damit überprüfen, ob der Bericht von Ihrem Shared Storage-Vorgang gesendet wurde. Um Informationslecks zu verhindern, wird pro Shared Storage-Vorgang genau ein Bericht gesendet (auch wenn keine Beiträge geleistet werden), unabhängig von der Anzahl der contributeToHistogram()-Aufrufe.

Die Private Aggregation API sendet aggregierbare Berichte mit einer zufälligen Verzögerung von bis zu einer Stunde. Wenn Sie jedoch eine Kontext-ID festlegen, um einen Bericht zu bestätigen, wird diese Verzögerung reduziert. In diesem Fall gibt es eine feste, kleinere Verzögerung von 5 Sekunden ab dem Start des Shared Storage-Vorgangs.

Beispiel für einen Workflow (siehe Diagramm oben):

1. Der Shared Storage-Vorgang wird mit einer Private Aggregation-Konfiguration ausgeführt, in der eine Kontext-ID angegeben ist, und es wird ein aggregierbarer Bericht generiert.
2. Die Kontext-ID ist in den generierten aggregierbaren Bericht eingebettet, der an Ihren Server gesendet wird.
3. Ihr Server erfasst die generierten aggregierbaren Berichte.
4. Prozesse auf Ihrem Server vergleichen die Kontext-ID in jedem aggregierbaren Bericht mit Ihren gespeicherten Kontext-IDs, um die Gültigkeit zu prüfen, bevor die Berichte in Batches zusammengefasst und an Ihren Aggregationsdienst gesendet werden.

Bestätigung der Kontext-ID

Eingehende Berichte an Ihren Collector-Server können auf verschiedene Arten überprüft werden, bevor sie an den Aggregationsdienst gesendet werden. Berichte mit ungültigen Kontext-IDs können abgelehnt werden, wenn die Kontext-ID:

• Unbekannt:Wenn ein Bericht mit einer Kontext-ID eingeht, die von Ihrem System nicht erstellt wurde, können Sie ihn verwerfen. So wird verhindert, dass unbekannte oder böswillige Akteure Daten in Ihre Aggregationspipeline einfügen.
• Duplikat:Wenn Sie zwei oder mehr Berichte mit derselben Kontext-ID erhalten, müssen Sie auswählen, welche Berichte Sie verwerfen möchten.
• Bei der Spamerkennung gekennzeichnet:
  • Wenn Sie bei der Bearbeitung des Berichts eines Nutzers verdächtige Aktivitäten feststellen, z. B. eine plötzliche Änderung der Aktivitäten, können Sie den Bericht verwerfen.
  • Sie können Berichte zusammen mit ihren Kontext-IDs und allen relevanten Signalen speichern, z. B. User-Agent oder Verweisquelle. Wenn Sie später das Nutzerverhalten analysieren und neue Spam-Indikatoren identifizieren, können Sie gespeicherte Berichte anhand der zugehörigen Kontext-IDs und Signale neu bewerten. So können Sie Berichte von Nutzern mit verdächtigen Aktivitäten verwerfen, auch wenn sie nicht von vornherein gekennzeichnet wurden.

Feedback geben

Die Private Aggregation API befindet sich in der aktiven Diskussion und kann sich daher in Zukunft ändern. Wenn Sie diese API ausprobieren und Feedback haben, freuen wir uns darauf.

• GitHub: Lesen Sie die Erläuterung, stellen Sie Fragen und beteiligen Sie sich an der Diskussion.
• Entwicklersupport: Fragen stellen und an Diskussionen im Privacy Sandbox Developer Support-Repository teilnehmen
• Treten Sie der Shared Storage API-Gruppe und der Protected Audience API-Gruppe bei, um die neuesten Ankündigungen zu Private Aggregation zu erhalten.