How to monitor network connectivity in a Flutter app

Docs/Tutorials/connectivity_sdk

Pro Reference for connectivity_sdk: every variable, option and package it generates. Command: archipelago generate connectivity_sdk

Generate the Connectivity SDK, react to network state changes, read ConnectivityState and ConnectivityType, and fetch the Wi-Fi SSID.

What you'll learn

• Generating the Connectivity SDK with API/Impl split
• Reacting to network state changes at runtime
• Reading ConnectivityState (a class) and the ConnectivityType enum
• Fetching the current Wi-Fi SSID on iOS and Android

Prerequisites

• An existing Archipelago monorepo (see Monorepo Scaffolding)

A Pro subscription is required. Run archipelago auth status to confirm your tier.

Step 1: Generate the Connectivity SDK

archipelago generate connectivity_sdk

The brick has no variables. The post-generation hook patches your workspace pubspec.yaml, your app pubspec.yaml and the app injector. You wire nothing by hand.

Step 2: Understand the Generated Structure

features/connectivity/
├── connectivity_api/
│   └── lib/src/
│       ├── connectivity_sdk.dart         # ConnectivitySDK contract
│       └── models/
│           ├── connectivity_state.dart   # ConnectivityState class
│           └── connectivity_type.dart    # ConnectivityType enum
└── connectivity_impl/
    └── lib/src/
        ├── connectivity_sdk_impl.dart    # connectivity_plus wrapper
        └── di/                           # GetIt module

Step 3: Check the Registration

The hook registers ConnectivityImplPackageModule in lib/di/injector.dart. You write no registration code.

ConnectivitySDKImpl is an eager singleton. It subscribes to the platform stream when DI builds it, so it stays in FeatureSDKRegistry. It has no screens and no routes.

Packages that only check connectivity depend on connectivity_api:

dependencies:
  connectivity_api:
    path: ../../features/connectivity/connectivity_api

Step 4: React to State Changes

ConnectivitySDK exposes a broadcast stream you can listen to anywhere:

final connectivity = getIt<ConnectivitySDK>();

connectivity.stateStream.listen((state) {
  if (!state.isOnline) showOfflineBanner();
});

ConnectivityState is a class. It has types (a list, because a device can report more than one interface), isOnline and wifiSsid. stateStream replays the current state when you subscribe. onlineStream emits distinct bool values.

ConnectivityType has these values: wifi, mobile, ethernet, vpn, bluetooth, satellite, other and none.

Step 5: Guard Network Calls

Use isOnline as a pre-flight check in your repositories. Take the SDK by constructor:

Future<List<Product>> fetchProducts() async {
  if (!_connectivity.isOnline) throw const NoConnectivityException();

  return _remoteDataSource.getProducts();
}

NoConnectivityException is your own exception class. The brick does not generate it. Catch it in the UI layer to show an offline message.

Step 6: Force a Connectivity Refresh

The SDK caches the last known state. To re-check at once, for example after a Retry tap:

final state = await connectivity.refresh();

Step 7: Read the Wi-Fi SSID (Optional)

final ssid = await connectivity.getWifiSsid(); // null if not on Wi-Fi or not allowed

Android: location permission required

Add to android/app/src/main/AndroidManifest.xml:

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

Request the permission at runtime before you call getWifiSsid(). The SDK does not ask for it.

iOS: Wi-Fi entitlement required

Add to your app's entitlements file (e.g. ios/Runner/Runner.entitlements):

<key>com.apple.developer.networking.wifi-info</key>
<true/>

Enable the Access Wi-Fi Information capability in Xcode and in your App ID on the Apple Developer portal.

Step 8: Integrate with the Feedback SDK

If you have the Feedback SDK installed, wire connectivity state into it so the offline queue drains automatically when the network returns:

connectivitySDK.stateStream.listen((state) {
  feedbackSDK.recordConnectivity(online: state.isOnline);
});

The Feedback SDK will flush its local queue the next time online becomes true.

Common Customizations

Customization	Where to Change
Show a persistent banner	Listen in a root ConsumerWidget / BlocListener
Retry failed requests	Re-subscribe to stateStream in your repository
Distinguish Wi-Fi vs mobile	Switch on ConnectivityState values in the listener
Cache data when offline	Add offline-first logic in your local datasource

Next Steps

• Set up the Feedback SDK to queue feedback submissions when offline
• Configure monitoring to track connectivity-related errors