Private Aggregation API – Übersicht

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

Um wichtige Funktionen bereitzustellen, auf die das Web angewiesen ist, wurde die Private Aggregation API entwickelt, um websiteübergreifende Daten datenschutzfreundlich zu aggregieren und zu erfassen.

Implementierungsstatus

Was ist die Private Aggregation API?

Mit der Private Aggregation API können Entwickler Berichte mit aggregierten 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 alle Nutzer in jedem Bucket (in der API als Aggregationsschlüssel bezeichnet) zusammenfassen, den Sie definieren. Bei Ihrem Histogrammaufruf werden Werte erfasst und ein gefiltertes aggregiertes Ergebnis in Form eines Zusammenfassungsberichts zurückgegeben. So sehen Sie beispielsweise die Anzahl der Websites, auf denen die Inhalte der einzelnen Nutzer ausgeliefert wurden, oder einen Fehler im Script eines Drittanbieters. Dieser Vorgang wird im Worklet einer anderen API ausgeführt.

Wenn Sie beispielsweise zuvor demografische und geografische Daten in Shared Storage erfasst haben, können Sie mit der Private Aggregation API ein Histogramm erstellen, das Ihnen ungefähr Aufschluss darüber gibt, wie viele Nutzer in New York City Ihre Inhalte websiteübergreifend gesehen haben. Wenn Sie diese Messwerte zusammenfassen möchten, können Sie die geografische Dimension in den Aggregationsschlüssel einfügen 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 zur Erfassung und Batchverarbeitung an Ihren Server gesendet. Die Batchberichte werden später vom Aggregationsdienst verarbeitet und ein Zusammenfassungsbericht erstellt.

Im Dokument Grundlagen der Private Aggregation API finden Sie weitere Informationen zu den wichtigsten Konzepten der Private Aggregation API.

Unterschiede zu Attributionsberichten

Die Private Aggregation API weist viele Ähnlichkeiten mit der Attribution Reporting API auf. Die Attribution Reporting API ist eine eigenständige API, die zum Erfassen von Conversions entwickelt wurde. Private Aggregation ist für websiteübergreifende Messungen in Verbindung mit APIs wie der Protected Audience API und Shared Storage konzipiert. Beide APIs generieren aggregierbare Berichte, die vom Back-End des Aggregationsdiensts verwendet werden, um Zusammenfassungsberichte zu erstellen.

In Attributionsberichten werden Daten aus einem Impressions- und einem Conversion-Ereignis verknüpft, die zu unterschiedlichen Zeitpunkten auftreten. Bei der privaten Aggregation wird ein einzelnes websiteübergreifendes Ereignis erfasst.

Diese API testen

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

Weitere Informationen zu Tests finden Sie unter Tests durchführen und daran teilnehmen.

Demo verwenden

Die Demo der Private Aggregation API für Shared Storage finden Sie unter goo.gle/shared-storage-demo. 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

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

Mit Shared Storage

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 wissen, wie viele einzelne Nutzer die Inhalte gesehen haben. Die Private Aggregation API kann beispielsweise eine Antwort wie „Etwa 317 einzelne Nutzer haben sich den Content ID 861 angesehen“ liefern.

Sie können in Shared Storage ein Flag festlegen, um anzugeben, ob der Nutzer die Inhalte bereits gesehen hat oder nicht. Beim ersten Besuch, bei dem das Flag nicht vorhanden ist, wird die private Aggregation aufgerufen und das Flag wird festgelegt. Bei nachfolgenden Besuchen des Nutzers, einschließlich websiteübergreifender Besuche, 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.

Demografische Messungen

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

Die private Aggregation kann eine Antwort liefern, z. B. „Ungefähr 317 einzelne Nutzer sind zwischen 18 und 45 Jahre alt und kommen aus Deutschland.“ Verwenden Sie Shared Storage, um auf demografische Daten aus einem Drittanbieterkontext zuzugreifen. Später können Sie einen Bericht mit der privaten Aggregation erstellen, indem Sie die Dimensionen „Altersgruppe“ und „Land“ im Aggregationsschlüssel codieren.

