react-native-background-runner v3.3.1

🌟react-native-background-runner🌟

• Installation
• Features
• Preview
• Demo For Location Tracker (ANDROID ONLY)
• IOS Setup
• Android Setup
• Usage
• License

Installation

• Through Yarn:

yarn add react-native-background-runner

• Through NPM:

npm install react-native-background-runner

Features 🚀🚀

• 🛠️ Our package is designed to tackle background-related issues on both iOS and Android platforms.

• 🧪 Test Phase: We are currently in the initial testing phase, with many exciting enhancements on the way.

• 🏃‍♂️ Background Runner on iOS: We've implemented a unique solution using the Location Core API trick to ensure seamless background running on iOS.

• 📍 Live Background Location Tracker (Android): Our package includes a powerful live background location tracker specifically built for Android devices.**

• 🆕 Coming Soon to iOS: Stay tuned for the upcoming release, which will include background location tracking functionality for iOS as well.

Preview

Demo-For-Location-Tracker-(ANDROID-ONLY)

IOS-Setup

Let us not forget the mandatory strings NSLocationAlwaysAndWhenInUseUsageDescription and NSLocationWhenInUseUsageDescription inside Our Info.plist. These are needed to display the permissions popup.

+   <key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
+	  <string>App Uses Location Services to allow background operations while performing long running tasks,  this insures data integrity on our side, and offers a better user experience</string>
+	  <key>NSLocationWhenInUseUsageDescription</key>
+	  <string>App Uses Location Services to allow background operations while performing long running tasks, this insures data integrity on our side, and offers a better user experience</string>

set the right capabilities for app

Android-Setup

Add the following code to android/app/src/main/AndroidManifest.xml:

<manifest ...>
  ...
  <application ...>
    ...
+    <service android:name="com.backgroundrunner.BackgroundRunnerTask" />
  </application>
</manifest>

After adding the code to the AndroidManifest.xml file, save the changes and continue with the Usage instructions.

Usage

Wrapper Component

To handle the lifecycle of your app, use the Runnable wrapper component. Place your app component within the Runnable component as follows:

<Runnable>
  {/* Your app component */}
</Runnable>

Background Task

To perform a background task, follow these steps:

• Define an asynchronous task function that takes taskData as a parameter. This function can have different implementations based on the platform.

  const task = async (taskData) => {
    await new Promise(async () => {
      const { delay } = taskData;
      for (let i = 0; Service.isRunning(); i++) {
        setRunnedValue(i);
        console.log('Runned -> ', i);
        await sleep(delay);
      }
    });
  };

• Use the toggleBackground function to control the background task. It checks if the background service is running and either starts or stops it accordingly.

const toggleBackground = async (runnerTask) => {
  if (!Service.isRunning()) {
    try {
      await Service.startRunnerTask(runnerTask, options);
      console.log('Successful start!');
    } catch (e) {
      console.log('Error', e);
    }
  } else {
    console.log('Stop background service');
    await Service.stop();
  }
};

Call toggleBackground(task) to start or stop the background task.

Location Tracker

For now, the location tracker only supports Android. Use the following methods to work with the location tracker:

• Start watching the user's location even if the app is closed:

Service.watchLocation(
  (location) => console.log('location =>>> ', location),
  options
);

• Stop watching the user's location:

Service.stopWatching();

• Listen for location update events:

DeviceEventEmitter.addListener('locationUpdate', handleLocationUpdate);

⚠️ Please note that the location tracker is currently only supported on Android.

License

MIT