- 📖 Table of Contents
- 📍 Overview
- 📦 Features
- 📂 repository Structure
- 🚀 Getting Started
- 🛣 Roadmap
- 🤝 Contributing
- 📄 License
- 👏 Acknowledgments
Start actions that continue to run in the grace period after the user switches apps. This library facilitates the
execution of ios's beginBackgroundTaskWithName and android's startForegroundService methods. The primary
objective is to emulate the behavior of beginBackgroundTaskWithName, allowing actions to persist even when the user
switches to another app. Examples include sending chat messages, creating tasks, or running synchronizations.
On iOS, the grace period typically lasts around 30 seconds, while on Android, foreground tasks can run for a longer duration, subject to device models and background policies. In general, a foreground task can safely run for about 30 seconds on both platforms. However, it's important to note that this library is not intended for background location tracking. iOS's limited 30-second window makes it impractical for such purposes. For background location tracking, alternatives like WorkManager or GTaskScheduler are more suitable.
For usage instructions, please refer to the Example provided.
- Execute JavaScript while the app is in the background.
- Run multiple foreground actions simultaneously.
- Forcefully terminate all foreground actions.
- Display notifications with customizable titles, descriptions, and optional progress bars, along with support for deep linking.
- Comply with the latest Android 34+ background policy, ensuring that foreground services continue to run without displaying a visible notification. Users can still access these services from the notification drawer.
- Receive notifications when the background execution time is about to expire. This feature allows users to save their data and terminate tasks gracefully.
- Limited support for web platforms. We recommend using the
runInJSmethod due to potential errors when attempting to run foreground actions on web browsers.
└── expo-foreground-actions/
├── .eslintrc.js
├── android/
├── example/
│ ├── App.tsx
│ ├── android/
│ ├── app.json
│ ├── babel.config.js
│ ├── metro.config.js
│ ├── package-lock.json
│ ├── package.json
│ ├── plugins/
│ │ └── expo-foreground-actions.js
│ ├── tsconfig.json
│ ├── webpack.config.js
│ └── yarn.lock
├── ios/
├── package-lock.json
├── package.json
├── plugins/
│ └── expo-foreground-actions.js
├── src/
│ ├── ExpoForegroundActions.types.ts
│ ├── ExpoForegroundActionsModule.ts
│ └── index.ts
├── tsconfig.json
└── yarn.lock
Dependencies
Please ensure you have the following dependencies installed on your system:
- ℹ️ Expo v49+
- ℹ️ Bare/Manage workflow, we do not support Expo GO
-
Clone the expo-foreground-actions repository:
NPM
npm install expo-foreground-actions
Yarn
yarn add expo-foreground-actions
-
Install the plugin, for now download the repo and copy the plugins folder to your project root.
-
Then update your app.json to include the plugin and a scheme if u wanna use the plugin with a deeplink.
https://docs.expo.dev/guides/linking/"expo": { "scheme": "myapp", "plugins": [ [ "./plugins/expo-foreground-actions" ] ], }
-
Make sure the plugin is loaded in your app.json, you can do this by running prebuild on managed or by running * pod install/gradle build* on bare.
For the time being, dedicated documentation is not available. However, you can explore the usage of current methods in the provided example app. Refer to the Example folder to understand how to utilize this package effectively.
export const runForegroundedAction = async (
act: (api: ForegroundApi) => Promise<void>,
androidSettings: AndroidSettings,
settings: Settings = { runInJS: false }
): Promise<void>;act: The foreground action function to be executed.androidSettings: Android-specific settings for the foreground action.settings: Additional settings for the foreground action.
export const startForegroundAction = async (
options?: AndroidSettings
): Promise<number>;options: Android-specific settings for the foreground action.
export const stopForegroundAction = async (id: number): Promise<void>;id: The unique identifier of the foreground action to stop.
export const updateForegroundedAction = async (
id: number,
options: AndroidSettings
): Promise<void>;id: The unique identifier of the foreground action to update.options: Updated Android-specific settings for the foreground action.
export const forceStopAllForegroundActions = async (): Promise<void>;- Forcefully stops all running foreground actions.
export const getForegroundIdentifiers = async (): Promise<number>;- Retrieves the identifiers of all currently running foreground actions.
export const getRanTaskCount = () => ranTaskCount;- Retrieves the count of tasks that have run.
export const getBackgroundTimeRemaining = async (): Promise<number>;- Retrieves the remaining background execution time on iOS.
export type ExpireEventPayload = {
remaining: number;
identifier: number;
};remaining: The remaining time in seconds before the foreground action expires.identifier: The unique identifier of the foreground action.
export interface AndroidSettings {
headlessTaskName: string;
notificationTitle: string;
notificationDesc: string;
notificationColor: string;
notificationIconName: string;
notificationIconType: string;
notificationProgress: number;
notificationMaxProgress: number;
notificationIndeterminate: boolean;
linkingURI: string;
}headlessTaskName: Name of the headless task associated with the foreground action.notificationTitle: Title of the notification shown during the foreground action.notificationDesc: Description of the notification.notificationColor: Color of the notification.notificationIconName: Name of the notification icon.notificationIconType: Type of the notification icon.notificationProgress: Current progress value for the notification.notificationMaxProgress: Maximum progress value for the notification.notificationIndeterminate: Indicates if the notification progress is indeterminate.linkingURI: URI to link to when the notification is pressed.
export interface Settings {
events?: {
onIdentifier?: (identifier: number) => void;
}
runInJS?: boolean,
}events: Event handlers for foreground actions.onIdentifier: A callback function called when an identifier is generated.
runInJS: Indicates whether to run the foreground action without using a headless task or ios background task.
ℹ️ Task 1: Initial launchℹ️ Task 2: Possiblity to run multiple foreground tasksℹ️ Any idea's are welcome =)
Contributions are welcome! Here are several ways you can contribute:
- Submit Pull Requests: Review open PRs, and submit your own PRs.
- Join the Discussions: Share your insights, provide feedback, or ask questions.
- Report Issues: Submit bugs found or log feature requests for ACETYLD.
Click to expand
- Fork the Repository: Start by forking the project repository to your GitHub account.
- Clone Locally: Clone the forked repository to your local machine using a Git client.
git clone <your-forked-repo-url>
- Create a New Branch: Always work on a new branch, giving it a descriptive name.
git checkout -b new-feature-x
- Make Your Changes: Develop and test your changes locally.
- Commit Your Changes: Commit with a clear and concise message describing your updates.
git commit -m 'Implemented new feature x.' - Push to GitHub: Push the changes to your forked repository.
git push origin new-feature-x
- Submit a Pull Request: Create a PR against the original project repository. Clearly describe the changes and their motivations.
Once your PR is reviewed and approved, it will be merged into the main branch.
This project is protected under the MIT License. For more details, refer to the LICENSE file.
- Idea/inspiration from https://github.com/Rapsssito/react-native-background-actions
- Expo for providing a platform to build universal apps using React Native.
- Benedikt for mentioning this package in the "thisweekinreact" newsletter: Week 176