react-native-background-fetch

When using Background Fetch on iOS, be aware of the following platform behaviors:

• App Termination: If your app is terminated, iOS will not fire events. There is no stopOnTerminate: false option available for iOS.
• Event Frequency: iOS uses a machine-learning algorithm to determine event frequency. It can take days for this algorithm to settle into a regular pattern. If your simulated events work, your configuration is likely correct.
• User Inactivity: If a user does not open your iOS app for long periods, iOS may stop firing events entirely.
• Scheduled Tasks: The scheduleTask method appears to only fire when the device is plugged into power.

Background Fetch attempts to awaken your app in the background approximately every 15 minutes to provide a short period of background running time. When a fetch event occurs, the plugin executes a provided callbackFn.

Key Constraints:

• Minimum Interval: You cannot increase the frequency of events. The plugin is set to the most frequent possible rate, and you will never receive an event faster than every 15 minutes.
• OS Throttling: The operating system automatically throttles the frequency of events based on usage patterns (e.g., if the device hasn't been used for a long time, or if an iOS user disables background refresh).
• Task Scheduling: The plugin now includes a scheduleTask method for scheduling arbitrary "one-shot" or periodic tasks.

To enable react-native-background-fetch in an Expo project, you must update your app.json with the following configurations:

1. Add react-native-background-fetch to the plugins array.
2. Configure ios.infoPlist to include the required UIBackgroundModes (fetch and processing) and BGTaskSchedulerPermittedIdentifiers (com.transistorsoft.fetch).

If you plan to use custom tasks via BackgroundFetch.scheduleTask, you must also add those specific task identifiers to the BGTaskSchedulerPermittedIdentifiers list.

{
  "expo": {
    "name": "your-app-name",
    "plugins": [
      "react-native-background-fetch"
    ],
    "ios": {
      "infoPlist": {
        "UIBackgroundModes": [
          "fetch",
          "processing"
        ],
        "BGTaskSchedulerPermittedIdentifiers": [
          "com.transistorsoft.fetch"
        ]
      }
    }
  }
}

The BGTaskScheduler API introduced in iOS 13 requires you to register BackgroundFetch in your AppDelegate.m file.

Add the import and call didFinishLaunching within didFinishLaunchingWithOptions:

+#import <TSBackgroundFetch/TSBackgroundFetch.h>

@implementation AppDelegate

(BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
  .
  .
+ // [REQUIRED] Register BackgroundFetch
+ [[TSBackgroundFetch sharedInstance] didFinishLaunching];

  return YES;
}

You can use react-native link to automatically install the plugin into your Podfile. After linking, you must install the new CocoaPods dependencies by running pod install from the ios directory.

# After running react-native link
$ cd ios
$ pod install

For manual installation on Android, you must include the project in your android/settings.gradle file so Gradle can locate the module within your node_modules directory.

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

To run the Expo example (compatible with Expo SDK 54+), navigate to the example/expo directory, install dependencies, and use npx expo prebuild to generate the native project files before running on a simulator or device.

cd example/expo
npm install
npx expo prebuild
npx expo run:ios
npx expo run:android

BackgroundFetch requires an implementation of the didPerformFetchWithCompletionHandler method in your AppDelegate. To add this:

1. Expand the RNBackgroundFetch project in Xcode.
2. Drag and drop the file RNBackgroundFetch+AppDelegate.m into your project.
3. Ensure the file is placed in the same folder where your app's AppDelegate.m resides.

If your project does not support auto-linking, you can manually link the package using the React Native CLI:

react-native link react-native-background-fetch

To add the plugin to your React Native project, use either yarn or npm depending on your package manager preference.

$ yarn add react-native-background-fetch

# OR

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

To ensure Xcode can locate TSBackgroundFetch.framework, you must update your Build Settings:

1. Go to the Build Settings tab in Xcode.
2. Search for "framework search path".
3. Add the following path and ensure recursive is selected: $(PROJECT_DIR)/../node_modules/react-native-background-fetch/ios