Setting Up the Connectivity SDK

What you'll learn

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

Prerequisites

• An existing Archipelago monorepo (see Monorepo Scaffolding)

Pro Feature

connectivity_sdk requires an active Pro subscription. Run archipelago auth status to confirm your tier.

Step 1: Generate the Connectivity SDK

archipelago generate connectivity_sdk

No variables are prompted. The post-gen hook automatically patches your workspace pubspec.yaml, your app pubspec.yaml, and the main injector file — no manual wiring needed.

Step 2: Understand the Generated Structure

features/connectivity/
├── connectivity_api/
│   └── lib/src/
│       ├── connectivity_sdk.dart         # Abstract SDK contract
│       ├── connectivity_state.dart       # ConnectivityState enum
│       └── exceptions/
│           └── no_connectivity_exception.dart
└── connectivity_impl/
    └── lib/src/
        ├── connectivity_sdk_impl.dart    # connectivity_plus wrapper
        └── di/                           # GetIt module

Step 3: Register the Feature

In your shell app's bootstrap.dart:

import 'package:connectivity_impl/connectivity_impl.dart';

FeatureRegistry.register(ConnectivityImpl());

Other packages that only need to check connectivity at call-site (e.g. a repository throwing NoConnectivityException) depend on connectivity_api:

# In a dependent feature's pubspec.yaml
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 covers all connection types the device can report:

Value	Meaning
wifi	Connected via Wi-Fi
mobile	Connected via mobile data
ethernet	Connected via Ethernet
vpn	Connected via VPN
bluetooth	Connected via Bluetooth tether
satellite	Connected via satellite
other	Connected, type unrecognised
none	No connection

isOnline is true for every value except none.

Step 5: Guard Network Calls

Use isOnline as a pre-flight check in your repositories:

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

  return _remoteDataSource.getProducts();
}

Catch NoConnectivityException in your UI layer to show a contextual offline message instead of a generic error.

Step 6: Force a Connectivity Refresh

The SDK caches the last known state. To re-check immediately (e.g. after the user taps a "Retry" button):

await connectivity.refresh();

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

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

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 with permission_handler before calling getWifiSsid().

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/>

The entitlement must also be enabled 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