Skip to content

Geofence API

Client-side geofence monitoring is the process of tracking the position of the device in relation to the geofences defined in Backendless. Functionality  in Backendless client libraries loads information about geofences (or a specific geofence) and tracks device positional changes. When the device crosses, stays in, or exits a geofence boundary, the Backendless client executes a callback. Based on this, Backendless client-side monitoring supports the following options:

In-app callback interface

Client applications must use a special interface to receive local callbacks. The Backendless library invokes the interface methods when the current device's location enters, stays in or exits a geofence:

void onPointEntered(geofenceName, geofenceId, latitude, longitude) {
  print("onPointEntered");
}

void onPointStayed(geofenceName, geofenceId, latitude, longitude) {
  print("onPointStayed");
}

void onPointExited(geofenceName, geofenceId, latitude, longitude) {
  print("onPointExited");
}
  • Remote callback for the on enter, on stay and on exit event. The Backendless client automatically notifies the server when a geofence event occurs. If there is an action associated with the event, Backendless executes on the server-side.

The API applies the options above either to a specific or all geofences. It is important to note that a Backendless client can monitor only the geofences which are not activated for the server-side monitoring. In other words, a geofence with the "Is Active" toggle in the Backendless console set to ON cannot be tracked on the client-side.

Android App Configuration

An Android part of the application which uses the Backendless Geofence API must include the following permission in the Android app manifest:

<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />

To enable location tracking while app is running in background, add the following manifest:

<service android:name="com.backendless.geo.LocationTracker"/>

In order to enable location tracking after device reboot (or power cycle), the following must be added to application's manifest:

<uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED" />  
<receiver android:name="com.backendless.AutoStart" >  
    <intent-filter>  
        <action android:name="android.intent.action.BOOT_COMPLETED"/>  
    </intent-filter>  
</receiver>

iOS App Configuration

An iOS part of the application can execute location updates in the background. The location updates are available when the app is killed, terminated or suspended. To activate this capability the following project options must be set:

  1. the "Background Modes" of the target's Capabilities is switched on, and "Location updates" and "Background fetch" are enabled:
    geoFence

  2. The NSLocationWhenInUseUsageDescription and NSLocationAlwaysAndWhenInUseUsageDescription keys are added to the .plist file.

Geofence APIs

The Geolocation service provides the following APIs:

Client-side location monitoring:

Executing a geofence action:

Retrieve geopoints from a geofence

Start location monitoring for a specific geofence with an in-app callback

Starts client-side monitoring of the device's location for the geofence. Uses the callback to notify when the device enters, stays in, or exits the geofence boundary.

Future<void> Backendless.geo.startClientGeofenceMonitoring({String geofenceName, GeofenceCallback geoPointEntered, GeofenceCallback geoPointStayed, GeofenceCallback geoPointExited});

where:

Argument                Description
geofenceName name of a geofence, which monitors the device's location.

geoPointEntered, geoPointStayed, geoPointExited- callback objects that the Backendless library notifies when the device crosses, stays in, or exits the geofence boundary.

Example

void onPointEntered(geofenceName, geofenceId, latitude, longitude) {
  print("onPointEntered");
}

void onPointStayed(geofenceName, geofenceId, latitude, longitude) {
  print("onPointStayed");
}

void onPointExited(geofenceName, geofenceId, latitude, longitude) {
  print("onPointExited");
}

Backendless.geo.startClientGeofenceMonitoring(
  geofenceName: "Shopping Mall", 
  geoPointEntered: onPointEntered, 
  geoPointStayed: onPointStayed, 
  geoPointExited: onPointExited).then((result) {
    print("Geofence monitoring has been started");
});

Start location monitoring for all geofences with an in-app callback

Starts client-side monitoring of the device's location for all geofences. Uses the callback to notify when the device enters, stays in or exits a geofence boundary.

Future<void> Backendless.geo.startClientGeofenceMonitoring({ GeofenceCallback geoPointEntered, GeofenceCallback geoPointStayed, GeofenceCallback geoPointExited});

where:

geoPointEntered, geoPointStayed, geoPointExited- callback objects that the Backendless library notifies when the device crosses, stays in, or exits the geofence boundary.

Example

void onPointEntered(geofenceName, geofenceId, latitude, longitude) {
  print("onPointEntered");
}

void onPointStayed(geofenceName, geofenceId, latitude, longitude) {
  print("onPointStayed");
}

void onPointExited(geofenceName, geofenceId, latitude, longitude) {
  print("onPointExited");
}

Backendless.geo.startClientGeofenceMonitoring(
  geofenceName: "Shopping Mall", 
  geoPointEntered: onPointEntered, 
  geoPointStayed: onPointStayed, 
  geoPointExited: onPointExited).then((result) {
    print("Geofence monitoring has been started for all geofences");
  });

Start location monitoring for a specific geofence with a remote callback

Starts client-side monitoring of the device's location for a specific geofence. This function notifies the server when the device enters, stays in, or exits the geofence boundary.

Future<void> Backendless.geo.startServerGeofenceMonitoring(GeoPoint geoPoint, [String geofenceName]);

where:

Argument                Description
geofenceName name of a geofence, which monitors the device's location.
geoPoint the geopoint object to pass to the server. The geopoint represents the current device location. It may be a geopoint stored in the Geolocation storage (with objectId assigned to it) or a new geopoint object. The Backendless client assigns the current location coordinates to the geoPoint object before sending it to the server.

