NavigatorUAData — Schnittstelle · JavaScript-Referenz

Signatur

interface NavigatorUAData

Beschreibung

NavigatorUAData ist die JavaScript-Seite der User-Agent Client Hints API. Eine Instanz erhält man über navigator.userAgentData (auch in Workern über WorkerNavigator.userAgentData). Einen eigenen Konstruktor gibt es nicht. Die Schnittstelle soll den schwer auswertbaren und datenschutzkritischen navigator.userAgent-String ablösen. Statt Browser, Version und Plattform per regulärem Ausdruck aus einem Freitext herauszulesen, bekommt man die Angaben hier strukturiert.

Die Daten sind in zwei Stufen aufgeteilt:

Niedrige Entropie (sofort und synchron verfügbar): brands (Array aus { brand, version } mit der Hauptversion), mobile (boolean) und platform (z. B. "Windows", "macOS", "Android").
Hohe Entropie (asynchron über getHighEntropyValues(hints)): zum Beispiel architecture, bitness, model, platformVersion, fullVersionList, wow64 und formFactors. Weil diese Werte zum Fingerprinting taugen, kann der Browser sie verzögern, verweigern oder leer zurückgeben.

Außerdem gibt es toJSON(). Die Methode liefert ein serialisierbares Objekt mit den Werten niedriger Entropie, praktisch für Logging oder zum Senden an den Server. Setzen Sie die API vor allem für progressive Verbesserung und Statistik ein. Für Funktionen des Browsers ist Feature-Detection weiterhin die bessere Wahl als die Erkennung des Browsers.

Parameter

Name	Typ	Default	Beschreibung
$hints Pflicht	string[]		Nur für `getHighEntropyValues()`: Liste der gewünschten Hinweise, z. B. `["architecture", "bitness", "model", "platformVersion", "fullVersionList", "wow64", "formFactors"]`. Unbekannte Werte werden ignoriert.

Rückgabewert

Typ

NavigatorUAData

Beschreibung

Das Objekt aus navigator.userAgentData mit den Eigenschaften brands, mobile und platform. getHighEntropyValues() gibt ein Promise<UADataValues> zurück, das immer auch die Werte niedriger Entropie enthält. toJSON() gibt ein einfaches Objekt zurück.

Beispiele

Instanz beziehen und Werte niedriger Entropie lesen

const uaData = navigator.userAgentData;

if (uaData) {
  console.log(uaData.platform);
  console.log(uaData.mobile);
  console.log(uaData.brands.map(({ brand, version }) => `${brand} ${version}`));
} else {
  // Fallback für Firefox/Safari
  console.log('Nicht unterstützt:', navigator.userAgent);
}

Windows false ["Chromium 124", "Google Chrome 124", "Not-A.Brand 99"]

Browser-Marke robust erkennen (GREASE-Einträge ignorieren)

const getBrowser = () => {
  const brands = navigator.userAgentData?.brands ?? [];
  // Absichtlich eingestreute Fantasie-Marken wie "Not-A.Brand" herausfiltern
  const real = brands.filter(({ brand }) => !/not.?a.?brand/i.test(brand));
  const preferred = real.find(({ brand }) => brand !== 'Chromium') ?? real[0];
  return preferred ? `${preferred.brand} ${preferred.version}` : 'unbekannt';
};

console.log(getBrowser());

Google Chrome 124

Werte hoher Entropie asynchron abfragen

const loadDetails = async () => {
  if (!navigator.userAgentData?.getHighEntropyValues) return null;
  try {
    const values = await navigator.userAgentData.getHighEntropyValues([
      'architecture',
      'bitness',
      'platformVersion',
      'fullVersionList'
    ]);
    return values;
  } catch (err) {
    // NotAllowedError, wenn der Browser die Anfrage ablehnt
    console.warn('Abgelehnt:', err.name);
    return null;
  }
};

const details = await loadDetails();
console.log(details?.architecture, details?.bitness, details?.platformVersion);

x86 64 15.0.0

Daten per toJSON() an den Server senden

const sendStats = async () => {
  const uaData = navigator.userAgentData;
  if (!uaData) return;
  await fetch('/api/stats', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ ua: uaData.toJSON(), ts: Date.now() })
  });
};

sendStats();

// Wichtig · Fallstricke

Browser-Kompatibilität: Die API gibt es nur in Chromium-Browsern (Chrome, Edge, Opera, Samsung Internet). Firefox und Safari unterstützen sie nicht, dort ist navigator.userAgentData undefined. Prüfen Sie deshalb immer mit optionaler Verkettung (?.) und sehen Sie einen Fallback vor.
Nur in sicheren Kontexten: Die API steht nur unter HTTPS oder localhost zur Verfügung.
GREASE: brands enthält absichtlich Fantasie-Einträge wie "Not-A.Brand" in wechselnder Reihenfolge. Verlassen Sie sich nie auf einen festen Index oder einen exakten Namen.
Nur die Hauptversion: brands[].version enthält nur die Hauptversion. Genaue Versionsnummern gibt es nur über fullVersionList als Wert hoher Entropie.
Windows 11 erkennen: Das geht nur über platformVersion. Werte ab 13 stehen für Windows 11.
Datenschutz: Werte hoher Entropie eignen sich zum Fingerprinting. Der Browser kann sie einschränken, und die Anfrage kann mit NotAllowedError abgelehnt werden. Fragen Sie nur ab, was Sie wirklich brauchen.
Serverseitig: Auf dem Server gibt es dieselben Daten als HTTP-Header (Sec-CH-UA, Sec-CH-UA-Platform, Sec-CH-UA-Mobile). Weitere Header fordert der Server über Accept-CH an.
Die API gilt noch als experimentell. Browser-Erkennung ersetzt keine Feature-Detection.

Siehe auch

Navigator.userAgentData NavigatorUAData.getHighEntropyValues() NavigatorUAData.toJSON() NavigatorUAData.brands NavigatorUAData.platform Navigator.userAgent Navigator