Work with Geotriggers

Geotriggers let you monitor your GIS data in real-time and receive notifications when specified conditions are met. The most common type of notification is when a device (such as a cellphone) enters or leaves an area (sometimes called Geofencing). With geotriggers, you can monitor locations from whatever AGSLocationDataSource you choose, while tapping into the full power of ArcGIS Runtime's AGSGeometryEngine for evaluating spatial relationships.

With geotriggers your apps can do things like:

  • Warn users when they enter a restricted or dangerous area.
  • Provide notifications about nearby points of interest or attractions.
  • Inform drivers when they enter or leave an area that has noise or speed restrictions.
  • Notify a customer when their delivery is about to arrive.

A geotrigger that routes to an associated charging station.

Using geotriggers in your app involves the following main steps.

  1. Define a geotrigger condition to monitor.
  2. Set up a geotrigger monitor and listen for events.
  3. React to notification events.

Define a Geotrigger condition to monitor

A AGSGeotrigger defines a condition that you want to monitor as the device location changes. For monitoring conditions based on a spatial relationship, ArcGIS Runtime provides the AGSFenceGeotrigger class.

For example, you could use a fence geotrigger to represent a condition such as "Inform me when my device location comes within 50 meters of one of my target areas".

The table below shows the meaningful parts of this condition and how they are represented in the Geotrigger API.

PartExampleAPI
Dynamic position"my device location"AGSGeotriggerFeed
Spatial operation"comes within"AGSFenceRuleType
Areas (fences) to check"my target areas"AGSFenceParameters

Geotrigger feed

To monitor your device location, pass a AGSLocationDataSource to a AGSLocationGeotriggerFeed. The AGSLocationDataSource is also what you use with the AGSLocationDisplay to show your position on a map.

You can use the following types of AGSLocationDataSource depending on your use case.

Fence parameters

You supply a AGSFenceParameters to monitor target areas, including an optional buffer distance. Depending on your workflow, you can make your fences visible or hidden in the map. Your user may not need to know exactly where the fences are, only when one has been entered or exited.

Your fences are based on either:

  • Graphics, which are light-weight, in-memory, and quick to create without needing a defined table schema. For example, graphics could represent a target area that the user sketches on the view. Graphic fences are dynamic, with new ones added, old ones removed, or geometry updates processed on-the-fly. For example, if your fences are polygons representing moving storm clouds, changes to these graphics will be evaluated in real-time. Use graphics when your condition uses temporary data created on the device. To represent fences using graphics, create a AGSGraphicFenceParameters or a AGSGraphicsOverlayFenceParameters.

  • Features from a AGSFeatureTable that can be filtered by attributes and/or geometry. Features allow you to monitor online and offline data that can be shared across the Esri ecosystem. Use features when your condition makes use of authoritative data that you share with your map or scene. You create a AGSFeatureFenceParameters to work with features.

Set up a Geotrigger monitor and listen for events

Once you have defined your geotrigger, you are ready to start monitoring it. The geotrigger itself just defines what you want to be notified about. To actually check for when things happen (conditions are met), you pass it to a geotrigger monitor.

The AGSGeotriggerMonitor is the heart of the geotriggers workflow: it takes a single AGSGeotrigger and monitors the condition it defines using real-time changes to the location feed. When a condition is met, it raises an event and provides the info your app needs in order to react appropriately.

Once you have created your AGSGeotriggerMonitor, you need to:

  • Subscribe to notification events so that you will be informed when the condition is met.
  • Watch for warnings that indicate something isn't working correctly.
  • Start the geotrigger monitor to begin monitoring and wait for notifications to start coming in.

React to notification events

Whenever your geotrigger monitor is in a started state, you should be ready to handle notifications that provide details for the condition that was met. The AGSGeotriggerNotificationInfo class provides information such as:

  • The location where the condition was met. You can zoom to this position by updating the viewpoint for your map view or scene view.
  • The geoelement for the fence, which includes all of its underlying attributes and attachments.
  • The AGSGeotriggerMonitor that sent the notification. You could use this to stop monitoring once a condition has been met.

