ObservabilityConfig class

Configuration for built-in observability hooks.

Pass to NativeWorkManager.configure to receive callbacks whenever a background task starts, completes, or fails. Useful for analytics, performance monitoring, and crash reporting — without having to manually subscribe to the events/progress streams everywhere in your app.

Setup

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await NativeWorkManager.initialize();

  NativeWorkManager.configure(
    observability: ObservabilityConfig(
      onTaskStart: (taskId, workerType) {
        analytics.track('bg_task_start', {'worker': workerType});
      },
      onTaskComplete: (event) {
        performance.record('task_duration', {
          'taskId': event.taskId,
          'elapsed': event.timestamp.difference(startTimes[event.taskId]!),
        });
      },
      onTaskFail: (event) {
        crashlytics.log('Background task failed: ${event.taskId}');
        if (event.message != null) {
          crashlytics.recordError(event.message!, null);
        }
      },
    ),
  );

  runApp(MyApp());
}

Callback Guarantees

• All callbacks are invoked on the main thread (same as the events/progress streams).
• Callbacks are fire-and-forget — exceptions inside them are caught and logged to avoid disrupting the events stream.
• onTaskStart fires when the native worker actually begins execution, driven by a dedicated lifecycle event from the native side. It fires for all tasks — including fast workers that never emit a progress update.
• onTaskComplete / onTaskFail are mutually exclusive for a given task.

Annotations

• @immutable

Constructors

ObservabilityConfig({void onTaskStart(String taskId, String workerType)?, void onTaskComplete(TaskEvent event)?, void onTaskFail(TaskEvent event)?, void onProgress(TaskProgress progress)?})

const

ObservabilityConfig.fromLogger(WorkManagerLogger logger)

Create an ObservabilityConfig from a WorkManagerLogger implementation.

factory

Properties

hashCode → int

The hash code for this object.

no setter, inherited

onProgress → void Function(TaskProgress progress)?

Called on every TaskProgress update for any task.

final

onTaskComplete → void Function(TaskEvent event)?

Called when a task completes successfully.

final

onTaskFail → void Function(TaskEvent event)?

Called when a task fails.

final

onTaskStart → void Function(String taskId, String workerType)?

Called when the native worker begins execution.

final

runtimeType → Type

A representation of the runtime type of the object.

no setter, inherited

Methods

noSuchMethod(Invocation invocation) → dynamic

Invoked when a nonexistent method or property is accessed.

inherited

toString() → String

A string representation of this object.

inherited

Operators

operator ==(Object other) → bool

The equality operator.

inherited