com.radiusnetworks.proximity

Interface ProximityKitMonitorNotifier

public interface ProximityKitMonitorNotifier

Defines events for major updates about beacon region visibility.

This interface should be implemented by classes that want to receive updates about coarse level transitions (for example entering or exiting) for beacon regions. These events apply to a beacon region and not to a single beacon (unless the region is defined such that it would fully qualify a single beacon).

For example, a convention app can use these events to provide the user a notification with their purchased ticket as they near the venue.

When frequent fine level details about individual beacons are necessary use ProximityKitRangeNotifier instead. For equivalent geofence related events use ProximityKitGeofenceNotifier

Monitor Notification Broadcasts

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 ProximityKitMonitorNotifier {
     // 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.setProximityKitMonitorNotifier(this);
 }
 

Since:

0.1.0

See Also:

ProximityKitBeaconRegion, ProximityKitGeofenceNotifier, ProximityKitRangeNotifier, ProximityKitManager.getProximityKitMonitorNotifier(), ProximityKitManager.setProximityKitMonitorNotifier(ProximityKitMonitorNotifier)

Field Summary

Fields

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.

Method Summary

Modifier and Type	Method and Description
void	didDetermineStateForRegion(int state, ProximityKitBeaconRegion region) Provides major state events for a beacon region.
void	didEnterRegion(ProximityKitBeaconRegion region) Called when at least one beacon matching the region criteria is visible.
void	didExitRegion(ProximityKitBeaconRegion region) Called when no beacons matching the region criteria are visible.

Field Detail

INSIDE

@Deprecated
static final int INSIDE

Deprecated. As of 0.13.0, replaced by RegionEvent.INSIDE.

Indicates the Android device is inside the defined region.

See Also:

Constant Field Values

OUTSIDE

@Deprecated
static final int OUTSIDE

Deprecated. As of 0.13.0, replaced by RegionEvent.OUTSIDE.

Indicates the Android device is outside the defined region.

See Also:

Constant Field Values

Method Detail

didDetermineStateForRegion

void didDetermineStateForRegion(int state,
                                ProximityKitBeaconRegion region)

Provides major state events for a beacon region.

This is called with a value of RegionEvent.INSIDE when at least one beacon matching the region criteria is visible. Conversely, this is called with a value of RegionEvent.OUTSIDE when no beacons defined by the region are visible.

As of 0.13.0 this is guaranteed to be called once for every region in the kit on the following events:

• ProximityKitManager.start()
• on a successful kit sync with the Proximity Kit server (see ProximityKitSyncNotifier)

Also with this release monitored region state is persisted across restarts. This means on service restart, such as a device reboot, the previous region state will be provided in state. For example, if the device was previously inside a region it will report INSIDE on start.

NOTE: this persisted region state is only considered valid for fifteen minutes. If the service is offline for longer than this time the state will be cleared and all regions will report OUTSIDE initially.

Parameters:

state - Major state of region. Either RegionEvent.INSIDE or RegionEvent.OUTSIDE

region - A ProximityKitBeaconRegion defining the beacon boundary criteria.

didEnterRegion

void didEnterRegion(ProximityKitBeaconRegion region)

Called when at least one beacon matching the region criteria is visible.

Parameters:

region - A ProximityKitBeaconRegion defining the beacon boundary criteria.

didExitRegion

void didExitRegion(ProximityKitBeaconRegion region)

Called when no beacons matching the region criteria are visible.

Parameters:

region - A ProximityKitBeaconRegion defining the beacon boundary criteria.