TaskConfig¶

Configuration object passed to BackgroundFetch.scheduleTask.

delay¶

delay: number;

The minimum delay in milliseconds before this task fires.

The OS may delay the task beyond this value depending on device conditions, battery state, and other scheduling constraints. Example

// Fire at least 30 seconds from now.
BackgroundFetch.scheduleTask({
  taskId: 'com.foo.task',
  delay: 30000,
});

periodic¶

periodic?: boolean;

Set true to schedule a repeating task. Defaults to false (one-shot).

When true, the task automatically re-schedules itself after each execution using the same TaskConfig.delay as the repeat interval. Example

BackgroundFetch.scheduleTask({
  taskId: 'com.foo.periodic',
  delay: 900000,    // 15 minutes in ms
  periodic: true,
});

requiresNetworkConnectivity iOS only¶

requiresNetworkConnectivity?: boolean;

Set true to require a network connection before this task runs.

On Android, use requiredNetworkType instead. Example

BackgroundFetch.scheduleTask({
  taskId: 'com.foo.networktask',
  delay: 60000,
  requiresNetworkConnectivity: true,      // <-- iOS
  requiredNetworkType: BackgroundFetch.NETWORK_TYPE_ANY, // <-- Android
});

taskId¶

taskId: string;

A unique identifier for this task.

The same taskId is delivered to the onEvent callback registered in BackgroundFetch.configure. Pass it to BackgroundFetch.finish to signal completion and to BackgroundFetch.stop to cancel the task.

Use reverse-domain notation to avoid collisions with other tasks. Example

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

// In your configure() callback:
BackgroundFetch.configure({}, async (taskId) => {
  if (taskId === 'com.myapp.sync') {
    await performSync();
  }
  BackgroundFetch.finish(taskId);
});

Android-only constraints¶

The following options apply to Android only.

enableHeadless Android only¶

enableHeadless?: boolean;

Set true to enable React Native's HeadlessJS mechanism for handling fetch events after app termination. Defaults to false.

Note

Requires stopOnTerminate false.

📂 index.js (MUST be in index.js):

import BackgroundFetch from "react-native-background-fetch";

const MyHeadlessTask = async (event) => {
  let taskId = event.taskId;
  let isTimeout = event.timeout;
  if (isTimeout) {
    // This task has exceeded its allowed running-time.
    console.log('[BackgroundFetch] Headless TIMEOUT:', taskId);
    BackgroundFetch.finish(taskId);
    return;
  }
  console.log('[BackgroundFetch HeadlessTask] start:', taskId);

  // Perform your work here...

  BackgroundFetch.finish(taskId);
};

// Register your BackgroundFetch HeadlessTask
BackgroundFetch.registerHeadlessTask(MyHeadlessTask);

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);
});