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.
Firebase JobDispatcher (default): The jobs can't be scheduled exactly and depending on the Android API version different
periodtime is allowed.
FirebaseJobDispatcheris the most battery efficient backward compatible way of scheduling background tasks.
AlarmManager by setting
true: Simple propriatery implementation that is only ment to be used while testing. It only cares about executing on time, all other parameters are ignored - job is not persisted on reboot.
- RN 0.36+
- Android API 16+
Want iOS? Go in and vote for Headless JS to be implemented for iOS: Product pains
$ yarn add react-native-background-job
$ npm install react-native-background-job --save
Mostly automatic installation
$ react-native link react-native-background-job
import com.pilloxa.backgroundjob.BackgroundJobPackage;to the imports at the top of the file.
new BackgroundJobPackage()to the list returned by the
Append the following lines to
include ':react-native-background-job' project(':react-native-background-job').projectDir = new File(rootProject.projectDir, '../node_modules/react-native-background-job/android')
- Insert the following lines inside the dependencies block in
android/app/build.gradleand bump the minSdkVersion to 21:
The jobs have to be registered each time React Native starts, this is done using the
register function. Since HeadlessJS does not mount any components the
register function must be run outside of any class definitions (see example/index.android.js)
Registering the job 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
true you allow this behavior. It is recommended that you do't use this, but for quick jobs should be fine.
For a full example check out example/index.android.js
Registers the job and the functions they should run.
This has to run on each initialization of React Native and it has to run in the global scope and not inside any
component life cycle methods. See example project. Only registering the job will not schedule the job.
It has to be scheduled by
schedule to start running.
;const backgroundJob =jobKey: "myJob"console;BackgroundJob;
Schedules a new job.
This only has to be run once while
register has to be run on each initialization of React Native.
obj.jobKeystring A unique key for the job that was used for registering, and be used for canceling in later stage.
obj.timeoutnumber The amount of time (in ms) after which the React instance should be terminated regardless of whether the task has completed or not. (optional, default
obj.periodnumber 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
obj.persistboolean If the job should persist over a device restart. (optional, default
obj.overrideboolean Whether this Job should replace pre-existing jobs with the same key. (optional, default
obj.networkTypenumber Only run for specific network requirements. (optional, default
obj.requiresChargingboolean Only run job when device is charging, (not respected by pre Android N devices) docs (optional, default
obj.requiresDeviceIdleboolean Only run job when the device is idle, (not respected by pre Android N devices) docs (optional, default
obj.exactboolean Schedule an job to be triggered precisely at the provided period. Note that this is not power-efficient way of doing things. (optional, default
obj.allowWhileIdleboolean Allow the scheduled job to execute also while it is in doze mode. (optional, default
obj.allowExecutionInForegroundboolean Allow the scheduled job to be executed even when the app is in foreground. Use it only for short running jobs. (optional, default
;const backgroundJob =jobKey: "myJob"console;BackgroundJob;var backgroundSchedule =jobKey: "myJob"BackgroundJob;
Cancel a specific job
Cancels all the scheduled jobs
Sets the global warning level
Checks Whether app is optimising battery using Doze,returns Boolean.
callbackCallback gets called with according parameters after result is received from Android module.
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:
No task registered for key myJob
Make sure you call the
register function at the global scope (i.e. not in any component life cycle methods (render, iDidMount etc)). Since the components are not rendered in Headless mode if you run the register function there it will not run in the background and hence the library will not find which function to run.
See example project
"active" when I'm running my Headless task in the background
This is a React Native issue, you can get around it by calling
NativeModules.AppState.getCurrentAppState directly instead.
My job always runs in the background even if I specified
requiresDeviceIdle or a specific
This is an Android issue, it seems that you can not have these restrictions at the same time as you have a periodic interval for pre Android N devices.
Pull Request Details
Included function for checking if the app is ignoring battery optimizations. #62
In Android SDK versions greater than 23, Doze is being used by apps by default, in order to optimize battery by temporarily turning off background tasks when the phone is left undisturbed for some hours.
But, some apps may require background tasks to keep running, ignoring doze and not optimizing battery (this means battery needs to be traded off for performance as per required). Apps that require continuous syncing of data to the server at short intervals of time are examples of such apps.
It would be good if the developer can check whether the app is optimizing battery. If it is, the user can be notified that the app would not perform as per expected and it will work properly only if the user manually removes it from the battery optimizing apps list which can be found in Settings-> Battery -> Options (button on top right) -> Battery Optimization and then selecting "All Apps" to change the battery optimization settings for the particular app.
The Changes that have been made are specifically for that purpose, a function (isAppIgnoringBatteryOptimization) has been included. It checks if the app is ignoring battery optimization and returns false if it is optimizing battery (in which case the user has to manually remove it from battery settings) and true otherwise.
Logic has also been added for scheduling the task by ignoring battery optimizations, if the app has been manually removed from the battery optimization list in settings (by the User).