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 Config.url).
onActivityChange	Fired with each change in device motion-activity.
onProviderChange	Fired after changes to device location-services configuration.
onHeartbeat	Periodic timed events. See Config.heartbeatInterval. iOS requires Config.preventSuspend.
onGeofence	Fired with each Geofence transition event (`ENTER, EXIT, DWELL`).
onGeofencesChange	Fired when the list of actively-monitored geofences changed. See Config.geofenceProximityRadius.
onSchedule	Fired for Config.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 setterinherited
runtimeType → Type: A representation of the runtime type of the object.
no setterinherited

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, int? 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)) → void: Subscribe to changes in motion activity.
onAuthorization(dynamic callback(AuthorizationEvent)) → void: Listen to Authorization events from Authorization.refreshUrl.
onConnectivityChange(dynamic callback(ConnectivityChangeEvent)) → void: Subscribe to changes in network connectivity.
onEnabledChange(dynamic callback(bool)) → void: Subscribe to changes in plugin State.enabled.
onGeofence(dynamic callback(GeofenceEvent)) → void: Subscribe to Geofence transition events.
onGeofencesChange(dynamic callback(GeofencesChangeEvent)) → void: Subscribe to changes in actively monitored geofences.
onHeartbeat(dynamic callback(HeartbeatEvent)) → void: Subscribe to periodic heartbeat events.
onHttp(dynamic callback(HttpEvent)) → void: Subscribe to HTTP events.
onLocation(dynamic success(Location), [dynamic failure(LocationError)?]) → void: Subscribe to location events
onMotionChange(dynamic callback(Location)) → void: Subscribe to motionchange events
onNotificationAction(dynamic callback(String)) → void: (Android only) Registers a button-click listener on a Custom Notification Layout
onPowerSaveChange(dynamic callback(bool)) → void: Subscribe to state changes in OS power-saving system.
onProviderChange(dynamic callback(ProviderChangeEvent)) → void: Subscribe to changes in device's location-services configuration / authorization.
onSchedule(dynamic callback(State)) → void: Subscribe to Config.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 Config.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 configure Config.schedule.
stop() → Future<State>: Disable location tracking.
stopBackgroundTask(int taskId) → Future<int>: Signal completion of startBackgroundTask
stopSchedule() → Future<State>: Halt scheduled tracking.
sync() → Future<List>: Manually execute upload configured Config.url