background_location_plus

A Flutter plugin for reliable foreground and background location tracking on iOS and Android.

Designed for apps that require precise, continuous geolocation such as delivery, workforce tracking, attendance, trip logging, field services, and more.

---

Features

• High-accuracy location updates
• Background location tracking (iOS & Android)
• Stream-based API
• Configurable accuracy, interval, and distance filter
• Customizable Android foreground notification
• Native permission handling (both platforms)
• Works with minimized, locked, or inactive apps

---

Installation

Add to your pubspec.yaml:

dependencies:
  background_location_plus: ^0.0.3

Then run:

flutter pub get

---

Platform Setup

iOS (Required)

1. Add permissions to Info.plist:

<key>NSLocationWhenInUseUsageDescription</key>
<string>Your location is used to track your trips.</string>
<key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
<string>Your location is used even in background.</string>
<key>NSLocationAlwaysUsageDescription</key>
<string>Your location is used even when the app is closed.</string>

2. Enable Background Modes in Xcode:

Open Xcode > Runner > Signing & Capabilities > + Capability > Background Modes, then enable:

• Location updates

Android (Required)

1. Add permissions to android/app/src/main/AndroidManifest.xml:

<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION" />
<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
<uses-permission android:name="android.permission.FOREGROUND_SERVICE_LOCATION" />
<uses-permission android:name="android.permission.WAKE_LOCK" />

2. Register the foreground service inside <application>:

<service
    android:name="com.workifyplus.background_location_plus.ForegroundLocationService"
    android:foregroundServiceType="location"
    android:exported="false" />

---

Usage

import 'package:background_location_plus/background_location_plus.dart';

// 1. Initialize (call once)
await BackgroundLocationPlus.initialize();

// 2. Configure (optional — defaults: best accuracy, 5s interval, 10m distance)
await BackgroundLocationPlus.configure(
  accuracy: "best",        // "best", "balanced", or "low"
  timeInterval: 5,         // seconds (iOS only — Android uses interval in ms via LocationRequest)
  distanceFilter: 10,      // meters
  notificationTitle: "Tracking",       // Android notification title
  notificationText: "Recording trip",  // Android notification body
);

// 3. Request permissions
final granted = await BackgroundLocationPlus.requestPermissions();
if (!granted) {
  await BackgroundLocationPlus.openAppSettings();
  return;
}

// 4. Listen to location stream
BackgroundLocationPlus.onLocation.listen((loc) {
  print('${loc['latitude']}, ${loc['longitude']}');
  print('accuracy: ${loc['accuracy']}, speed: ${loc['speed']}');
  print('timestamp: ${loc['timestamp']}');
});

// 5. Start / Stop
await BackgroundLocationPlus.start();
await BackgroundLocationPlus.stop();

// 6. Check status
final running = await BackgroundLocationPlus.isRunning();

// 7. Dispose when done
await BackgroundLocationPlus.dispose();

---

API Reference

Method	Returns	Description
initialize()	Future<void>	Initialize native components. Safe to call multiple times.
configure(...)	Future<void>	Set accuracy, interval, distance, notification text. Applies in real-time if already running.
requestPermissions()	Future<bool>	Request location permissions natively. Returns true if granted.
start()	Future<bool>	Start location tracking.
stop()	Future<bool>	Stop location tracking.
isRunning()	Future<bool>	Check if tracking is active.
onLocation	Stream<Map>	Stream of location events with latitude, longitude, accuracy, speed, timestamp.
openAppSettings()	Future<void>	Opens the app's system settings page.
dispose()	Future<void>	Release resources. Call when plugin is no longer needed.

---

Example App

Check the /example folder for a full working app.

---

Roadmap

• Geofence support
• Activity recognition
• Custom notification icon support
• Web platform stub

---

Contributing

Pull requests are welcome. Please open an issue if you find a bug or require a feature.

License

MIT License — see LICENSE file.

Libraries

background_location_plus