Berichts-IDs

Informationen zur Funktionsweise von Berichts-IDs in Protected Audience-Auktionen

Übersicht

Berichts-IDs sind Kennungen, die mit einer Anzeige verknüpft sind und zum Generieren, Bewerten und Erstellen von Berichten verwendet werden können. Die Berichts-IDs werden vom Käufer in der Konfiguration der Interessengruppe angegeben. Sie sind in generateBid(), scoreAd(), reportResult() und reportWin() unter verschiedenen Bedingungen verfügbar, die in diesem Leitfaden erläutert werden.

Mit Berichts-IDs können Sie eine Kennung für eine Anzeige melden und Anwendungsfälle wie Angebote ermöglichen.

Verfügbarkeit von Identitäten für die Berichterstellung

Es gibt drei Berichts-IDs von zwei Typen:

• Nicht auswählbare Berichts-IDs
  • buyerReportingId (String)
  • buyerAndSellerReportingId (String)
• Auswählbare Berichts-IDs
  • selectableBuyerAndSellerReportingIds (ein Stringarray)

Die Berichts-IDs verhalten sich unterschiedlich, je nachdem, ob auswählbare Berichts-IDs verwendet werden. Wenn nur nicht auswählbare Berichts-IDs verwendet werden, sind diese nur in den Berichtsfunktionen verfügbar. Wenn auswählbare Berichts-IDs zusammen mit nicht auswählbaren Berichts-IDs verwendet werden, sind alle definierten IDs auch in generateBid() und scoreAd() verfügbar.

Wichtig: Berichts-IDs werden auf K-Anonymität geprüft, bevor sie in den Berichtsfunktionen (reportResult() und reportWin()) verfügbar werden.

Nicht auswählbare Berichts-IDs

Verfügbarkeit auswählbarer Berichts-IDs

buyerReportingId und buyerAndSellerReportingId sind nicht auswählbare Berichts-IDs, die in der Konfiguration der Interessengruppe definiert sind und in den Berichtsfunktionen für Käufer und Verkäufer verfügbar werden. Die Berichtsfunktionen für Käufer und Verkäufer werden nur für die Gewinneranzeige ausgeführt. Sie erhalten die für diese Anzeige definierten Berichts-IDs.

Wenn sie ohne auswählbare Berichts-IDs verwendet wird, erhält die Funktion für Käuferberichte je nach Überschreibungsverhalten buyerReportingId oder buyerAndSellerReportingId und die Funktion für Verkäuferberichte buyerAndSellerReportingId. Wenn weder buyerReportingId noch buyerAndSellerReportingId in der Konfiguration der Interessengruppe definiert sind, wird der Name der Interessengruppe (interestGroupName) des Gewinnergebots an die Funktion reportWin() übergeben.

Nicht auswählbare IDs sind in generateBid() und scoreAd() nicht verfügbar, wenn sie nicht in Verbindung mit auswählbaren Berichts-IDs verwendet werden.

IDs für Berichte in Interessengruppen

Die Berichts-IDs werden vom Käufer für jede Anzeige in einer Interessengruppe definiert:

navigator.joinAdInterestGroup({
  owner: 'https://buyer.example',
  name: 'example-interest-group',
  ads: [{
    renderUrl: `https://buyer.example/ad.html`,
    // buyerAndSellerReportingId goes to the buyer and seller reporting functions
    buyerAndSellerReportingId: 'bsrid123',
    // buyerReportingId is defined here as an example, but
    // is not used due to the overwrite rules described later
    buyerReportingId: 'brid123',
  }]
});

Verkäuferberichte

Während der Berichterstellungsphase für Verkäufer ist der Wert buyerAndSellerReportingId für reportResult() verfügbar:

function reportResult(..., browserSignals, ...) {
  const {
    buyerAndSellerReportingId // 'bsrid123'
  } = browserSignals;

  sendReportTo(`https://seller.example/report?bsrid=${buyerAndSellerReportingId}`);
}

