🚀 React Native Background Task Manager

The most comprehensive React Native library for managing foreground services with advanced task management, Android 14+ compliance, and enhanced notification capabilities.

Perfect for apps that need to perform long-running background tasks like data synchronization, file processing, location tracking, or media processing while keeping users informed through rich, interactive notifications.

✨ Why Choose This Library?

🎯 Core Features

• 🔥 Foreground Services - Keep your app running in the background with persistent notifications
• 📱 Rich Notifications - Customizable notifications with actions, progress bars, and buttons
• 🔄 Advanced Task Management - Task scheduling, prioritization, retry mechanisms, and lifecycle control
• 🛡️ Android 14+ Ready - Full compliance with latest Android requirements and service types
• ⚡ Smart Permission Handling - Automated permission requests and validation for all Android versions
• 🔋 Battery Optimization - Built-in battery optimization exemption handling
• 📊 Service Metrics - Real-time performance monitoring and detailed statistics
• 🏗️ Production Ready - Comprehensive test coverage, TypeScript support, and extensive documentation

🎨 Enhanced Capabilities

• 🎮 Multiple Action Buttons - Up to 3 interactive notification buttons with custom handlers
• 📈 Progress Tracking - Determinate and indeterminate progress indicators with real-time updates
• 🎵 Custom Notifications - Sounds, vibration, colors, and visual customization
• 🔗 Event System - Comprehensive event listeners for service lifecycle management
• 🧩 Headless Tasks - Background task execution support for React Native
• 📱 Cross-Platform - Seamlessly works on Android (iOS support planned)
• 🔒 Type Safe - Full TypeScript support with comprehensive type definitions

🚀 Quick Start

📦 Installation

npm install react-native-background-task-manager
# or
yarn add react-native-background-task-manager

⚡ Basic Usage

import ForegroundService from 'react-native-background-task-manager';

// Start a basic foreground service
await ForegroundService.startService({
  taskName: 'MyBackgroundTask',
  taskTitle: 'Background Sync',
  taskDesc: 'Syncing data with server...',
  serviceType: 'dataSync', // Required for Android 14+
  importance: 'DEFAULT',
  color: '#4CAF50'
});

// Check if service is running
const isRunning = await ForegroundService.isServiceRunning();

// Stop the service
await ForegroundService.stopService();

🎨 Advanced Usage with Progress

import ForegroundService from 'react-native-background-task-manager';

// Start service with progress tracking and action buttons
await ForegroundService.startService({
  taskName: 'FileProcessor',
  taskTitle: 'Processing Files',
  taskDesc: 'Processing media files...',
  serviceType: 'mediaProcessing',
  importance: 'HIGH',
  
  // Progress configuration
  progress: {
    max: 100,
    curr: 0,
    indeterminate: false
  },
  
  // Multiple action buttons
  actions: [
    { id: 'pause', title: 'Pause', icon: 'pause' },
    { id: 'settings', title: 'Settings', icon: 'settings' },
    { id: 'stop', title: 'Stop', icon: 'stop' }
  ],
  
  // Visual customization
  color: '#4CAF50',
  vibration: true,
  setOnlyAlertOnce: true,
  
  // Auto-stop after completion
  autoStop: true,
  timeoutMs: 300000 // 5 minutes timeout
});

// Update progress
await ForegroundService.updateService({
  taskDesc: 'Processing... 50%',
  progress: { max: 100, curr: 50 }
});

// Handle action button presses
ForegroundService.addEventListener({
  onActionPress: (actionId) => {
    switch(actionId) {
      case 'pause':
        // Handle pause action
        break;
      case 'stop':
        ForegroundService.stopService();
        break;
    }
  }
});

🔧 Task Management

import { TaskManager } from 'react-native-background-task-manager';

// Add a recurring task
const taskId = TaskManager.addTask(
  async () => {
    // Your background task logic
    console.log('Executing background task...');
    await syncDataWithServer();
  },
  {
    delay: 5000,        // Initial delay
    onLoop: true,       // Repeat task
    priority: 'high',   // Task priority
    retryCount: 3,      // Retry on failure
    timeout: 30000,     // Task timeout
    onSuccess: () => console.log('Task completed successfully'),
    onError: (error) => console.error('Task failed:', error)
  }
);

// Get task statistics
const stats = TaskManager.getStats();
console.log(`Running tasks: ${stats.runningTasks}`);

// Control tasks
TaskManager.pauseTask(taskId);
TaskManager.resumeTask(taskId);
TaskManager.removeTask(taskId);

📚 Documentation

📖 Complete Guides

