background_locator_neo 1.1.0

A Flutter plugin to request the location even if the app is killed. Sending the location to a dart function in background, also provide a meter filter

background_locator_neo

A robust Flutter plugin for receiving location updates even when the app is in the background, killed, or the device has been rebooted.

This is a modern fork of background_locator_fixed, updated for Flutter 3.x, Dart 3.x, and Android 15/16 (API 35/36) and iOS 13+ compatibility.

---

🌟 Features

• Headless Execution: Receive location updates via a top-level or static Dart callback that runs in its own isolate.
• Persistence: Survives app termination (swiped away) and device reboots (Android).
• Foreground Service: Fully compliant with Android's Foreground Service requirements for location tracking.
• Modern iOS Support: Includes support for pausesLocationUpdatesAutomatically and activityType.
• Customizable: Control accuracy, interval, distance filters, and notification appearance.
• Dual Client Support: Choose between Google Play Services (Fused) or standard Android Location Manager.

---

🚀 Getting Started

1. Installation

Add background_locator_neo to your pubspec.yaml:

dependencies:
  background_locator_neo: ^1.1.0

---

2. Android Setup

Permissions & Service Declaration

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

<manifest xmlns:android="http://schemas.android.com/apk/res/android">
    <!-- Required Permissions -->
    <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.WAKE_LOCK" />
    <uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
    <uses-permission android:name="android.permission.FOREGROUND_SERVICE_LOCATION" />
    <uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED"/>

    <application ...>
        <!-- Required Service -->
        <service
            android:name="upendra.bajpai.background_locator_neo.IsolateHolderService"
            android:permission="android.permission.FOREGROUND_SERVICE"
            android:exported="true"
            android:foregroundServiceType="location" />
            
        <!-- Optional: Reboot Support -->
        <receiver android:name="upendra.bajpai.background_locator_neo.BootBroadcastReceiver"
            android:enabled="true"
            android:exported="true">
            <intent-filter>
                <action android:name="android.intent.action.BOOT_COMPLETED"/>
            </intent-filter>
        </receiver>
    </application>
</manifest>

---

3. iOS Setup

Info.plist Configuration

Add these keys to your ios/Runner/Info.plist:

<key>NSLocationWhenInUseUsageDescription</key>
<string>This app needs access to location when open.</string>
<key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
<string>This app needs access to location when in the background.</string>
<key>UIBackgroundModes</key>
<array>
    <string>location</string>
</array>

AppDelegate Configuration (Swift)

You must register the plugin registrant callback in ios/Runner/AppDelegate.swift:

import UIKit
import Flutter
import background_locator_neo 

@UIApplicationMain
@objc class AppDelegate: FlutterAppDelegate {
  override func application(
    _ application: UIApplication,
    didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
  ) -> Bool {
    GeneratedPluginRegistrant.register(with: self)
    
    // ⚡ CRITICAL: Register the background plugin registrant callback
    BackgroundLocatorPlugin.setPluginRegistrantCallback { registry in
        GeneratedPluginRegistrant.register(with: registry)
    }
    
    return super.application(application, didFinishLaunchingWithOptions: launchOptions)
  }
}

---

4. Usage

Step 1: Define a Top-Level Callback

Define your location handler as a top-level function or static method. It must be annotated with @pragma('vm:entry-point').

import 'package:background_locator_neo/location_dto.dart';

@pragma('vm:entry-point')
void locationCallback(LocationDto locationDto) {
  print('Location Update: ${locationDto.latitude}, ${locationDto.longitude}');
}

Step 2: Initialize & Register

Call initialize() at app startup, then register for updates.

import 'package:background_locator_neo/background_locator.dart';
import 'package:background_locator_neo/settings/ios_settings.dart';
import 'package:background_locator_neo/settings/android_settings.dart';

void startLocationService() async {
  await BackgroundLocator.initialize();
  
  await BackgroundLocator.registerLocationUpdate(
    locationCallback,
    iosSettings: IOSSettings(
        accuracy: LocationAccuracy.NAVIGATION,
        pausesLocationUpdatesAutomatically: false,
        showsBackgroundLocationIndicator: true
    ),
    androidSettings: AndroidSettings(
        accuracy: LocationAccuracy.NAVIGATION,
        interval: 10,
        distanceFilter: 0,
        androidNotificationSettings: AndroidNotificationSettings(
            notificationChannelName: 'Location tracking',
            notificationTitle: 'Tracking Active',
            notificationMsg: 'App is tracking your location'
        )
    )
  );
}

---

🛠️ Credits & History

This project is a refactored and modernized version of the original background_locator plugin, maintained to support the latest Android and iOS standards.

Special thanks to:

• Rekab (Original creator)
• Yukams (Maintainer of background_locator_fixed)

---

📄 License

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