Bevor die ID in reportResult() verfügbar ist, wird sie auf K-Anonymität mit dem Eigentümer der Interessengruppe, der URL des Gebotsscripts, der Render-URL und der Anzeigengröße geprüft. Die Anzeigengröße wird bis mindestens Q1 2025 von dieser Prüfung ausgeschlossen. Wenn die Daten nicht k-anonym sind, wird die Funktion reportResult() trotzdem ausgeführt, der Wert der Berichts-ID ist jedoch nicht in der Funktion verfügbar.

Käuferberichte

Während der Berichtsphase für Käufer in der Auktion wird reportWin() eine Berichts-ID zugewiesen. Wenn in der Interessengruppe mehr als eine Berichts-ID definiert ist, wird eine Überschreibungsregel angewendet, bei der buyerAndSellerReportingId buyerReportingId überschreibt:

• Wenn sowohl buyerAndSellerReportingId als auch buyerReportingId definiert sind, wird buyerReportingId von buyerAndSellerReportingId überschrieben und buyerAndSellerReportingId ist in reportWin() verfügbar.
• Wenn nur buyerReportingId definiert ist, ist buyerReportingId verfügbar.
• Wenn weder buyerAndSellerReportingId noch buyerReportingId definiert sind, ist interestGroupName verfügbar.

function reportWin(..., browserSignals, ...) {
  const {
    buyerAndSellerReportingId // 'bsrid123'
  } = browserSignals;

  sendReportTo(`https://seller.example/report?bsrid=${buyerAndSellerReportingId}`);
}

Die Berichts-ID, die in reportWin() verfügbar ist, wird auf K-Anonymität mit dem Inhaber der Interessengruppe, der URL des Gebotsscripts, der Render-URL und der Anzeigengröße geprüft. Die Anzeigengröße wird bis mindestens zum 1. Quartal 2025 von dieser Prüfung ausgenommen. Wenn die K-Anonymität nicht gegeben ist, wird reportWin() trotzdem ausgeführt, aber der Wert der Berichts-ID ist in der Funktion nicht verfügbar.

Nur buyerReportingId ist definiert

Wenn in der Konfiguration der Interessengruppe nur buyerReportingId definiert ist:

navigator.joinAdInterestGroup({
  owner: 'https://buyer.example',
  name: 'example-interest-group',
  ads: [{
    renderUrl: `https://buyer.example/ad.html`,
    buyerReportingId: 'brid123',
  }]
});

Dann ist buyerReportingId in reportWin() verfügbar:

function reportWin(..., browserSignals, ...) {
  const {
    buyerReportingId, // 'brid123'
  } = browserSignals;
}

Bevor buyerReportingId für reportWin() verfügbar wird, wird buyerReportingId auf K-Anonymität mit dem Inhaber der Interessengruppe, der URL des Gebotsscripts, der Render-URL und der Anzeigengröße geprüft. Die Anzeigengröße wird bis mindestens Q1 2025 von dieser Prüfung ausgeschlossen.

Nur „buyerAndSellerReportingId“ ist definiert

Wenn in der Konfiguration der Interessengruppe nur buyerAndSellerReportingId definiert ist:

navigator.joinAdInterestGroup({
  owner: 'https://buyer.example',
  name: 'example-interest-group',
  ads: [{
    renderUrl: `https://buyer.example/ad.html`,
    buyerAndSellerReportingId: 'bsrid123',
  }]
});

Dann ist buyerAndSellerReportingId in reportWin() verfügbar:

function reportWin(..., browserSignals, ...) {
  const {
    buyerAndSellerReportingId, // 'bsrid123'
  } = browserSignals;
}

Bevor buyerAndSellerReportingId für reportWin() verfügbar wird, wird buyerAndSellerReportingId auf K-Anonymität mit dem Inhaber der Interessengruppe, der URL des Gebotsscripts, der Render-URL und der Anzeigengröße geprüft. Die Anzeigengröße wird bis mindestens Q1 2025 von dieser Prüfung ausgenommen.

Sowohl buyerAndSellerReportingId als auch buyerReportingId sind definiert

Wenn sowohl buyerAndSellerReportingId als auch buyerReportingId in der Konfiguration der Interessengruppe definiert sind:

navigator.joinAdInterestGroup({
  owner: 'https://buyer.example',
  name: 'example-interest-group',
  ads: [{
    renderUrl: `https://buyer.example/ad.html`,
    buyerReportingId: 'brid123',
    buyerAndSellerReportingId: 'bsrid123',
  }]
});

