expo-task-manager
provides an API that allows you to manage long-running tasks, in particular those tasks that can run while your app is in the background.
Some features of this module are used by other modules under the hood. Here is a list of Expo modules that use TaskManager:Android Device | Android Emulator | iOS Device | iOS Simulator | Web |
---|---|---|---|---|
expo install expo-task-manager
. To use it in bare React Native app, follow its installation instructions;TaskManager
works out of the box in the Expo Go app on Android, but on iOS you'll need to test using a custom Expo Go build.UIBackgroundModes
array in your Info.plist file. In standalone apps this array is empty by default, so in order to use background features you will need to add appropriate keys to your app.json configuration.
Here is an example of an app.json configuration that enables background location and background fetch:{ "expo": { ... "ios": { ... "infoPlist": { ... "UIBackgroundModes": [ "location", "fetch" ] } } } }
Signing & Capabilities
, adding the BackgroundMode
capability (if absent), and checking either Location updates
or Background fetch
, depending on your needs.AppDelegate.h
, AppDelegate
subclasses the UMAppDelegateWrapper
class from @unimodules/core
, like so:#import <UMCore/UMAppDelegateWrapper.h> @interface AppDelegate : UMAppDelegateWrapper <RCTBridgeDelegate>
import React from 'react'; import { Text, TouchableOpacity } from 'react-native'; import * as TaskManager from 'expo-task-manager'; import * as Location from 'expo-location'; const LOCATION_TASK_NAME = 'background-location-task'; const requestPermissions = async () => { const { status } = await Location.requestPermissionsAsync(); if (status === 'granted') { await Location.startLocationUpdatesAsync(LOCATION_TASK_NAME, { accuracy: Location.Accuracy.Balanced, }); } }; const PermissionsButton = () => ( <TouchableOpacity onPress={requestPermissions}> <Text>Enable background location</Text> </TouchableOpacity> ); TaskManager.defineTask(LOCATION_TASK_NAME, ({ data, error }) => { if (error) { // Error occurred - check `error.message` for more details. return; } if (data) { const { locations } = data; // do something with the locations captured in the background } }); export default PermissionsButton;
import * as TaskManager from 'expo-task-manager';
Name | Type | Description |
---|---|---|
taskName | string | Name of the task. It must be the same as the name you provided when registering the task. |
taskExecutor | TaskManagerTaskExecutor | A function that will be invoked when the task with given taskName is executed. |
Defines task function. It must be called in the global scope of your JavaScript bundle.
In particular, it cannot be called in any of React lifecycle methods like componentDidMount
.
This limitation is due to the fact that when the application is launched in the background,
we need to spin up your JavaScript app, run your task and then shut down — no views are mounted
in this scenario.
void
Provides information about tasks registered in the app.
A promise which fulfills with an array of tasks registered in the app. Example:
[ { taskName: 'location-updates-task-name', taskType: 'location', options: { accuracy: Location.Accuracy.High, showsBackgroundLocationIndicator: false, }, }, { taskName: 'geofencing-task-name', taskType: 'geofencing', options: { regions: [...], }, }, ]
Name | Type | Description |
---|---|---|
taskName | string | Name of the task. |
Retrieves options
associated with the task, that were passed to the function registering the task
(eg. Location.startLocationUpdatesAsync
).
Promise<TaskOptions>
A promise which fulfills with the options
object that was passed while registering task
with given name or null
if task couldn't be found.
Determine if the TaskManager
API can be used in this app.
Promise<boolean>
A promise fulfills with true
if the API can be used, and false
otherwise.
On the web it always returns false
.
Name | Type | Description |
---|---|---|
taskName | string | Name of the task. |
Checks whether the task is already defined.
boolean
Name | Type | Description |
---|---|---|
taskName | string | Name of the task. |
Determine whether the task is registered. Registered tasks are stored in a persistent storage and preserved between sessions.
Promise<boolean>
A promise which fulfills with a boolean
value whether or not the task with given name
is already registered.
Unregisters all tasks registered for the running app. You may want to call this when the user is signing out and you no longer need to track his location or run any other background tasks.
Promise<void>
A promise which fulfills as soon as all tasks are completely unregistered.
Name | Type | Description |
---|---|---|
taskName | string | Name of the task to unregister. |
Unregisters task from the app, so the app will not be receiving updates for that task anymore.
It is recommended to use methods specialized by modules that registered the task, eg.
Location.stopLocationUpdatesAsync
.
Promise<void>
A promise which fulfills as soon as the task is unregistered.
Type of task executor – a function that handles the task.
Name | Type | Description |
---|---|---|
body | TaskManagerTaskBody | - |
Error object that can be received through TaskManagerTaskBody
when the
task fails.
Name | Type | Description |
---|---|---|
code | string | number | - |
message | string | - |
Represents an already registered task.
Name | Type | Description |
---|---|---|
options | any | Provides options that the task was registered with. |
taskName | string | Name that the task is registered with. |
taskType | string | Type of the task which depends on how the task was registered. |
Represents the object that is passed to the task executor.
Name | Type | Description |
---|---|---|
data | T | An object of data passed to the task executor. Its properties depends on the type of the task. |
error | null | TaskManagerError | Error object if the task failed or null otherwise. |
executionInfo | TaskManagerTaskBodyExecutionInfo | Additional details containing unique ID of task event and name of the task. |
Additional details about execution provided in TaskManagerTaskBody
.
Name | Type | Description |
---|---|---|
appState (optional) | 'active' | 'background' | 'inactive' | (iOS only) State of the application. |
eventId | string | Unique ID of task event. |
taskName | string | Name of the task. |