### Install React Native Background Actions

Source: https://context7.com/rapsssito/react-native-background-actions/llms.txt

Install the library using npm or Yarn. For iOS, ensure CocoaPods are installed.

```bash
yarn add react-native-background-actions
# or
npm install --save react-native-background-actions

# iOS: install CocoaPods
cd ios && pod install && cd ..
```

--------------------------------

### Install with npm

Source: https://github.com/rapsssito/react-native-background-actions/blob/master/INSTALL.md

Use this command to add the library to your project when using npm.

```bash
npm install --save react-native-background-actions
```

--------------------------------

### Install with Yarn

Source: https://github.com/rapsssito/react-native-background-actions/blob/master/INSTALL.md

Use this command to add the library to your project when using Yarn.

```bash
yarn add react-native-background-actions
```

--------------------------------

### Start and Stop Background Service

Source: https://github.com/rapsssito/react-native-background-actions/blob/master/README.md

Demonstrates how to start a background task with specified options and how to stop the service. Note that calling stop() prevents new tasks from starting. Calling start() twice will stop the previous task and initiate a new one. Starting a service while it's already running in the background has no effect.

```javascript
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();
```

--------------------------------

### iOS Pod Install

Source: https://github.com/rapsssito/react-native-background-actions/blob/master/INSTALL.md

After installing the package, run this command in the 'ios' directory to link native dependencies using CocoaPods.

```bash
$ cd ios && pod install && cd ..
```

--------------------------------

### BackgroundService.start(task, options)

Source: https://context7.com/rapsssito/react-native-background-actions/llms.txt

Registers and launches a background task. On Android, it registers the task as a HeadlessJS task and displays a foreground service notification. On iOS, the task runs immediately in the background extension window. If a task is already running, calling start() will stop the previous one first.

```APIDOC
## BackgroundService.start(task, options)

### Description
Registers and launches a background task. On Android the task is registered as a HeadlessJS task and a foreground service notification is shown. On iOS the task runs immediately in the background extension window. Calling `start()` while a task is already running will stop the previous task first.

### Parameters
#### Task Function (`task`)
- **task** (function) - Required - The JavaScript function to be executed in the background. This function receives an object containing parameters passed via the `options.parameters`.

#### Options (`options`)
- **taskName** (string) - Required - An internal unique identifier for the task.
- **taskTitle** (string) - Required (Android) - The title for the Android notification.
- **taskDesc** (string) - Required (Android) - The body text for the Android notification.
- **taskIcon** (object) - Optional - Configuration for the notification icon.
  - **name** (string) - Required - The name of the icon file (e.g., 'ic_launcher').
  - **type** (string) - Required - The type of the icon folder (e.g., 'mipmap').
- **color** (string) - Optional - The accent color for the notification (default: '#ffffff').
- **linkingURI** (string) - Optional (Android) - A deep link URI to open when the notification is tapped.
- **parameters** (object) - Optional - An object containing custom parameters to be passed to the `task` function.

### Request Example
```javascript
import BackgroundService from 'react-native-background-actions';

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

const uploadTask = async (taskData) => {
  const { endpoint, interval } = taskData;
  await new Promise(async (resolve) => {
    let count = 0;
    while (BackgroundService.isRunning()) {
      try {
        await fetch(endpoint, { method: 'POST', body: JSON.stringify({ tick: count }) });
        count++;
      } catch (e) {
        console.error('Upload failed:', e);
      }
      await sleep(interval);
    }
  });
};

const options = {
  taskName: 'DataUpload',
  taskTitle: 'Uploading Data',
  taskDesc: 'Syncing in background',
  taskIcon: {
    name: 'ic_launcher',
    type: 'mipmap',
  },
  color: '#0080ff',
  linkingURI: 'myapp://home',
  parameters: {
    endpoint: 'https://api.example.com/sync',
    interval: 5000,
  },
};

try {
  await BackgroundService.start(uploadTask, options);
  console.log('Background task started');
} catch (e) {
  console.error('Failed to start background task:', e);
}
```
```

--------------------------------

### Start Background Task with Options

Source: https://context7.com/rapsssito/react-native-background-actions/llms.txt

Registers and launches a background task. On Android, it uses HeadlessJS and shows a foreground notification. On iOS, it runs in the background extension. Ensure the task function is defined and options are correctly set.

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

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