Dann ist aufgrund des Überschreibungsverhaltens nur buyerAndSellerReportingId in reportWin() verfügbar:

function reportWin(..., browserSignals, ...) {
  const {
    buyerAndSellerReportingId, // 'bsrid123'
  } = browserSignals;
}

Bevor buyerAndSellerReportingId für reportWin() verfügbar wird, wird buyerAndSellerReportingId auf K-Anonymität mit dem Inhaber der Interessengruppe, der URL des Gebotsscripts, der Render-URL und der Anzeigengröße geprüft. Die Anzeigengröße wird bis mindestens Q1 2025 von dieser Prüfung ausgeschlossen.

Weder buyerAndSellerReportingId noch buyerReportingId sind definiert

Wenn in der Konfiguration der Interessengruppe keine Berichts-IDs definiert sind:

navigator.joinAdInterestGroup({
  owner: 'https://buyer.example',
  name: 'example-interest-group',
  ads: [{
    renderUrl: `https://buyer.example/ad.html`,
  }]
});

Dann ist die Interessengruppe name in reportWin() verfügbar:

function reportWin(..., browserSignals, ...) {
  const {
    interestGroupName, // 'example-interest-group'
  } = browserSignals;
}

Bevor der Name der Interessengruppe (interestGroupName) für reportWin() verfügbar wird, wird er auf K-Anonymität mit dem Inhaber der Interessengruppe, der URL des Gebotsscripts, der Render-URL und der Anzeigengröße geprüft. Die Anzeigengröße wird bis mindestens Q1 2025 von dieser Prüfung ausgeschlossen.

Auswählbare Berichts-IDs

Verfügbarkeit von Berichts-IDs mit wählbarer Berichts-ID

Mit auswählbaren Berichts-IDs kann ein Käufer während der Gebotserstellung eine ID auswählen. Der Browser stellt den ausgewählten Wert dann für scoreAd() und Berichtsfunktionen zur Verfügung. Der Wert selectableBuyerAndSellerReportingIds, ein String-Array, wird an generateBid() übergeben. Der Käufer kann eine ausgewählte ID als selectedBuyerAndSellerReportingId zurückgeben.

Die Funktionen generateBid() und scoreAd() werden für jede in der Interessengruppenkonfiguration definierte Anzeige ausgeführt und erhalten die Berichts-IDs für jede Anzeige. Die Berichtsfunktionen für Käufer und Verkäufer werden nur für die Gewinneranzeige ausgeführt. Sie erhalten die für diese Anzeige definierten Berichts-IDs.

Wenn nicht auswählbare Berichts-IDs in Verbindung mit auswählbaren Berichts-IDs verwendet werden, unterscheidet sich ihr Verhalten vom im vorherigen Abschnitt beschriebenen Workflow. Im Gegensatz zum ursprünglichen Verhalten, bei dem nicht auswählbare Berichts-IDs nur in Berichtsfunktionen verfügbar waren, können nicht auswählbare Berichts-IDs mit auswählbaren Berichts-IDs auch in generateBid() und scoreAd() verfügbar gemacht werden.

Hinweis :Die auswählbaren IDs für die Berichterstellung sind in der stabilen Version ab M130 verfügbar. Bevor die auswählbaren Berichts-IDs die stabile Version erreichen, können sie getestet werden. Dazu starten Sie Canary M130 über die Befehlszeile mit den Flags --enable-privacy-sandbox-ads-apis --disable-features=EnforcePrivacySandboxAttestations --enable-features=ProtectedAudienceDealsSupport

.

Interessengruppe

Das Feld „Auswählbare Berichts-IDs“ (selectableBuyerAndSellerReportingIds) ist ein Array von Strings, das vom Käufer in der Interessengruppe für eine Anzeige definiert wurde. Nicht auswählbare Berichts-IDs können auch zusammen mit auswählbaren Berichts-IDs definiert werden:

