NetworkInformation.effectiveType — Eigenschaft · JavaScript-Referenz

Signatur

NetworkInformation.effectiveType

Beschreibung

Die schreibgeschützte Eigenschaft effectiveType der Schnittstelle NetworkInformation (erreichbar über navigator.connection) gibt an, wie schnell sich die aktuelle Verbindung anfühlt. Der Browser leitet den Wert aus kürzlich gemessenen Umlaufzeiten (rtt) und Downlink-Werten (downlink) ab. Die tatsächliche Technik (WLAN, Ethernet, Mobilfunk) spielt dabei keine Rolle. Ein langsames WLAN kann also "3g" melden, ein schnelles LTE-Netz "4g".

Die Werte richten sich grob nach diesen Schwellen:

"slow-2g": RTT ≥ 2000 ms, Downlink ≤ 50 kbit/s. Taugt nur für kleine Textdaten.
"2g": RTT ≥ 1400 ms, Downlink ≤ 70 kbit/s. Kleine Bilder sind möglich.
"3g": RTT ≥ 270 ms, Downlink ≤ 700 kbit/s. Größere Assets wie hochaufgelöste Bilder oder Audio sind möglich.
"4g": alles darüber. Geeignet für HD-Video und Echtzeit-Anwendungen.

Typische Einsatzfälle sind adaptives Laden: kleinere Bilder, keine Autoplay-Videos, kein Prefetching oder gebündelte Anfragen bei langsamen Verbindungen. Über das Ereignis change auf navigator.connection kann man auf Änderungen des Werts reagieren.

Behandle den Wert immer als Hinweis für progressive Verbesserung, nie als verlässliche Messung. Wenn die API fehlt, sollte der Code auf ein sinnvolles Standardverhalten zurückfallen.

Rückgabewert

Typ

"slow-2g" | "2g" | "3g" | "4g"

Beschreibung

Eine Zeichenkette mit dem geschätzten effektiven Verbindungstyp. Die Eigenschaft ist schreibgeschützt.

Beispiele

Effektiven Verbindungstyp mit Feature-Erkennung auslesen

const connection = navigator.connection;

if (connection && 'effectiveType' in connection) {
  console.log(`Effektiver Typ: ${connection.effectiveType}`);
  console.log(`RTT: ${connection.rtt} ms, Downlink: ${connection.downlink} Mbit/s`);
} else {
  console.log('Network Information API nicht verfügbar');
}

Effektiver Typ: 4g RTT: 50 ms, Downlink: 10 Mbit/s

Adaptives Laden von Bildern je nach Verbindung

const getImageQuality = () => {
  const type = navigator.connection?.effectiveType ?? '4g'; // Standard: volle Qualität
  switch (type) {
    case 'slow-2g':
    case '2g':
      return 'low';
    case '3g':
      return 'medium';
    default:
      return 'high';
  }
};

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

Lade Bilder in Qualität: high

Auf Änderungen der Verbindung reagieren

const connection = navigator.connection;

const handleChange = () => {
  const slow = ['slow-2g', '2g'].includes(connection.effectiveType);
  document.documentElement.classList.toggle('sparmodus', slow);
  console.log(`Verbindung jetzt: ${connection.effectiveType}, Sparmodus: ${slow}`);
};

if (connection) {
  connection.addEventListener('change', handleChange);
  handleChange();
  // Später wieder entfernen:
  // connection.removeEventListener('change', handleChange);
}

Verbindung jetzt: 3g, Sparmodus: false

Prefetching nur bei schneller Verbindung

const prefetch = (url) => {
  const { effectiveType, saveData } = navigator.connection ?? {};
  if (saveData || (effectiveType && effectiveType !== '4g')) {
    console.log(`Prefetch übersprungen (${effectiveType ?? 'unbekannt'})`);
    return;
  }
  const link = document.createElement('link');
  link.rel = 'prefetch';
  link.href = url;
  document.head.append(link);
  console.log(`Prefetch gestartet: ${url}`);
};

prefetch('/artikel/naechste-seite.html');

Prefetch gestartet: /artikel/naechste-seite.html

// Wichtig · Fallstricke

Browser-Kompatibilität: Nur Chromium-basierte Browser (Chrome, Edge, Opera, Samsung Internet) unterstützen die Eigenschaft. Firefox und Safari kennen navigator.connection nicht. Prüfe sie daher immer per Feature-Erkennung (z. B. navigator.connection?.effectiveType) und sieh einen Standardwert vor.
Nicht der physische Typ: effectiveType beschreibt die gemessene Qualität, nicht die Technik. Für die Technik gibt es NetworkInformation.type, das aber noch schlechter unterstützt wird.
Obergrenze "4g": Einen höheren Wert wie „5g“ gibt es nicht. Schnelle Glasfaser- und 5G-Verbindungen melden ebenfalls "4g".
Ungenauigkeit: Die Werte beruhen auf kürzlich beobachteten Anfragen. Der Browser rundet sie und versieht sie mit Rauschen, um Fingerprinting zu erschweren. Direkt nach dem Seitenaufruf oder nach einem Netzwechsel können sie veraltet sein.
Nur im sicheren Kontext bzw. in Workern: Die API steht im Fenster und in Web Workern zur Verfügung. Die Spezifikation ist ein Entwurf der WICG und kein W3C-Standard.
Kombiniere den Wert mit saveData, damit der ausdrückliche Wunsch des Nutzers nach Datensparsamkeit berücksichtigt wird.
Serverseitig liefert der Client-Hint-Header ECT dieselbe Information, wenn der Server ihn per Accept-CH: ECT anfordert.

Siehe auch

Navigator.connection NetworkInformation.type NetworkInformation.rtt NetworkInformation.saveData NetworkInformation.downlink