Signatur
Beschreibung
self.navigator.userAgentData ist das Gegenstück zu navigator.userAgentData im Hauptthread. Die Eigenschaft steht in Dedicated, Shared und Service Workern zur Verfügung und gibt ein NavigatorUAData-Objekt zurück. Darüber kann ein Worker Informationen über Browser und Plattform in strukturierter Form auslesen, ohne den fehleranfälligen userAgent-String zu parsen.
Das Objekt stellt sofort nur wenige Informationen mit geringer Entropie bereit: brands (Liste von Marke und Hauptversion), mobile (boolean) und platform (z. B. "Windows"). Detailliertere Werte mit hoher Entropie wie platformVersion, architecture, model oder fullVersionList müssen Sie ausdrücklich und asynchron über getHighEntropyValues() anfordern. Der Browser kann das ablehnen oder die Werte verallgemeinern.
Typische Anwendungsfälle sind die Telemetrie in einem Service Worker (z. B. Plattform zu Fehlerberichten hinzufügen), das Laden plattformabhängiger Ressourcen in einem Worker oder die Protokollierung. Zur Erkennung von Funktionen sollten Sie trotzdem vorrangig die Feature-Erkennung nutzen und nicht die Browser-Erkennung.
Rückgabewert
NavigatorUAData-Objekt mit den Eigenschaften brands, mobile und platform sowie den Methoden getHighEntropyValues() und toJSON(). In Browsern ohne Unterstützung (oder in unsicheren Kontexten) ist die Eigenschaft undefined.Beispiele
Werte mit geringer Entropie im Worker auslesen
// worker.js
const uaData = self.navigator.userAgentData;
if (uaData) {
const brands = uaData.brands.map(({ brand, version }) => `${brand} ${version}`);
console.log('Marken:', brands.join(', '));
console.log('Mobil:', uaData.mobile);
console.log('Plattform:', uaData.platform);
} else {
// Fallback für Firefox/Safari
console.log('UA-String:', self.navigator.userAgent);
}Werte mit hoher Entropie asynchron anfordern
// worker.js
const getPlatformDetails = async () => {
const uaData = self.navigator.userAgentData;
if (!uaData) return null;
const details = await uaData.getHighEntropyValues([
'architecture',
'bitness',
'platformVersion',
'fullVersionList'
]);
return details;
};
getPlatformDetails().then((details) => {
self.postMessage({ type: 'ua-details', details });
});Service Worker: Plattform in Fehlerberichte aufnehmen
// sw.js
const clientInfo = () => {
const ua = self.navigator.userAgentData;
return ua ? ua.toJSON() : { userAgent: self.navigator.userAgent };
};
self.addEventListener('error', (event) => {
fetch('/api/errors', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ message: event.message, client: clientInfo() })
});
});// Wichtig · Fallstricke
- Browser-Kompatibilität: Wird nur von Chromium-basierten Browsern unterstützt (Chrome, Edge, Opera, Samsung Internet). Firefox und Safari stellen die API nicht bereit. Prüfen Sie deshalb immer mit
if (self.navigator.userAgentData), ob sie vorhanden ist, und sehen Sie einen Ersatzweg vor. - Nur sichere Kontexte: Die Eigenschaft steht nur über HTTPS oder
localhostzur Verfügung. - Experimentell: Die Spezifikation ist ein Entwurf der WICG und kein fertiger Standard. Die Eigenschaften können sich noch ändern.
- GREASE:
brandsenthält absichtlich Fantasie-Einträge wie"Not-A.Brand", und die Reihenfolge wechselt. Suchen Sie gezielt nach einer bestimmten Marke und verlassen Sie sich nicht auf eine Position im Array. - Datenschutz:
getHighEntropyValues()kann vom Browser eingeschränkt oder abgelehnt werden (Promise wird mitNotAllowedErrorabgelehnt). Fordern Sie nur die Werte an, die Sie wirklich brauchen, da sie zum Fingerprinting beitragen. - Serverseitig stehen dieselben Informationen über die HTTP-Header
Sec-CH-UA*bereit. Werte mit hoher Entropie müssen dort perAccept-CHangefordert werden.