navigator.joinAdInterestGroup({
  owner: 'https://buyer.example',
  name: 'example-interest-group',
  ads: [{
    renderUrl: `https://buyer.example/ad.html`,
    buyerReportingId: 'brid123',
    buyerAndSellerReportingId: 'bsrid123',
    selectableBuyerAndSellerReportingIds: ['sbsrid1', 'sbsrid2', 'sbsrid3']
  }]
});

Generierung von Käufergeboten

Wenn selectableBuyerAndSellerReportingIds in der Konfiguration der Interessengruppe definiert wurde, ist sie zusammen mit anderen definierten Berichts-IDs in generateBid() verfügbar.

function generateBid(interestGroup, ...) {
  const [{
    buyerReportingId, // 'brid123'
    buyerAndSellerReportingId, // 'bsrid123'
    selectableBuyerAndSellerReportingIds // ['sbsrid1', 'sbsrid2', 'sbsrid3']
  }] = interestGroup.ads;

  return {
    bid: 1,
    render: 'https://buyer.example/ad.html',
    selectedBuyerAndSellerReportingId: 'sbsrid2' // Buyer returns the selected ID
  };
}

Der Käufer kann eine der IDs aus dem selectableBuyerAndSellerReportingIds-Array in generateBid() auswählen und die ausgewählte ID als selectedBuyerAndSellerReportingId zurückgeben. Das Gebot wird abgelehnt, wenn der ausgewählte Wert nicht im selectableBuyerAndSellerReportingIds-Array enthalten ist. Wenn selectableBuyerAndSellerReportingIds in der Konfiguration der Interessengruppe definiert ist und der Käufer selectedBuyerAndSellerReportingId nicht von generateBid() zurückgibt, wird für die Identitäten für die Berichterstellung das für nicht auswählbare Identitäten für die Berichterstellung beschriebene Verhalten verwendet.

Ein Gebot mit einem zurückgegebenen Wert für selectedbuyerAndSellerReportingId kann die Auktion nur gewinnen, wenn der Wert von selectedbuyerAndSellerReportingId gemeinsam mit buyerAndSellerReportingId (falls vorhanden), buyerReportingId (falls vorhanden), dem Inhaber der Interessengruppe, der URL des Gebotsscripts, der Render-URL und der Anzeigengröße k-anonym ist. Die Anzeigengröße ist bis mindestens Q1 2025 von dieser Prüfung ausgenommen.

Hinweis: Wenn generateBid() noch einmal ausgeführt wird, weil bei der ersten Ausführung keine Gebote mit Anzeigen erzielt wurden, die die K-Anonymitätsprüfung bestanden haben, sind bei der Wiederholung keine selectableBuyerAndSellerReportingIds in der Interessengruppe vorhanden, die die K-Anonymitätsprüfung nicht bestehen.

Bewertung von Verkäuferanzeigen

Für den Verkäufer wird die selectedBuyerAndSellerReportingId, die vom Käufer von generateBid() zurückgegeben wurde, in scoreAd() verfügbar, zusammen mit buyerAndSellerReportingId, sofern diese in der Konfiguration der Interessengruppe definiert wurde.

function scoreAd(..., browserSignals, ...) {
  const {
    buyerAndSellerReportingId, // 'bsrid123'
    selectedBuyerAndSellerReportingId, // 'sbsrid2'
  } = browserSignals;

  // ...
}

Verkäuferberichte

Für Verkäuferberichte ist die selectedBuyerAndSellerReportingId, die vom Käufer von generateBid() zurückgegeben wurde, in reportResult() zusammen mit buyerAndSellerReportingId verfügbar, sofern diese in der Interessengruppe definiert wurde.

function reportResult(..., browserSignals, ...) {
  const {
    buyerAndSellerReportingId, // 'bsrid123'
    selectedBuyerAndSellerReportingId // 'sbsrid2'
  } = browserSignals;
  
  // ...
}

Wenn selectableBuyerAndSellerReportingIds in der Konfiguration der Interessengruppe definiert und selectedBuyerAndSellerReportingId von generateBid() zurückgegeben wurde, kann die Auktion nur dann gewonnen werden, wenn selectedBuyerAndSellerReportingId und buyerAndSellerReportingId (falls vorhanden) k-anonym mit dem Inhaber der Interessengruppe, der URL des Gebotsscripts, der Render-URL und der Anzeigengröße sind (die Anzeigengröße ist bis mindestens Q1 2025 von dieser Prüfung ausgenommen) und reportResult() für dieses Gebot nicht ausgeführt wird. Wenn reportResult() also mit einem Wert für selectedBuyerAndSellerReportingId aufgerufen wird, haben die Berichts-IDs die K-Anonymitätsprüfung bestanden und alle definierten Berichts-IDs sind in reportResult() verfügbar.

