NetworkInformation — Schnittstelle · JavaScript-Referenz

Signatur

interface NetworkInformation extends EventTarget

Beschreibung

Das Interface NetworkInformation gehört zur Network Information API. Es gibt Auskunft darüber, wie das Gerät mit dem Netzwerk verbunden ist. Eine Instanz legt man nicht selbst an: Man erhält sie über navigator.connection im Hauptthread oder über self.navigator.connection in Web Workern.

Die wichtigsten Eigenschaften, alle nur lesbar:

effectiveType: geschätzte Verbindungsqualität als 'slow-2g', '2g', '3g' oder '4g'. Der Wert beruht auf gemessenen Werten für Durchsatz und Latenz, nicht auf der tatsächlichen Funktechnik.
downlink: geschätzte Download-Bandbreite in Megabit pro Sekunde, auf 25 kbit/s gerundet.
rtt: geschätzte Umlaufzeit (Round-Trip-Time) in Millisekunden, auf 25 ms gerundet.
saveData: true, wenn die Person im Browser oder Betriebssystem den Datensparmodus eingeschaltet hat.
type: Art der Verbindung, z. B. 'wifi', 'cellular', 'ethernet' oder 'none'. In Desktop-Browsern ist dieser Wert meist nicht verfügbar.
downlinkMax: theoretische Höchstbandbreite der Verbindungstechnik in Mbit/s. Nur wenige Browser unterstützen diese Eigenschaft.

Typische Einsatzfälle sind adaptive Inhalte: Bei langsamer Verbindung oder eingeschaltetem Datensparmodus liefert man Bilder und Videos in geringerer Qualität, verzichtet auf automatisches Abspielen oder schaltet Prefetching ab. Über das Event change, das man mit addEventListener('change', …) oder der Eigenschaft onchange abonniert, reagiert man auf Wechsel der Verbindung während der Laufzeit.

Die API ist nicht standardisiert. Sie ist ein Entwurf der WICG und funktioniert praktisch nur in Chromium-Browsern. Setze sie deshalb nur zur progressiven Verbesserung ein und prüfe vorher, ob sie vorhanden ist.

Rückgabewert

Typ

NetworkInformation | undefined

Beschreibung

navigator.connection gibt ein NetworkInformation-Objekt zurück. In Browsern ohne Unterstützung (Firefox, Safari) ist der Wert undefined.

Beispiele

Verbindungsdaten auslesen (mit Prüfung auf Unterstützung)

const connection = navigator.connection;

if (connection) {
  console.log('Effektiver Typ:', connection.effectiveType);
  console.log('Downlink (Mbit/s):', connection.downlink);
  console.log('RTT (ms):', connection.rtt);
  console.log('Datensparmodus:', connection.saveData);
} else {
  console.log('Network Information API wird nicht unterstützt.');
}

Effektiver Typ: 4g Downlink (Mbit/s): 10 RTT (ms): 50 Datensparmodus: false

Bildqualität an die Verbindung anpassen

const shouldUseLowQuality = () => {
  const c = navigator.connection;
  if (!c) return false; // Ohne API: Standardqualität
  return c.saveData || ['slow-2g', '2g', '3g'].includes(c.effectiveType);
};

const img = document.querySelector('#hero');
img.src = shouldUseLowQuality()
  ? '/img/hero-small.webp'
  : '/img/hero-large.webp';

console.log('Geladen:', img.src);

Geladen: https://example.com/img/hero-large.webp

Auf Verbindungswechsel reagieren mit addEventListener und onchange

const connection = navigator.connection;

const handleChange = () => {
  console.log(`Verbindung geändert: ${connection.effectiveType}, ${connection.downlink} Mbit/s`);
  // Autoplay nur bei schneller Verbindung erlauben
  document.querySelectorAll('video').forEach((v) => {
    v.autoplay = connection.effectiveType === '4g' && !connection.saveData;
  });
};

if (connection) {
  connection.addEventListener('change', handleChange);

  // Später wieder entfernen, z. B. beim Verlassen der Ansicht
  setTimeout(() => connection.removeEventListener('change', handleChange), 60_000);

  // Alternative über die Eigenschaft (erlaubt nur einen Handler):
  // connection.onchange = handleChange;
}

Verbindung geändert: 3g, 1.45 Mbit/s

Prefetching im Service Worker oder Worker steuern

// Funktioniert im Hauptthread und in Workern
const conn = self.navigator.connection;

const canPrefetch = () => !conn || (!conn.saveData && conn.effectiveType === '4g');

const prefetch = async (urls) => {
  if (!canPrefetch()) {
    console.log('Prefetch übersprungen');
    return;
  }
  await Promise.all(urls.map((url) => fetch(url, { priority: 'low' })));
  console.log(`${urls.length} Ressourcen vorgeladen`);
};

prefetch(['/api/articles?page=2', '/img/next.webp']);

2 Ressourcen vorgeladen

// Wichtig · Fallstricke

Browser-Kompatibilität: Die API ist experimentell und nur in Chromium-Browsern verfügbar. Firefox und Safari (auch unter iOS) unterstützen sie nicht. Prüfe daher immer mit if (navigator.connection) und sieh ein sinnvolles Standardverhalten vor.
Nur Schätzwerte: effectiveType, downlink und rtt werden aus bereits gemessenem Datenverkehr abgeleitet. Sie sind gerundet und aus Datenschutzgründen gedeckelt: downlink höchstens 10 Mbit/s, rtt höchstens 3000 ms. Auch bei Glasfaser zeigt effectiveType deshalb höchstens '4g' an.
Kein Rückschluss auf Kosten: type fehlt in Desktop-Browsern häufig. Aus 'wifi' folgt nicht, dass die Verbindung kostenlos ist, denn es kann sich um einen mobilen Hotspot handeln. Ob Daten gespart werden sollen, erkennt man zuverlässiger an saveData.
Serverseitige Alternative: Über Client Hints (Save-Data, ECT, Downlink, RTT) kann der Server dieselben Informationen schon beim ersten Request auswerten. Gerade Save-Data wird breiter unterstützt.
Datenschutz: Verbindungsdaten können zum Fingerprinting beitragen. Das ist einer der Gründe, warum andere Browser-Hersteller die API ablehnen.
onchange nimmt nur einen einzigen Handler auf. Wenn mehrere Stellen im Code auf Änderungen reagieren sollen, verwende addEventListener.

Siehe auch

Navigator.connection Navigator.onLine ChapterInformation XRDepthInformation WorkerLocation