public interface ProximityKitGeofenceNotifier
This interface should be implemented by classes that want to receive updates about coarse level transitions (for example entering or exiting) for geofence regions.
For example, a convention app can use these events to provide the user a notification with their purchased ticket as they near the venue.
Be aware that the location services accuracy mode and network availability will have a direct impact on the enter and exit events. The accuracy of a location measurement can often vary from 5 - 50 meters. Ensure that you configure the geofence radius large enough to allow for less accurate measurements.
Per the Android geofence guide the underlying logic for how enter and exit events are calculated is as follows:
On most devices, the geofence service uses only network location for geofence triggering. The service uses this approach because network location consumes much less power, it takes less time to get discrete locations, and most importantly it's available indoors. Starting with Google Play services 3.2, the geofence service calculates the overlapping ratio of the location circle and the geofence circle and only generates the entrance alert when the ratio is at least 85% for a bigger geofence or 75% for a smaller geofence. For an exit alert, the ratio threshold used is 15% or 25%.
Release 0.13.0 introduced the ProximityRegion interface to represent a generic region
defined in Proximity Kit. Along with this came RegionEvent objects and local
region monitoring event broadcasts. The broadcast events mirror these notification callbacks
and are available as a more generic alternative messaging path.
Region monitoring events are broadcast using local notifications through
LocalBroadcastManager. The choice for
using LocalBroadcastManager was based
on prioritizing performance and security over having to force apps to include an additional
dependency.
Be sure your app includes the v4 compat library
to be able to use LocalBroadcastManager. For most apps this won't be an issue as most other support library
and Google Play services packages already include it.
To receive the ProximityRegion event broadcasts setup a BroadcastReceiver and IntentFilter with one or more of the broadcast actions. Intents sent by LocalBroadcastManager must be registered
dynamically through registerReceiver() and cannot be declared in the manifest. After receiving the intent convert
it into a RegionEvent using RegionEvent.fromIntent(Intent).
public class MonitorRegionEventReceiver extends BroadcastReceiver {
static final MonitorRegionEventReceiver INSTANCE = new MonitorRegionEventReceiver();
static final IntentFilter FILTER;
static {
IntentFilter filter = new IntentFilter(RegionEvent.ACTION_REGION_ENTER);
filter.addAction(RegionEvent.ACTION_REGION_EXIT);
filter.addAction(RegionEvent.ACTION_REGION_STATE_DETERMINED);
FILTER = filter;
}
@Override
public void onReceive(Context context, Intent intent) {
RegionEvent monitorEvent = RegionEvent.fromIntent(intent);
switch (intent.getAction()) {
case RegionEvent.ACTION_REGION_ENTER:
// Perform enter related tasks
break;
case RegionEvent.ACTION_REGION_EXIT:
// Perform exit related tasks
break;
case RegionEvent.ACTION_REGION_STATE_DETERMINED:
// Perform state related tasks
break;
default:
Log.w(
"MonitorRegionEventReceiver",
"Received unknown intent action: " + intent.getAction()
);
}
}
}
public class SampleApp extends Application implements ProximityKitGeofenceNotifier {
// Storage for an instance of the manager
private static volatile ProximityKitManager pkManager = null;
@Override
public void onCreate() {
super.onCreate();
// Proximity Kit manager instance configuration and creation
LocalBroadcastManager.getInstance(this)
.registerReceiver(
MonitorRegionEventReceiver.INSTANCE,
MonitorRegionEventReceiver.FILTER
);
pkManager.setProximityKitGeofenceNotifier(this);
}
ProximityKitGeofenceRegion,
ProximityKitMonitorNotifier,
ProximityKitManager.getProximityKitGeofenceNotifier(),
ProximityKitManager.setProximityKitGeofenceNotifier(ProximityKitGeofenceNotifier),
Creating and Monitoring Geofences > Use Best Practices for Geofencing: Choose the optimal
radius for your geofence
,
Creating and Monitoring Geofences > Troubleshoot the Geofence Entrance Event
| Modifier and Type | Field and Description |
|---|---|
static int |
INSIDE
Deprecated.
As of 0.13.0, replaced by
RegionEvent.INSIDE. |
static int |
OUTSIDE
Deprecated.
As of 0.13.0, replaced by
RegionEvent.OUTSIDE. |
| Modifier and Type | Method and Description |
|---|---|
void |
didDetermineStateForGeofence(int state,
ProximityKitGeofenceRegion geofence)
Provides major state events for a geofence region.
|
void |
didEnterGeofence(ProximityKitGeofenceRegion geofence)
Called when the Android device is inside the defined
geofence region. |
void |
didExitGeofence(ProximityKitGeofenceRegion geofence)
Called when the Android device transitions to outside the defined
geofence region. |
@Deprecated static final int INSIDE
RegionEvent.INSIDE.@Deprecated static final int OUTSIDE
RegionEvent.OUTSIDE.void didDetermineStateForGeofence(int state,
ProximityKitGeofenceRegion geofence)
This is called with a value of RegionEvent.INSIDE when at the Android device
determines that it is within the bounds of the geofence region. Conversely, this
is called with a value of RegionEvent.OUTSIDE when the device leaves the geofence region it was previously within.
state - Major state of geofence. Either
RegionEvent.INSIDE or RegionEvent.OUTSIDEgeofence - The ProximityKitGeofenceRegion defining the boundary criteria.void didEnterGeofence(ProximityKitGeofenceRegion geofence)
geofence region.geofence - The ProximityKitGeofenceRegion boundary the device is now within.void didExitGeofence(ProximityKitGeofenceRegion geofence)
geofence region.geofence - The ProximityKitGeofenceRegion boundary the device is no longer within.