• 📋 API Reference - Complete API documentation with examples
• 🛠️ Installation Guide - Detailed setup instructions for Android
• ⚡ Quick Start Guide - Get up and running in minutes
• 📝 Examples Collection - Real-world usage examples and demos
• ❓ FAQ - Frequently asked questions and solutions
• 🔄 Migration Guide - Upgrading from older versions

🔗 Quick Links

| Topic | Description | Link | |-------|-------------|------| | Service Types | Android 14+ service type requirements | See Installation Guide | | Permissions | Required permissions and setup | See Installation Guide | | Troubleshooting | Common issues and solutions | See FAQ | | Examples | Real-world usage examples | See Examples |

🛠️ Android Setup Requirements

Required Permissions

Add to android/app/src/main/AndroidManifest.xml:

<!-- Core permissions -->
<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
<uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
<uses-permission android:name="android.permission.WAKE_LOCK" />

<!-- Android 14+ service type permissions -->
<uses-permission android:name="android.permission.FOREGROUND_SERVICE_DATA_SYNC" />
<uses-permission android:name="android.permission.FOREGROUND_SERVICE_MEDIA_PROCESSING" />
<!-- Add other service types as needed -->

Service Declaration

<application>
  <service
      android:name="com.reactnativeforegroundservice.ForegroundService"
      android:enabled="true"
      android:exported="false"
      android:foregroundServiceType="dataSync|mediaProcessing" />
</application>

For complete setup instructions, see Installation Guide

🔧 Android 14+ Service Types

| Service Type | Permission | Use Case | |-------------|------------|----------| | dataSync | FOREGROUND_SERVICE_DATA_SYNC | Data synchronization, API calls | | mediaProcessing | FOREGROUND_SERVICE_MEDIA_PROCESSING | Audio/video processing | | location | FOREGROUND_SERVICE_LOCATION | GPS tracking, location services | | camera | FOREGROUND_SERVICE_CAMERA | Camera operations | | microphone | FOREGROUND_SERVICE_MICROPHONE | Audio recording | | phoneCall | FOREGROUND_SERVICE_PHONE_CALL | VoIP, calling features |

🎯 Real-World Examples

📊 Data Synchronization

// Perfect for apps that sync data in the background
await ForegroundService.startService({
  taskName: 'DataSync',
  taskTitle: 'Syncing Data',
  taskDesc: 'Downloading latest updates...',
  serviceType: 'dataSync',
  importance: 'LOW',
  color: '#2196F3',
  progress: { max: 100, curr: 0 },
  autoStop: true
});

🎵 Media Processing

// Ideal for audio/video processing apps
await ForegroundService.startService({
  taskName: 'AudioProcessor',
  taskTitle: 'Processing Audio',
  taskDesc: 'Converting audio files...',
  serviceType: 'mediaProcessing',
  importance: 'DEFAULT',
  actions: [
    { id: 'pause', title: 'Pause', icon: 'pause' },
    { id: 'cancel', title: 'Cancel', icon: 'close' }
  ],
  progress: { max: 100, curr: 0 }
});

📍 Location Tracking

// Great for fitness, delivery, or tracking apps
await ForegroundService.startService({
  taskName: 'LocationTracker',
  taskTitle: 'Tracking Location',
  taskDesc: 'Recording your route...',
  serviceType: 'location',
  importance: 'DEFAULT',
  actions: [
    { id: 'stop', title: 'Stop Tracking', icon: 'stop' }
  ],
  color: '#4CAF50'
});

📈 Performance & Best Practices

🔋 Battery Optimization

• Request Exemption: Always request battery optimization exemption for critical services
• Service Types: Use specific service types instead of generic ones
• Auto-Stop: Enable autoStop for finite tasks to prevent unnecessary battery drain

📱 User Experience

• Clear Descriptions: Use descriptive task titles and descriptions
• Progress Updates: Keep users informed with progress indicators
• Action Buttons: Provide pause/stop controls for better user control

🔧 Development Tips

• Error Handling: Always wrap service calls in try-catch blocks
• Permission Checks: Verify permissions before starting services
• Testing: Test on various Android versions and devices

🧪 Testing

Run the comprehensive test suite:

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage
npm run test:coverage

# Type checking
npm run typescript

# Linting
npm run lint

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Setup

git clone https://github.com/paulkiren/react-native-background-task-manager.git
cd react-native-background-task-manager
npm install
npm run validate

📄 License

MIT License - see LICENSE for details.

🙏 Acknowledgments

• React Native community for inspiration and feedback
• Android developers for comprehensive foreground service documentation
• Contributors who help improve this library

📞 Support

• 🐛 Bug Reports: GitHub Issues
• 💬 Questions: GitHub Discussions
• 📖 Documentation: API Reference

⬆ Back to Top

Made with ❤️ by the React Native community