This documentation is available as Markdown for AI agents and LLMs. See the full Markdown index or append .md to any documentation URL.
Expo BackgroundFetch
A library that provides API for performing background fetch tasks.
Deprecated: Theexpo-background-fetchlibrary is being replaced by a new version inexpo-background-task.expo-background-fetchis not receiving patches and will be removed in an upcoming release.
expo-background-fetch provides an API to perform background fetch tasks, allowing you to run specific code periodically in the background to update your app. This module uses TaskManager Native API under the hood.
Known issues iOS
BackgroundFetch only works when the app is backgrounded, not if the app was terminated or upon device reboot. You can check out the relevant GitHub issue for more details.
On iOS the BackgroundFetch library requires you to use a development build since Background Fetch is not enabled in the iOS Expo Go app.
Installation
If you are installing this in an existing React Native app, make sure to install expo in your project.
Configuration iOS
To be able to run background fetch tasks on iOS, you need to add the fetch value to the UIBackgroundModes array in your app's Info.plist file. This is required for background fetch to work properly.
If you're using CNG, the required UIBackgroundModes configuration will be applied automatically by prebuild.
Configure UIBackgroundModes manually on iOS
If you're not using Continuous Native Generation (CNG) or you're using a native ios project manually, then you'll need to add the following to your Expo.plist file:
Usage
Below is an example that demonstrates how to use expo-background-fetch.
Triggering background fetches
Background fetches can be difficult to test because they can happen inconsistently. Fortunately, you can trigger background fetches manually when developing your apps.
For iOS, you can use the Instruments app on macOS to manually trigger background fetches:
- Open the Instruments app. The Instruments app can be searched through Spotlight (Cmd ⌘ + Space) or opened from
/Applications/Xcode.app/Contents/Applications/Instruments.app - Select
Time Profiler - Select your device / simulator and pick the
Expo Goapp - Press the
Recordbutton in the top left corner - Navigate to the
DocumentMenu and selectSimulate Background Fetch - Expo Go:
For Android, you can set the minimumInterval option of your task to a small number and background your application like so:
async function registerBackgroundFetchAsync() { return BackgroundFetch.registerTaskAsync(BACKGROUND_FETCH_TASK, { minimumInterval: 1 * 60, // task will fire 1 minute after app is backgrounded }); }
API
import * as BackgroundFetch from 'expo-background-fetch';
Methods
Deprecated: Use
getStatusAsync()fromexpo-background-taskinstead. Theexpo-background-fetchpackage has been deprecated.
Gets a status of background fetch.
Promise<BackgroundFetchStatus | null>Returns a promise which fulfils with one of BackgroundFetchStatus enum values.
Deprecated: Use
registerTaskAsync()fromexpo-background-taskinstead. Theexpo-background-fetchpackage has been deprecated.
Registers background fetch task with given name. Registered tasks are saved in persistent storage and restored once the app is initialized.
Promise<void>Example
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.BackgroundFetchResult.NewData : BackgroundFetch.BackgroundFetchResult.NoData; } catch (error) { return BackgroundFetch.BackgroundFetchResult.Failed; } });
Deprecated: Use the
registerTaskAsync()method from expo-background-task package, and specifyBackgroundTaskOptionsargument instead, when setting task interval time.
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 Go.
Promise<void>A promise which fulfils once the minimum interval is set.
Deprecated: Use
unregisterTaskAsync()fromexpo-background-taskinstead. Theexpo-background-fetchpackage has been deprecated.
Unregisters background fetch task, so the application will no longer be executing this task.
Promise<void>A promise which fulfils when the task is fully unregistered.
Interfaces
Enums
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.
BackgroundFetchStatus.Denied = 1The user explicitly disabled background behavior for this app or for the whole system.
BackgroundFetchStatus.Restricted = 2Background 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.
Permissions
Android
On Android, this module might listen when the device is starting up. It's necessary to continue working on tasks started with startOnBoot. It also keeps devices "awake" that are going idle and asleep fast, to improve reliability of the tasks. Because of this both the RECEIVE_BOOT_COMPLETED and WAKE_LOCK permissions are added automatically.