expo-background-fetch

Perform periodic tasks in the background on iOS and Android

expo-background-fetch

Version: 55.0.6

Expo universal module for BackgroundFetch API. Allows you to register background tasks that run periodically even when the app is closed or in the background.

Installation

npx expo install expo-background-fetch expo-task-manager

Usage

import * as BackgroundFetch from 'expo-background-fetch';
import * as TaskManager from 'expo-task-manager';

const BACKGROUND_FETCH_TASK = 'background-fetch-task';

// Define task
TaskManager.defineTask(BACKGROUND_FETCH_TASK, async () => {
  const now = Date.now();
  console.log(`Background fetch executed at ${new Date(now).toISOString()}`);
  
  // Perform your background work here
  await fetchDataFromAPI();
  
  return BackgroundFetch.BackgroundFetchResult.NewData;
});

// Register task
async function registerBackgroundFetch() {
  return BackgroundFetch.registerTaskAsync(BACKGROUND_FETCH_TASK, {
    minimumInterval: 60 * 15, // 15 minutes
    stopOnTerminate: false,
    startOnBoot: true,
  });
}

API Reference

Methods

registerTaskAsync(taskName, options) · (taskName: string, options?: BackgroundFetchOptions) => Promise<void>

Registers a background fetch task

await BackgroundFetch.registerTaskAsync('my-task', {
  minimumInterval: 900, // 15 minutes in seconds
});

unregisterTaskAsync(taskName) · (taskName: string) => Promise<void>

Unregisters a background fetch task

await BackgroundFetch.unregisterTaskAsync('my-task');

getStatusAsync() · () => Promise<BackgroundFetchStatus>

Gets background fetch status

const status = await BackgroundFetch.getStatusAsync();
console.log('Status:', status);

setMinimumIntervalAsync(seconds) · (seconds: number) => Promise<void>

Sets minimum fetch interval (iOS only)

await BackgroundFetch.setMinimumIntervalAsync(60 * 30); // 30 minutes

Types

BackgroundFetchOptions

minimumInterval · number

Minimum interval in seconds between fetches. Default: 900 (15 min)

stopOnTerminate · boolean

Whether to stop task when app is terminated. Default: true

startOnBoot · boolean

Whether to start task on device boot (Android). Default: false

BackgroundFetchResult

enum BackgroundFetchResult {
  NoData = 1,
  NewData = 2,
  Failed = 3,
}

Examples

Sync Data in Background

import * as BackgroundFetch from 'expo-background-fetch';
import * as TaskManager from 'expo-task-manager';

const SYNC_TASK = 'background-sync';

TaskManager.defineTask(SYNC_TASK, async () => {
  try {
    // Fetch new data
    const response = await fetch('https://api.example.com/data');
    const data = await response.json();
    
    // Store locally
    await AsyncStorage.setItem('cached-data', JSON.stringify(data));
    
    return BackgroundFetch.BackgroundFetchResult.NewData;
  } catch (error) {
    console.error('Background sync failed:', error);
    return BackgroundFetch.BackgroundFetchResult.Failed;
  }
});

// Register on app start
async function setupBackgroundSync() {
  const status = await BackgroundFetch.getStatusAsync();
  
  if (status === BackgroundFetch.BackgroundFetchStatus.Available) {
    await BackgroundFetch.registerTaskAsync(SYNC_TASK, {
      minimumInterval: 60 * 60, // 1 hour
    });
  }
}

Platform Support

Platform	Supported
iOS	✅
Android	✅
Web	❌

Configuration

app.json

{
  "expo": {
    "plugins": [
      [
        "expo-background-fetch",
        {
          "android": {
            "minInterval": 15
          }
        }
      ]
    ]
  }
}

Best Practices

1. Battery Efficiency: Keep background tasks short
2. Minimum Interval: Respect system-imposed minimum intervals
3. Error Handling: Always handle errors gracefully
4. Return Values: Return appropriate BackgroundFetchResult
5. Testing: Test on real devices, not simulators

Background fetch intervals are not guaranteed. The system may adjust intervals based on battery, usage patterns, and other factors.

Resources

• Official Documentation
• GitHub Repository