A geofence is an imaginary circular region around a particular place. Geofences provide a convenient way to determine if a device has arrived or left. For example you might define a geofence to represent the region within 100 meters of the user's office so the app can remind her to pick up milk on the way home. Other use cases include:
- Changing settings or disabling ring tones when at work or home
- Offering a promotion when user reaches a certain store
- Sending a notification to Mom when daughter leaves school
- Reminding me to call Dave when I get to work tomorrow morning
- Alerting IT manager that a particular device has been removed from the building (possibly stolen)
A geofence object is defined by a point (latitude, longitude), a radius around that point in meters, whether you want to be notified of entry or exit, and how often you want to check. To use the geofencing API you first define a geofence object (WPSGeoFence) and then register for callbacks by calling setGeoFence.
Here's the Android code to define one:
This would define a geo-fence with a radius of 100m, indicate you want notification of entry into this area, and set the check interval to 1000 milliseconds. Once defined, you must pass the geofence object to the XPS.setGeoFence method and provide a callback to be called when the entry condition is met. For example:
You can use the returned handle object to cancel a geofence later by calling XPS.cancelGeoFence.
Geofences will only be monitored in the context of pending periodic location requests, which means your app also needs to call getPeriodicLocation for geofences to work. This gives you maximum control over how often location is being checked. See the included documentation for more details.