npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

react-native-background-actions

v3.0.1

Published

React Native background service library for running background tasks forever in Android & iOS

Downloads

35,665

Readme

React Native background service library for running background tasks forever in Android & iOS. Schedule a background job that will run your JavaScript when your app is in the background or foreground.

WARNING

  • Android: This library relies on React Native's HeadlessJS for Android. Before building your JS task, make sure to read all the documentation. The jobs will run even if the app has been closed. In Android 12+ you will not be able to launch background tasks from the background.

  • iOS: This library relies on iOS's UIApplication beginBackgroundTaskWithName method, which won't keep your app in the background forever by itself. However, you can rely on other libraries like react-native-track-player that use audio, geolocalization, etc. to keep your app alive in the background while you excute the JS from this library.

Table of Contents

React Native / Android / iOS compatibility

To use this module you need to ensure you are using the correct version of React Native. If you are using an Android (targetSdkVersion) version lower than 31 (introduced in React Native 0.68.0) you will need to upgrade before attempting to use react-native-background-actions's latest version.

| Version | React Native version | Android (targetSdkVersion) version | iOS version | | ------- | -------------------- | ---------------------------------- | ------------ | | 3.X.X | >= Unknown | >= 31 | >= Unknown | | 2.6.7 | >= Unknown | >= Unknown | >= Unknown |

Install

Go to INSTALL.md to see the how to install, compatibility with RN and Linking process.

Usage

Example Code

import BackgroundService from 'react-native-background-actions';

const sleep = (time) => new Promise((resolve) => setTimeout(() => resolve(), time));

// You can do anything in your task such as network requests, timers and so on,
// as long as it doesn't touch UI. Once your task completes (i.e. the promise is resolved),
// React Native will go into "paused" mode (unless there are other tasks running,
// or there is a foreground app).
const veryIntensiveTask = async (taskDataArguments) => {
    // Example of an infinite loop task
    const { delay } = taskDataArguments;
    await new Promise( async (resolve) => {
        for (let i = 0; BackgroundService.isRunning(); i++) {
            console.log(i);
            await sleep(delay);
        }
    });
};

const options = {
    taskName: 'Example',
    taskTitle: 'ExampleTask title',
    taskDesc: 'ExampleTask description',
    taskIcon: {
        name: 'ic_launcher',
        type: 'mipmap',
    },
    color: '#ff00ff',
    linkingURI: 'yourSchemeHere://chat/jane', // See Deep Linking for more info
    parameters: {
        delay: 1000,
    },
};


await BackgroundService.start(veryIntensiveTask, options);
await BackgroundService.updateNotification({taskDesc: 'New ExampleTask description'}); // Only Android, iOS will ignore this call
// iOS will also run everything here in the background until .stop() is called
await BackgroundService.stop();

If you call stop() on background no new tasks will be able to be started! Don't call .start() twice, as it will stop performing previous background tasks and start a new one. If .start() is called on the backgound, it will not have any effect.

Options

| Property | Type | Description | | ------------- | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | taskName | <string> | Task name for identification. | | taskTitle | <string> | Android Required. Notification title. | | taskDesc | <string> | Android Required. Notification description. | | taskIcon | <taskIconOptions> | Android Required. Notification icon. | | color | <string> | Notification color. Default: "#ffffff". | | linkingURI | <string> | Link that will be called when the notification is clicked. Example: "yourSchemeHere://chat/jane". See Deep Linking for more info. Default: undefined. | | progressBar | <taskProgressBarOptions> | Notification progress bar. | | parameters | <any> | Parameters to pass to the task. |

taskIconOptions

Android only | Property | Type | Description | | --------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | | name | <string> | Required. Icon name in res/ folder. Ex: ic_launcher. | | type | <string> | Required. Icon type in res/ folder. Ex: mipmap. | | package | <string> | Icon package where to search the icon. Ex: com.example.package. It defaults to the app's package. It is highly recommended to leave like that. |

Example:

photo5837026843969041365

taskProgressBarOptions

Android only | Property | Type | Description | | --------------- | ----------- | --------------------------------------------- | | max | <number> | Required. Maximum value. | | value | <number> | Required. Current value. | | indeterminate | <boolean> | Display the progress status as indeterminate. |

Example:

ProgressBar

Deep Linking

Android only

To handle incoming links when the notification is clicked by the user, first you need to modify your android/app/src/main/AndroidManifest.xml and add an <intent-filter> (fill yourSchemeHere with the name you prefer):

  <manifest ... >
      ...
      <application ... >
          <activity
              ...
              android:launchMode="singleTask"> // Add this if not present
                  ...
                  <intent-filter android:label="filter_react_native">
                      <action android:name="android.intent.action.VIEW" />
                      <category android:name="android.intent.category.DEFAULT" />
                      <category android:name="android.intent.category.BROWSABLE" />
                      <data android:scheme="yourSchemeHere" />
                  </intent-filter>
      </application>
    </manifest>

You must provide a linkingURI in the BackgroundService's options that matches the scheme you just added to android/app/src/main/AndroidManifest.xml:

const options = {
    taskName: 'Example',
    taskTitle: 'ExampleTask title',
    taskDesc: 'ExampleTask description',
    taskIcon: {
        name: 'ic_launcher',
        type: 'mipmap',
    },
    color: '#ff00ff',
    linkingURI: 'yourSchemeHere://chat/jane', // Add this
    parameters: {
        delay: 1000,
    },
};


await BackgroundService.start(veryIntensiveTask, options);

React Native provides a Linking class to get notified of incoming links. Your JavaScript code must then listen to the url using React Native Linking class:

import { Linking } from 'react-native';

Linking.addEventListener('url', handleOpenURL);

function handleOpenURL(evt) {
    // Will be called when the notification is pressed
    console.log(evt.url);
    // do something
}

Events

'expiration'

iOS only Listen for the iOS-only expiration handler that allows you to 'clean up' shortly before the app’s remaining background time reaches 0. Check the iOS documentation for more info.

BackgroundService.on('expiration', () => {
    console.log('I am being closed :(');
});

await BackgroundService.start(veryIntensiveTask, options);

Maintainers

Acknowledgments

License

The library is released under the MIT license. For more information see LICENSE.