Attributionsquellen registrieren

Informationen zum Registrieren von Quellen, um Klicks und Aufrufe den entsprechenden Ereignissen zuzuordnen

Eine Attributionsquelle ist ein anzeigenbezogenes Ereignis (ein Klick oder eine Impression), an das eine Ad-Tech-Plattform die folgenden Arten von Informationen anhängen kann:

• Kontextbezogene Berichtsdaten wie die ID des Anzeigen-Creatives, Informationen zur Kampagne oder geografische Daten.
• Ein Conversion-Ziel, also die Website, auf der Nutzer Ihrer Erwartung nach Conversions ausführen.

Wenn Sie die Schritte in diesem Dokument ausführen, können Sie Quellen (Anzeigenimpressionen oder ‑klicks) registrieren, denen der Browser dann Conversions zuordnet.

Registrierungsmethoden

Verwenden Sie zum Registrieren von Attributionsquellen HTML-Elemente oder JavaScript-Aufrufe:

• <a>-Tag
• <img>-Tag
• <script>-Tag
• fetch Anruferweiterung
• XMLHttpRequest
• window.open Anruferweiterung

Dadurch werden Netzwerkanfragen generiert, auf die Sie mit einem HTTP-Antwortheader für die Quellregistrierung antworten.

Quellen für Klicks oder Aufrufe registrieren

So registrieren Sie eine Attributionsquelle für Klicks oder Aufrufe: Vollständige Anleitung Hier die Zusammenfassung:

1. Quellenregistrierung starten Verwenden Sie ein HTML-Element oder einen JavaScript-Aufruf, um eine Anfrage zu stellen. Dieser Schritt unterscheidet sich für Klicks und Aufrufe, wie Sie in den folgenden Abschnitten sehen werden.

2. Schließen Sie die Quellenregistrierung ab, indem Sie mit dem Header für die Quellenregistrierung antworten. Antworten Sie auf diese Anfrage mit dem Header Attribution-Reporting-Register-Source. Geben Sie in diesem Header die ausgewählte Attribution Reporting-Konfiguration an. Dieser Schritt ist für Klicks und Aufrufe identisch.

   Beispiel für Zusammenfassungsberichte:

   {
     "aggregation_keys": {
       "campaignCounts": "0x159",
       "geoValue": "0x5"
     },
     "aggregatable_report_window": "86400",
     "destination": "https://example.com"
   }
   

   Beispiel für Berichte auf Ereignisebene:

   {
     "source_event_id": "12340873456",
     "destination": "[eTLD+1]",
     "expiry": "[64-bit signed integer]",
     "priority": "[64-bit signed integer]",
     "event_report_window": "[64-bit signed integer]"
   }
   

Erforderliche und optionale Attribute

Wenn Sie HTML-Elemente verwenden oder JavaScript-Aufrufe zum Registrieren von Quellen ausführen, müssen Sie möglicherweise attributionsrc oder attributionReporting verwenden. In der folgenden Tabelle finden Sie Informationen dazu, wann diese erforderlich sind.

Wenn attributionsrc optional ist, wird durch die Verwendung angegeben, dass die Anfrage für Attribution Reporting infrage kommt. Wenn Sie attributionsrc verwenden, sendet der Browser den Header Attribution-Reporting-Eligible. Er ist auch für die App-zu-Web-Analyse nützlich: Wenn attributionsrc vorhanden ist, sendet der Browser den Attribution-Reporting-Support-Header.

Schritt 1: Quellenregistrierung starten

Schritt 1 ist für Klicks und Aufrufe unterschiedlich.

Wenn Sie eine Attributionsquelle für einen Klick registrieren möchten, können Sie ein <a>-Tag oder JavaScriptwindow.open() verwenden.

Anker verwenden

Fügen Sie attributionsrc den vorhandenen <a>-Tags hinzu, für die Sie Impressionen oder Klicks erfassen möchten:

<a href="https://shoes.example/..." attributionsrc>Click me</a>

Weitere Informationen finden Sie im Beispielcode.

Skript verwenden

Rufe window.open() mit attributionsrc an:

window.open(
  "https://shoes.example/...",
  "_blank",
  "attributionsrc");

Damit diese Methode berücksichtigt wird, muss sie innerhalb von 5 Sekunden nach der Nutzerinteraktion aufgerufen werden.

Anstelle von attributionsrc können Sie für ein Bild oder Skript einen einzelnen URL-Wert angeben:

<a href=... attributionsrc="https://a.example/register-source">Click me</a>

Wenn Sie attributionsrc in JavaScript einen Wert zuweisen, müssen Sie die URL codieren, falls sie Sonderzeichen wie = enthält, die dazu führen würden, dass der Parameter nicht richtig geparst wird.