Käuferberichte

Wenn selectableBuyerAndSellerReportingIds in der Interessengruppenkonfiguration definiert wurde und selectedBuyerAndSellerReportingId von generateBid() zurückgegeben wurde, sind alle Berichts-IDs verfügbar, die in der Interessengruppenkonfiguration definiert wurden. Ähnlich wie bei Verkäuferberichten können Gebote, deren Berichts-IDs nicht k-anonym sind, die Auktion nicht gewinnen und reportWin() wird für dieses Gebot nicht ausgeführt.

function reportWin(..., browserSignals, ...) {
  const {
    buyerReportingId, // 'brid123'
    buyerAndSellerReportingId, // 'bsrid123'
    selectedBuyerAndSellerReportingId // 'sbsrid2'
  } = browserSignals;

  // ...
}

Regeln überschreiben

Im Folgenden finden Sie eine Zusammenfassung der Überschreibungsregeln für nicht auswählbare und auswählbare Berichts-IDs. Welcher von selectableBuyerAndSellerReportingIds, buyerAndSellerReportingId, buyerReportingId und dem Namen der Interessengruppe an reportWin() übergeben wird, wird vom Browser anhand der folgenden Logik bestimmt:

• Wenn selectedBuyerAndSellerReportingId von einem Gebot zurückgegeben wird, sind selectedBuyerAndSellerReportingId, buyerAndSellerReportingId (falls in der Interessengruppe definiert) und buyerReportingId (falls in der Interessengruppe definiert) für Berichte verfügbar.
• Wenn buyerAndSellerReportingId in der Interessengruppe definiert ist, ist nur buyerAndSellerReportingId für Berichte verfügbar.
• Wenn buyerReportingId in der Interessengruppe definiert ist, ist nur buyerReportingId für Berichte verfügbar.
• Andernfalls ist nur die Interessengruppe name für die Berichterstellung verfügbar.

In der folgenden Tabelle wird das Überschreibungsverhalten beschrieben:

Sind die IDs für die Berichterstellung in der Konfiguration der Interessengruppe definiert?			Verfügbare Berichts-IDs
selectableBuyerAnd SellerReportingIds	buyerAndSeller ReportingId	buyerReportingId	reportWin()	reportResult()
Ja und in generateBid() ausgewählt	Optional	Optional	1) selectedBuyerAnd SellerReportingIds 2) buyerAndSeller ReportingId (falls definiert) 3) buyerReportingId (falls definiert)	1) selectedBuyerAnd SellerReportingIds 2) buyerAndSeller ReportingId (falls definiert)
Nein oder nicht ausgewählt in generateBid()	Ja	Ignoriert	buyerAndSeller ReportingId	buyerAndSeller ReportingId
Nein oder nicht ausgewählt in generateBid()	Nein	Ja	buyerReportingId	Keine
Nein oder nicht ausgewählt in generateBid()	Nein	Nein	interestGroupName	Keine

Mit Nutzern interagieren und Feedback geben

• Weitere Informationen zu Identitäten für die Berichterstellung finden Sie im Abschnitt „Identität für die Berichterstellung“ der Erläuterung zu geschützten Zielgruppen.
• GitHub: Stellen Sie Fragen und verfolgen Sie die Diskussion in den Issues im API-Repository.
• W3C: Im WICG-Anruf werden Anwendungsfälle nach Branche besprochen.
• Ankündigungen: Sie können der Mailingliste beitreten oder sie ansehen.
• Privacy Sandbox-Entwicklersupport: Im Repository für den Privacy Sandbox-Entwicklersupport können Sie Fragen stellen und an Diskussionen teilnehmen.
• Chromium: Fügen Sie einen Chromium-Fehler hinzu, um Fragen zur Implementierung zu stellen, die in Chrome getestet werden kann.