// Task function — receives the parameters object from options.parameters
const uploadTask = async (taskData) => {
  const { endpoint, interval } = taskData;
  await new Promise(async (resolve) => {
    let count = 0;
    while (BackgroundService.isRunning()) {
      try {
        await fetch(endpoint, { method: 'POST', body: JSON.stringify({ tick: count }) });
        count++;
      } catch (e) {
        console.error('Upload failed:', e);
      }
      await sleep(interval);
    }
  });
};

const options = {
  taskName: 'DataUpload',
  taskTitle: 'Uploading Data',
  taskDesc: 'Syncing in background',
  taskIcon: {
    name: 'ic_launcher',
    type: 'mipmap',
  },
  color: '#0080ff',
  linkingURI: 'myapp://home',
  parameters: {
    endpoint: 'https://api.example.com/sync',
    interval: 5000,
  },
};

// Start
try {
  await BackgroundService.start(uploadTask, options);
  console.log('Background task started');
} catch (e) {
  console.error('Failed to start background task:', e);
}
```

--------------------------------

### Android 14+ Manifest Configuration

Source: https://github.com/rapsssito/react-native-background-actions/blob/master/INSTALL.md

For Android 14 and above, specify the foregroundServiceType in your service tag. This example uses 'dataSync'.

```xml
<manifest ... >
      ...
       <uses-permission
        android:name="android.permission.FOREGROUND_SERVICE_DATA_SYNC"
       />
        <application ... >
          ...
          <service 
            android:name="com.asterinet.react.bgactions.RNBackgroundActionsTask"
            android:foregroundServiceType="dataSync"
          />
          ...
        </application>
      ...
    </manifest>
```

--------------------------------

### BackgroundService.isRunning()

Source: https://context7.com/rapsssito/react-native-background-actions/llms.txt

Synchronously checks if a background task has been started and is currently running. It returns true if the task is active and false once `stop()` is called.

```APIDOC
## `BackgroundService.isRunning()` — Check task running state

Synchronously returns `true` if a task was started and has not been stopped. Returns `false` as soon as `stop()` is called, regardless of whether the task function has finished executing. Commonly used as a loop guard inside the task itself.

### Usage

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

// Check from UI
console.log('Is running?', BackgroundService.isRunning()); // true or false
```

### Example Task Guard

```js
const pollingTask = async (taskData) => {
  const { pollInterval } = taskData;
  await new Promise(async (resolve) => {
    while (BackgroundService.isRunning()) {  // Loop exits when stop() is called
      const response = await fetch('https://api.example.com/status');
      const data = await response.json();
      console.log('Poll result:', data);
      await new Promise((r) => setTimeout(r, pollInterval));
    }
    resolve();
  });
};
```
```

--------------------------------

### Check Task Running State with BackgroundService.isRunning()

Source: https://context7.com/rapsssito/react-native-background-actions/llms.txt

Use `BackgroundService.isRunning()` to synchronously check if a background task has been started and not yet stopped. It's useful as a loop guard within the task itself to ensure it terminates when `stop()` is called.

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

const pollingTask = async (taskData) => {
  const { pollInterval } = taskData;
  await new Promise(async (resolve) => {
    while (BackgroundService.isRunning()) {  // Loop exits when stop() is called
      const response = await fetch('https://api.example.com/status');
      const data = await response.json();
      console.log('Poll result:', data);
      await new Promise((r) => setTimeout(r, pollInterval));
    }
    resolve();
  });
};

// Check from UI
console.log('Is running?', BackgroundService.isRunning()); // true or false
```

--------------------------------

### BackgroundService.stop()

Source: https://context7.com/rapsssito/react-native-background-actions/llms.txt

Stops the active background task and dismisses the Android foreground notification. After calling stop(), isRunning() returns false immediately, even if the task promise has not yet resolved. Calling start() again after stop() is safe.

```APIDOC
## BackgroundService.stop()

### Description
Stops the active background task and dismisses the Android foreground notification. After calling `stop()`, `isRunning()` returns `false` immediately even if the task promise has not yet resolved. Calling `start()` again after `stop()` is safe.

### Method
POST

### Endpoint
`/stop`

