Signatur
Beschreibung
Die Methode toJSON() ist der Serialisierer der Schnittstelle NavigatorUAData aus der User-Agent Client Hints API. Sie liefert ein einfaches JavaScript-Objekt mit den Low-Entropy-Werten, die der Browser ohne weitere Nachfrage herausgibt: brands, mobile und platform.
Die Methode wird meist nicht direkt aufgerufen. JSON.stringify(navigator.userAgentData) ruft sie automatisch auf. Ohne toJSON() käme dabei nur {} heraus, weil die Eigenschaften als Getter am Prototyp liegen und keine eigenen, aufzählbaren Eigenschaften sind.
Typische Einsatzfälle sind Logging, Telemetrie und Fehlerberichte: Man sendet die Low-Entropy-Daten an einen Server oder speichert sie. High-Entropy-Werte wie platformVersion, architecture, model oder fullVersionList gehören nicht dazu. Diese muss man asynchron über getHighEntropyValues() abfragen.
Rückgabewert
brands, mobile und platform.Beispiele
Low-Entropy-Daten direkt auslesen
if ('userAgentData' in navigator) {
const data = navigator.userAgentData.toJSON();
console.log(data.platform, data.mobile);
console.log(data.brands.map(b => `${b.brand} ${b.version}`).join(', '));
} else {
console.log('User-Agent Client Hints nicht unterstützt');
}Automatische Serialisierung mit JSON.stringify
const ua = navigator.userAgentData;
// JSON.stringify ruft intern ua.toJSON() auf
console.log(JSON.stringify(ua));Fehlerbericht mit Low- und High-Entropy-Daten senden
const reportError = async (error) => {
const ua = navigator.userAgentData;
let client = { userAgent: navigator.userAgent };
if (ua) {
const high = await ua.getHighEntropyValues(['platformVersion', 'architecture']);
client = { ...ua.toJSON(), ...high };
}
await fetch('/api/errors', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ message: error.message, client })
});
};
window.addEventListener('error', (e) => reportError(e.error ?? new Error(e.message)));// Wichtig · Fallstricke
- Kompatibilität:
navigator.userAgentDatagibt es nur in Chromium-Browsern und nur in sicheren Kontexten (HTTPS). Firefox und Safari unterstützen die API nicht. Prüfen Sie deshalb immer zuerst mit'userAgentData' in navigator. - Der Rückgabewert ist ein Objekt, kein String. Einen JSON-String erhalten Sie erst mit
JSON.stringify(). - High-Entropy-Werte wie
platformVersion,modeloderfullVersionListsind nicht enthalten. Nutzen Sie dafürgetHighEntropyValues(). - Die
brands-Liste enthält absichtlich eine Pseudo-Marke (z. B."Not-A.Brand") in zufälliger Reihenfolge („GREASE“). Werten Sie deshalb nie Position oder Anzahl der Einträge aus, sondern suchen Sie gezielt nach dem Markennamen. - Datenschutz: Auch Low-Entropy-Daten können zum Fingerprinting beitragen. Übertragen Sie sie nur, wenn Sie sie wirklich brauchen.