Signatur
Beschreibung
setPrivateToken() gehört zur Private State Token API (früher „Trust Tokens“). Damit können Websites Vertrauenssignale („dieser Nutzer ist vermutlich kein Bot“) seitenübergreifend weitergeben, ohne dass der Nutzer darüber verfolgt werden kann. Ein Aussteller (Issuer) gibt kryptografisch verblindete Token aus. Andere Seiten können sie später einlösen und bekommen dafür einen Einlösungsnachweis (Redemption Record, RR), den sie an ihre Server schicken.
Die Methode legt fest, welche dieser Operationen der folgende Request ausführen soll. Die Werte entsprechen der Option privateToken von fetch():
"token-request": neue Token beim Aussteller anfordern."token-redemption": ein vorhandenes Token einlösen und einen Einlösungsnachweis erhalten."send-redemption-record": gespeicherte Einlösungsnachweise der angegebenen Aussteller im HeaderSec-Redemption-Recordan den Zielserver mitsenden.
Rufe die Methode nach open() und vor send() auf. Den kryptografischen Teil (Header Sec-Private-State-Token) erledigt der Browser selbst. Dein Code legt nur die Operation fest und bestimmt, an welchen Server der Request geht. Für neuen Code ist meist fetch() mit der Option privateToken die bessere Wahl. setPrivateToken() ist für bestehenden Code gedacht, der auf XMLHttpRequest aufbaut.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $privateToken Pflicht | Object | Objekt, das die Token-Operation beschreibt. Enthält folgende Eigenschaften:
|
Rückgabewert
undefined). Das Ergebnis der Operation kommt erst mit der Antwort des Requests. Beim Token-Abruf speichert der Browser die Token intern, beim Einlösen den Einlösungsnachweis.Beispiele
Token beim Aussteller anfordern (Ausgabe)
const issuer = 'https://issuer.example';
// Nur Token anfordern, wenn noch keine vorhanden sind
const hasToken = await document.hasPrivateToken(issuer);
if (!hasToken) {
const xhr = new XMLHttpRequest();
xhr.open('GET', `${issuer}/.well-known/private-state-token/issuance`);
xhr.setPrivateToken({
version: 1,
operation: 'token-request'
});
xhr.onload = () => console.log('Token-Ausgabe abgeschlossen, Status:', xhr.status);
xhr.onerror = () => console.error('Token-Ausgabe fehlgeschlagen');
xhr.send();
}Token einlösen und Einlösungsnachweis erzwingen
const issuer = 'https://issuer.example';
const xhr = new XMLHttpRequest();
xhr.open('GET', `${issuer}/.well-known/private-state-token/redemption`);
try {
xhr.setPrivateToken({
version: 1,
operation: 'token-redemption',
refreshPolicy: 'refresh' // neuen Nachweis erzwingen statt Cache nutzen
});
xhr.onload = async () => {
const hasRecord = await document.hasRedemptionRecord(issuer);
console.log('Einlösungsnachweis vorhanden:', hasRecord);
};
xhr.send();
} catch (err) {
// z. B. NotAllowedError, wenn die Permissions Policy die Einlösung verbietet
console.error(`${err.name}: ${err.message}`);
}Einlösungsnachweis an den eigenen Server senden
const sendTrustSignal = (payload) => new Promise((resolve, reject) => {
const xhr = new XMLHttpRequest();
xhr.open('POST', '/api/checkout');
xhr.setRequestHeader('Content-Type', 'application/json');
// Der Browser hängt den Header Sec-Redemption-Record an
xhr.setPrivateToken({
version: 1,
operation: 'send-redemption-record',
issuers: ['https://issuer.example']
});
xhr.onload = () => resolve(xhr.status);
xhr.onerror = () => reject(new Error('Netzwerkfehler'));
xhr.send(JSON.stringify(payload));
});
const status = await sendTrustSignal({ cartId: 42 });
console.log('Server-Antwort:', status);Feature-Erkennung vor der Nutzung
const supportsPrivateTokens =
typeof XMLHttpRequest !== 'undefined' &&
'setPrivateToken' in XMLHttpRequest.prototype;
console.log(supportsPrivateTokens
? 'Private State Tokens per XHR verfügbar'
: 'Nicht unterstützt – auf andere Anti-Betrugs-Maßnahmen ausweichen');// Wichtig · Fallstricke
Kompatibilität: Die API ist experimentell und nicht standardisiert. Sie läuft nur in Chromium-basierten Browsern (Chrome, Edge, Opera). Firefox und Safari unterstützen sie nicht. Prüfe deshalb immer vorher, ob setPrivateToken vorhanden ist, und sieh eine Alternative vor.
Aufrufreihenfolge: Wird die Methode vor open() oder nach send() aufgerufen, wirft sie eine InvalidStateError-DOMException.
Permissions Policy: Die Ausgabe erfordert die Direktive private-state-token-issuance, das Einlösen und Senden private-state-token-redemption. Blockiert die Policy die Operation, zum Beispiel in einem eingebetteten iframe ohne allow-Attribut, entsteht eine NotAllowedError. Ein fehlerhaftes privateToken-Objekt (etwa send-redemption-record ohne issuers) führt zu einem TypeError.
Weitere Fallstricke:
- Aussteller müssen bei Chrome registriert sein. Nicht registrierte Aussteller werden ignoriert.
- Die Zahl der Einlösungen pro Aussteller und Top-Level-Seite ist begrenzt (Rate-Limit). Mit
refreshPolicy: "refresh"verbrauchst du dieses Kontingent schnell. - Einlösungsnachweise sind nur ein Vertrauenssignal und kein Identitätsnachweis. Dein Server muss sie selbst prüfen, zum Beispiel über Signatur und Ablaufdatum.