background_fetch

• [iOS] Adopt FlutterSceneLifeCycleDelegate for Flutter 3.41 UIScene lifecycle support.
• [Changed] Bump minimum Flutter SDK constraint to >=3.38.0.

• [Android] Fix MissingPluginException on com.transistorsoft/flutter_background_fetch/methods after app relaunch when a foreground service kept the process alive post-termination. HeadlessTask now destroys its background FlutterEngine when the main Activity re-attaches, and BackgroundFetchModule tracks method channels per-BinaryMessenger so destroying one engine (e.g. a sibling plugin's headless isolate) no longer strips the handler from another engine's channel.

• Update native libs for 4.1.0
• [iOS] Migrate /example to Flutter 3.41 UIScene lifecycle (adopt FlutterImplicitEngineDelegate, register plugins via didInitializeImplicitFlutterEngine:, add UIApplicationSceneManifest with FlutterSceneDelegate). TSBackgroundFetch 4.1's +load auto-registers BGTask launch handlers before the BGTaskScheduler deadline, which is required for UIScene apps where the plugin's application:didFinishLaunchingWithOptions: is delivered too late via Flutter's scene fallback.

• [Changed] Renamed HeadlessTask class to HeadlessEvent to align with TypeScript API. A typedef HeadlessTask = HeadlessEvent alias is provided for backwards compatibility.
• [Changed] Simplified README with links to new Documentation Site.

• Add CLAUDE.md with SDK architecture, build commands, and conventions
• [iOS] Fix podspec public_header_files glob to match actual header location The public_header_files glob was pointing to Sources/include/ but the header lives under Sources/background_fetch/include/, so the glob matched zero files. This broke module resolution when building with CocoaPods and use_frameworks! from Xcode.

• Both the plugin's iOS and Android core libs (TSBackgroundFetch.xcframework, tsbackgroundfetch.aar) are now published to Cocoapods, Swift Package Manager and Sonatype for android. This is especially wonderful for android, as now there's no more need of the custom maven url in the root build.gradle.
• See the Setup Guides for both iOS and Android (they have changed from previous versions).

• [iOS] Add Swift Package Manager support

• [Android] Update gradle config. Default compileSdkVersion 34

Merge branch 'remove-unused-imports'

• [Android] Removed unused import related to Flutter V1 embedding.

Merge branch 'update-android-dependencies'

• [Android] Remove unrequired dependency appcompat.
• [Android] Bump default androidx.lifecycle:lifecycle-runtime version to 2.7.0.
• [Android] Add @NonNull annotations to flutter plugin methods.
• [Android] Enable multidex in Android /example.

Merge branch 'release-1.3.5'

• Update analysis_options.yaml for pub.dev. There are no code changes from 1.3.4.

• Change return-type of BackgroundFetch.finish from void to Future<void>.

Merge branch 'codesign'

• [iOS] Code-sign TSBackgroundFetch.xcframework with new Apple Organization (9224-2932 Quebec Inc) certificate.

Merge branch 'PrivacyInfo'

• [iOS] codesign TSBackgroundFetch.xcframework.
• [iOS] Add PrivacyInfo.xcprivacy into .podfile config.

• [iOS] Move PrivacyInfo -> TSBackgroundFetch.xcframework.

Merge branch 'PrivacyInfo'

• [iOS] Implement new iOS Privacy Manifest

Merge branch 'release-1.2.4'

• [iOS] Remove reference to symbol BGHealthResearchTask for now

• [iOS] ensure scheduleTask callback is executed on main-thread.
• [Android] Update Android Setup Instructions for flutter >= 3.19.0 (New Android Architecture).

• [iOS] Only allow registration of BGProcessingTasks (Permitted background task scheduler identifiers) in Info.plist which are prefixed with com.transistorsoft. Any other task identifier will be ignored.
• [Android] Remove deprecated registerWith V1 flutter plugin architecture.

• [Android] Detect and dispose of duplicate events. Android JobService has a bug for devices running <= Android M where multiple backgrou nd-fetch events could fire within the same second.

• [Android] Android 14 (SDK 34) support..
• [Android] Android 14 support: When using forceAlarmManager: true, you must now optionally add the permission android.permission.SCHEDULE_EXACT_ALARM to your AndroidManifest to schedule exact alarms. Otherwise AlarmManager will use in-exact alarms. :open_file_folder: AndroidManifest. NOTE You must include the permission exactly as-shown with android:minSdkVersion="34".

<manifest>
    <!-- [background-fetch] OPTIONAL:  allows forceAlarmManager: true to use exact alarms -->
    <uses-permission android:name="android.permission.SCHEDULE_EXACT_ALARM" android:maxSdkVersion="33" />
    .
    .
    .
</manifest>

• [Android] Fix an issue booting the app with flutter run with screen off where plugin incorrectly detects the app is headless.

• [Android] Gradle v8 now requires namespace attribute in gradle files.

• [Android] Fix NPE in mEventChannelTask in certain situations. See #322.

• [Android] [Fix] Add a null-check in didDetachFromEngine, fixing a reported null-pointer exception.
• [Android] [Added] Log the jobId when .scheduleTask is called so that developers can simulate events with adb shell.

• [Android] Fix error FlutterJNI was detached from native C++ when Android back button is pressed. In this case, Flutter detaches the MainActivity from the app and headless-mode was not being detected.

• [Android] add @pragma('vm:entry-point') to lib's _headlessCallbackDispatcher, required for release builds on Flutter >= 3.3.0.

• [Android] Use LifecycleManager for modern headless-detection instead of legacy mechanism requiring permission GET_TASKS.

• [iOS] Fix type-error when .start() raises an error (#281)
• [Android] Better error-handling when headlessTask is registered incorrectly (#242)
• [Android] Android 12 compatibility: Add new required permission android.permission.SCHEDULE_EXACT_ALARM

• [Fixed][Android] Fix typo related to requiredNetworkType, causing null pointer error.

• [Changed][Android] Remove deprectated jcenter repository. Replaced with mavenCentral.

• [Changed][Android] Allow multiple calls to .configure to allow re-configuring the fetch task. Existing task will be cancelled and a new periodic fetch task re-scheduled according to new config.
• [Changed][Android] Ignore initial fetch task fired immediately.
• [Changed][Android] android:exported="false" on BootReceiver to resolve reported security analysis.

• Release 1.0.0-nullsafety.3 as 1.0.0

• [Fixed][Android] null check in FetchStreamHandler that mEventSink != null
• [Changed][Android] Add new logic block to isMainActivityActive: compare launchActivityName with task.baseActivity.getClassName()

• [Fixed][Android] Flutter 2 broke Android Headless Task with Null-pointer exception.

• [Fixed][Android] Fix java.lang.NullPointerException: Attempt to invoke virtual method 'java.lang.String com.transistorsoft.tsbackgroundfetch.BGTask.getTaskId()' on a null object reference

• [Changed] Implement null-safety (Thanks to @GinoTerlouw).

• [Added][iOS] Implement two new iOS options for BackgroundFetch.scheduleTask:

  • bool requiresNetworkConnectivity
  • bool requiresCharging (previously Android-only).

• [Changed][iOS] Migrate TSBackgroundFetch.framework to new .xcframework for MacCatalyst support with new Apple silcon.

:warning: Breaking Change: Requires cocoapods >= 1.10+.

iOS' new .xcframework requires cocoapods >= 1.10+:

$ pod --version
// if < 1.10.0
$ sudo gem install cocoapods

• [Added] task-timeout callback. BackgroundFetch.configure now accepts a 3rd argument onTimeout callback. This callback will be executed when the operating system has signalled your task has expired before your task has called BackgroundFetch.finish(taskId). You must stop whatever you're task is doing and execute BackgroundFetch.finish(taskId) immediately.

BackgroundFetch.configure(BackgroundFetchConfig(
  minimumFetchInterval: 15
), (String taskId) {  // <-- task callback.
  print("[BackgroundFetch] taskId: $taskId");
  BackgroundFetch.finish(taskId);
}, (String taskId) {  // <-- NEW:  task-timeout callback.
  // This task has exceeded its allowed running-time.  You must stop what you're doing immediately finish(taskId)
  print("[BackgroundFetch] TIMEOUT taskId: $taskId");
  BackgroundFetch.finish(taskId);
});

:warning: [Android] Breaking Change For Android Headless-task

• Since the registered Android headless-task (BackgroundFetch.registerHeadlessTask) can only receive a single parameter, your headless-task will now receive a HeadlessTask task instance rather than String taskId in order to differentiate task-timeout events.

OLD

void myBackgroundFetchHeadlessTask(String taskId) async { // <-- OLD:  String taskId
  print("[BackgroundFetch] Headless task: $taskId");
  BackgroundFetch.finish(taskId);
}
BackgroundFetch.registerHeadlessTask(myBackgroundFetchHeadlessTask);

NEW

void myBackgroundFetchHeadlessTask(HeadlessTask task) async { // <-- NEW:  HeadlessTask now provided.
  String taskId = task.taskId;    // <-- NEW:  Get taskId from HeadlessTask
  bool isTimeout = task.timeout;  // <-- NEW:  true if this task has timed-out.
  if (isTimeout) {
    // This task has exceeded its allowed running-time.  You must stop what you're doing immediately finish(taskId)
    print("[BackgroundFetch] Headless TIMEOUT: $taskId");
    BackgroundFetch.finish(taskId);
    return;
  }
  print("[BackgroundFetch] Headless task: $taskId");
  BackgroundFetch.finish(taskId);
}
BackgroundFetch.registerHeadlessTask(myBackgroundFetchHeadlessTask);

• [Fixed][Android] com.android.tools.build:gradle:4.0.0 no longer allows "direct local aar dependencies". The Android Setup now requires a custom maven url to be added to your app's root android/build.gradle:

allprojects {
    repositories {
        google()
        jcenter()
+       maven {
+           // [required] background_fetch
+           url "${project(':background_fetch').projectDir}/libs"
+       }
    }
}

• [Fixed][Android] using forceAlarmManager: true fails to restart fetch events after reboot.
• [Fixed] Android check wakeLock.isHeld() before executing wakeLock.release().

• [Fixed] [iOS] bug with start plugin after executing stop.

• [Fixed] [Android] Add @Keep annotation to HeadlessTask.java to prevent minifying this classs in release builds since the SDK uses reflection to find this class.

• [Fixed] [Android] stopOnTerminate not cancelling scheduled job / Alarm when fired task fired after terminate.

• [Android] Fix Android NPE in hasTaskId for case where plugin is installed first time in had previous version of plugin

• [Added] [Android] New option forceAlarmManager for bypassing JobScheduler mechanism in favour of AlarmManager for more precise scheduling task execution.
• [Changed] Migrate iOS deprecated "background-fetch" API to new BGTaskScheduler. See new required steps in iOS Setup.
• [Added] Added new BackgroundFetch.scheduleTask method for scheduling custom "onehot" and periodic tasks in addition to the default fetch-task.

BackgroundFetch.configure(BackgroundFetchConfig(
  minimumFetchInterval: 15,
  stopOnTerminate: false
), (String taskId) {  // <-- [NEW] taskId provided to Callback
  print("[BackgroundFetch] taskId: $taskId");
  switch(taskId) {
    case 'foo':
      // Handle scheduleTask 'foo'
      break;
    default:
      // Handle default fetch event.
      break;
  }
  BackgroundFetch.finish(taskId);  // <-- [NEW] Provided taskId to #finish method.
});

// This event will end up in Callback provided to #configure above.
BackgroundFetch.scheduleTask(TaskConfig(
  taskId: 'foo',  //<-- required
  delay: 60000,
  periodic: false  
));

• [Changed] Upgrade to new Flutter Plugin API "V2". Requires flutter sdk version 1.12. See Upgrading pre 1.12 Android Projects

• [Fixed] Resolve Android StrictMode violations; typically from accessing SharedPreferences on main-thread.

• Fix error FlutterMain.findBundleAppPath(). The plugin modified a deprecated API for flutter 1.9.1, breaking those on previous flutter versions. Will use deprecated API for now.

• Implement Android JobInfo constraints.
• Fix NSLog warnings casting to long
• Default startOnBoot: true in example

• Use AndroidX.

• Fixed bug with setting jobServiceClass using a reference to HeadlessJobService.class. This crashes devices < api 21, since Android's JobService wasn't available until then. Simply provide the class name as a String.

• Fixed issue with Android headless config.

• First working implementation

• First working implementation