carp_background_location

CARP Background Location Plugin

A background location plugin for Android and iOS which works even when the app is in the background. This is a simple wrapper to the background_locator plugin. Refer to the background_locator's wiki page for install and setup instruction.

Android setup

Add the following permissions to your manifest:

    <uses-permission android:name="android.permission.INTERNET" />
    <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.RECEIVE_BOOT_COMPLETED"/>

Afterwards, include the following entries within the application tag, as follows:

<application
       ...
        <receiver
                android:name="rekab.app.background_locator.LocatorBroadcastReceiver"
                android:enabled="true"
                android:exported="true"
        />

        <receiver android:name="rekab.app.background_locator.BootBroadcastReceiver"
                  android:enabled="true">
            <intent-filter>
                <action android:name="android.intent.action.BOOT_COMPLETED"/>
            </intent-filter>
        </receiver>

        <service
                android:name="rekab.app.background_locator.LocatorService"
                android:permission="android.permission.BIND_JOB_SERVICE"
                android:exported="true"
        />
        <service
                android:name="rekab.app.background_locator.IsolateHolderService"
                android:permission="android.permission.FOREGROUND_SERVICE"
                android:exported="true"
        />
    </application>

NOTE In Android 11 location permissions cannot be set automatically by the app (via the manifest file). Google writes on this page that:

On Android 11 (API level 30) and higher [...] the system dialog doesn’t include the Allow all the time option. Instead, users must enable background location on a settings page, as shown in figure 7.

Hence, for this plugin (and the example app) to work, you need to go to this settings screen and manually set the permission to "Alow all the time".

iOS setup

Add the following entries to your Info.plist file

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

Next, overwrite your AppDelegate.swift in the XCode project with:

import UIKit
import Flutter

import background_locator

func registerPlugins(registry: FlutterPluginRegistry) -> () {
    if (!registry.hasPlugin("BackgroundLocatorPlugin")) {
        GeneratedPluginRegistrant.register(with: registry)
    }
}


@UIApplicationMain
@objc class AppDelegate: FlutterAppDelegate {
  override func application(
    _ application: UIApplication,
    didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
  ) -> Bool {
    GeneratedPluginRegistrant.register(with: self)
    BackgroundLocatorPlugin.setPluginRegistrantCallback(registerPlugins)
    return super.application(application, didFinishLaunchingWithOptions: launchOptions)
  }
}

Usage

  // configure the location manager
  LocationManager().interval = 1;
  LocationManager().distanceFilter = 0;
  LocationManager().notificationTitle = 'CARP Location Example';
  LocationManager().notificationMsg = 'CARP is tracking your location';

  // get the current location
  await LocationManager().getCurrentLocation();

  // start listen to location updates
  StreamSubscription<LocationDto> locationSubscription = LocationManager()
      .locationStream
      .listen((LocationDto dto) => print(dto));

  // cancel listening and stop the location manager
  locationSubscription?.cancel();
  LocationManager().stop();

See the example app for a complete example of usage.

Features and bugs

Please file feature requests and bug reports at the issue tracker.

License

This software is copyright (c) Copenhagen Center for Health Technology (CACHET) at the Technical University of Denmark (DTU). This software is available 'as-is' under a MIT license.