BackgroundGeolocation class

Primary plugin API.

Events

BackgroundGeolocation is event-based and highly configurable through the Config API.

Method	Description
onLocation	Fired with each recorded Location
onMotionChange	Fired when the plugin changes state between moving / stationary
onHttp	Fired with each HTTP response from your server. (see HttpConfig.url).
onActivityChange	Fired with each change in device motion-activity.
onProviderChange	Fired after changes to device location-services configuration.
onHeartbeat	Periodic timed events. See AppConfig.heartbeatInterval. iOS requires AppConfig.preventSuspend.
onGeofence	Fired with each Geofence transition event (ENTER, EXIT, DWELL).
onGeofencesChange	Fired when the list of actively-monitored geofences changed. See GeoConfig.geofenceProximityRadius.
onSchedule	Fired for AppConfig.schedule events.
onConnectivityChange	Fired when network-connectivity changes (connected / disconnected).
onPowerSaveChange	Fired when state of operating-system's "power-saving" feature is enabled / disabled.
onEnabledChange	Fired when the plugin is enabled / disabled via its start / stop methods.
onNotificationAction	(Android only) Fired when a Notification.actions button is clicked upon a custom Notification.layout

Example

NOTE: import '...' as bg This is to namespace the plugin's classes, a number of which use common names, such as State, Config, Location, etc.

import 'package:flutter_background_geolocation/flutter_background_geolocation.dart' as bg;

class _MyHomePageState extends State<MyHomePage> {
  @override
  void initState() {
    // 1.  Listen to events (See docs for all 12 available events).
    //
    // Fired whenever a location is recorded
    bg.BackgroundGeolocation.onLocation((bg.Location location) {
      print('[location] - ${location}');
    });

    // Fired whenever the plugin changes motion-state (stationary->moving and vice-versa)
    bg.BackgroundGeolocation.onMotionChange((bg.Location location) {
      print('[motionchange] - ${location}');
    });

    // Fired whenever the state of location-services changes.  Always fired at boot
    bg.BackgroundGeolocation.onProviderChange((bg.ProviderChangeEvent event) {
      print('[providerchange] - ${event}');
    });

    ////
    // 2.  Configure the plugin
    //
    bg.BackgroundGeolocation.ready(bg.Config(
        desiredAccuracy: bg.Config.DESIRED_ACCURACY_HIGH,
        distanceFilter: 10.0,
        stopOnTerminate: false,
        startOnBoot: true,
        debug: true,
        logLevel: bg.Config.LOG_LEVEL_VERBOSE
    )).then((bg.State state) {
      if (!state.enabled) {
        ////
        // 3.  Start the plugin.
        //
        bg.BackgroundGeolocation.start();
      }
    });
  }
}

Constructors

BackgroundGeolocation()

Properties

hashCode → int

The hash code for this object.

no setter, inherited

runtimeType → Type

A representation of the runtime type of the object.

no setter, inherited

Methods

noSuchMethod(Invocation invocation) → dynamic

Invoked when a nonexistent method or property is accessed.

inherited

toString() → String

A string representation of this object.

inherited

Operators

operator ==(Object other) → bool

The equality operator.

inherited

Static Properties

count → Future<int>

Retrive the count of all locations current stored in the plugin's SQLite database.

no setter

geofences → Future<List<Geofence>>

Retrieve all Geofence.

no setter

locations → Future<List>

Retrive a List of Location currently stored in the plugin's SQLite database.

no setter

log → Future<String>

@deprecated Use Logger instead.

no setter

odometer → Future<double>

Retrieve the current distance-traveled ("odometer").

no setter

providerState → Future<ProviderChangeEvent>

Get current state of location-services, including authorization status.

no setter

sensors → Future<Sensors>

Returns the presence of device sensors accelerometer, gyroscope, magnetometer

no setter

state → Future<State>

Return the current State of the plugin, including all Config parameters.

no setter

Static Methods

addGeofence(Geofence geofence) → Future<bool>

Adds a Geofence to be monitored by the native Geofencing API.

addGeofences(List<Geofence> geofences) → Future<bool>

Adds a list of Geofence to be monitored by the native Geofencing API.

changePace(bool isMoving) → Future<bool>

Manually toggles the plugin's motion state between stationary and moving.

destroyLocation(String uuid) → Future<bool>

Destory a single location by Location.uuid.

destroyLocations() → Future<bool>

Remove all records in plugin's SQLite database.

