connectivity_validator 0.1.2

Validated internet connectivity for Flutter: detects real internet access (not just a network link) and captive portals on Android, iOS, macOS, and Web.

connectivity_validator

Flutter plugin for validated internet connectivity: real internet access, not just “network connected.” Detects captive portals and router-without-internet on Android, iOS, and macOS. Web support uses a browser reachability probe; strict Web validation requires a CORS-enabled endpoint. Stream-based, Android, iOS, macOS & Web.

Features

• Validated connectivity (real internet, not only link up) on Android, iOS, and macOS
• Captive portal and “WiFi on, no internet” detection on Android, iOS, and macOS
• Real-time stream (onConnectivityChanged)
• Android (API 24+), iOS (12.0+), macOS (10.14+) and Web

Why connectivity_validator?

Most connectivity packages tell you whether a network interface is up — not whether you can actually reach the internet. So your app shows “online” while stuck behind a hotel WiFi login page, or when the router has lost its upstream connection.

connectivity_validator answers the question you actually care about: can the device reach the internet right now? On mobile/desktop it combines native OS validation (NET_CAPABILITY_VALIDATED on Android, NWPathMonitor on iOS/macOS) with a lightweight HTTPS probe to generate_204 endpoints. On Web it uses navigator.onLine plus a browser fetch probe (see Web setup).

	connectivity_plus	internet_connection_checker	connectivity_validator
Network interface up	✅	✅	✅
Real internet reachable	❌	✅	✅ / ⚠️¹
Captive portal detected	❌	❌	✅ / ⚠️¹
Native OS validation	❌	❌	✅
Web support	✅	✅	✅
Real-time stream	✅	✅	✅

¹ Android, iOS, and macOS strictly validate HTTP 204. The default Web probe can confirm browser reachability but cannot inspect a cross-origin response for captive-portal detection; provide a CORS-enabled probeUrl for strict Web validation.

Installation

Requires Dart >=3.4.0 and Flutter >=3.22.0.

pubspec.yaml

dependencies:
  connectivity_validator: ^0.1.2

flutter pub get

Platform setup

Android — Add to AndroidManifest.xml if needed:

<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />

iOS

• Swift Package Manager (default) — No extra setup. Flutter uses SPM for the plugin.
• CocoaPods — If your project uses CocoaPods for this plugin, run in the project root:

  cd ios && pod install && cd ..
  

macOS — The app sandbox blocks outgoing requests by default, so the HTTPS validation probe needs the network client entitlement. Add it to both macos/Runner/DebugProfile.entitlements and macos/Runner/Release.entitlements:

<key>com.apple.security.network.client</key>
<true/>

Without this the plugin always reports offline on macOS.

Web setup

On Web there is no native OS “validated” signal. The plugin uses:

1. navigator.onLine as a baseline (browser says the network interface is up)
2. A fetch probe to confirm real reachability

CORS caveat: Cross-origin fetch in no-cors mode returns an opaque response — JavaScript cannot read response.status, so the default probe cannot verify HTTP 204 the way Android/iOS/macOS do. The default is a GET to https://www.gstatic.com/generate_204 in no-cors mode: a fulfilled promise counts as online; network error or timeout counts as offline.

Google/Cloudflare generate_204 URLs usually do not expose CORS headers for browsers. For precise status-code validation (require HTTP 204), pass a same-origin or CORS-enabled endpoint you control:

final validator = ConnectivityValidator(
  probeUrl: 'https://your-domain.com/connectivity-check', // must return 204 + CORS
);

When probeUrl is set, Web uses CORS mode and treats status == 204 as online. Non-CORS custom URLs will fail closed (report offline).

Content Security Policy (CSP): If your Web app sets connect-src, it must allow the probe origin. For the default probe, add https://www.gstatic.com; with a custom probe, allow that endpoint instead. A same-origin probeUrl avoids cross-origin CORS; a restrictive policy must still allow 'self'.

probeUrl is accepted on all platforms for API parity but is ignored on Android, iOS, and macOS (those keep their native probe lists).

Periodic probes run about every 12s while you listen to the stream, and pause when the tab is hidden (document.visibilityState).

Usage

import 'package:connectivity_validator/connectivity_validator.dart';

final validator = ConnectivityValidator();

validator.onConnectivityChanged.listen((isOnline) {
  if (isOnline) {
    // Internet validated
  } else {
    // No internet or captive portal
  }
});

Get initial state and listen to changes:

final validator = ConnectivityValidator();

// Get initial state
final initialStatus = await validator.onConnectivityChanged.first;
print('Initial status: ${initialStatus ? "Online" : "Offline"}');

// Listen to changes
validator.onConnectivityChanged.listen((isOnline) {
  print('Connectivity changed: ${isOnline ? "Online" : "Offline"}');
});

Live status (stream) + manual check (on-demand):

final validator = ConnectivityValidator();

// Live updates
validator.onConnectivityChanged.listen((isOnline) => /* update UI */);

// On-demand check (e.g. button tap)
final isOnline = await validator.getConnectivityStatus;

In UI (e.g. StreamBuilder):

StreamBuilder<bool>(
  stream: ConnectivityValidator().onConnectivityChanged,
  initialData: false,
  builder: (context, snapshot) {
    final isOnline = snapshot.data ?? false;
    return Text(isOnline ? 'Online' : 'Offline');
  },
)

Run the example:

cd example && flutter pub get && flutter run

Web (Chrome) — toggle network to test online/offline:

cd example && flutter pub get && flutter run -d chrome

Documentation

• State management (GetX, Provider, Riverpod, BLoC, ValueNotifier)
• API reference
• How it works
• Best practices
• Troubleshooting

Contributing

Contributions welcome. See the GitHub repo.

License

See LICENSE.