Example

// Create a geopoint. The coordinates are irrelevant
// because Backendless client will update them when the 
// current location of the device where this program runs changes.
// The geopoint with the updated coordinates will be delivered 
// to the server when the the current location triggers a 
// geofence event;
GeoPoint myLocation = GeoPoint.fromLatLng(0, 0)
  ..metadata = {
    "__deviceId": deviceToken,
  };

Backendless.geo.startServerGeofenceMonitoring(myLocation, "Radio City Hall").then((result) {
  print("Geofence monitoring has been started");
});

Start location monitoring for all geofences with a remote callback

Starts client-side monitoring of the device's location for all geofences. This function notifies the server when the device enters, stays in or exits a geofence boundary.

Future<void> Backendless.geo.startServerGeofenceMonitoring(GeoPoint geoPoint);

where:

Argument                Description
geoPoint the geopoint object to pass to the server. The geopoint represents the current device location. It may be a geopoint stored in the Geolocation storage (with objectId assigned to it) or a new geopoint object. The Backendless client assigns current location coordinates to the geoPoint object before sending it to the server.

Example

// Create a geopoint. The coordinates are irrelevant
// because Backendless client will update them when the
// current location of the device where this program runs changes.
// The geopoint with the updated coordinates will be delivered
// to the server when the the current location triggers a
// geofence event;
GeoPoint myLocation = GeoPoint.fromLatLng(0, 0)
  ..metadata = {
    "__deviceId": deviceToken,
  };

Backendless.geo.startServerGeofenceMonitoring(myLocation, "Radio City Hall").then((result) {
  print("Geofence monitoring has been started for all geofences");
});

Stop location monitoring for a specific geofence

Stops client-side monitoring of the device's location for the geofence.

Future<void> Backendless.geo.stopGeofenceMonitoring([String geofenceName]);

where:

Argument                Description
geofenceName name of the geofence for which device location monitoring will stop.

Example

Backendless.geo.stopGeofenceMonitoring("Home");

Stop location monitoring for all geofences

Stops client-side monitoring of device locations for all geofences.

Future<void> Backendless.geo.stopGeofenceMonitoring();

Example

Backendless.geo.stopGeofenceMonitoring();

Configure Location Tracker

Configures client-side location tracker

Future<void> Backendless.geo.setLocationTrackerParameters(int minTime, int minDistance, int acceptedDistanceAfterReboot);

where:

Argument                Description
minTime minimum time in milliseconds as an interval between location updates;
minDistance minimum distance in meters as a difference between locations; if distance is less than this value, android service will not send new coordinates to app;
acceptedDistanceAfterReboot max distance between two locations after rebooting the device; if distance is greater than this value, service resets location status and starts fence(s) monitoring from the beginning. Used when user reboots the device.

Run the OnEnter Action

Requests the server to run the configured OnEnter action for a geofence either for all geopoints located within the geofence or for the specified geopoint.

Method:

Future<void> Backendless.geo.runOnEnterAction(String geoFenceName, [GeoPoint geoPoint]);

where:

Argument                Description
geofenceName name of the geofence on which the OnEnter action will run.
geoPoint a geopoint which will be used as the context for the action execution. Any substitutions which the action may be configured with will be resolved against the geopoint.

Example

Backendless.geo.runOnEnterAction("Home");

Run the OnStay Action

Requests the server to run the configured OnStay action for a geofence either for all geopoints located within the geofence or for the specified geopoint.

Method:

Future<void> Backendless.geo.runOnStayAction(String geoFenceName, [GeoPoint geoPoint]);

where:

Argument                Description
geofenceName name of a geofence on which the OnStay action will run.
geoPoint a geopoint which will be used as the context for the action execution. Any substitutions which the action may be configured with will be resolved against the geopoint.

Example

Backendless.geo.runOnStayAction("Home");

Run the OnExit Action

Requests the server to run the configured OnExit action for a geofence either for all geopoints located within the geofence or for the specified geopoint.

Method:

Future<void> Backendless.geo.runOnExitAction(String geoFenceName, [GeoPoint geoPoint]);

where:

Argument                Description
geofenceName name of a geofence on which the OnExit action will run.
geoPoint a geopoint which will be used as the context for the action execution. Any substitutions which the action may be configured with will be resolved against the geopoint.

Example

Backendless.geo.runOnExitAction("Home");

Retrieve Geopoints from a Geofence

Retrieves a collection of geopoints currently located within a geofence

Method:

Future<List<GeoPoint>> Backendless.geo.getPoints({String geofenceName, BackendlessGeoQuery query, GeoCluster geoCluster});

where:

Argument                Description
geofenceName name of a geofence to retrieve the geopoints from.
query a BackendlessGeoQuery object controlling various aspects of geopoint retrieval such as paging, inclusion of metadata and/or SQL search query.

Example

The example loads geopoints from a geofence called "Manhattan". The returned geopoints will have metadata properties and will match the SQL query:

BackendlessGeoQuery geoQuery = BackendlessGeoQuery()
  ..includeMeta = true
  ..whereClause = "businessType='restaurant' and rating > 3";

Backendless.geo.getPoints(geofenceName: "Manhattan", query: geoQuery);