network_health_monitor #

Lightweight Flutter package that continuously monitors internet connectivity and network quality.

This package only reports network state. It is UI-agnostic — your app owns offline/slow UI. No per-screen or API-layer checks are required.

Platforms #

Web: validate your probe URL for CORS before relying on it.

Install #

dependencies:
  network_health_monitor: ^0.1.1

import 'package:network_health_monitor/network_health_monitor.dart';

Basic usage #

WidgetsFlutterBinding.ensureInitialized();

final monitor = NetworkHealthMonitor();
await monitor.startMonitoring();

monitor.statusStream.listen((status) {
  switch (status) {
    case NetworkStatus.checking:
      break;
    case NetworkStatus.online:
      break;
    case NetworkStatus.slow:
      break;
    case NetworkStatus.offline:
      break;
  }
});

Notes #

• Default probe (https://www.cloudflare.com/cdn-cgi/trace) checks general internet, not your backend.
• If the default probe fails, best-effort public fallbacks are tried (gstatic generate_204, Microsoft connect test). They improve resilience but do not guarantee internet detection (third-party endpoints can change). Custom healthCheckUrl does not auto-add public fallbacks.
• Captive-portal HTML responses are treated as offline.
• Connectivity-type changes are handled immediately; silent internet loss is caught on the next periodic check (default 30s) and on app resume.
• Latency means HTTP request latency (not pure network RTT).
• measureBandwidth defaults to false. When enabled, bandwidthProbeUrl is required (approximate download throughput only).
• Each statusStream subscription first emits currentStatus, then future changes.
• Stale in-flight HTTP results cannot overwrite a newer connectivity OFFLINE event.
• Call dispose() when the monitor is no longer needed (e.g. app teardown).

Retry #

final result = await monitor.retry();

retry() and check() run an on-demand evaluation and return a [NetworkHealthResult].

States #

Stabilization #

Set consecutiveBadChecksForSlow / consecutiveGoodChecksForOnline to 1 and shorten periodicCheckInterval if you want faster status transitions.

Config #

NetworkHealthConfig(
  healthCheckUrl: 'https://www.cloudflare.com/cdn-cgi/trace',
  // Optional; defaults to public fallbacks when using the default primary URL.
  // Pass [] to disable fallbacks, or your own list.
  // fallbackHealthCheckUrls: [...],
  slowLatency: const Duration(milliseconds: 1500),
  requestTimeout: const Duration(seconds: 8),
  periodicCheckInterval: const Duration(seconds: 30),
  consecutiveBadChecksForSlow: 2,
  consecutiveGoodChecksForOnline: 2,
  measureBandwidth: false,
);

// If measuring approximate download throughput:
NetworkHealthConfig(
  measureBandwidth: true,
  bandwidthProbeUrl: 'https://cdn.example.com/probe.bin',
  bandwidthProbeBytes: 50 * 1024,
  slowDownloadSpeedKbps: 300,
);

* Applied automatically only when healthCheckUrl is the package default.

API #

NetworkHealthResult #

Example #

See example/main.dart.