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

expo-foreground-actions

v0.4.5

Published

My new module

Downloads

117

Readme


📖 Table of Contents


📍 Overview

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.


📦 Features

For IOS & Android:

  • Execute JavaScript while the app is in the background.
  • Run multiple foreground actions simultaneously.
  • Forcefully terminate all foreground actions.

For Android:

  • 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.

For IOS:

  • Receive notifications when the background execution time is about to expire. This feature allows users to save their data and terminate tasks gracefully.

Web Support:

  • Limited support for web platforms. We recommend using the runInJS method due to potential errors when attempting to run foreground actions on web browsers.

📂 Repository Structure

└── 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

🚀 Getting Started

Dependencies

Please ensure you have the following dependencies installed on your system:

- ℹ️ Expo v49+

- ℹ️ Bare/Manage workflow, we do not support Expo GO

🔧 Installation

  1. Clone the expo-foreground-actions repository:

    NPM

    npm install expo-foreground-actions

    Yarn

    yarn add expo-foreground-actions
  2. Install the plugin, for now download the repo and copy the plugins folder to your project root.

  3. 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"
        ]
      ],
    }
  4. 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.

🤖 How to use?

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.

Example

🤖 Functions

runForegroundedAction

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.

startForegroundAction

export const startForegroundAction = async (
  options?: AndroidSettings
): Promise<number>;
  • options: Android-specific settings for the foreground action.

stopForegroundAction

export const stopForegroundAction = async (id: number): Promise<void>;
  • id: The unique identifier of the foreground action to stop.

updateForegroundedAction

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.

forceStopAllForegroundActions

export const forceStopAllForegroundActions = async (): Promise<void>;
  • Forcefully stops all running foreground actions.

getForegroundIdentifiers

export const getForegroundIdentifiers = async (): Promise<number>;
  • Retrieves the identifiers of all currently running foreground actions.

getRanTaskCount

export const getRanTaskCount = () => ranTaskCount;
  • Retrieves the count of tasks that have run.

getBackgroundTimeRemaining

export const getBackgroundTimeRemaining = async (): Promise<number>;
  • Retrieves the remaining background execution time on iOS.

🤖 Interfaces

ExpireEventPayload

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.

AndroidSettings

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.

Settings

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.

🛣 Project Roadmap

  • [X] ℹ️ Task 1: Initial launch
  • [X] ℹ️ Task 2: Possiblity to run multiple foreground tasks
  • [ ] ℹ️ Any idea's are welcome =)

🤝 Contributing

Contributions are welcome! Here are several ways you can contribute:

Contributing Guidelines

  1. Fork the Repository: Start by forking the project repository to your GitHub account.
  2. Clone Locally: Clone the forked repository to your local machine using a Git client.
    git clone <your-forked-repo-url>
  3. Create a New Branch: Always work on a new branch, giving it a descriptive name.
    git checkout -b new-feature-x
  4. Make Your Changes: Develop and test your changes locally.
  5. Commit Your Changes: Commit with a clear and concise message describing your updates.
    git commit -m 'Implemented new feature x.'
  6. Push to GitHub: Push the changes to your forked repository.
    git push origin new-feature-x
  7. 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.


📄 License

This project is protected under the MIT License. For more details, refer to the LICENSE file.


👏 Acknowledgments

  • 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

Return