flutter_offline

The OfflineRetryController allows you to manage manual connectivity retries with exponential backoff.

Key features:

• Exponential backoff: Automatically increases delay (1s, 2s, 4s, 8s, 16s).
• Configurable: Set maxRetries and retryCooldown.
• Reactive: Extends ChangeNotifier, so you can add a listener to trigger setState() when retry status changes.
• Auto-reset: Resets automatically upon reconnection.

To use it, instantiate the controller, add a listener, and pass it to the retryController property of an OfflineBuilder.

class _MyWidgetState extends State<MyWidget> {
  late final OfflineRetryController _retryController;

  @override
  void initState() {
    super.initState();
    _retryController = OfflineRetryController(
      maxRetries: 5,
      retryCooldown: const Duration(seconds: 2),
    );
    // Listen to changes to update UI (e.g., retry count or status)
    _retryController.addListener(() => setState(() {}));
  }

  @override
  void dispose() {
    _retryController.dispose();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return OfflineBuilder(
      retryController: _retryController,
      connectivityBuilder: (context, connectivity, child) {
        final connected = !connectivity.contains(ConnectivityResult.none);
        return Column(
          children: [
            Text(connected ? 'ONLINE' : 'OFFLINE'),
            if (!connected)
              ElevatedButton(
                // Use .canRetry to check if more attempts are allowed
                onPressed: _retryController.canRetry ? _retryController.retry : null,
                child: Text('Retry (${_retryController.retryCount}/5)'),
              ),
          ],
        );
      },
    );
  }
}

The OfflineRetryController is a ChangeNotifier used to manage manual retry attempts when a connection is lost. It implements exponential backoff and provides state information that can be used to drive UI elements like retry buttons.

Key Features

• Exponential Backoff: Automatically increases the delay between retries using the formula 2^retryCount seconds.
• Retry Throttling: Uses retryCooldown to prevent users from spamming the retry action.
• State Tracking: Provides retryCount, isRetrying, and canRetry to help you build responsive UI.

Customizing Retry Behavior

To perform actual network requests or specific logic during a retry, you must subclass OfflineRetryController and override onRetry() and onRetryError().

Implementation Example

class MyRetryController extends OfflineRetryController {
  MyRetryController({
    int maxRetries = 5,
    Duration retryCooldown = const Duration(seconds: 2),
  }) : super(maxRetries: maxRetries, retryCooldown: retryCooldown);

  @override
  Future<void> onRetry() async {
    // Implement your actual network call or data sync here
    await myApiService.fetchData();
  }

  @override
  void onRetryError(Object error, StackTrace stackTrace) {
    print('Retry failed: $error');
  }
}

The OfflineBuilder widget is the primary entry point for reacting to connectivity changes in your Flutter application. It listens to connectivity updates and provides the current list of ConnectivityResult values to a connectivityBuilder function.

To use it, you must provide either a builder or a child. The connectivityBuilder receives the current connectivity state and allows you to decide how to render your UI based on whether the device is online or offline.

Key parameters:

• connectivityBuilder: A function (context, connectivity, child) => Widget that receives the current list of ConnectivityResult.
• debounceDuration: The time to wait before emitting a connectivity change (defaults to 3 seconds) to avoid UI flickering during unstable network transitions.
• retryController: An optional OfflineRetryController to manage manual retry logic.
• errorBuilder: An optional widget to display if a platform error occurs during connectivity monitoring.