HeadlessEvent

The event object delivered to a BackgroundFetch.registerHeadlessTask handler when the app is running in a terminated (headless) state on Android.

Property	Type	Description
taskId	string	Identifier of the task that fired. Pass to BackgroundFetch.finish.
timeout	boolean	true when the OS signals that background time is nearly exhausted.

📂 index.js (MUST be in index.js):

import BackgroundFetch, { HeadlessEvent } from "react-native-background-fetch";

const MyHeadlessTask = async (event: HeadlessEvent) => {
  let taskId = event.taskId;
  let isTimeout = event.timeout;
  if (isTimeout) {
    console.log('[BackgroundFetch] Headless TIMEOUT:', taskId);
    BackgroundFetch.finish(taskId);
    return;
  }
  console.log('[BackgroundFetch HeadlessTask] start:', taskId);

  // Perform your work here...

  BackgroundFetch.finish(taskId);
};

// Register your BackgroundFetch HeadlessTask
BackgroundFetch.registerHeadlessTask(MyHeadlessTask);

taskId

taskId: string;

The identifier of the task that fired this headless event.

Pass this value to BackgroundFetch.finish when your work is complete.

timeout

timeout: boolean;

true when the OS signals that background running-time is nearly exhausted.

When a timeout event fires you must immediately call BackgroundFetch.finish and stop any in-progress work. Failure to do so may cause the OS to penalize your app.