Navigator.userAgentData — Eigenschaft · JavaScript-Referenz

Signatur

Navigator.userAgentData

Beschreibung

Die schreibgeschützte Eigenschaft navigator.userAgentData liefert ein NavigatorUAData-Objekt. Es ist der moderne, datenschutzfreundlichere Nachfolger des klassischen navigator.userAgent-Strings. Statt einen langen, schwer auszuwertenden String zu parsen, bekommen Sie strukturierte Daten.

Gering-entropische Werte sind sofort verfügbar: brands (Array aus { brand, version }), mobile (boolean) und platform (z. B. "Windows", "macOS", "Android"). Hoch-entropische Werte wie genaue Browserversion (fullVersionList), Betriebssystemversion (platformVersion), Architektur, Bitness oder Gerätemodell müssen Sie ausdrücklich und asynchron über getHighEntropyValues() anfordern.

Einsatz: Statistik, Fehlerberichte, plattformspezifische Download-Links oder Tastenkürzel-Hinweise (⌘ vs. Strg). Für die Prüfung, ob ein Feature vorhanden ist, bleibt Feature Detection trotzdem der bessere Weg als die Erkennung des Browsers.

Rückgabewert

Typ

NavigatorUAData | undefined

Beschreibung

Ein NavigatorUAData-Objekt mit brands, mobile, platform sowie den Methoden getHighEntropyValues(hints) und toJSON(). In Browsern ohne Unterstützung oder in unsicheren Kontexten ist die Eigenschaft undefined.

Beispiele

Gering-entropische Werte mit Fallback auslesen

const uaData = navigator.userAgentData;

if (uaData) {
  console.log('Plattform:', uaData.platform);
  console.log('Mobil:', uaData.mobile);
  console.log('Marken:', uaData.brands.map(b => `${b.brand} ${b.version}`).join(', '));
} else {
  // Firefox/Safari: auf klassischen UA-String zurückfallen
  console.log('Fallback:', navigator.userAgent);
}

Plattform: Windows Mobil: false Marken: Chromium 124, Google Chrome 124, Not-A.Brand 99

Hoch-entropische Werte asynchron anfordern

const getDeviceInfo = async () => {
  if (!navigator.userAgentData) return null;
  const info = await navigator.userAgentData.getHighEntropyValues([
    'platformVersion',
    'architecture',
    'bitness',
    'model',
    'fullVersionList'
  ]);
  return info;
};

getDeviceInfo().then(info => console.log(info));

{ architecture: 'x86', bitness: '64', brands: [...], fullVersionList: [...], mobile: false, model: '', platform: 'Windows', platformVersion: '15.0.0' }

Echte Browsermarke erkennen und Tastenkürzel anpassen

const uaData = navigator.userAgentData;

// "Not A Brand"-Einträge (GREASE) herausfiltern
const realBrands = uaData?.brands.filter(b => !/not.?a.?brand/i.test(b.brand)) ?? [];
const isChrome = realBrands.some(b => b.brand === 'Google Chrome');

const isMac = uaData
  ? uaData.platform === 'macOS'
  : /Mac/.test(navigator.userAgent);

document.querySelector('#hint').textContent =
  `Speichern mit ${isMac ? '⌘' : 'Strg'} + S`;
console.log({ isChrome, isMac });

{ isChrome: true, isMac: false }

// Wichtig · Fallstricke

Browser-Kompatibilität: Nur Chromium-basierte Browser (Chrome, Edge, Opera, Samsung Internet). Firefox und Safari unterstützen die Eigenschaft nicht. Prüfen Sie deshalb immer mit if (navigator.userAgentData) oder optionaler Verkettung (?.).
Sicherer Kontext: Nur über HTTPS bzw. localhost verfügbar. Seit Chrome 110 auch in Web Workern über WorkerNavigator.userAgentData.
GREASE: brands enthält absichtlich Fantasie-Einträge wie "Not-A.Brand" in wechselnder Reihenfolge. Verlassen Sie sich nie auf den Index oder auf eine feste Reihenfolge.
Hoch-entropische Werte: Der Browser kann getHighEntropyValues() ablehnen (Promise wird mit NotAllowedError abgelehnt) oder Werte weglassen bzw. verallgemeinern. Außerdem kann eine Permissions-Policy die Werte in iframes einschränken.
Windows 11: Nur platformVersion ab "13.0.0" weist auf Windows 11 hin. Der klassische UA-String meldet weiterhin „Windows NT 10.0“.
Datenschutz: Fordern Sie nur die Werte an, die Sie wirklich brauchen, denn hoch-entropische Daten erleichtern Fingerprinting.
Serverseitig bekommen Sie dieselben Informationen über die HTTP-Header Sec-CH-UA*. Zusätzliche Header fordern Sie mit Accept-CH an.

Siehe auch

Navigator.userAgent NavigatorUAData NavigatorUAData.getHighEntropyValues() Navigator.platform Navigator WorkerNavigator.userAgentData NavigateEvent.userInitiated