### Usage
```javascript
import BackgroundService from 'react-native-background-actions';

const handleStopPress = async () => {
  if (BackgroundService.isRunning()) {
    await BackgroundService.stop();
    console.log('Background task stopped');
  }
};

// Guard: new tasks cannot be started from the background after stop() is called.
// If you need to restart, ensure stop() is only called from the foreground.
```
```

--------------------------------

### iOS Info.plist Configuration

Source: https://github.com/rapsssito/react-native-background-actions/blob/master/INSTALL.md

Add these keys to your Info.plist file to enable background task scheduling for App Store submission.

```xml
<key>BGTaskSchedulerPermittedIdentifiers</key>
    <array>
        <string>$(PRODUCT_BUNDLE_IDENTIFIER)</string>
    </array>
```

--------------------------------

### foregroundServiceType option

Source: https://context7.com/rapsssito/react-native-background-actions/llms.txt

An option for `BackgroundService.start` on Android 14+ (API 34) to specify the foreground service type(s). This requires corresponding declarations in `AndroidManifest.xml`.

```APIDOC
## `foregroundServiceType` option — Android foreground service type (Android 14+ / API 34)

Specifies one or more foreground service types as required by Android 14+. The values are OR-ed together at the native level. All specified types must be declared in `AndroidManifest.xml` under `android:foregroundServiceType` and have their corresponding `<uses-permission>` entries. Ignored on Android versions below API 29 and on iOS.

### Parameters for `BackgroundService.start`

- **foregroundServiceType** (array of strings) - Optional - An array of strings specifying the foreground service types (e.g., `['location', 'microphone']`).

### AndroidManifest.xml Requirements

```xml
<manifest xmlns:android="http://schemas.android.com/apk/res/android" ...>
    <uses-permission android:name="android.permission.FOREGROUND_SERVICE"/>
    <!-- Example permissions for location and microphone -->
    <uses-permission android:name="android.permission.FOREGROUND_SERVICE_LOCATION"/>
    <uses-permission android:name="android.permission.FOREGROUND_SERVICE_MICROPHONE"/>

    <application ...>
        <service
            android:name=".YourBackgroundService"
            android:foregroundServiceType="location|microphone" ... />
    </application>
</manifest>
```

### Usage

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

const locationAudioTask = async (taskData) => {
  await new Promise(async (resolve) => {
    while (BackgroundService.isRunning()) {
      // Collect GPS + audio data
      await new Promise((r) => setTimeout(r, 2000));
    }
    resolve();
  });
};

await BackgroundService.start(locationAudioTask, {
  taskName: 'LocationAudioCapture',
  taskTitle: 'Recording',
  taskDesc: 'Capturing location and audio',
  taskIcon: { name: 'ic_launcher', type: 'mipmap' },
  foregroundServiceType: ['location', 'microphone'], // Array of types
  parameters: {},
});
```
```

--------------------------------

### Link React Native Background Actions via CLI

Source: https://github.com/rapsssito/react-native-background-actions/blob/master/INSTALL.md

Use this command to automatically link the library for React Native versions prior to 0.60.

```bash
$ react-native link react-native-background-actions
```

--------------------------------

### iOS Info.plist Configuration

Source: https://context7.com/rapsssito/react-native-background-actions/llms.txt

Required configuration for iOS Info.plist for App Store submission, specifying permitted background task identifiers.

```xml
<key>BGTaskSchedulerPermittedIdentifiers</key>
<array>
    <string>$(PRODUCT_BUNDLE_IDENTIFIER)</string>
</array>
```

--------------------------------

### Manually Link Android for React Native < 0.60

Source: https://github.com/rapsssito/react-native-background-actions/blob/master/INSTALL.md

Manual linking steps for Android. Ensure to add the import statement and the package to your Application file, and update your Gradle files.

```java
import com.asterinet.react.bgactions.BackgroundActionsPackage;

```

```java
new BackgroundActionsPackage()
```

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

```

```gradle
compile project(':react-native-background-actions')

```

--------------------------------

### Background Task Options

Source: https://github.com/rapsssito/react-native-background-actions/blob/master/README.md

Configuration options for background tasks, primarily for Android notifications.

```APIDOC
## Options

### Description
Configuration options for background tasks, primarily for Android notifications.

### Parameters
#### Task Options
- **taskName** (string) - Required - Task name for identification.
- **taskTitle** (string) - Required (Android) - Notification title.
- **taskDesc** (string) - Required (Android) - Notification description.
- **taskIcon** (object) - Required (Android) - Notification icon configuration. See `taskIconOptions`.
- **color** (string) - Optional - Notification color. Default: `"#ffffff"`.
- **linkingURI** (string) - Optional - Link to be called when the notification is clicked. Default: `undefined`.
- **progressBar** (object) - Optional - Notification progress bar configuration. See `taskProgressBarOptions`.
- **foregroundServiceType** (Array<string>) - Optional (Android only) - Array of foreground service types to combine. Must match `android:foregroundServiceType` in `AndroidManifest.xml`.
- **parameters** (any) - Optional - Parameters to pass to the task.