Messung der Häufigkeit von mindestens K

Sie können die Anzahl der Nutzer messen, die einen bestimmten Inhalt oder eine bestimmte Anzeige in einem bestimmten Browser mindestens K-mal gesehen haben, wobei K ein zuvor festgelegter Wert ist.

Die private Aggregation kann beispielsweise eine Antwort wie „Ungefähr 89 Nutzer haben sich die Content-ID 581 mindestens dreimal angesehen“ liefern. Ein Zähler kann im freigegebenen Speicher von verschiedenen Websites erhöht und in einem Worklet gelesen werden. Sobald die Anzahl K erreicht ist, kann ein Bericht mithilfe der privaten Aggregation eingereicht werden.

Multi-Touch-Attribution

Mithilfe der Marketing-Attribution können Werbetreibende den Beitrag von Marketingtaktiken und nachfolgenden Anzeigeninteraktionen zu Verkäufen oder Conversions ermitteln.

Mit der Protected Audience API

Mit der Protected Audience API können Sie Remarketing und benutzerdefinierte Zielgruppen verwenden. Mit Private Aggregation können Sie Ereignisse aus Käufer- und Verkäufer-Worklets erfassen. 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() zusammenfassen und mit contributeToHistogramOnEvent(), einer speziellen Erweiterung für die Protected Audience API, Berichte basierend auf einem Trigger erstellen.

Verfügbare Funktionen

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

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 es im freigegebenen Speicher für die Reichweitenmessung 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 Private Aggregation immer dann aufgerufen, wenn der websiteübergreifende iframe-Inhalt geladen wird. Der Iframe-Code lädt das Worklet und das Worklet ruft die Private Aggregation API mit der Inhalts-ID auf, die in einen Aggregationsschlüssel (Bucket) umgewandelt wurde.

contributeToHistogramOnEvent()

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

Die privateAggregation.contributeToHistogramOnEvent(eventType, contribution)-Methode nimmt einen eventType an, der das auslösende Ereignis angibt, und die contribution, die gesendet werden soll, wenn das Ereignis ausgelöst wird. Das auslösende Ereignis kann von der Auktion selbst nach deren Ende stammen, z. B. ein Ereignis vom Typ „Auktion gewonnen“ oder „Auktion verloren“. Es kann sich aber auch um ein Ereignis von einem eingegrenzten Frame handeln, in dem die Anzeige gerendert wurde.

Wenn Sie einen Bericht für Auktionsereignisse senden möchten, können Sie zwei reservierte Keywords verwenden: reserved.win, reserved.loss und reserved.always. Wenn Sie einen Bericht einreichen möchten, der durch ein Ereignis aus einem eingegrenzten Frame ausgelöst wird, müssen Sie einen benutzerdefinierten Ereignistyp definieren. Wenn Sie das Ereignis über einen eingegrenzten Frame auslösen möchten, verwenden Sie die Methode fence.reportEvent() der Fenced Frames Ads Reporting API.

Im folgenden Beispiel wird ein Bericht zu Impressionen gesendet, wenn das Ereignis „auction_win“ ausgelöst wird, und ein Bericht zu Klicks, wenn ein click-Ereignis vom eingezäunten 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 Hilfeartikel Erweiterte Berichte zur privaten Aggregation.

enableDebugMode()

Drittanbieter-Cookies sind zwar weiterhin verfügbar, aber wir stellen einen vorübergehenden Mechanismus bereit, der das Debuggen und Testen durch Aktivieren des Debug-Modus erleichtert. Mit einem Debug-Bericht können Sie Ihre cookiebasierten Messungen mit Ihren Messungen mit privater Aggregation vergleichen und Ihre API-Integration schnell überprüfen.

