BackgroundFetch¶

configure¶

fun configure(config: BackgroundFetchConfig, callback: BackgroundFetch.Callback)

Configure the plugin and begin listening for background-fetch events.

Calling configure automatically starts background-fetch (equivalent to calling BackgroundFetch.start immediately after configuration).

The BackgroundFetchConfig.minimumFetchInterval option controls how frequently iOS will wake your app in the background. Android uses JobScheduler (or AlarmManager when forceAlarmManager is true) and supports additional scheduling constraints such as requiredNetworkType, requiresCharging, etc.

Warning

You must call BackgroundFetch.finish within your event callback. Failure to do so will result in the OS throttling future background events for your app.

Basic configuration

val config = BackgroundFetchConfig.Builder()
    .setMinimumFetchInterval(15)   // minutes
    .build()

BackgroundFetch.getInstance(context).configure(config, object : BackgroundFetch.Callback {
    override fun onFetch(taskId: String) {
        Log.d(TAG, "[BackgroundFetch] Event received: $taskId")
        // Perform your work here...
        BackgroundFetch.getInstance(context).finish(taskId)
    }
    override fun onTimeout(taskId: String) {
        Log.d(TAG, "[BackgroundFetch] TIMEOUT: $taskId")
        BackgroundFetch.getInstance(context).finish(taskId)
    }
})

finish¶

fun finish(taskId: String)

Signal to the OS that your background task is complete.

Warning

You must call finish at the end of every background-fetch event callback. Failure to call finish has serious consequences:

iOS — The OS may terminate your app and penalise future background-wake frequency.
Android — The JobScheduler job will not be considered complete and the OS may throttle or block future executions.

Always call finish as quickly as possible, even when your task encounters an error. For timeout events, call finish immediately without doing any additional work. Example

override fun onFetch(taskId: String) {
    Log.d(TAG, "[BackgroundFetch] Event received: $taskId")
    try {
        // Perform your work here...
    } finally {
        // Always finish, even on error.
        BackgroundFetch.getInstance(context).finish(taskId)
    }
}
override fun onTimeout(taskId: String) {
    Log.d(TAG, "[BackgroundFetch] TIMEOUT: $taskId")
    BackgroundFetch.getInstance(context).finish(taskId)
}

registerHeadlessTask Android only¶

fun setJobService(className: String): Builder

Register a function to execute when the app is terminated while background-fetch events remain active.

Requires stopOnTerminate false and enableHeadless true.

How it works¶

When Android terminates the app, the native module launches a minimal JS context (without the React Native UI) and invokes your headless task function. This allows you to handle background events even when the app is not running.

Registration¶

Call registerHeadlessTask at your app's entry point (index.js), outside any React component. The registration must happen before the OS attempts to fire a headless event.

Restrictions¶

Do not import modules that depend on the React Native UI runtime (e.g. components, navigation, Redux stores that render UI).
Keep the task lightweight — the OS may kill the JS context at any time.
Always call BackgroundFetch.finish before the returned Promise resolves. Example

// 1. Register your headless class on the config Builder (by fully-qualified name).
val config = BackgroundFetchConfig.Builder()
    .setMinimumFetchInterval(15)
    .setStopOnTerminate(false)     // <-- Continue after app termination
    .setStartOnBoot(true)          // <-- Restart on device reboot
    .setJobService(MyHeadlessTask::class.java.name)
    .build()

// 2. The named class is instantiated by reflection as HeadlessTask(Context, BGTask).
class MyHeadlessTask(context: Context, task: BGTask) {
    init {
        val taskId = task.taskId
        if (task.timedOut) {
            // OS is about to kill the context — finish immediately.
            Log.d(TAG, "[BackgroundFetch] TIMEOUT: $taskId")
            BackgroundFetch.getInstance(context).finish(taskId)
        } else {
            Log.d(TAG, "[BackgroundFetch] Headless event, taskId: $taskId")
            // ... perform lightweight work ...
            BackgroundFetch.getInstance(context).finish(taskId)
        }
    }
}

scheduleTask¶

fun scheduleTask(config: BackgroundFetchConfig)

Schedule a custom one-shot or periodic background task in addition to the default fetch event registered with BackgroundFetch.configure.

Custom tasks fire the same onEvent callback registered in BackgroundFetch.configure, identified by their TaskConfig.taskId. Call BackgroundFetch.finish with that taskId to signal completion, and BackgroundFetch.stop with the taskId to cancel.

iOS¶

On iOS, custom tasks are registered using the BGProcessingTask API. You must declare each taskId in your app's Info.plist under BGTaskSchedulerPermittedIdentifiers before calling scheduleTask.

Android¶

Android uses JobScheduler (or AlarmManager when forceAlarmManager is true) and supports all AbstractConfig scheduling constraints. One-shot task

val task = BackgroundFetchConfig.Builder()
    .setTaskId("com.transistorsoft.customtask")
    .setDelay(5000L)   // milliseconds
    .setPeriodic(false)
    .build()

// Custom tasks fire the same Callback registered in configure().
BackgroundFetch.getInstance(context).scheduleTask(task)

start¶

fun start(taskId: String)

Start subscribing to background-fetch events.

BackgroundFetch.configure calls start automatically. Use start explicitly only after a previous call to BackgroundFetch.stop. Example

// Resume after a previous stop().
BackgroundFetch.getInstance(context).start("com.transistorsoft.fetch")

status¶

fun status(): Int

Query the current authorization status of the Background Fetch API.

Value	Constant	Description
`0`	BackgroundFetchStatus.STATUS_RESTRICTED	Background fetch updates are unavailable and the user cannot enable them again (e.g. parental controls).
`1`	BackgroundFetchStatus.STATUS_DENIED	The user explicitly disabled background behavior for this app or the whole system.
`2`	BackgroundFetchStatus.STATUS_AVAILABLE	Background fetch is available and enabled.
Example

// Android has no per-app switch — status() is always STATUS_AVAILABLE (2).
val status = BackgroundFetch.getInstance(context).status()
if (status == BackgroundFetch.STATUS_AVAILABLE) {
    Log.d(TAG, "Background fetch available")
}

stop¶

fun stop(taskId: String?)

Stop subscribing to background-fetch events.

If a taskId is provided, only that specific scheduled task is cancelled.
If no taskId is provided, all background-fetch and scheduled tasks are cancelled.

Use BackgroundFetch.start to resume after stopping. Example

// Stop all background-fetch + scheduled tasks (null = all).
BackgroundFetch.getInstance(context).stop(null)

// Stop a single scheduled task by taskId.
BackgroundFetch.getInstance(context).stop("com.transistorsoft.customtask")