#### taskIconOptions
**Android only**
- **name** (string) - Required - Icon name in res/ folder. Ex: `ic_launcher`.
- **type** (string) - Required - Icon type in res/ folder. Ex: `mipmap`.
- **package** (string) - Optional - Icon package where to search the icon. Ex: `com.example.package`. Defaults to the app's package.

#### taskProgressBarOptions
**Android only**
- **max** (number) - Required - Maximum value for the progress bar.
- **value** (number) - Required - Current value for the progress bar.
- **indeterminate** (boolean) - Optional - Display the progress status as indeterminate.
```

--------------------------------

### BackgroundService.isRunning()

Source: https://context7.com/rapsssito/react-native-background-actions/llms.txt

Checks if a background task is currently running.

```APIDOC
## BackgroundService.isRunning()

### Description
Checks if a background task is currently running. Returns `true` if a task is active, `false` otherwise.

### Method
GET

### Endpoint
`/isRunning`

### Response
#### Success Response (200)
- **isRunning** (boolean) - Indicates whether a background task is currently running.
```

--------------------------------

### BackgroundService.on('expiration', handler)

Source: https://context7.com/rapsssito/react-native-background-actions/llms.txt

Registers a handler to be called on iOS when the system is about to reclaim background execution time. This allows for graceful cleanup or state saving before the task is terminated.

```APIDOC
## `BackgroundService.on('expiration', handler)` — iOS expiration event

Fired on iOS shortly before the system reclaims background execution time (i.e., the background time budget is nearly exhausted). Use this to perform cleanup, save state, or gracefully stop the task before termination. This event is iOS-only; Android ignores it.

### Parameters

- **event** (string) - Must be `'expiration'`.
- **handler** (function) - The callback function to execute when the expiration event is fired.

### Usage

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

// Register the handler BEFORE calling start()
BackgroundService.on('expiration', () => {
  console.log('iOS: background time is about to expire — cleaning up');
  // Save any in-progress state, cancel pending requests, etc.
});

const backgroundTask = async (taskData) => {
  await new Promise(async (resolve) => {
    while (BackgroundService.isRunning()) {
      // Do work...
      await new Promise((r) => setTimeout(r, 1000));
    }
    resolve();
  });
};

await BackgroundService.start(backgroundTask, {
  taskName: 'IosSafeTask',
  taskTitle: 'Running Task',
  taskDesc: 'Task is active',
  taskIcon: { name: 'ic_launcher', type: 'mipmap' },
});
```
```

--------------------------------

### Configure Foreground Service Type (Android)

Source: https://github.com/rapsssito/react-native-background-actions/blob/master/README.md

Specify the foreground service type(s) for Android. Flags are OR-ed together, and all values must match your AndroidManifest.xml. Ignored on Android versions below API 29.

```javascript
foregroundServiceType: ['location'],
```

```javascript
foregroundServiceType: ['location', 'microphone'],
```

--------------------------------

### Android Manifest Permissions

Source: https://github.com/rapsssito/react-native-background-actions/blob/master/INSTALL.md

Include these permissions in your AndroidManifest.xml to allow foreground services and wake locks.

```xml
<manifest ... > \
        ... \
        <uses-permission android:name="android.permission.FOREGROUND_SERVICE" /> \
        <uses-permission android:name="android.permission.WAKE_LOCK" /> \
        ... \
    </manifest>
```

--------------------------------

### Listen for Incoming Links with React Native Linking

Source: https://github.com/rapsssito/react-native-background-actions/blob/master/README.md

Use React Native's Linking class to listen for incoming URLs. This function will be called when a notification is pressed, allowing you to process the URL.

```javascript
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
}
```

--------------------------------

### Handle Deep Linking from Notification (Android)

Source: https://context7.com/rapsssito/react-native-background-actions/llms.txt

Configure your app to handle deep links when a notification is tapped on Android. Ensure the `linkingURI` in the service options matches the `android:scheme` in your `AndroidManifest.xml`.

