GeofenceEvent class

Event-object provided to BackgroundGeolocation.onGeofence.

Example

BackgroundGeolocation.onGeofence((GeofenceEvent event) {
  print('[geofence] ${event.identifier}, ${event.action}');
});

Geofencing Guide


The Background Geolocation SDK implements the native iOS and Android Geofencing APIs.

ℹ️ Note:

Adding Geofences


Adding a single geofence with BackgroundGeolocation.addGeofence.

Example

BackgroundGeolocation.addGeofence(Geofence(
  identifier: "Home",
  radius: 200,
  latitude: 45.51921926,
  longitude: -73.61678581,
  notifyOnEntry: true,
  notifyOnExit: true,
  extras: {
    "route_id": 1234
  }
)).then((bool success) {
  print('[addGeofence] success');
}).catchError((dynamic error) {
  print('[addGeofence] FAILURE: $error');
});

Adding multiple geofences with BackgroundGeolocation.addGeofences.

Example

BackgroundGeolocation.addGeofences([Geofence(
  identifier: "Home",
  radius: 200,
  latitude: 45.51921926,
  longitude: -73.61678581,
  notifyOnEntry: true,
), Geofence(
  identifier: "Work",
  radius: 200,
  latitude: 45.61921927,
  longitude: -73.71678582,
  notifyOnEntry: true
)]).then((bool success) {
  print('[addGeofences] success');
}).catchError((dynamic error) => {
  print('[addGeofences] FAILURE: $error');
});

ℹ️ Note: Adding a geofence having an Geofence.identifier which already exists within the SDK's geofence database will cause the previous record to be destroyed and the new one inserted.

Listening for Geofence Events

Listen to geofence events with BackgroundGeolocation.onGeofence.

Example

// Listen for geofence events.
BackgroundGeolocation.onGeofence((GeofenceEvent event) {
  print('[geofence] ${event.identifier}, ${event.action}');
});

Infinite Geofencing

The Background Geolocation SDK contains unique and powerful Geofencing features that allow you to monitor any number of circular geofences you wish (thousands even), in spite of limits imposed by the native platform APIs (20 for iOS; 100 for Android).

The SDK achieves this by storing your geofences in its database, using a geospatial query to determine those geofences in proximity (Config.geofenceProximityRadius), activating only those geofences closest to the device's current location (according the limit imposed by the corresponding platform).

Listening for changes in the actively-monitored set-of-geofences.

As the SDK periodically queries for geofences within the Config.geofenceProximityRadius, you can listen for changes in the actively-monitored geofences using the event BackgroundGeolocation.onGeofencesChange. This event will let you know those geofences which have begun to be actively monitored (GeofencesChangeEvent.on) in addition to those which just ceased to be actively monitored (GeofencesChangeEvent.off).

Example

BackgroundGeolocation.onGeofencesChange((GeofencesChangeEvent event) {
  // Create map circles
  event.on.forEach((Geofence geofence) {
    createGeofenceMarker(geofence)
  });

  // Remove map circles
  event.off.forEach((String identifier) {
    removeGeofenceMarker(identifier);
  }
});

⚠️ Note:

Removing Geofences

Once a geofence has been inserted into the SDK's database using BackgroundGeolocation.addGeofence or BackgroundGeolocation.addGeofences, they will be monitored forever. If you've configured Config.stopOnTerminate false and Config.startOnBoot true, geofences will continue to be monitored even if the application is terminated or device rebooted. To cease monitoring a geofence or geofences, you must remove them from the SDK's database.

Removing a single geofence by Geofence.identifier:

BackgroundGeolocation.removeGeofence('HOME').then((bool success) {
  print('[removeGeofence] success');
});

Removing all geofences with BackgroundGeolocation.removeGeofences:

BackgroundGeolocation.removeGeofences().then((bool success) {
  print('[removeGeofences] all geofences have been destroyed');
});

Querying Geofences

Use the method BackgroundGeolocation.geofences property to retrieve the entire Array of Geofence stored in the SDK's database:

List<Geofence> geofences = await BackgroundGeolocation.geofences;
print('[getGeofences: $geofences');

Monitoring only geofences

The BackgroundGeolocation SDK allows you to optionally monitor only geofences without constant location-tracking. To engage geofences-only mode, use the method BackgroundGeolocation.startGeofences instead of BackgroundGeolocation.start.

Use option Config.geofenceModeHighAccuracy:true to improve the responsiveness of geofence events.

BackgroundGeolocation.onGeofence((GeofenceEvent event) {
  print('[geofence]: ' + event.toString());
});

BackgroundGeolocation.ready(Config(
  url: 'http://your.server.com/geofences',
  autoSync: true,
  geofenceModeHighAccuracy: true   // <-- consumes more power; default is false.
)).then((State state) {
  // engage geofences-only mode:
  BackgroundGeolocation.startGeofences();
});

Toggling between tracking-modes BackgroundGeolocation.start and BackgroundGeolocation.startGeofences:

The SDK can easily be toggled between State.trackingMode simply by executing the corresponding BackgroundGeolocation.start or BackgroundGeolocation.startGeofences methods.

// Listen to geofence events
BackgroundGeolocation.onGeofence((GeofenceEvent event) {
  print('[geofence] ' + event.toString());
  if (event.identifier == 'DANGER_ZONE') {
    if (event.action == 'ENTER') {
      // Entering the danger-zone, we want to aggressively track location.
      BackgroundGeolocation.start();
    } else if (event.action == 'EXIT') {
      // Exiting the danger-zone, we resume geofences-only tracking.
      BackgroundGeolocation.startGeofences();
    }
  }
});

// Add a geofence.
BackgroundGeolocation.addGeofence(Geofence(
  identifier: "DANGER_ZONE",
  radius: 1000,
  latitude: 45.51921926,
  longitude: -73.61678581,
  notifyOnEntry: true,
  notifyOnExit: true,
));

// Ready the plugin.
BackgroundGeolocation.ready(Config(
  desiredAccuracy: BackgroundGeolocation.DESIRED_ACCURACY_HIGH,
  distanceFilter: 10,
  url: 'http://your.server.com/locations',
  autoSync: true
)).then((State state) {
  BackgroundGeolocation.startGeofences();
});

Constructors

GeofenceEvent(Map params)

Properties

action ↔ String
The transition event that caused the geofence to fire (ENTER | EXIT | DWELL).
read / write
extras ↔ Map
Optional Geofence.extras
read / write
identifier ↔ String
Geofence.identifier of the Geofence which fired.
read / write
location Location
The Location where this geofence triggered.
read / write
hashCode → int
The hash code for this object.
read-only, inherited
runtimeType → Type
A representation of the runtime type of the object.
read-only, inherited

Methods

toString({dynamic compact: bool }) → String
Returns a string representation of this object.
noSuchMethod(Invocation invocation) → dynamic
Invoked when a non-existent method or property is accessed.
inherited

Operators

operator ==(dynamic other) → bool
The equality operator.
inherited