When you receive a AGSGeotriggerNotificationInfo you could display a message to the user to tell them what happened. You could take other action, such as selecting a feature on the map or routing to a location. Alternatively, you may not need to interact with the user at all, perhaps writing to a logfile or taking some internal action in your app.

Customizing Notifications

Optionally, you can provide an expression that defines the message for your AGSGeotrigger, using the Arcade language. This controls the message provided with AGSGeotriggerNotificationInfo that is populated whenever the geotrigger condition is met. The expression uses the Geotrigger Notification Profile, which gives you access to:

  • The $feedfeature (the device location, for example) and its geometry and attributes.
  • Whether the area was "entered" or "exited".
  • The $fencefeature (the target area) and its geometry and attributes.

You can also make use of other functions and objects available in Arcade, such as the Geometry() or Now() functions. For example, the following geotrigger message expression:

"Hello, you have entered " + $fencefeature.name + " with a heading of " + $feedfeature.heading + " degrees at " + Now()

Might result in a GeotriggerNotificationInfo.message of:

Hello, you have entered Area 1 with a heading of 45 degrees at 01 Jan 2021 12:00:00 pm.

Working with Geotriggers when your app is in the background

Many geotrigger workflows monitor and provide notifications while the user is interacting with and viewing the app. Sometimes, however, your app needs to provide notifications for a geotrigger condition while the user is engaged in other tasks, even when the app is not active. When working on mobile devices, it is particularly important to consider how geotriggers will behave when you navigate away from the app. In these scenarios, your app must contain logic that ensures its geotriggers are monitored when running in the background.

On iOS devices, see Handling location events in the background in the Apple developer doc for a good overview of handling location events in the background. With this approach, iOS will give your app execution time for monitoring geotriggers when a location is received. Certain configurations will even relaunch your app when new location updates are received.

To enable background locations, you must request the relevant permissions and allow them when prompted by the app. Essentially, you need specific location permissions set for your app, and a CLLocationManager with the allowsBackgroundLocationUpdates property enabled. ArcGIS Runtime provides access to an iOS CLLocationManager via the AGSCLLocationDataSource which you use to create a AGSLocationGeotriggerFeed. If you need to make use of custom location behavior you can also derive your own AGSLocationDataSource. When you are finished monitoring geotriggers you must tell the iOS Core location to stop monitoring locations.

You must also provide a message that explains why the app requires access to device location. For example, to access location information at all times, setup an NSLocationAlwaysAndWhenInUseUsageDescription in the Info.plist file.

Performance considerations

Geotriggers may monitor conditions for long periods of time (maybe the entire time that your app is running). To minimize memory usage and to maximize your device's battery life, consider some factors that can affect the performance of your geotrigger code.

Device specifications determine the limits of what you can successfully monitor. For example, mobile devices with reduced memory capacity can handle fewer fences than a powerful desktop computer. For typical workflows, you can expect mobile devices to effectively monitor tens of thousands of fences and perform well. By comparison, the same geotrigger code running on a desktop machine could handle hundreds of thousands of fences. As a guideline, you should try to monitor the minimum amount of fence data required for your application. Geotriggers use your device's GPS and may continue to run in the background. To reduce your device's battery consumption, turn GPS off when it is not required. Geotriggers are not monitored unless there are location or graphics updates.

When using online features as fences, the total number of fences you can monitor is limited by the service's maximum feature count (usually 1,000 - 2,000 features). To create fences beyond that limit, you can split the features between several geotriggers. You can also use multiple geotriggers to monitor features from different feature tables within one application. When using online feature data, there is the possibility of losing network connectivity, which can affect your app's availability. If you need to guarantee consistent performance without relying on network availability, consider taking the fence data offline.

Your browser is no longer supported. Please upgrade your browser for the best experience. See our browser deprecation post for more details.