```javascript
import { Linking } from 'react-native';
import BackgroundService from 'react-native-background-actions';

// Handle incoming deep link when notification is tapped
Linking.addEventListener('url', (event) => {
  console.log('Opened from notification:', event.url);
  // e.g. navigate to a specific screen
});

// AndroidManifest.xml must include:
// <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="myapp" />
// </intent-filter>

await BackgroundService.start(myTask, {
  taskName: 'Notifier',
  taskTitle: 'App is running',
  taskDesc: 'Tap to open the chat',
  taskIcon: { name: 'ic_launcher', type: 'mipmap' },
  linkingURI: 'myapp://chat/support', // Must match AndroidManifest.xml scheme
  parameters: {},
});
```

--------------------------------

### AndroidManifest.xml for Deep Linking

Source: https://github.com/rapsssito/react-native-background-actions/blob/master/README.md

Modify your AndroidManifest.xml to include an intent filter for handling incoming links when a notification is clicked. Ensure the activity's launchMode is set to 'singleTask'.

```xml
<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>
```

--------------------------------

### Android Manifest for Location Services

Source: https://github.com/rapsssito/react-native-background-actions/blob/master/INSTALL.md

If your background task involves location services, use 'location' for foregroundServiceType and add the necessary permissions.

```xml
<manifest ... >
      ...
       <uses-permission
        android:name="android.permission.FOREGROUND_SERVICE_LOCATION"
       />
       <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
       <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
        <application ... >
          ...
          <service 
            android:name="com.asterinet.react.bgactions.RNBackgroundActionsTask"
            android:foregroundServiceType="location"
          />
          ...
        </application>
      ...
    </manifest>
```

--------------------------------

### Set Linking URI for Background Service

Source: https://github.com/rapsssito/react-native-background-actions/blob/master/README.md

Provide a linkingURI in the BackgroundService options that matches the scheme added to your AndroidManifest.xml to handle incoming links.

```javascript
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);
```

--------------------------------

### Configure Android Foreground Service Type with foregroundServiceType option

Source: https://context7.com/rapsssito/react-native-background-actions/llms.txt

Specify one or more foreground service types for Android 14+ (API 34) using the `foregroundServiceType` option. Ensure these types are declared in `AndroidManifest.xml` with corresponding permissions. This option is ignored on older Android versions and iOS.

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

// AndroidManifest.xml must declare:
// android:foregroundServiceType="location|microphone"
// with permissions FOREGROUND_SERVICE_LOCATION and FOREGROUND_SERVICE_MICROPHONE

const locationAudioTask = async (taskData) => {
  await new Promise(async (resolve) => {
    while (BackgroundService.isRunning()) {
      // Collect GPS + audio data
      await new Promise((r) => setTimeout(r, 2000));
    }
    resolve();
  });
};

await BackgroundService.start(locationAudioTask, {
  taskName: 'LocationAudioCapture',
  taskTitle: 'Recording',
  taskDesc: 'Capturing location and audio',
  taskIcon: { name: 'ic_launcher', type: 'mipmap' },
  foregroundServiceType: ['location', 'microphone'], // Array of types
  parameters: {},
});
```

--------------------------------

### Handle iOS Expiration Event with BackgroundService.on('expiration', handler)

Source: https://context7.com/rapsssito/react-native-background-actions/llms.txt

Register a handler for the 'expiration' event on iOS, which fires before the system reclaims background execution time. Use this to perform necessary cleanup or save state before the task is terminated. This event is iOS-specific.

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

// Register the handler BEFORE calling start()
BackgroundService.on('expiration', () => {
  console.log('iOS: background time is about to expire — cleaning up');
  // Save any in-progress state, cancel pending requests, etc.
});

const backgroundTask = async (taskData) => {
  await new Promise(async (resolve) => {
    while (BackgroundService.isRunning()) {
      // Do work...
      await new Promise((r) => setTimeout(r, 1000));
    }
    resolve();
  });
};

await BackgroundService.start(backgroundTask, {
  taskName: 'IosSafeTask',
  taskTitle: 'Running Task',
  taskDesc: 'Task is active',
  taskIcon: { name: 'ic_launcher', type: 'mipmap' },
});
```

--------------------------------

### Handle iOS Expiration Event

Source: https://github.com/rapsssito/react-native-background-actions/blob/master/README.md

Listen for the iOS-only 'expiration' event to perform cleanup operations shortly before the app's background time limit is reached. This is specific to iOS.

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

