Background Tasks
Background Tasks
The Background Task API makes it easy to run background tasks. Currently, this plugin supports running a task when the app is backgrounded, and soon will support periodic background fetch operations.
Background Task Guidelines
Mobile operating systems have strict, constantly changing guidelines for background tasks. Running indefinitely in the background is limited to apps that need to play audio, maintain VoIP connections, track geolocation for navigation purposes, and a limited set of other tasks. All other apps should expect to perform periodic, short background tasks, such as finishing an upload when the app goes to the background, and periodically syncing data.
Plugins that claim to offer infinite background operation outside of those core use cases will cause App Store rejections! This limitation is the same for developers using any mobile app technology, not just Capacitor.
Generally, Android is less strict about background tasks, but your app should code to the lowest common denominator in order to be a good actor on all platforms.
NOTE: On iOS setTimeout
and setInterval
won't work once your app is in background, so don't use them inside beforeExit
.
Example
import { Plugins } from '@capacitor/core';
const { App, BackgroundTask } = Plugins;
App.addListener('appStateChange', state => {
if (!state.isActive) {
// The app has become inactive. We should check if we have some work left to do, and, if so,
// execute a background task that will allow us to finish that work before the OS
// suspends or terminates our app:
let taskId = BackgroundTask.beforeExit(async () => {
// In this function We might finish an upload, let a network request
// finish, persist some data, or perform some other task
// Example of long task
var start = new Date().getTime();
for (var i = 0; i < 1e18; i++) {
if (new Date().getTime() - start > 20000) {
break;
}
}
// Must call in order to end our task otherwise
// we risk our app being terminated, and possibly
// being labeled as impacting battery life
BackgroundTask.finish({
taskId,
});
});
}
});
API
beforeExit(...)
beforeExit(cb: Function) => CallbackID
When the app is backgrounded, this method allows you to run a short-lived background task that will ensure that you can finish any work your app needs to do (such as finishing an upload or network request). This is especially important on iOS as any operations would normally be suspended without initiating a background task.
This method should finish in less than 3 minutes or your app risks being terminated by the OS.
When you are finished, this callback must call BackgroundTask.finish({ taskId })
where taskId
is the value returned from BackgroundTask.beforeExit()
Param | Type | Description |
---|---|---|
cb | Function | the task to run when the app is backgrounded but before it is terminated |
Returns: string
finish(...)
finish(options: { taskId: CallbackID; }) => void
Notify the OS that the given task is finished and the OS can continue backgrounding the app.
Param | Type |
---|---|
options | { taskId: string; } |
Interfaces
Function
Creates a new function.
Prop | Type |
---|---|
prototype | any |
length | number |
arguments | any |
caller | Function |
Method | Signature | Description |
---|---|---|
apply | (this: Function, thisArg: any, argArray?: any) => any | Calls the function, substituting the specified object for the this value of the function, and the specified array for the arguments of the function. |
call | (this: Function, thisArg: any, ...argArray: any[]) => any | Calls a method of an object, substituting another object for the current object. |
bind | (this: Function, thisArg: any, ...argArray: any[]) => any | For a given function, creates a bound function that has the same body as the original function. The this object of the bound function is associated with the specified object, and has the specified initial parameters. |
toString | () => string | Returns a string representation of a function. |