connectivity_plus_wrapper 1.0.0 copy "connectivity_plus_wrapper: ^1.0.0" to clipboard
connectivity_plus_wrapper: ^1.0.0 copied to clipboard

A smarter, more insightful Flutter connectivity package.** Goes beyond basic online/offline detection to provide meaningful connection statuses, quality analysis, and seamless transition handling.

connectivity_plus_wrapper 🌐 #

pub package License: MIT Flutter

A smarter, more insightful Flutter connectivity package. Goes beyond basic online/offline detection to provide meaningful connection statuses, quality analysis, and seamless transition handling.

Stop guessing your app's connection state. Start understanding it.


🌟 Why Choose This Package? #

Most connectivity packages answer one question: "Am I online?" This package answers the much more important questions:

  • "Is my connection good enough to make an API call?" 🚀
  • "Did the connection just come back after being lost?" 🔄
  • "Is the user on an unstable WiFi network?" 📶
  • "How long was the user offline for?" ⏱️

Feature Comparison #

Feature connectivity_plus internet_connection_checker connectivity_plus_wrapper
Basic Connectivity (WiFi, Mobile)
Real Internet Access Check
Smart Statuses (Unstable, Restored, Roaming)
Transition Tracking (with duration)
Quality-Based Analysis
Pre-built UI Widgets
Customizable Test Servers

💡 Getting Started #

Installation #

Add this to your pubspec.yaml:

dependencies:
  connectivity_plus_wrapper: ^1.0.0

Basic Usage #

Initialize the wrapper (ensure bindings are initialized first).

Listen to the stream of smart statuses.

React meaningfully in your UI.

import 'package:connectivity_plus_wrapper/connectivity_plus_wrapper.dart';

void main() {
  // Initialize Flutter bindings
  WidgetsFlutterBinding.ensureInitialized();
  runApp(MyApp());
}

class MyApp extends StatefulWidget {
  const MyApp({super.key});

  @override
  State<MyApp> createState() => _MyAppState();
}

class _MyAppState extends State<MyApp> {
  late ConnectivityWrapper connectivityWrapper;
  bool _isInitialized = false;

  @override
  void initState() {
    super.initState();
    _initializeConnectivity();
  }

  Future<void> _initializeConnectivity() async {
    connectivityWrapper = ConnectivityWrapper();
    await connectivityWrapper.init(); // Initialize after bindings are ready
    setState(() => _isInitialized = true);
  }

  @override
  Widget build(BuildContext context) {
    if (!_isInitialized) return const CircularProgressIndicator();

    return MaterialApp(
      home: DefaultConnectivityWrapper(
        connectivityWrapper: connectivityWrapper,
        child: const MyHomePage(),
      ),
    );
  }
}

class MyHomePage extends StatelessWidget {
  const MyHomePage({super.key});

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: ConnectivityBuilder(
        builder: (context, status) {
          return Center(
            child: Column(
              mainAxisAlignment: MainAxisAlignment.center,
              children: [
                Icon(
                  status.isConnected ? Icons.wifi : Icons.wifi_off,
                  size: 64,
                  color: status.isConnected ? Colors.green : Colors.red,
                ),
                const SizedBox(height: 16),
                Text(
                  status.description, // User-friendly description
                  style: const TextStyle(fontSize: 24),
                ),
              ],
            ),
          );
        },
      ),
    );
  }
}

🧠 Core Concepts & API #

Smart Statuses (ConnectionStatus) #

We provide nuanced statuses that actually help you decide what to do in your app.

Status Description Use Case Example
disconnected No internet access. Disable sync buttons, show offline message.
connected Stable, reliable connection. Proceed with high-bandwidth operations.
restored Internet access was just regained. Retry failed requests, refresh data.
unstable Connection is intermittent or slow. Avoid large downloads, warn the user.
roaming Connected via mobile data in roaming. Warn about potential costs before downloading.
checking Briefly shown while assessing connection quality. Show a loading indicator.

Tracking Transitions (ConnectionTransition) #

Understand the story behind the connection change, not just the new state.

// Listen to rich transition events
connectivityWrapper.onTransition.listen((transition) {
  debugPrint('Went from ${transition.from} to ${transition.to}');
  debugPrint('Was offline for: ${transition.duration}');

  if (transition.isRestored) {
    // Re-sync data after being offline for 2 minutes
    if (transition.duration > const Duration(minutes: 2)) {
      refreshAppData();
    }
  }
});

