flutter_offline_background_location #

Offline background location tracking for Flutter (Android). Records location when the app is in background or closed, without requiring internet.

Features #

• Background tracking: Foreground service keeps recording when the app is closed or in background.
• Offline: Uses GPS/device location only; no network needed.
• Configurable: Interval, accuracy, notification text, retention, and max records.
• Session support: Each start/stop creates a session; filter locations by sessionId.
• DB maintenance: Optional retentionDays and maxRecords to limit storage.

Installation #

Add to your pubspec.yaml:

dependencies:
  flutter_offline_background_location: ^1.0.0

Then run flutter pub get.

For local development from a path (e.g. when the plugin lives in your repo), you can use:

dependencies:
  flutter_offline_background_location:
    path: ../packages/flutter_background_location

Android permissions #

Your app must request location and (on Android 13+) notification permission before starting tracking. The plugin declares in its manifest:

• ACCESS_FINE_LOCATION
• ACCESS_BACKGROUND_LOCATION
• FOREGROUND_SERVICE
• FOREGROUND_SERVICE_LOCATION
• POST_NOTIFICATIONS

Request them at runtime (e.g. with permission_handler) before calling startTracking().

Usage #

1. Configure (once, or when you want to change settings):

import 'package:flutter_offline_background_location/flutter_background_location.dart';

final plugin = FlutterBackgroundLocation.instance;

await plugin.configure(const BackgroundLocationConfig(
  intervalMinutes: 1,
  accuracy: LocationAccuracy.high,
  notificationTitle: 'Location tracking',
  notificationBody: 'Recording your position.',
  retentionDays: 30,   // 0 = unlimited
  maxRecords: 10000,   // 0 = unlimited
));

2. Initialize (creates DB and runs cleanup; call before first start):

await plugin.initialize();

3. Start / stop tracking:

await plugin.startTracking();
// ...
await plugin.stopTracking();

4. Read locations:

final list = await plugin.getLocations(limit: 100);
final last = await plugin.getLastLocation();

Optional filters: sinceTimestamp, sessionId.

5. Optional manual cleanup (retention and max records):

await plugin.runCleanup();

6. Clear all stored data (deletes every location record):

await plugin.clearAllLocations();

Configuration #

LocationRecord #

Each record has: id, latitude, longitude, timestamp, and optionally accuracy, altitude, speed, bearing, provider, sessionId.

Example app #

Run the example:

cd example
flutter pub get
flutter run

License #

BSD 3-Clause. See LICENSE file.