Skip to content
Schedule background data synchronization using React Native.
Branch: master
Clone or download
nvlbg and ferrannp Allow user to choose userVisible value (#13)
* Allow user to choose userVisible value
* Bump version
* Update readme
Latest commit 2d53ca6 Mar 26, 2018
Type Name Latest commit message Commit time
Failed to load latest commit information.
__tests__ - Change package name to react-native-sync-adapter Apr 24, 2017
android Allow user to choose userVisible value (#13) Mar 26, 2018
flow-typed/npm Add Flow + Jest + Init example app. Feb 5, 2017
.babelrc Initial commit: react-native init. Jan 20, 2017
.eslintignore Install example deps on CircleCI + add Jest coverage/ in .eslintignore. Feb 5, 2017
.eslintrc.json Bump dependencies. Oct 16, 2017
.flowconfig Bump dependencies. Oct 16, 2017
LICENSE Create LICENSE Feb 5, 2017 Allow user to choose userVisible value (#13) Mar 26, 2018
circle.yml Update CircleCI to use Yarn (#11) Oct 16, 2017
index.js Add syncImmediately. Oct 20, 2017
package.json Allow user to choose userVisible value (#13) Mar 26, 2018
yarn.lock Bump dependencies. Oct 16, 2017


Circle CI npm version

Intelligent Job-Scheduling port to React Native: Scheduling data background synchronizations that run in your JavaScript.

Read a broader introduction in the following post: React Native and Native Modules: The Android SyncAdapter


  • React Native 0.36+


Under the hood, this library uses a SyncAdapter:

  • Android will trigger a sync using our syncFlexTime to decide when is the best moment to do so (battery efficiency)
  • No need to worry about internet connection
  • No need to worry about the user restarting the device
  • Compatible with all Android versions supported by RN (4.1+)


This library is only for Android. If you want to do something similar on iOS, I recommend using react-native-background-fetch.

Getting started

yarn add react-native-sync-adapter


react-native link react-native-sync-adapter

Manual Android required step

Open up the string.xml file of your Android project. You need to add the following (just change the content):

<string name="app_name">YourAppName</string>
<string name="rnsb_sync_account_type" translatable="false"></string>
<string name="rnsb_content_authority" translatable="false"></string>

This will override the default values from the library and make them unique for your app.


You need to register a task with a specific name and only with this specific name: TASK_SYNC_ADAPTER. You should do it in the same place where you register your app:

AppRegistry.registerComponent('MyApp', () => MyApp);
AppRegistry.registerHeadlessTask('TASK_SYNC_ADAPTER', () => TestTask);

Then, on your top most component:

import SyncAdapter from 'react-native-sync-adapter';


componentDidMount() {


That is all! Some extras:


The default timeout for your Headless JS task is 5 minutes (300000ms). If you want to override this value, you will also need to override strings.xml again:

<!-- Overrides default timeout to 10 minutes -->
<string name="rnsb_default_timeout" translatable="false">600000</string>

User visible

By default the user will not be able to manually enable/disable syncs through the Account settings. If you want the user to have this option, you need to override strings.xml:

<!-- Allows the user to enable/disable the sync functionality through the Account settings -->
<string name="rnsb_user_visible" translatable="false">true</string>

Running the task while the app is in the foreground

By default, the sync task will only run if the app is not in the foreground. This is one of the default caveats from HeadlessJS. If you want to override this behavior, you can, one more time overriding strings.xml:

<string name="rnsb_allow_foreground">true</string>

Broadcast Receiver

If you want to trigger a sync natively (e.g. responding to a broadcast receiver), you can call:

SyncAdapter.syncImmediately(Context context, int syncInterval, int syncFlexTime);



Schedules background syncs within your app.

Object: {
  syncInterval: number;
  syncFlexTime: number;
  • syncInterval: The amount of time in seconds that you wish to elapse between periodic syncs
  • syncFlexTime: The amount of flex time in seconds before syncInterval that you permit for the sync to take place. Must be less than syncInterval

A good example could be syncInterval: 12 * 60 * 60 (12 hours) and syncFlexTime: 0.5 * 60 * 60 (30 minutes).

Notice that syncFlexTime only works for Android 4.4+, for older versions, that value will be ignored and syncs will be always exact.


Invoke the sync task. Use the same values as in the init call.

Object: {
  syncInterval: number;
  syncFlexTime: number;

Be aware that for this method to work (if you call it from inside your app) you need to allow the task to work on the foreground.

Running example

You can try this library running the example app:

cd example && yarn && npm start

Then just run:

react-native run-android

Be careful: The installed app will trigger a sync around every minute (so it is easy to see that is working). If you debug the app, you should be able to see the HeadlessJS ouputing: Headless JS task was fired! (remember not to have the app on the foreground: Unless you override this behavior). After you try it, I recommend to uninstall the app so you don't harm your device battery life.

You can’t perform that action at this time.