await BackgroundService.start(veryIntensiveTask, options);
```

--------------------------------

### Android Manifest Permissions

Source: https://context7.com/rapsssito/react-native-background-actions/llms.txt

Required permissions for Android, including foreground service and wake lock. For Android 14+, specify the foreground service type.

```xml
<manifest>
  <uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
  <uses-permission android:name="android.permission.WAKE_LOCK" />

  <!-- Android 14+ (API 34): declare the specific foreground service type permission -->
  <uses-permission android:name="android.permission.FOREGROUND_SERVICE_DATA_SYNC" />

  <application>
    <!-- Android 14+: foregroundServiceType must match what you pass in options -->
    <service
      android:name="com.asterinet.react.bgactions.RNBackgroundActionsTask"
      android:foregroundServiceType="dataSync"
    />
  </application>
</manifest>
```

--------------------------------

### BackgroundService.updateNotification(taskData)

Source: https://context7.com/rapsssito/react-native-background-actions/llms.txt

Dynamically updates the foreground service notification content on Android while a task is running. This is useful for displaying real-time progress. The method has no effect on iOS.

```APIDOC
## `BackgroundService.updateNotification(taskData)` — Update Android notification (Android only)

Dynamically updates the foreground service notification content while the task is running. Useful for showing real-time progress. On iOS, this method returns immediately without effect.

### Parameters

- **taskData** (object) - Required - An object containing properties to update the notification. Supported properties include `taskDesc` (string) and `progressBar` (object).
  - **taskDesc** (string) - The description text for the notification.
  - **progressBar** (object) - An object to configure the progress bar.
    - **max** (number) - The maximum value for the progress bar.
    - **value** (number) - The current value of the progress bar.
    - **indeterminate** (boolean) - If true, the progress bar is indeterminate.

### Usage

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

const progressTask = async (taskData) => {
  const { totalItems } = taskData;
  await new Promise(async (resolve) => {
    for (let i = 0; i <= totalItems && BackgroundService.isRunning(); i++) {
      // Update notification text and progress bar
      await BackgroundService.updateNotification({
        taskDesc: `Processing item ${i} of ${totalItems}`,
        progressBar: {
          max: totalItems,
          value: i,
          indeterminate: false,
        },
      });
      await new Promise((r) => setTimeout(r, 500));
    }
    resolve();
  });
};

await BackgroundService.start(progressTask, {
  taskName: 'FileProcessor',
  taskTitle: 'Processing Files',
  taskDesc: 'Starting...', 
  taskIcon: { name: 'ic_launcher', type: 'mipmap' },
  progressBar: { max: 100, value: 0 },
  parameters: { totalItems: 100 },
});
```
```

--------------------------------

### Update Android Notification with BackgroundService.updateNotification()

Source: https://context7.com/rapsssito/react-native-background-actions/llms.txt

Dynamically update the foreground service notification content on Android while the task is running. This is useful for displaying real-time progress. This method has no effect on iOS.

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

const progressTask = async (taskData) => {
  const { totalItems } = taskData;
  await new Promise(async (resolve) => {
    for (let i = 0; i <= totalItems && BackgroundService.isRunning(); i++) {
      // Update notification text and progress bar
      await BackgroundService.updateNotification({
        taskDesc: `Processing item ${i} of ${totalItems}`,
        progressBar: {
          max: totalItems,
          value: i,
          indeterminate: false,
        },
      });
      await new Promise((r) => setTimeout(r, 500));
    }
    resolve();
  });
};

await BackgroundService.start(progressTask, {
  taskName: 'FileProcessor',
  taskTitle: 'Processing Files',
  taskDesc: 'Starting...', 
  taskIcon: { name: 'ic_launcher', type: 'mipmap' },
  progressBar: { max: 100, value: 0 },
  parameters: { totalItems: 100 },
});
```

--------------------------------

### Stop Background Task

Source: https://context7.com/rapsssito/react-native-background-actions/llms.txt

Stops the active background task and dismisses the Android foreground notification. `isRunning()` returns false immediately after calling `stop()`. Ensure `stop()` is called from the foreground to allow restarting.

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

const handleStopPress = async () => {
  if (BackgroundService.isRunning()) {
    await BackgroundService.stop();
    console.log('Background task stopped');
  }
};

// Guard: new tasks cannot be started from the background after stop() is called.
// If you need to restart, ensure stop() is only called from the foreground.
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.