🛠️ Advanced Usage #

Custom Configuration #

Tweak the package to your app's needs.

// Create a customized wrapper
final customWrapper = ConnectivityWrapper(
  testServers: [
    'https://your-api.com/health', // Ping your own server first
    'https://www.google.com',
  ],
  unstableThreshold: const Duration(seconds: 5), // How long before 'restored' becomes 'connected'
  checkInterval: const Duration(seconds: 3), // How often to check quality
);

// Add more servers later
customWrapper.addTestServers(['https://cloudflare.com']);

ConnectivityAware Mixin #

Make any Stateful Widget automatically react to connection changes.

class MyDataScreen extends StatefulWidget {
  const MyDataScreen({super.key});

  @override
  State<MyDataScreen> createState() => _MyDataScreenState();
}

class _MyDataScreenState extends State<MyDataScreen> with ConnectivityAware<MyDataScreen> {

  @override
  void didChangeDependencies() {
    super.didChangeDependencies();
    final wrapper = DefaultConnectivityWrapper.of(context)!.connectivityWrapper;
    initConnectivityAware(wrapper.onStatusChange); // Initialize the mixin
  }

  @override
  void onConnectionStatusChanged(ConnectionStatus status) {
    // This method is called every time the status changes
    if (status == ConnectionStatus.restored) {
      ScaffoldMessenger.of(context).showSnackBar(
        const SnackBar(content: Text('Welcome back online! Data refreshed.')),
      );
      loadData(); // Reload data when connection is restored
    }
  }

  @override
  Widget build(BuildContext context) {
    // Your widget build method...
  }
}

ConnectivityOverlay Widget #

Add a sleek, automatic overlay that informs users about their connection status without blocking your UI.

return ConnectivityOverlay(
  child: YourAppContent(), // Your normal app scaffold
  showDuration: const Duration(seconds: 4), // How long to show non-critical statuses
);

Overlay Example


📚 Full API Reference #

ConnectivityWrapper #

The main class to manage connectivity status.

Method / Getter Description
Future<void> init() Initializes the plugin. Must be called!
Stream<ConnectionStatus> onStatusChange Stream of smart connection statuses.
Stream<ConnectionTransition> onTransition Stream of transitions between statuses.
Future<ConnectionStatus> get currentStatus Gets the current status (async).
Future<bool> get isReallyConnected Checks for a real, usable internet connection.
void addTestServers(List<String> urls) Adds custom URLs to check for internet quality.
void configureTiming({...}) Configures timing thresholds for status changes.
void dispose() Stops all listeners and timers.

🚀 Use Cases #

  • E-commerce App: Prevent orders from being placed with an unstable connection. Refresh the cart automatically when connection is restored.
  • Video Streaming App: Warn users about potential buffering on unstable connections. Pause downloads if status changes to roaming.
  • News App: Cache articles on disconnected. Retry failed image loads automatically on restored.
  • Finance App: Block transactions or show a strong warning on any connection that isn't connected.

🤝 Contributing #

We love contributions! Please feel free to open issues, suggest features, and submit pull requests. Let's make this package even better together.

  1. Fork the project.
  2. Create your feature branch (git checkout -b feature/amazing-feature).
  3. Commit your changes (git commit -m 'Add some amazing feature').
  4. Push to the branch (git push origin feature/amazing-feature).
  5. Open a Pull Request.

📄 License #

This project is licensed under the MIT License. See the LICENSE file for details.


🙏 Acknowledgments #

  • Built upon the great work of the connectivity_plus and internet_connection_checker packages.
  • Made with ❤️ for the Flutter community.

Questions? Feel free to open an issue on GitHub!

0
likes
130
points
114
downloads

Publisher

unverified uploader

Weekly Downloads

A smarter, more insightful Flutter connectivity package.** Goes beyond basic online/offline detection to provide meaningful connection statuses, quality analysis, and seamless transition handling.

Repository (GitHub)
View/report issues

Documentation

API reference

License

MIT (license)

Dependencies

connectivity_plus, flutter, internet_connection_checker

More

Packages that depend on connectivity_plus_wrapper