So codieren Sie:

const encodedUrl = encodeURIComponent(
  "https://adtech.example/attribution_source?ad_id=...");
window.open(
  "https://shoes.example/landing",
   "_blank",
   `attributionsrc=${encodedUrl}`);

attributionsrc kann auch eine durch Leerzeichen getrennte Liste von URLs enthalten, wie hier mit einem <a>-Tag veranschaulicht:

<a href=... attributionsrc="https://a.example/register-source
  https://b.example/register-source">Click me</a>

oder wie hier mit window.open().

window.open("...", "_blank", `attributionsrc=${encodedUrl1}
  attributionsrc=${encodedUrl2}`)

In solchen Fällen erhalten beide URLs attributionsrc-Anfragen, die für die Navigationsquelle infrage kommen (Anfragen mit dem Header Attribution-Reporting-Eligible).

attributionsrc mit oder ohne Wert

Wie Sie bereits gesehen haben, können Sie attributionsrc ohne URL angeben. Sie können auch eine einzelne URL angeben. Alternativ können Sie eine durch Leerzeichen getrennte Liste mit URLs verwenden.

Wenn Sie URLs verwenden, initiiert der Browser eine separate Keep-Alive-Abrufanfrage – eine für jede URL –, die den Attribution-Reporting-Eligible-Anfrageheader enthält.

Dies ist nützlich, wenn Sie die Quellregistrierung durchführen möchten, indem Sie auf eine Anfrage antworten, die sich von der Hauptanfrage des Elements unterscheidet.

Wenn Sie beispielsweise Quellen für Klicks auf ein Anker-Element registrieren müssen, haben Sie möglicherweise keine Kontrolle über das Ziel. In diesem Fall benötigen Sie eine Konfiguration, bei der Sie den Header für die Quellregistrierung als Antwort auf eine Anfrage senden, die von der Navigation getrennt ist und die Sie vollständig kontrollieren können. Wenn Sie einen expliziten Wert für attributionsrc angeben, weisen Sie den Browser an, diese zusätzliche Anfrage zu senden, und konfigurieren das Ziel.

Wenn Sie eine Attributionsquelle für eine Ansicht registrieren möchten, können Sie ein Bild- oder Script-Tag verwenden, dem Sie das Attribut attributionsrc hinzufügen.

Alternativ können Sie JavaScript fetch() oder XMLHttpRequest() verwenden.

Mit einem Bild

<img attributionsrc
src="https://adtech.example/attribution_source?ad_id=...">

Mit einem Script

<script attributionsrc
  src="https://adtech.example/attribution_source?ad_id=..."></script>

Optional können Sie einen URL-Wert für attributionsrc auf dieselbe Weise wie für Klicks angeben. Das heißt, für ein Bild oder ein Script können Sie die attributionsrc-URL(s) so festlegen:

Mit einer einzelnen URL:

<img attributionsrc="https://adtech.example/attribution_source?ad_id=123">

Mit einer Liste von URLs:

<img attributionsrc="https://a.example/register-source
  https://b.example/register-source">

fetch() oder XMLHttpRequest() verwenden

Dieser Code simuliert im Grunde, was bei einer HTML-Anfrage mit attributionsrc passieren würde:

const attributionReporting = {
  eventSourceEligible: true,
  triggerEligible: false,
};

// Optionally set keepalive to make sure the request outlives the page.
window.fetch("https://adtech.example/attribution_source?my_ad_id=123",
  { keepalive: true, attributionReporting });

const attributionReporting = {
  eventSourceEligible: true,
  triggerEligible: false,
};

const req = new XMLHttpRequest();
req.open("GET", url);
req.setAttributionReporting(attributionReporting);
req.send();

Schritt 2: Mit Header antworten (Klicks und Aufrufe)

Der nächste Schritt für Klicks und Aufrufe besteht darin, mit dem Attribution-Reporting-Register-Source-Header zu antworten.

Weitere Informationen finden Sie im Beispielcode.

Wenn Sie die Browseranfrage auf dem Server empfangen, antworten Sie und fügen Sie in Ihre Antwort den Attribution-Reporting-Register-Source-Header ein.

res.set(
  "Attribution-Reporting-Register-Source",
  JSON.stringify({
    // Use source_event_id to map it to any granular information
    // you need at ad-serving time
    source_event_id: "412444888111012",
    destination: "https://advertiser.example",
    // Optional fields
    expiry: "604800",
    priority: "100",
    debug_key: "122939999"
  })
);

Nach der Stringifizierung sieht der Header so aus:

{"source_event_id":"412444888111012","destination":"https://advertiser.example","expiry":"604800","priority":"100","debug_key":"122939999"}

Nächste Schritte

Attributions-Trigger registrieren