Wenn Sie privateAggregation.enableDebugMode() im Worklet aufrufen, wird der Debug-Modus aktiviert, wodurch aggregierbare Berichte die unverschlüsselte (in Klartext) Nutzlast enthalten. Sie können diese Nutzlasten dann mit dem lokalen Testtool des Aggregationsdiensts 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() stillschweigend fehl.

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

Sie können nur einmal pro Kontext aufgerufen werden. Alle nachfolgenden Aufrufe lösen eine Ausnahme aus.

// Enables debug mode
privateAggregation.enableDebugMode();

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

Überprüfung von Meldungen

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. Sie können dies verhindern, indem Sie die Echtheit von Berichten mithilfe einer Kontext-ID überprüfen.

Wenn Sie eine Kontext-ID festlegen, können Sie dafür sorgen, dass die Daten korrekt sind, wenn sie zu den endgültigen zusammengefassten Ergebnissen beitragen. Dazu gehören:

• Verhinderung von unzulässigen oder unechten Berichten: Sorgen Sie dafür, dass Berichte über legitime und authentische API-Aufrufe generiert werden, um die Fälschung von Berichten für böswillige Akteure zu erschweren.
• Wiedergabe von Berichten verhindern: Versuche, alte Berichte wiederzuverwenden, werden erkannt und abgelehnt. So trägt jeder Bericht nur einmal zu den zusammengefassten Ergebnissen bei.

Shared Storage

Wenn Sie Shared Storage zum Ausführen eines Vorgangs verwenden, mit dem ein aggregierbarer Bericht gesendet werden kann, können Sie außerhalb des Worklets eine nicht vorhersehbare ID festlegen.

Diese ID ist in den Bericht eingebettet, der aus dem Worklet erstellt wurde. Sie können sie beim Aufrufen der Methoden run() oder selectURL() für freigegebenen Speicher im Optionsobjekt unter dem Schlüssel privateAggregationConfig angeben.

Beispiel:

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

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

Die Private Aggregation API sendet Berichte mit aggregierten Daten 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, kürzere Verzögerung von 5 Sekunden nach Beginn des Vorgangs für den freigegebenen Speicher.

Beispiel für einen Workflow (wie im Diagramm oben dargestellt):

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

Kontext-ID bestätigen

Eingehende Berichte auf Ihrem Collector-Server können auf unterschiedliche Weise ü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 nicht von Ihrem System erstellt wurde, können Sie ihn verwerfen. So wird verhindert, dass unbekannte oder böswillige Akteure Daten in Ihre Aggregationspipeline einschleusen.
• Duplikat:Wenn Sie zwei oder mehr Berichte mit derselben Kontext-ID erhalten, müssen Sie auswählen, welchen Bericht Sie verwerfen möchten.
• Von der Spamerkennung gemeldet:
  • Wenn Sie bei der Verarbeitung eines Berichts verdächtige Aktivitäten eines Nutzers feststellen, z. B. eine plötzliche Änderung der Aktivitäten eines Nutzers, können Sie ihn verwerfen.
  • Sie können Berichte zusammen mit ihren Kontext-IDs und allen relevanten Signalen speichern (z. B. User-Agent, Verweisquelle usw.). 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 noch einmal auswerten. So können Sie Meldungen von Nutzern mit verdächtigen Aktivitäten ablehnen, auch wenn sie nicht ursprünglich gemeldet wurden.

Feedback geben und mit anderen Nutzern interagieren

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

• GitHub: Lesen Sie den Erläuterungsartikel, stellen Sie Fragen und nehmen Sie an der Diskussion teil.
• Entwicklersupport: Im Privacy Sandbox Developer Support-Repository können Sie Fragen stellen und an Diskussionen teilnehmen.
• Treten Sie der Shared Storage API-Gruppe und der Protected Audience API-Gruppe bei, um aktuelle Ankündigungen zur Privaten Aggregation zu erhalten.