Background Location Tracker #

Flutter library for tracking location in both foreground and background modes.

Features #

• ✅ Foreground and background location tracking
• ✅ High accuracy and configurable settings
• ✅ Permission management
• ✅ Real-time location stream
• ✅ Distance and bearing calculations
• ✅ Mock location filtering
• ✅ Android and iOS support
• ✅ Notification support (Android)

Installation #

Add the following to your pubspec.yaml:

dependencies:
  background_location_tracker:
    path: ../background_location_tracker  # or from pub.dev

Platform Konfiqurasiyası #

Android #

Add the following to android/app/src/main/AndroidManifest.xml:

<manifest>
    <!-- Foreground location permission -->
    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
    <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
    
    <!-- Background location permission (Android 10+) -->
    <uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION" />
    
    <!-- Foreground service permission (Android 9+) -->
    <uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
    <uses-permission android:name="android.permission.FOREGROUND_SERVICE_LOCATION" />
    
    <application>
        ...
    </application>
</manifest>

iOS #

Add the following to ios/Runner/Info.plist:

<dict>
    <!-- Foreground location permission -->
    <key>NSLocationWhenInUseUsageDescription</key>
    <string>This app requires permission to access your location while in use</string>
    
    <!-- Background location permission -->
    <key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
    <string>This app requires permission to access your location in the background</string>
    
    <key>NSLocationAlwaysUsageDescription</key>
    <string>This app requires permission to access your location in the background</string>
    
    <!-- Background modes -->
    <key>UIBackgroundModes</key>
    <array>
        <string>location</string>
    </array>
</dict>

Usage #

1. Simple usage #

import 'package:background_location_tracker/background_location_tracker_library.dart';

final locationTracker = BackgroundLocationTracker();

// Check permission
final permission = await locationTracker.checkPermission();

// Request permission if not granted
if (!permission.isGranted) {
  await locationTracker.requestPermission();
}

// Get current location
final location = await locationTracker.getCurrentLocation();
print('Lat: ${location?.latitude}, Lng: ${location?.longitude}');

2. Real-time tracking #

// Listen to location updates
locationTracker.onLocationUpdate.listen((location) {
  print('Yeni məkan: ${location.latitude}, ${location.longitude}');
  print('Dəqiqlik: ${location.accuracy}m');
  print('Sürət: ${location.speed}m/s');
});

// Listen to errors
locationTracker.onError.listen((error) {
  print('Xəta: $error');
});

// Start tracking
await locationTracker.startTracking();

// Stop tracking
await locationTracker.stopTracking();

3. Tracking with configuration #

final settings = LocationSettings(
  accuracy: LocationAccuracy.high,
  distanceFilter: 10.0, // 10 meters
  timeInterval: 5000, // 5 seconds
  enableBackgroundTracking: true,
  showBackgroundNotification: true,
  notificationTitle: 'Location Tracking',
  notificationText: 'Your location is being tracked',
  allowMockLocations: false,
);

await locationTracker.startTracking(settings);

4. Background tracking #

// Request background permission
final permission = await locationTracker.requestPermission(
  requestBackgroundPermission: true,
);

if (permission == LocationPermissionStatus.always) {
  // Start background tracking
  final settings = LocationSettings(
    accuracy: LocationAccuracy.high,
    distanceFilter: 10.0,
    enableBackgroundTracking: true,
    showBackgroundNotification: true,
  );
  
  await locationTracker.startTracking(settings);
}

5. Distance calculation #

final distance = locationTracker.getDistanceBetween(
  40.4093, // start lat
  49.8671, // start lng
  40.4105, // end lat
  49.8680, // end lng
);
print('Distance: ${distance}m');

final bearing = locationTracker.getBearingBetween(
  40.4093, 49.8671,
  40.4105, 49.8680,
);
print('Bearing: ${bearing}°');

6. Utility methods #

// Is location service enabled?
final isEnabled = await locationTracker.isLocationServiceEnabled();

// Open app settings
await locationTracker.openAppSettings();

// Open location settings
await locationTracker.openLocationSettings();

// Last known location
final lastLocation = locationTracker.lastLocation;

// Is tracking active?
final isTracking = locationTracker.isTracking;

LocationData Model #

class LocationData {
  final double latitude;
  final double longitude;
  final double accuracy;
  final double? altitude;
  final double? speed;
  final double? speedAccuracy;
  final double? heading;
  final DateTime timestamp;
  final bool isMocked;
}

LocationSettings Model #

class LocationSettings {
  final LocationAccuracy accuracy;
  final double distanceFilter;
  final int? timeInterval;
  final bool enableBackgroundTracking;
  final bool showBackgroundNotification;
  final String? notificationTitle;
  final String? notificationText;
  final bool pauseLocationUpdatesAutomatically;
  final bool allowMockLocations;
}

LocationAccuracy Enum #

enum LocationAccuracy {
  lowest,              // Lowest accuracy
  low,                 // Low accuracy (~10km)
  medium,              // Medium accuracy (~100m)
  high,                // High accuracy (~10m)
  best,                // Best accuracy (GPS)
  bestForNavigation,   // Best for navigation
}

LocationPermissionStatus Enum #

enum LocationPermissionStatus {
  denied,              // Denied
  deniedForever,       // Denied permanently
  whileInUse,          // Only while in use
  always,              // Always (including background)
  notDetermined,       // Not determined
}

Tips #

1. Background tracking: Background permission must be requested separately on Android 10+ and iOS
2. Battery optimization: Choose appropriate distanceFilter and timeInterval values
3. Mock location: Use allowMockLocations: false in production
4. Notification: On Android, notification is mandatory for background tracking
5. Dispose: Call locationTracker.dispose() when widget is disposed

License #

MIT License

Author #

Fermayi Hesenov