location_tracking

A Flutter plugin for receiving location updates even when the app is terminated. Works on both iOS and Android platforms with full support for background execution.

Features

• 🌍 Continuous location tracking in background
• 📱 Works even when app is killed/terminated
• 🔋 Battery-efficient location updates
• 🎯 Configurable accuracy and update intervals
• 🔔 Android notification support
• 📍 Distance filter to reduce unnecessary updates
• 🔄 Auto-restart after device reboot (Android)
• ⚙️ Platform-specific settings for iOS and Android

Platform Support

Platform	Support	Min Version
Android	✅ Full	API 21+
iOS	✅ Full	iOS 11.0+
Web	❌ Not supported	-
Windows	❌ Not supported	-
macOS	❌ Not supported	-
Linux	❌ Not supported	-

Note: Web, Windows, macOS, and Linux platforms are not supported as they don't have native background location tracking capabilities.

Installation

Add this to your package's pubspec.yaml file:

dependencies:
  location_tracking: ^2.1.1

Then run:

flutter pub get

Platform Setup

Android

Add the following permissions to your AndroidManifest.xml:

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

iOS

Add the following to your Info.plist:

<key>NSLocationWhenInUseUsageDescription</key>
<string>This app needs access to location when in use</string>
<key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
<string>This app needs access to location in background</string>
<key>NSLocationAlwaysUsageDescription</key>
<string>This app needs access to location in background</string>
<key>UIBackgroundModes</key>
<array>
    <string>location</string>
    <string>fetch</string>
</array>

Usage

Basic Example

import 'package:location_tracking/background_locator.dart';
import 'package:location_tracking/location_dto.dart';
import 'package:location_tracking/settings/android_settings.dart';
import 'package:location_tracking/settings/ios_settings.dart';
import 'package:location_tracking/settings/locator_settings.dart';

// Initialize the plugin
await BackgroundLocator.initialize();

// Register location update
await BackgroundLocator.registerLocationUpdate(
  locationCallback,
  initCallback: initCallback,
  disposeCallback: disposeCallback,
  androidSettings: AndroidSettings(
    accuracy: LocationAccuracy.NAVIGATION,
    interval: 5,
    distanceFilter: 0,
    androidNotificationSettings: AndroidNotificationSettings(
      notificationChannelName: 'Location tracking',
      notificationTitle: 'Start Location Tracking',
      notificationMsg: 'Track location in background',
      notificationBigMsg: 'Background location is on to keep the app up-to-date with your location.',
    ),
  ),
  iosSettings: IOSSettings(
    accuracy: LocationAccuracy.NAVIGATION,
    distanceFilter: 0,
  ),
);

// Callback functions (must be top-level or static)
@pragma('vm:entry-point')
static void locationCallback(LocationDto locationDto) {
  print('Location: ${locationDto.latitude}, ${locationDto.longitude}');
}

@pragma('vm:entry-point')
static void initCallback(Map<dynamic, dynamic> params) {
  print('Callback initialized');
}

@pragma('vm:entry-point')
static void disposeCallback() {
  print('Callback disposed');
}

// Stop location updates
await BackgroundLocator.unRegisterLocationUpdate();

Configuration Options

Android Settings

• accuracy: Location accuracy (POWERLOW, LOW, BALANCED, HIGH, NAVIGATION)
• interval: Update interval in seconds
• distanceFilter: Minimum distance (meters) to trigger update
• androidNotificationSettings: Notification configuration for foreground service

iOS Settings

• accuracy: Location accuracy
• distanceFilter: Minimum distance (meters) to trigger update
• showsBackgroundLocationIndicator: Show blue bar indicator
• stopWithTerminate: Stop tracking when app terminates

Additional Resources

For more detailed information, check out:

• Example app - Complete working example
• API Documentation

Important Notes

• Callback functions must be top-level functions or static methods
• Use @pragma('vm:entry-point') annotation on callbacks
• Request location permissions before starting tracking
• On Android 10+, background location permission requires user approval
• iOS requires "Always" location permission for background tracking

Troubleshooting

Android

• Ensure all required permissions are in AndroidManifest.xml
• Check that notification settings are properly configured
• Verify foreground service is running

iOS

• Ensure Info.plist has all required location keys
• Check that background modes include "location"
• Verify "Always" permission is granted

License

This project is licensed under the MIT License - see the LICENSE file for details.

Contributors

Thanks to all who have contributed to this plugin:

• Original creators and maintainers of background_locator
• Yukams - background_locator_2 fork
• Rekab - Original background_locator creator
• All other contributors who have helped improve this package

Credits

This package is based on the excellent work of the background_locator community. Special thanks to:

• Natnael Seyoum and Tekletsadik Aknaw for background_locator_3
• Yukams for background_locator_2
• The original Rekab team for creating background_locator