NavigatorUAData.getHighEntropyValues() — Methode · JavaScript-Referenz

Signatur

NavigatorUAData.prototype.getHighEntropyValues(hints)

Beschreibung

Die Methode getHighEntropyValues() gehört zum Interface NavigatorUAData, das über navigator.userAgentData erreichbar ist. Sie ist Teil der User-Agent Client Hints, die den klassischen, immer weiter eingefrorenen navigator.userAgent-String ersetzen sollen. Standardmäßig stellt der Browser nur Werte mit geringer Entropie bereit (brands, mobile, platform). Alles, was sich zur Identifizierung einzelner Nutzer eignet, etwa die genaue Betriebssystem-Version oder das Gerätemodell, muss ausdrücklich über diese Methode angefordert werden.

Du übergibst ein Array mit den Namen der gewünschten Hinweise. Zurück kommt ein Promise, das mit einem Objekt erfüllt wird. Darin stehen immer die Low-Entropy-Werte und dazu die angeforderten High-Entropy-Werte, soweit der Browser sie herausgibt. Weil die Abfrage asynchron läuft, kann der Browser vorher Datenschutzregeln prüfen oder die Anfrage ablehnen.

Typische Einsatzfälle sind:

das richtige Download-Paket anbieten, abhängig von Architektur und Bitness (arm/x86, 32/64),
Windows 11 von Windows 10 unterscheiden (über platformVersion),
die genaue Browserversion für Diagnose- oder Support-Formulare ermitteln (fullVersionList).

Die Methode gibt es nur in sicheren Kontexten (HTTPS). Feature-Erkennung ist Pflicht, denn Firefox und Safari kennen navigator.userAgentData nicht.

Parameter

Name	Typ	Default	Beschreibung
$hints Pflicht	Array<string>		Liste der gewünschten Hinweise. Gültige Werte: `"architecture"`, `"bitness"`, `"formFactors"`, `"fullVersionList"`, `"model"`, `"platformVersion"`, `"wow64"` sowie das veraltete `"uaFullVersion"`. Unbekannte Namen werden ignoriert.

Rückgabewert

Typ

Promise<UADataValues>

Beschreibung

Ein Promise, das mit einem Objekt erfüllt wird. Es enthält immer brands, mobile und platform, dazu die angeforderten Schlüssel, etwa architecture (string), bitness (string), model (string), platformVersion (string), fullVersionList (Array von {brand, version}), wow64 (boolean) und formFactors (Array<string>). Das Promise wird mit einem NotAllowedError (DOMException) abgelehnt, wenn der Browser die Herausgabe verweigert.

Beispiele

Plattform-Details mit Feature-Erkennung abfragen

const getUaDetails = async () => {
  if (!navigator.userAgentData) {
    // Fallback für Firefox/Safari
    return { userAgent: navigator.userAgent };
  }
  try {
    return await navigator.userAgentData.getHighEntropyValues([
      'architecture',
      'bitness',
      'model',
      'platformVersion',
      'fullVersionList'
    ]);
  } catch (err) {
    console.warn('Client Hints verweigert:', err.name);
    return null;
  }
};

getUaDetails().then(console.log);

{ architecture: "x86", bitness: "64", brands: [{ brand: "Chromium", version: "124" }, …], fullVersionList: [{ brand: "Google Chrome", version: "124.0.6367.91" }, …], mobile: false, model: "", platform: "Windows", platformVersion: "15.0.0" }

Windows 11 von Windows 10 unterscheiden

const detectWindowsVersion = async () => {
  const uaData = navigator.userAgentData;
  if (!uaData || uaData.platform !== 'Windows') return null;

  const { platformVersion } = await uaData.getHighEntropyValues(['platformVersion']);
  const major = Number.parseInt(platformVersion.split('.')[0], 10);
  // Ab platformVersion 13 handelt es sich um Windows 11
  return major >= 13 ? 'Windows 11' : 'Windows 10 oder älter';
};

detectWindowsVersion().then((v) => console.log(v));

Windows 11

Passenden Download-Link je nach Architektur wählen

const pickDownload = async () => {
  const fallback = 'https://example.com/download/app-x64.exe';
  if (!navigator.userAgentData) return fallback;

  const { architecture, bitness } =
    await navigator.userAgentData.getHighEntropyValues(['architecture', 'bitness']);

  if (architecture === 'arm') return 'https://example.com/download/app-arm64.exe';
  if (bitness === '32') return 'https://example.com/download/app-x86.exe';
  return fallback;
};

pickDownload().then((url) => {
  document.querySelector('#download').href = url;
});

// Wichtig · Fallstricke

Browser-Unterstützung: Nur Chromium-basierte Browser (Chrome, Edge, Opera, Samsung Internet) unterstützen die Methode. In Firefox und Safari ist navigator.userAgentData undefined. Prüfe das immer vorher und sieh einen Fallback vor.
Nur sichere Kontexte: Die Methode steht nur unter HTTPS bzw. localhost zur Verfügung.
Datenschutz: High-Entropy-Werte eignen sich für Fingerprinting. Frag nur die Hinweise an, die du wirklich brauchst. Der Browser darf Anfragen ablehnen (NotAllowedError) oder in Zukunft ungenauere Werte liefern.
Leere Werte: model ist auf Desktop-Geräten meist ein leerer String. platformVersion kann unter Linux leer sein.
Veraltet: uaFullVersion ist abgekündigt. Nimm stattdessen fullVersionList.
Serverseitig: Die gleichen Informationen erhältst du über die HTTP-Header Sec-CH-UA-*. Dafür muss der Server sie vorher mit Accept-CH anfordern.
Keine Feature-Erkennung ersetzen: Um herauszufinden, ob der Browser eine Funktion kann, ist direkte Feature-Erkennung robuster als das Auswerten von Browser- oder Versionsangaben.
Die Methode steht auch in Web Workern über WorkerNavigator.userAgentData zur Verfügung.

Siehe auch

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