@rn-native-utils/workmanager

A React Native library for performing background data syncs in Android using Android's WorkManager.

Installation

npm install @rn-native-utils/workmanager

or

yarn add @rn-native-utils/workmanager

Supported Platforms

Currently, this library only supports Android.

Usage

First, import the necessary functions and types from the library:

import { schedule, cancel, disableAppIgnoringBatteryOptimization, SchedulerTypes, WorkerPolicy, TimeUnits } from '@rn-native-utils/workmanager';
import type { BackgroundSchedulerParams } from '@rn-native-utils/workmanager';

Scheduling a Background Task

To schedule a background task, use the schedule function:

// ...
const params: BackgroundSchedulerParams = {
  taskKey: 'uniqueTaskKey',
  // Add other required parameters
};

const callback = async () => {
  // Your background task logic here
};

try {
  const isScheduled = await schedule(params, callback);
  if (isScheduled) {
    console.log('Background task scheduled successfully');
  } else {
    console.log('Failed to schedule background task');
  }
} catch (error) {
  console.error('Error scheduling background task:', error);
}

Canceling a Background Task

To cancel a scheduled background task, use the cancel function:

try {
  const isCanceled = await cancel('uniqueTaskKey');
  if (isCanceled) {
    console.log('Background task canceled successfully');
  } else {
    console.log('Failed to cancel background task');
  }
} catch (error) {
  console.error('Error canceling background task:', error);
}

Disabling Battery Optimization

To disable battery optimization for your app, which may be necessary for reliable background task execution, use the disableAppIgnoringBatteryOptimization function:

try {
  const isDisabled = disableAppIgnoringBatteryOptimization();
  if (isDisabled) {
    console.log('Battery optimization disabled successfully');
  } else {
    console.log('Failed to disable battery optimization');
  }
} catch (error) {
  console.error('Error disabling battery optimization:', error);
}

API Reference

Enums

The library provides several enums for configuring background tasks:

enum SchedulerTypes {
periodic = 'PERIODIC',
oneTime = 'ONE_TIME',
}

enum WorkerPolicy {
KEEP = 'KEEP',
REPLACE = 'REPLACE',
UPDATE = 'UPDATE',
}

enum TimeUnits {
HOUR = 'HOUR',
DAY = 'DAY',
SECOND = 'SECOND',
MINUTES = 'MINUTES',
}

Functions

1. schedule(params: BackgroundSchedulerParams, callback: Task): Promise<boolean>

   Schedules a background task with the given parameters and callback function.

2. cancel(taskKey: string): Promise<boolean>

   Cancels a scheduled background task with the specified task key.

3. disableAppIgnoringBatteryOptimization(): boolean

   Attempts to disable battery optimization for the app to ensure reliable background task execution.

Types

The BackgroundSchedulerParams type is used to configure the background task. Refer to the library's type definitions for the exact structure and available options.

BackgroundSchedulerParams

Property	Type	Required	Description
taskKey	string	Yes	Unique identifier for the background task
type	SchedulerTypes	Yes	Type of scheduler (PERIODIC or ONE_TIME)
maxRetryAttempts	number	No	Maximum number of retry attempts if task fails
retryDelay	number	No	Delay between retry attempts in milliseconds
taskTimeout	number	No	Maximum time allowed for task execution
allowedInForeground	boolean	No	Whether task can run while app is in foreground
syncInterval	number	No	Interval between periodic syncs
syncIntervalType	TimeUnits	No	Unit for syncInterval (SECOND, MINUTES, HOUR, DAY)
syncFlexTime	number	No	Flex time window for periodic syncs
syncFlexTimeType	TimeUnits	No	Unit for syncFlexTime
workerPolicy	WorkerPolicy	No	Policy for handling existing workers
extras	Record<string, any>	No	Additional data to be passed to the background task

Error Handling

All functions in this library throw errors if something goes wrong during execution. It's recommended to wrap calls to these functions in try-catch blocks for proper error handling.

Platform Specific Notes

• This library currently only supports Android. Calls to these functions on unsupported platforms (like iOS) will return false or do nothing.
• Make sure you have the necessary Android permissions and configurations set up in your project for background tasks to work properly.

Contributing

See the contributing guide to learn how to contribute to the repository and the development workflow.

License

MIT

---

Made with create-react-native-library