destroyLog() → Future<bool>

@deprecated Use Logger instead.

emailLog(String email) → Future<bool>

@deprecated Use Logger instead.

finish(int taskId) → Future<int>

@deprecated. Renamed to stopBackgroundTask

geofenceExists(String identifier) → Future<bool>

Returns true if the SDK already contains the Geofence in its database.

getCurrentPosition({int? samples, int? timeout, int? maximumAge, bool? persist, double? desiredAccuracy, Map<String, dynamic>? extras}) → Future<Location>

Retrieves the current Location.

getGeofence(String identifier) → Future<Geofence?>

Retrieve all a single Geofence by identifier.

insertLocation(Map params) → Future<String>

TODO

onActivityChange(dynamic callback(ActivityChangeEvent)) → Subscription

Subscribe to changes in motion activity.

onAuthorization(dynamic callback(AuthorizationEvent)) → Subscription

Listen to Authorization events from Authorization.refreshUrl.

onConnectivityChange(dynamic callback(ConnectivityChangeEvent)) → Subscription

Subscribe to changes in network connectivity.

onEnabledChange(dynamic callback(bool)) → Subscription

Subscribe to changes in plugin State.enabled.

onGeofence(dynamic callback(GeofenceEvent)) → Subscription

Subscribe to Geofence transition events.

onGeofencesChange(dynamic callback(GeofencesChangeEvent)) → Subscription

Subscribe to changes in actively monitored geofences.

onHeartbeat(dynamic callback(HeartbeatEvent)) → Subscription

Subscribe to periodic heartbeat events.

onHttp(dynamic callback(HttpEvent)) → Subscription

Subscribe to HTTP events.

onLocation(dynamic success(Location), [dynamic failure(LocationError)?]) → Subscription

Subscribe to location events

onMotionChange(dynamic callback(Location)) → Subscription

Subscribe to motionchange events

onNotificationAction(dynamic callback(String)) → Subscription

(Android only) Registers a button-click listener on a Custom Notification Layout

onPowerSaveChange(dynamic callback(bool)) → Subscription

Subscribe to state changes in OS power-saving system.

onProviderChange(dynamic callback(ProviderChangeEvent)) → Subscription

Subscribe to changes in device's location-services configuration / authorization.

onSchedule(dynamic callback(State)) → Subscription

Subscribe to AppConfig.schedule events.

playSound(dynamic soundId) → Future<bool>

Register with the Transistor Software demo server

ready(Config config) → Future<State>

Signal to the plugin that your app is launched and ready, proving the default Config.

registerHeadlessTask(void callback(HeadlessEvent)) → Future<bool>

Registers a function to receive events from BackgroundGeolocation while in the terminated ("Headless") state.

removeGeofence(String identifier) → Future<bool>

Removes a Geofence having the given Geofence.identifier`.

removeGeofences() → Future<bool>

Destroy all Geofence.

removeListener(Function callback) → bool

Removes a single event-listener.

removeListeners() → Future<bool>

Remove all event-listeners registered with the plugin:

requestPermission() → Future<int>

Manually request location permission from the user with the configured GeoConfig.locationAuthorizationRequest.

requestTemporaryFullAccuracy(String purpose) → Future<int>

[iOS 14+] iOS 14 has introduced a new [Precise: On] switch on the location authorization dialog allowing users to disable high-accuracy location.

reset([Config? config]) → Future<State>

Resets the plugin configuration to documented default-values.

setConfig(Config config) → Future<State>

Re-configure the plugin's Config parameters.

setOdometer(double value) → Future<Location>

Initialize the odometer to any arbitrary value.

start() → Future<State>

Enable location tracking.

startBackgroundTask() → Future<int>

Sends a signal to OS that you wish to perform a long-running task.

startGeofences() → Future<State>

Engages the geofences-only State.trackingMode.

startSchedule() → Future<State>

Initiate the configured AppConfig.schedule.

stop() → Future<State>

Disable location tracking.

stopBackgroundTask(int taskId) → Future<int>

Signal completion of startBackgroundTask

stopSchedule() → Future<State>

Halt scheduled tracking.

stopWatchPosition(int watchId) → Future<bool>

sync() → Future<List>

Manually execute upload configured HttpConfig.url

watchPosition({int? timeout, int? interval, bool? persist, int? desiredAccuracy, Map<String, dynamic>? extras, void onLocation(Location)?}) → Future<Subscription>