lifecycle_guard_ios

The robust iOS implementation for mission-critical background execution.

This package ensures your background tasks get the execution time they need on iOS devices using native BGTaskScheduler APIs.

Demo

See the iOS Background Task flow in action:

Try the iOS Interactive Demo

The iOS Challenge

iOS is notoriously strict. When an app is swiped away or minimized, it is suspended almost instantly. Unlike Android, you cannot simply start a persistent "service." lifecycle_guard_ios utilizes Apple's BGTaskScheduler framework to request dedicated processing time from the kernel. This allows your app to finish critical work (like a database sync) even if the UI process has been suspended or terminated.

Step-by-Step Installation (Detailed)

1. Add Dependency

Add this to your pubspec.yaml:

dependencies:
  lifecycle_guard_ios: ^1.0.1

2. Configure Capabilities (Xcode)

To allow background execution on iOS, you must enable specific capabilities in Xcode:

1. Open your project in Xcode.
2. Select the Runner target and go to Signing & Capabilities.
3. Click + Capability and search for Background Modes.
4. Check the following two boxes:
   • Background fetch
   • Background processing (This is critical for long tasks)

3. Update Info.plist

Apple requires you to whitelist your background task identifiers. Open ios/Runner/Info.plist and add:

<key>BGTaskSchedulerPermittedIdentifiers</key>
<array>
    <string>com.crealify.lifecycle_guard.background_task</string>
</array>

Full Example Code (Complete main.dart)

import 'package:flutter/material.dart';
import 'package:lifecycle_guard_ios/lifecycle_guard_ios.dart';

void main() {
  // 1. Initialize Flutter bindings for native channel support
  WidgetsFlutterBinding.ensureInitialized();
  runApp(const MaterialApp(home: IOSGuardExample()));
}

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

  /// This function requests background processing time from iOS
  Future<void> _triggerIosTask() async {
    try {
      // Register the task with BGTaskScheduler
      // iOS will then allocate a window for your task to run.
      await LifecycleGuardIos().runSecureTask(
        id: "ios_sync_001",
        payload: {
          "user": "developer_pro",
          "action": "secure_data_upload",
        },
      );
      debugPrint("iOS Guard scheduled: Your task is now protected.");
    } catch (e) {
      debugPrint("Failed to schedule iOS task: $e");
    }
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('iOS Background Guard')),
      body: Center(
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: [
            const Icon(Icons.apple, size: 80),
            const SizedBox(height: 20),
            ElevatedButton(
              onPressed: _triggerIosTask,
              style: ElevatedButton.styleFrom(backgroundColor: Colors.black, foregroundColor: Colors.white),
              child: const Text('Request Background Processing'),
            ),
          ],
        ),
      ),
    );
  }
}

iOS Specific Features

• BGTaskScheduler Integration: Follows the official Apple architecture for background work.
• Isolate Protection: Spawns a dedicated background Isolate to keep your Dart logic running.
• Resource Management: Automatically respects iOS system battery and data budgets.
• Graceful Termination Handling: Provides hooks to save state if iOS finally decides to reclaim resources.

License

BSD 3-Clause License — see LICENSE for details.