Navigator.connection — Eigenschaft · JavaScript-Referenz

Signatur

get Navigator.connection

Beschreibung

Die schreibgeschützte Eigenschaft navigator.connection liefert ein NetworkInformation-Objekt. Es beschreibt die aktuelle Netzwerkverbindung des Geräts. Die wichtigsten Eigenschaften sind effectiveType ('slow-2g', '2g', '3g' oder '4g'), downlink (geschätzte Bandbreite in Mbit/s), rtt (geschätzte Round-Trip-Zeit in Millisekunden) und saveData (der Nutzer hat den Datensparmodus aktiviert).

Gedacht ist die API für adaptives Laden: Bei langsamer Verbindung oder aktivem Datensparmodus lädt man kleinere Bilder, verzichtet auf automatisch startende Videos oder schaltet Prefetching ab. Über das Ereignis change auf dem Objekt bekommt man mit, wenn sich die Verbindungsqualität ändert.

Die Werte sind Schätzungen, die der Browser aus kürzlich gemessenem Datenverkehr ableitet. Aus Datenschutzgründen sind sie gerundet: rtt auf 25 ms, downlink auf 25 kbit/s. Nimm sie deshalb als grobe Orientierung und nicht als genaue Messung. Weil die Eigenschaft in vielen Browsern fehlt, musst du ihre Verfügbarkeit immer prüfen und für den Fall ohne API ein sinnvolles Standardverhalten vorsehen (Progressive Enhancement).

Rückgabewert

Typ

NetworkInformation | undefined

Beschreibung

Ein NetworkInformation-Objekt (erbt von EventTarget) mit den Eigenschaften effectiveType, downlink, downlinkMax, rtt, saveData und – nur auf manchen Plattformen – type. In Browsern ohne Unterstützung ist der Wert undefined.

Beispiele

Verbindungsinformationen mit Feature-Erkennung auslesen

const conn = navigator.connection;

if (conn) {
  console.log(`Typ: ${conn.effectiveType}`);
  console.log(`Bandbreite: ${conn.downlink} Mbit/s`);
  console.log(`RTT: ${conn.rtt} ms`);
  console.log(`Datensparmodus: ${conn.saveData}`);
} else {
  console.log('Network Information API nicht verfügbar');
}

Typ: 4g Bandbreite: 10 Mbit/s RTT: 50 ms Datensparmodus: false

Adaptives Laden: Bildqualität nach Verbindung wählen

const chooseImageQuality = () => {
  const conn = navigator.connection;
  // Ohne API: Standardqualität
  if (!conn) return 'medium';
  if (conn.saveData) return 'low';
  if (['slow-2g', '2g'].includes(conn.effectiveType)) return 'low';
  if (conn.effectiveType === '3g') return 'medium';
  return 'high';
};

const quality = chooseImageQuality();
document.querySelectorAll('img[data-src]').forEach((img) => {
  img.src = img.dataset.src.replace('{q}', quality);
});
console.log(`Bildqualität: ${quality}`);

Bildqualität: high

Auf Änderungen der Verbindung reagieren (change-Ereignis)

const conn = navigator.connection;

const handleChange = () => {
  console.log(`Neuer Typ: ${conn.effectiveType}, ${conn.downlink} Mbit/s`);
  document.body.classList.toggle('slow-network',
    ['slow-2g', '2g', '3g'].includes(conn.effectiveType));
};

if (conn) {
  conn.addEventListener('change', handleChange);
  // Alternativ: conn.onchange = handleChange;

  // Später wieder abmelden:
  // conn.removeEventListener('change', handleChange);
}

Neuer Typ: 3g, 1.45 Mbit/s

Prefetching nur bei guter Verbindung

const shouldPrefetch = () => {
  const conn = navigator.connection;
  if (!conn) return true;
  return !conn.saveData && conn.effectiveType === '4g';
};

if (shouldPrefetch()) {
  const link = document.createElement('link');
  link.rel = 'prefetch';
  link.href = '/naechste-seite.html';
  document.head.append(link);
  console.log('Prefetch aktiviert');
}

Prefetch aktiviert

// Wichtig · Fallstricke

Browser-Kompatibilität: Experimentelle API, die nur Chromium-basierte Browser unterstützen (Chrome, Edge, Opera, Samsung Internet, Chrome für Android). Firefox und Safari (auch iOS) kennen sie nicht, dort ist navigator.connection undefined. Prüfe die Verfügbarkeit also immer, z. B. mit if ('connection' in navigator) oder optionaler Verkettung (navigator.connection?.effectiveType).
type und downlinkMax (z. B. 'wifi', 'cellular') gibt es praktisch nur in Chrome für Android und ChromeOS. Auf dem Desktop fehlen sie.
effectiveType ist nicht der echte Netztyp: Ein langsames WLAN kann als '3g' erscheinen, ein schnelles Mobilnetz als '4g'. Werte über 4G (z. B. 5G) werden ebenfalls als '4g' gemeldet.
Datenschutz: Die Werte sind absichtlich gerundet und begrenzt, um Fingerprinting zu erschweren. Deshalb sollte man keine feingranulare Logik auf sie stützen.
Der Datensparmodus wird serverseitig zusätzlich über den HTTP-Header Save-Data: on mitgeteilt. Für serverseitiges adaptives Ausliefern ist das oft die bessere Lösung.
Die Eigenschaft steht auch in Web Workern zur Verfügung (WorkerNavigator.connection).
Ob das Gerät überhaupt online ist, prüft man mit navigator.onLine und den Ereignissen online/offline, nicht mit dieser API.

Siehe auch

Navigator.onLine Navigator MediaTrackSettings.echoCancellation Navigator.contacts Navigator.appVersion