BackgroundFetchConfig

Configuration object passed to BackgroundFetch.configure.

minimumFetchInterval

minimumFetchInterval?: number;

The minimum interval in minutes between background-fetch events. Defaults to 15 minutes. The minimum allowed value is 15 minutes.

Note

The OS does not guarantee fetch events will fire at exactly this interval. iOS adjusts timing based on usage patterns and battery state. This is a minimum hint, not a precise schedule.

Example

BackgroundFetch.configure({
  minimumFetchInterval: 15,   // iOS: fire no more often than every 15 minutes
}, async (taskId) => {
  BackgroundFetch.finish(taskId);
});

---

Android-only constraints

The following options apply to Android only.

enableHeadless Android only

enableHeadless?: boolean;

Set true to enable the headless mechanism for handling fetch events after app termination. Defaults to false.

Note

Requires stopOnTerminate false.

Warning

You must be prepared to write Java code.

Headless Setup

Step 1: Create a file named BackgroundFetchHeadlessTask.java in your app (e.g. src/android/). The file can be located anywhere but MUST be named BackgroundFetchHeadlessTask.java:

package com.transistorsoft.cordova.backgroundfetch;

import android.content.Context;
import android.util.Log;

import com.transistorsoft.tsbackgroundfetch.BackgroundFetch;
import com.transistorsoft.tsbackgroundfetch.BGTask;

public class BackgroundFetchHeadlessTask implements HeadlessTask {
    @Override
    public void onFetch(Context context, BGTask task) {
        String taskId = task.getTaskId();
        boolean isTimeout = task.getTimedOut();
        if (isTimeout) {
            Log.d(BackgroundFetch.TAG, "TIMEOUT: " + taskId);
            BackgroundFetch.getInstance(context).finish(taskId);
            return;
        }
        Log.d(BackgroundFetch.TAG, "onFetch: " + taskId);
        // Perform your work here...

        BackgroundFetch.getInstance(context).finish(taskId);
    }
}

Step 2: In your config.xml, add a <resource-file> within <platform name="android">:

<platform name="android">
    <resource-file
        src="src/android/BackgroundFetchHeadlessTask.java"
        target="app/src/main/java/com/transistorsoft/cordova/backgroundfetch/BackgroundFetchHeadlessTask.java" />
</platform>

• src: path to your custom BackgroundFetchHeadlessTask.java.
• target: must be exactly as shown above.

Testing Your Headless Task

After terminating your app, simulate a fetch event while observing $ adb logcat:

adb shell cmd jobscheduler run -f com.your.app.package.name 999

forceAlarmManager Android only

forceAlarmManager?: boolean;

Force the use of Android's AlarmManager API instead of JobScheduler. Defaults to false.

By default the plugin uses JobScheduler on API 21+ and falls back to AlarmManager on older devices. Set true to force AlarmManager regardless of API level.

Note

AlarmManager bypasses the scheduling optimisations of JobScheduler and is less battery-efficient. Use it only when JobScheduler does not meet your timing requirements.

requiredNetworkType Android only

requiredNetworkType?: NetworkType;

Specify the kind of network connectivity required to run this task. Defaults to NetworkType.NETWORK_TYPE_NONE (no network required).

If the required network type is unavailable, the task will not run until the constraint is satisfied.

Value	Constant	Description
0	NetworkType.NETWORK_TYPE_NONE	No network constraint.
1	NetworkType.NETWORK_TYPE_ANY	Any active network connection.
2	NetworkType.NETWORK_TYPE_CELLULAR	Cellular (mobile data) connection.
3	NetworkType.NETWORK_TYPE_UNMETERED	Unmetered (e.g. Wi-Fi) connection.
4	NetworkType.NETWORK_TYPE_NOT_ROAMING	Non-roaming connection.

On iOS, use TaskConfig.requiresNetworkConnectivity instead. Example

BackgroundFetch.scheduleTask({
  taskId: 'com.foo.sync',
  delay: 60000,
  requiredNetworkType: BackgroundFetch.NETWORK_TYPE_UNMETERED,
});

requiresBatteryNotLow Android only

requiresBatteryNotLow?: boolean;

Set true to require the device's battery level to be above the "low battery" threshold before running this task. Defaults to false.

requiresCharging Android only

requiresCharging?: boolean;

Set true to require the device to be charging (or connected to permanent power) before running this task. Defaults to false.

requiresDeviceIdle Android only

requiresDeviceIdle?: boolean;

Set true to require the device to be idle (not actively used) before running this task. Defaults to false.

This is a good option for resource-intensive tasks. Battery usage is still attributed to your app and surfaced to the user in battery stats.

requiresStorageNotLow Android only

requiresStorageNotLow?: boolean;

Set true to require the device's available storage to be above the "low storage" threshold before running this task. Defaults to false.

startOnBoot Android only

startOnBoot?: boolean;

Set true to resume background-fetch events when the device is rebooted. Defaults to false.

Note

Requires stopOnTerminate false.

stopOnTerminate Android only

stopOnTerminate?: boolean;

Set false to continue receiving background-fetch events after the user terminates the app. Defaults to true.

Note

startOnBoot requires stopOnTerminate: false.

Example

BackgroundFetch.configure({
  stopOnTerminate: false,
  startOnBoot: true,
  enableHeadless: true,
}, async (taskId) => {
  BackgroundFetch.finish(taskId);
});