initialize static method

Future<void> initialize({
  1. required AppInitializationCallback appInitializationCallback,
  2. String initialNotificationTitle = 'Background Service',
  3. String initialNotificationContent = 'Processing tasks...',
  4. String? notificationIconName,
})

Initializes the background service.

This method should be called once, typically in your application's main() function, before runApp().

  • appInitializationCallback: A user-defined function that will be executed in the background isolate when the service starts. It's responsible for setting up resources and registering job handlers. See AppInitializationCallback.
  • initialNotificationTitle: The title for the persistent notification displayed on Android when the service is in foreground mode.
  • initialNotificationContent: The content text for the persistent notification.
  • notificationIconName: (Android only) The name of the drawable resource for exists in your android/app/src/main/res/drawable-* folders.
Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();

  await GenericBackgroundService.initialize(
    appInitializationCallback: _myAppBackgroundInit,
    initialNotificationTitle: "My App Service",
    initialNotificationContent: "Processing background tasks...",
  );

  runApp(MyApp());
}

@pragma('vm:entry-point')
Future<void> _myAppBackgroundInit(ServiceInstance service) async {
  // Initialize DB for background isolate
  final db = await AppDatabase().openNewConnection();
  GenericBackgroundService.setBackgroundDbConnection(db);

  // Register handlers
  GenericBackgroundService.registerJobHandler('myTask', _myTaskHandler);
}

Implementation

//    the notification icon (e.g., 'ic_bg_service_small'). Ensure this icon
///   exists in your `android/app/src/main/res/drawable-*` folders.
///
/// ```dart
/// Future<void> main() async {
///   WidgetsFlutterBinding.ensureInitialized();
///
///   await GenericBackgroundService.initialize(
///     appInitializationCallback: _myAppBackgroundInit,
///     initialNotificationTitle: "My App Service",
///     initialNotificationContent: "Processing background tasks...",
///   );
///
///   runApp(MyApp());
/// }
///
/// @pragma('vm:entry-point')
/// Future<void> _myAppBackgroundInit(ServiceInstance service) async {
///   // Initialize DB for background isolate
///   final db = await AppDatabase().openNewConnection();
///   GenericBackgroundService.setBackgroundDbConnection(db);
///
///   // Register handlers
///   GenericBackgroundService.registerJobHandler('myTask', _myTaskHandler);
/// }
/// ```
static Future<void> initialize({
  required AppInitializationCallback appInitializationCallback,
  String initialNotificationTitle = 'Background Service',
  String initialNotificationContent = 'Processing tasks...',
  String? notificationIconName, // e.g., 'ic_bg_service_small'
}) async {
  _appInitializationCallback = appInitializationCallback;

  // Android Notification Channel (Optional, but good for customization)
  // If you use flutter_local_notifications, create channel there.
  // This is a basic setup if not using a separate notification plugin.

  await _service.configure(
    iosConfiguration: IosConfiguration(
      autoStart: true,
      onForeground: _onStart,
      onBackground: _onIosBackground,
    ),
    androidConfiguration: AndroidConfiguration(
      onStart: _onStart,
      autoStart: true,
      isForegroundMode: true, // Recommended for reliability
      notificationChannelId: notificationChannelId,
      initialNotificationTitle: initialNotificationTitle,
      initialNotificationContent: initialNotificationContent,
      foregroundServiceNotificationId: backgroundServiceNotificationId,
      // Optional: if you have a custom icon in android/app/src/main/res/drawable
      // notificationIcon: notificationIconName != null
      //     ? AndroidResource(name: notificationIconName, defType: 'drawable')
      //     : null,
    ),
  );
  log('BackgroundService: Configured.');
}