Expo

Documentation

BackgroundFetch

Provides API to perform background fetch tasks. This module uses TaskManager Native API under the hood.
Platform Compatibility
Android DeviceAndroid EmulatoriOS DeviceiOS SimulatorWeb

For managed apps, you'll need to run expo install expo-background-fetch. It is not yet available for bare React Native apps.

In order to use BackgroundFetch API in standalone and detached apps on iOS, your app has to include background mode in the Info.plist file. See background tasks configuration guide for more details.

import * as BackgroundFetch from 'expo-background-fetch';

Gets a status of background fetch.

Returns a promise resolving to one of these values:
  • BackgroundFetch.Status.Restricted — Background updates are unavailable and the user cannot enable them again. This status can occur when, for example, parental controls are in effect for the current user.
  • BackgroundFetch.Status.Denied - The user explicitly disabled background behavior for this app or for the whole system.
  • BackgroundFetch.Status.Available - Background updates are available for the app.

Registers background fetch task with given name. Registered tasks are saved in persistent storage and restored once the app is initialized.

  • taskName (string) -- Name of the task to register. The task needs to be defined first - see TaskManager.defineTask for more details.
  • options (object) -- An object of options:
    • minimumInterval (number) -- Inexact interval in seconds between subsequent repeats of the background fetch alarm. The final interval may differ from the specified one to minimize wakeups and battery usage. On Android it defaults to 15 minutes. On iOS it calls BackgroundFetch.setMinimumIntervalAsync behind the scenes and the default value is the smallest fetch interval supported by the system (10-15 minutes).
    • stopOnTerminate (boolean) -- Whether to stop receiving background fetch events after user terminates the app. Defaults to true. (Android only)
    • startOnBoot (boolean) -- Whether to restart background fetch events when the device has finished booting. Defaults to false. (Android only)

Returns a promise that resolves once the task is registered and rejects in case of any errors.

Background fetch task receives no data, but your task should return a value that best describes the results of your background fetch work.
  • BackgroundFetch.Result.NoData - There was no new data to download.
  • BackgroundFetch.Result.NewData - New data was successfully downloaded.
  • BackgroundFetch.Result.Failed - An attempt to download data was made but that attempt failed.
This return value is to let iOS know what the result of your background fetch was, so the platform can better schedule future background fetches. Also, your app has up to 30 seconds to perform the task, otherwise your app will be terminated and future background fetches may be delayed.
import * as BackgroundFetch from 'expo-background-fetch';
import * as TaskManager from 'expo-task-manager';

TaskManager.defineTask(YOUR_TASK_NAME, () => {
  try {
    const receivedNewData = // do your background fetch here
    return receivedNewData ? BackgroundFetch.Result.NewData : BackgroundFetch.Result.NoData;
  } catch (error) {
    return BackgroundFetch.Result.Failed;
  }
});

Unregisters background fetch task, so the application will no longer be executing this task.

  • taskName (string) -- Name of the task to unregister.

A promise resolving when the task is fully unregistered.

Sets the minimum number of seconds that must elapse before another background fetch can be initiated. This value is advisory only and does not indicate the exact amount of time expected between fetch operations.
This method doesn't take any effect on Android.
It is a global value which means that it can overwrite settings from another application opened through Expo client.

  • minimumInterval (number) -- Number of seconds that must elapse before another background fetch can be called.

A promise resolving once the minimum interval is set.