HTMLIFrameElement.privateToken — Eigenschaft · JavaScript-Referenz

Signatur

HTMLIFrameElement.privateToken

Beschreibung

Die Eigenschaft privateToken spiegelt das Attribut privatetoken eines <iframe>-Elements. Sie gehört zur Private State Token API (früher „Trust Tokens“). Mit ihr kann eine Seite Vertrauenssignale, z. B. „dieser Nutzer ist kein Bot“, über Website-Grenzen hinweg weitergeben, ohne dass der Nutzer dabei wiedererkennbar wird.

Der Wert ist eine Zeichenkette mit einem serialisierten JSON-Objekt. Dessen Felder entsprechen der Option privateToken von fetch(). Setzt man das Attribut, führt der Browser die angegebene Token-Operation beim Navigieren des Frames aus. Das Ergebnis, etwa ein Einlösungsnachweis (Redemption Record), wird dann im Header der Anfrage an die Frame-URL mitgeschickt.

Typische Anwendungsfälle:

eingebettete Werbung oder Widgets, die einen Einlösungsnachweis eines vertrauenswürdigen Token-Ausstellers (Issuer) erhalten sollen
Betrugs- und Bot-Erkennung in Drittanbieter-Frames, ohne Cookies von Drittanbietern zu nutzen

Wichtige Felder des Objekts: version (derzeit 1), operation (z. B. "token-redemption" oder "send-redemption-record"), refreshPolicy ("none" oder "refresh") und issuers (ein Array mit Issuer-Origins, nötig bei "send-redemption-record").

Parameter

Name	Typ	Default	Beschreibung
$version Pflicht	number	1	Version des Private-State-Token-Protokolls. Derzeit ist nur `1` gültig.
$operation Pflicht	"token-redemption" \| "send-redemption-record" \| "token-request"		Die auszuführende Operation. In iframes sind vor allem `"token-redemption"` und `"send-redemption-record"` sinnvoll. Tokens anfordern (`"token-request"`) geschieht normalerweise per `fetch()`.
$refreshPolicy	"none" \| "refresh"	"none"	Nur bei `"token-redemption"`: Mit `"refresh"` wird ein neuer Einlösungsnachweis erzwungen, auch wenn noch ein gültiger im Cache liegt.
$issuers	string[]		Liste der Issuer-Origins, deren Einlösungsnachweise mitgesendet werden sollen. Pflicht bei `"send-redemption-record"`.

Rückgabewert

Typ

string

Beschreibung

Der aktuelle Wert des Attributs privatetoken als JSON-Zeichenkette. Ist das Attribut nicht gesetzt, ist der Wert ein leerer String "". Beim Setzen wird der String unverändert ins Attribut übernommen.

Beispiele

Einlösungsnachweis an ein eingebettetes Widget senden

const frame = document.createElement('iframe');

// Optionen als JSON-String – kein Objekt zuweisen!
frame.privateToken = JSON.stringify({
  version: 1,
  operation: 'send-redemption-record',
  issuers: ['https://issuer.example']
});

frame.src = 'https://widget.example/embed';
document.body.append(frame);

console.log(frame.getAttribute('privatetoken'));

{"version":1,"operation":"send-redemption-record","issuers":["https://issuer.example"]}

Vorhandenen Wert auslesen und auswerten

// HTML: <iframe id="ad" src="https://ads.example/slot"
//   privatetoken='{"version":1,"operation":"token-redemption","refreshPolicy":"none"}'></iframe>
const ad = document.querySelector('#ad');

const raw = ad.privateToken;
const options = raw ? JSON.parse(raw) : null;
console.log(options?.operation);

token-redemption

Funktionserkennung vor der Nutzung

const supportsPST = 'privateToken' in HTMLIFrameElement.prototype;

const frame = document.createElement('iframe');
if (supportsPST) {
  frame.privateToken = JSON.stringify({
    version: 1,
    operation: 'token-redemption',
    refreshPolicy: 'refresh'
  });
} else {
  console.warn('Private State Tokens werden nicht unterstützt – Fallback nutzen.');
}
frame.src = 'https://partner.example/check';
document.body.append(frame);

// Wichtig · Fallstricke

Experimentell und nicht standardisiert: Nur Chromium-basierte Browser (Chrome, Edge) unterstützen die Eigenschaft. Firefox und Safari kennen sie nicht. Prüfe die Unterstützung vorher, z. B. mit 'privateToken' in HTMLIFrameElement.prototype.
String statt Objekt: Weise immer JSON.stringify(...) zu. Ein direkt zugewiesenes Objekt wird zu "[object Object]" und damit wirkungslos.
Zeitpunkt: Das Attribut wirkt nur bei der Navigation des Frames. Setze es also vor src bzw. vor dem Einfügen ins DOM. Ändert man es später, wird keine neue Operation ausgelöst.
Permissions Policy: Die Operationen brauchen die Berechtigungen private-state-token-redemption bzw. private-state-token-issuance. In Drittanbieter-Frames müssen sie gegebenenfalls über das Attribut allow freigegeben werden.
Nur sichere Kontexte: Die Eigenschaft funktioniert nur über HTTPS. Außerdem gibt es Ratenbegrenzungen für Einlösungen pro Issuer und Top-Level-Seite. Plane daher einen Fallback ein.
Datenschutz: Die Tokens enthalten bewusst nur wenige Bits an Information. Als Ersatz für Nutzerkennungen oder Tracking sind sie nicht geeignet.

Siehe auch

HTMLIFrameElement.browsingTopics HTMLIFrameElement.featurePolicy HTMLIFrameElement.allow HTMLIFrameElement.height HTMLIFrameElement.name