HTMLImageElement.attributionSrc — Eigenschaft · JavaScript-Referenz

Signatur

HTMLImageElement.attributionSrc

Beschreibung

Die Eigenschaft attributionSrc gehört zur Attribution Reporting API. Mit dieser API lassen sich Werbe-Conversions messen, ohne dass Drittanbieter-Cookies nötig sind. Die Eigenschaft spiegelt das HTML-Attribut attributionsrc wider. Ist sie gesetzt, schickt der Browser mit der Bildanfrage den Header Attribution-Reporting-Eligible mit. Der Server kann dann in seiner Antwort die Header Attribution-Reporting-Register-Source oder Attribution-Reporting-Register-Trigger zurückgeben. Damit registriert er eine Attributionsquelle (zum Beispiel eine Werbeeinblendung) oder einen Auslöser (zum Beispiel einen Kauf).

Es gibt zwei Varianten:

Leerer String: Der Header Attribution-Reporting-Eligible wird an den Server gesendet, auf den src zeigt. Die Registrierung läuft dann über die Antwort auf die Bildanfrage selbst.
Eine oder mehrere URLs, durch Leerzeichen getrennt: Der Browser schickt zusätzlich eigene Anfragen an diese URLs, jeweils mit dem Header. So kann ein anderer Server die Registrierung übernehmen, etwa wenn das Bild von einem CDN kommt, das Sie nicht selbst steuern.

In der Praxis dient das vor allem für Tracking-Pixel (1×1-Bilder), die eine Werbeeinblendung oder eine Conversion melden. Damit das Setzen per JavaScript wirkt, muss die Eigenschaft vor src gesetzt werden. Sonst ist die Anfrage womöglich schon ohne den Header unterwegs.

Rückgabewert

Typ

string

Beschreibung

Der aktuelle Wert des Attributs attributionsrc. Das kann ein leerer String sein oder eine Liste von URLs, die durch Leerzeichen getrennt sind. Wenn das Attribut fehlt, ist der Wert ebenfalls ein leerer String. Beim Schreiben wird der zugewiesene String als Attributwert übernommen.

Beispiele

Tracking-Pixel mit leerem attributionSrc erzeugen

// Werbeeinblendung als Attributionsquelle registrieren
const pixel = document.createElement('img');
pixel.width = 1;
pixel.height = 1;
pixel.alt = '';
// WICHTIG: vor src setzen, damit der Header mitgesendet wird
pixel.attributionSrc = '';
pixel.src = 'https://ads.example.com/impression?campaign=4711';
document.body.append(pixel);

console.log(pixel.hasAttribute('attributionsrc'));

true

Registrierung über separate Server-URLs

const img = document.createElement('img');
const sources = [
  'https://tracker-a.example/register-source?id=abc',
  'https://tracker-b.example/register-source?id=abc'
];
// Mehrere URLs durch Leerzeichen getrennt
img.attributionSrc = sources.map(encodeURI).join(' ');
img.src = 'https://cdn.example.net/banner.png';
img.alt = 'Sommerangebot';
document.querySelector('#ad-slot')?.append(img);

console.log(img.attributionSrc.split(' ').length);

2

Feature-Erkennung vor der Nutzung

const supportsAttribution = 'attributionSrc' in HTMLImageElement.prototype &&
  document.featurePolicy?.allowsFeature?.('attribution-reporting') !== false;

const trackConversion = (orderId) => {
  const img = new Image(1, 1);
  if (supportsAttribution) {
    img.attributionSrc = '';
  }
  img.src = `https://shop.example/conversion?order=${encodeURIComponent(orderId)}`;
};

trackConversion('A-1001');
console.log('Attribution Reporting unterstützt:', supportsAttribution);

Attribution Reporting unterstützt: true (in Chromium; sonst false)

// Wichtig · Fallstricke

Experimentell und nicht überall verfügbar: Die Eigenschaft gibt es nur in Chromium-Browsern. Firefox und Safari unterstützen sie nicht. Prüfen Sie daher vorher mit 'attributionSrc' in HTMLImageElement.prototype. In Browsern ohne Unterstützung legt eine Zuweisung nur eine gewöhnliche JavaScript-Eigenschaft an und hat keine Wirkung.
Reihenfolge beachten: Setzen Sie attributionSrc vor src. Ändern Sie die Eigenschaft erst später, wird eine Anfrage, die schon läuft, nicht nachträglich um den Header ergänzt.
Berechtigungsrichtlinie: Die Funktion wird über die Permissions Policy attribution-reporting gesteuert. In Cross-Origin-iframes muss sie gegebenenfalls ausdrücklich erlaubt werden, zum Beispiel mit allow="attribution-reporting".
Nur über HTTPS: Die URLs müssen aus einem sicheren Kontext stammen, also über HTTPS erreichbar sein. Der Server muss zudem die passenden Attribution-Reporting-Register-*-Header senden. Andernfalls wird nichts registriert.
Datenschutz: Die API wurde als Teil der Privacy Sandbox entwickelt. Berichte kommen verzögert und mit Rauschen versehen an. Nutzer können die Funktion in den Browsereinstellungen abschalten. Verlassen Sie sich also nicht darauf, dass jede Conversion gemeldet wird.
Bei <img> kann nur ein ereignisbasierter Auslöser oder eine Quelle registriert werden, keine Navigationsquelle. Navigationsquellen gibt es nur bei Links (HTMLAnchorElement.attributionSrc) und bei window.open().

Siehe auch

Window.open() HTMLImageElement.fetchPriority HTMLImageElement.currentSrc HTMLImageElement.align HTMLImageElement.naturalHeight