Schedule background jobs that run your JavaScript when your app is in the background.

The jobs will run even if the app has been closed and, by default, also persists over restarts.

This library relies on React Native's HeadlessJS which is currently only supported on Android.

On the native side it uses JobScheduler which means that the jobs can't be scheduled exactly and for Android 23+ they fire at most once per 15 minutes +-5 minutes. JobSceduler was used since it seemed to be the most battery efficient way of scheduling background tasks. I'm open to pull requests that implement more exact scheduling.

• RN 0.36+
• Android API 21+

• Android

Want iOS? Go in and vote for Headless JS to be implemented for iOS: Product pains

$ yarn add react-native-background-job

or

$ npm install react-native-background-job --save

$ react-native link react-native-background-job

1. Open up android/app/src/main/java/[...]/MainActivity.java

   • Add import com.pilloxa.backgroundjob.BackgroundJobPackage; to the imports at the top of the file
   • Add new BackgroundJobPackage() to the list returned by the getPackages() method

2. Append the following lines to android/settings.gradle:

       include ':react-native-background-job'
       project(':react-native-background-job').projectDir = new File(rootProject.projectDir, 	'../node_modules/react-native-background-job/android')
   

3. Insert the following lines inside the dependencies block in android/app/build.gradle:

         compile project(':react-native-background-job')
   

The jobs have to be registered each time React Native starts, this is done using the register function. This does not mean that the job is scheduled, it just informs React Native that this job function should be tied to this jobKey. The job is then scheduled using the schedule function. The job will not fire while the app is in the foreground. This is since the job is run on the only JavaScript thread and if running the job when app is in the foreground it would freeze the app.

Registers jobs and the functions they should run.

This has to run on each initialization of React Native. Only doing this will not start running the job. It has to be scheduled by schedule to start running.

Parameters

• obj Object
  • obj.jobKey string A unique key for the job
  • obj.job function The JS-function that will be run

Examples

import BackgroundJob from 'react-native-background-job';

const backgroundJob = {
 jobKey: "myJob",
 job: () => console.log("Running in background")
};

BackgroundJob.register(backgroundJob);

Schedules a new job.

This only has to be run once while register has to be run on each initialization of React Native.

Parameters

• obj Object
  • obj.jobKey string A unique key for the job
  • obj.timeout number How long the JS job may run before being terminated by Android (in ms).
  • obj.period number? The frequency to run the job with (in ms). This number is not exact, Android may modify it to save batteries. Note: For Android > N, the minimum is 900 0000 (15 min). (optional, default 900000)
  • obj.persist boolean? If the job should persist over a device restart. (optional, default true)
  • obj.warn boolean? If a warning should be raised if overwriting a job that was already scheduled. (optional, default true)

Examples

import BackgroundJob from 'react-native-background-job';

const backgroundJob = {
 jobKey: "myJob",
 job: () => console.log("Running in background")
};

BackgroundJob.register(backgroundJob);

var backgroundSchedule = {
 jobKey: "myJob",
 timeout: 5000
}

BackgroundJob.schedule(backgroundSchedule);

Fetches all the currently scheduled jobs

Parameters

• obj Object
  • obj.callback function (Array) A list of all the scheduled jobs will be passed to the callback

Examples

import BackgroundJob from 'react-native-background-job';

BackgroundJob.getAll({callback: (jobs) => console.log("Jobs:",jobs)});

Cancel a specific job

Parameters

• obj Object
  • obj.jobKey string The unique key for the job
  • obj.warn boolean? If one tries to cancel a job that has not been scheduled it will warn (optional, default true)

Examples

import BackgroundJob from 'react-native-background-job';

BackgroundJob.cancel({jobKey: 'myJob'});

Cancels all the scheduled jobs

Examples

import BackgroundJob from 'react-native-background-job';

BackgroundJob.cancelAll();

Sets the global warning level

Parameters

• warn boolean

Examples

import BackgroundJob from 'react-native-background-job';

BackgroundJob.setGlobalWarnings(false);

If you are using Android API +25 you can manually trigger the jobs by using the following command in a terminal:

$ adb shell cmd jobscheduler run -f your.package jobIntId

jobIntId: is the hashed jobKey. Get that value by going to Java REPL and input:

"yourJobKey".hashCode();
// 1298333557

This is a React Native issue, you can get around it by calling NativeModules.AppState.getCurrentAppState directly instead.