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	bool	true when the OS signals that background time is nearly exhausted.

📂 lib/main.dart:

import 'package:flutter/material.dart';
import 'package:background_fetch/background_fetch.dart';

// This "Headless Task" is run when the app is terminated.
// Must be a top-level or static function.
@pragma('vm:entry-point')
void backgroundFetchHeadlessTask(HeadlessEvent task) async {
  String taskId = task.taskId;
  bool isTimeout = task.timeout;
  if (isTimeout) {
    // This task has exceeded its allowed running-time.
    print("[BackgroundFetch] Headless TIMEOUT: $taskId");
    BackgroundFetch.finish(taskId);
    return;
  }
  print("[BackgroundFetch] Headless event received: $taskId");
  BackgroundFetch.finish(taskId);
}

void main() {
  runApp(MyApp());

  // Register to receive BackgroundFetch events after app is terminated.
  // Requires {stopOnTerminate: false, enableHeadless: true}
  BackgroundFetch.registerHeadlessTask(backgroundFetchHeadlessTask);
}

taskId

String taskId

The identifier of the task that fired this headless event.

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

timeout

bool timeout

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.