Polygon Geofencing

The Background Geolocation SDK for Flutter v4.13.0, React Native v4.14.0, Cordova v4.15.0 and Capacitor v5.2.0 now includes support for Polygon Geofencing (sold separately as an add-on).

For years, users have asked if the Background Geolocation SDK supports polygon geofencing but the native Geofencing APIs for both Android and iOS offer only circular geofences with a center point and radius.

I’ve always had an idea in the back of my mind about how I might solve this so I finally took a crack at it.

The solution involves wrapping the polygon within a native circular geofence:

In the image above, the blue polygons represent the actual polygon geofences and the containing green circles are traditional circular geofences provided by the native iOS/Android Geofencing APIs. The background-geolocation SDK automatically calculates the containing, native circular geofence by solving the “minimum enclosing circle” problem for the given polygon Geofence.vertices . For this reason, you do not provide latitude, longitude, or radius when adding a polygon geofence:

// Flutter
BackgroundGeolocation.addGeofence(Geofence(
  identifier: 'Home',
  notifyOnEntry: true,
  notifyOnExit: true,
  vertices: [
    [45.518947279987714, -73.6049889209514],  // <-- [lat, lng]
    [45.5182711292279, -73.60338649600598],
    [45.517082240237634, -73.60432670908212],
    [45.51774871402813, -73.60604928622278]
  ]
));

// Cordova, Capacitor, React Native
BackgroundGeolocation.addGeofence({
  identifier: 'Home',
  notifyOnEntry: true,
  notifyOnExit: true,
  vertices: [
    [45.518947279987714, -73.6049889209514],  // <-- [lat, lng]
    [45.5182711292279, -73.60338649600598],
    [45.517082240237634, -73.60432670908212],
    [45.51774871402813, -73.60604928622278]
  ]
});

• When the device enters the containing circular geofence, the SDK uses that as a signal that the device is approaching a polygon. At this moment, the SDK begins aggressively monitoring the location to perform “hit-testing” upon the polygon using a fast algorithm implemented with C++ code.
• When the device exits the containing circular geofence, that’s the SDK’s signal for it to cease monitoring that polygon.

Wrapping the polygon within a native circular geofence is crucial, since native geofences are monitored by the OS and given special priority and privileges . On iOS, if your app is currently terminated, the OS will relaunch your app in the background to service the geofence event. On Android, the OS will launch a foreground-service, regardless if running in the background or terminated. Also, when the device is not within any circular geofence, there is no polygon evaluation running at all. Some solutions out there tax the CPU by constantly evaluating each registered polygon with each recorded location, significantly draining the battery.

In the following images, the red and green arrows represent onGeofence ENTER / EXIT events where green = ENTER and red = EXIT

Entering / exiting a polygon around a park:

Entering / exiting a cross-shaped polygon

Entering / exiting a diamond-shaped polygon

Try it now in the demo apps.

The demo apps for Flutter, React Native and Capacitor now include a polygon geofence designer. For React Native and Flutter, long-press on the map; for Capacitor, just a single map-click.