{"id":17623465,"url":"https://github.com/rapsssito/react-native-background-actions","last_synced_at":"2025-05-15T02:04:38.284Z","repository":{"id":37397350,"uuid":"233913691","full_name":"Rapsssito/react-native-background-actions","owner":"Rapsssito","description":"React Native background service library for running background tasks forever in Android \u0026 iOS.","archived":false,"fork":false,"pushed_at":"2024-07-29T21:23:01.000Z","size":759,"stargazers_count":856,"open_issues_count":41,"forks_count":130,"subscribers_count":8,"default_branch":"master","last_synced_at":"2025-04-03T10:07:10.740Z","etag":null,"topics":["android","background","background-task","ios","react-native","react-native-library"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Rapsssito.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":["Rapsssito"]}},"created_at":"2020-01-14T18:59:19.000Z","updated_at":"2025-04-03T02:33:37.000Z","dependencies_parsed_at":"2024-03-13T00:32:08.601Z","dependency_job_id":"8395c49c-00a3-42eb-9621-e46ace0ee36f","html_url":"https://github.com/Rapsssito/react-native-background-actions","commit_stats":{"total_commits":82,"total_committers":14,"mean_commits":5.857142857142857,"dds":"0.36585365853658536","last_synced_commit":"a6e3e1ae95679404c84eab3071df151a852c0e70"},"previous_names":[],"tags_count":28,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Rapsssito%2Freact-native-background-actions","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Rapsssito%2Freact-native-background-actions/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Rapsssito%2Freact-native-background-actions/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Rapsssito%2Freact-native-background-actions/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Rapsssito","download_url":"https://codeload.github.com/Rapsssito/react-native-background-actions/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248368353,"owners_count":21092343,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["android","background","background-task","ios","react-native","react-native-library"],"created_at":"2024-10-22T21:09:44.163Z","updated_at":"2025-04-11T09:33:19.708Z","avatar_url":"https://github.com/Rapsssito.png","language":"Java","funding_links":["https://github.com/sponsors/Rapsssito"],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n    \u003cimg src=\"https://i.imgur.com/G8BUzdZ.png\" /\u003e\n    \u003cbr\u003e\u003c/br\u003e\n    \u003cimg src=\"https://github.com/Rapsssito/react-native-background-actions/workflows/Release/badge.svg\" /\u003e\n    \u003cimg src=\"https://img.shields.io/npm/dw/react-native-background-actions\" /\u003e\n    \u003cimg src=\"https://img.shields.io/npm/v/react-native-background-actions?color=gr\u0026label=npm%20version\" /\u003e\n\u003c/p\u003e\n\nReact Native background service library for running **background tasks forever in Android \u0026 iOS**. Schedule a background job that will run your JavaScript when your app is in the background or foreground.\n\n### WARNING\n- **Android**: This library relies on React Native's [`HeadlessJS`](https://facebook.github.io/react-native/docs/headless-js-android) for Android. Before building your JS task, make sure to read all the [documentation](https://facebook.github.io/react-native/docs/headless-js-android). The jobs will run even if the app has been closed. [In Android 12+](https://developer.android.com/guide/components/foreground-services#background-start-restrictions) you will not be able to launch background tasks from the background. A notification will be shown when the task is running, it is not possible to start the service without it. The notification will only be visible in Android.\n\n- **iOS**: This library relies on iOS's [`UIApplication beginBackgroundTaskWithName` method](https://developer.apple.com/documentation/uikit/uiapplication/1623051-beginbackgroundtaskwithname?language=objc), which **won't keep your app in the background forever** by itself. However, you can rely on other libraries like [`react-native-track-player`](https://github.com/react-native-kit/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.\n\n\n## Table of Contents \u003c!-- omit in toc --\u003e\n\n- [React Native / Android / iOS compatibility](#react-native--android--ios-compatibility)\n- [Install](#install)\n- [Usage](#usage)\n  - [Example Code](#example-code)\n  - [Options](#options)\n    - [taskIconOptions](#taskiconoptions)\n    - [taskProgressBarOptions](#taskprogressbaroptions)\n  - [Deep Linking](#deep-linking)\n  - [Events](#events)\n    - ['expiration'](#expiration)\n- [Maintainers](#maintainers)\n- [Acknowledgments](#acknowledgments)\n- [License](#license)\n\n## React Native / Android / iOS compatibility\nTo 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.\n\n| Version | React Native version | Android (targetSdkVersion) version | iOS version  |\n| ------- | -------------------- | ---------------------------------- | ------------ |\n| `4.X.X` | `\u003e= Unknown`         | `\u003e= 34`                            | `\u003e= Unknown` |\n| `3.X.X` | `\u003e= Unknown`         | `\u003e= 31`                            | `\u003e= Unknown` |\n| `2.6.7` | `\u003e= Unknown`         | `\u003e= Unknown`                       | `\u003e= Unknown` |\n\n## Install\n\nGo to [INSTALL.md](./INSTALL.md) to see the how to install, compatibility with RN and Linking process.\n\n## Usage\n\n### Example Code\n\n```js\nimport BackgroundService from 'react-native-background-actions';\n\nconst sleep = (time) =\u003e new Promise((resolve) =\u003e setTimeout(() =\u003e resolve(), time));\n\n// You can do anything in your task such as network requests, timers and so on,\n// as long as it doesn't touch UI. Once your task completes (i.e. the promise is resolved),\n// React Native will go into \"paused\" mode (unless there are other tasks running,\n// or there is a foreground app).\nconst veryIntensiveTask = async (taskDataArguments) =\u003e {\n    // Example of an infinite loop task\n    const { delay } = taskDataArguments;\n    await new Promise( async (resolve) =\u003e {\n        for (let i = 0; BackgroundService.isRunning(); i++) {\n            console.log(i);\n            await sleep(delay);\n        }\n    });\n};\n\nconst options = {\n    taskName: 'Example',\n    taskTitle: 'ExampleTask title',\n    taskDesc: 'ExampleTask description',\n    taskIcon: {\n        name: 'ic_launcher',\n        type: 'mipmap',\n    },\n    color: '#ff00ff',\n    linkingURI: 'yourSchemeHere://chat/jane', // See Deep Linking for more info\n    parameters: {\n        delay: 1000,\n    },\n};\n\n\nawait BackgroundService.start(veryIntensiveTask, options);\nawait BackgroundService.updateNotification({taskDesc: 'New ExampleTask description'}); // Only Android, iOS will ignore this call\n// iOS will also run everything here in the background until .stop() is called\nawait BackgroundService.stop();\n```\n\u003e If you call stop() on background no new tasks will be able to be started!\n\u003e Don't call .start() twice, as it will stop performing previous background tasks and start a new one. \n\u003e If .start() is called on the backgound, it will not have any effect.\n\n### Options\n| Property      | Type                                                  | Description                                                                                                                                                                    |\n| ------------- | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |\n| `taskName`    | `\u003cstring\u003e`                                            | Task name for identification.                                                                                                                                                  |\n| `taskTitle`   | `\u003cstring\u003e`                                            | **Android Required**. Notification title.                                                                                                                                      |\n| `taskDesc`    | `\u003cstring\u003e`                                            | **Android Required**. Notification description.                                                                                                                                |\n| `taskIcon`    | [`\u003ctaskIconOptions\u003e`](#taskIconOptions)               | **Android Required**. Notification icon.                                                                                                                                       |\n| `color`       | `\u003cstring\u003e`                                            | Notification color. **Default**: `\"#ffffff\"`.                                                                                                                                  |\n| `linkingURI`  | `\u003cstring\u003e`                                            | Link that will be called when the notification is clicked. Example: `\"yourSchemeHere://chat/jane\"`. See [Deep Linking](#deep-linking) for more info. **Default**: `undefined`. |\n| `progressBar` | [`\u003ctaskProgressBarOptions\u003e`](#taskProgressBarOptions) | Notification progress bar.                                                                                                                                                     |\n| `parameters`  | `\u003cany\u003e`                                               | Parameters to pass to the task.                                                                                                                                                |\n\n#### taskIconOptions\n**Android only**\n| Property  | Type       | Description                                                                                                                                          |\n| --------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `name`    | `\u003cstring\u003e` | **Required**. Icon name in res/ folder. Ex: `ic_launcher`.                                                                                           |\n| `type`    | `\u003cstring\u003e` | **Required**. Icon type in res/ folder. Ex: `mipmap`.                                                                                                |\n| `package` | `\u003cstring\u003e` | 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.** |\n\nExample:\n\n![photo5837026843969041365](https://user-images.githubusercontent.com/44206249/72532521-de49e280-3873-11ea-8bf6-00618bcb82ab.jpg)\n\n#### taskProgressBarOptions\n**Android only**\n| Property        | Type        | Description                                   |\n| --------------- | ----------- | --------------------------------------------- |\n| `max`           | `\u003cnumber\u003e`  | **Required**. Maximum value.                  |\n| `value`         | `\u003cnumber\u003e`  | **Required**. Current value.                  |\n| `indeterminate` | `\u003cboolean\u003e` | Display the progress status as indeterminate. |\n\nExample:\n\n![ProgressBar](https://developer.android.com/images/ui/notifications/notification-progressbar_2x.png)\n\n### Deep Linking\n**Android only**\n\nTo 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 `\u003cintent-filter\u003e` (fill `yourSchemeHere` with the name you prefer):\n```xml\n  \u003cmanifest ... \u003e\n      ...\n      \u003capplication ... \u003e\n          \u003cactivity\n              ...\n              android:launchMode=\"singleTask\"\u003e // Add this if not present\n                  ...\n                  \u003cintent-filter android:label=\"filter_react_native\"\u003e\n                      \u003caction android:name=\"android.intent.action.VIEW\" /\u003e\n                      \u003ccategory android:name=\"android.intent.category.DEFAULT\" /\u003e\n                      \u003ccategory android:name=\"android.intent.category.BROWSABLE\" /\u003e\n                      \u003cdata android:scheme=\"yourSchemeHere\" /\u003e\n                  \u003c/intent-filter\u003e\n      \u003c/application\u003e\n    \u003c/manifest\u003e\n```\n\nYou must provide a `linkingURI` in the BackgroundService's [options](#options) that matches the scheme you just added to **`android/app/src/main/AndroidManifest.xml`**:\n```js\nconst options = {\n    taskName: 'Example',\n    taskTitle: 'ExampleTask title',\n    taskDesc: 'ExampleTask description',\n    taskIcon: {\n        name: 'ic_launcher',\n        type: 'mipmap',\n    },\n    color: '#ff00ff',\n    linkingURI: 'yourSchemeHere://chat/jane', // Add this\n    parameters: {\n        delay: 1000,\n    },\n};\n\n\nawait BackgroundService.start(veryIntensiveTask, options);\n```\n\nReact 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:\n```js\nimport { Linking } from 'react-native';\n\nLinking.addEventListener('url', handleOpenURL);\n\nfunction handleOpenURL(evt) {\n    // Will be called when the notification is pressed\n    console.log(evt.url);\n    // do something\n}\n```\n\n### Events\n#### 'expiration'\n**iOS only**\nListen 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](https://developer.apple.com/documentation/uikit/uiapplication/1623031-beginbackgroundtask) for more info.\n\n```js\nBackgroundService.on('expiration', () =\u003e {\n    console.log('I am being closed :(');\n});\n\nawait BackgroundService.start(veryIntensiveTask, options);\n\n```\n\n## Maintainers\n\n* [Rapsssito](https://github.com/rapsssito) [[Support me :heart:](https://github.com/sponsors/Rapsssito)]\n\n## Acknowledgments\n\n* iOS part originally forked from [react-native-background-timer](https://github.com/ocetnik/react-native-background-timer)\n\n## License\n\nThe library is released under the MIT license. For more information see [`LICENSE`](/LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frapsssito%2Freact-native-background-actions","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frapsssito%2Freact-native-background-actions","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frapsssito%2Freact-native-background-actions/lists"}