Android Features – Check-out

Introduction

Point SDK can optionally track when a device leaves a Fence or a Beacon proximity. This is known as ‘checking out’.

Checking out enriches the analytics you will receive from Point SDK by recording ‘dwell time’ – the approximate number of minutes a device spent at a location – against check-ins.

The check-out feature also allows your app to be notified in real-time when a device ‘checks out’ of a Fence or Beacon that has previously been checked into.

For Fences, check-out occurs as soon as the SDK confidently determines that the device is outside of a checked in Fence area.  The exact distance of travel is dependent on environmental conditions and the opportunity for battery conservation.

For Beacons, check-out occurs when the device leaves the Beacon’s full range, and it is no longer detectable.  The exact range for check-out from a Beacon is highly dependent on the Beacon’s hardware configuration. This is irrespective of any closer proximity that may have been chosen for checking in, within the Point Access web interface.

image

GEOLINE™ components and check-out

As they have no area, GEOLINE™ components cannot be utilized for a check-out.

This has more of an impact should a Percentage Crossed condition be applied to a Zone containing both Geofences and GEOLINE™, as the device will provide a check-out after the appropriate percentage is crossed by checking into Fences but will not provide a check-out if the device checked into a GEOLINE™.

In summary, it is possible but not good practice to include GEOLINE™ components in a Zone that is to be utilized for checking out.

Enabling Check-out

Check-out is enabled by Zone, and the setting applies to all Fences and/or Beacons within it.

In the Point Access web interface, enable check-out from the options within any Zone save dialog.

Check-out and Minimum Re-trigger Time (MRT)

The minimum re-trigger time ensures that a fence or beacon is not triggered continuously within a Zone; when check-out is enabled for a Zone, the Minimum Re-trigger Time starts from the point of ‘check-out’.

Check-out and Custom Actions

By default, enabling check-out for a Zone will have the effect of ‘dwell time’ being recorded against check-ins in your zone’s Activity Log.

Most often, check-out will be used in conjunction with Custom Actions to drive richer app behavior via callbacks.

If a Zone has a Custom Action and is selected as a check-out Zone, then the following methods within your implementation of ApplicationNotificationListener are called depending on whether a Fence or Beacon has been checked out of.

image

When to expect a check-out callback

Note that the check-in callback, driven by the Custom Action, specifies a Boolean flag named isCheckOut which tells your app whether or not to expect a subsequent check-out callback.

Currently, this will be true for check-ins occurring in any Zone marked for check-out, except those triggered by crossing a Geoline™.

Use the isCheckOut flag when driving UI elements and other behaviors which rely on a later check-out callback.

Please refer to the Fence check-in and Beacon check-in documentation pages, as well as the ApplicationNotificationListener API specification.

image

Thread safety

These callbacks should be thread-safe and should not update UI views directly; they should be wrapped into runOnUiThread or communicated to UI thread using a Handler.

Fence callback

@Override
public void onCheckedOutFromFence(FenceInfo fenceInfo, ZoneInfo zoneInfo, int dwellTime, Map<String, String> customData){
    // This will be called when device leaves CheckOut Fence
    // Using handler bound to UI thread to interact with UI Elements
    handler.post(new Runnable() {
        @Override
        public void run() {
            Toast.makeText(getApplicationContext(), "Left: " + fenceInfo.getName() + " dwellTime,min=" + dwellTime, Toast.LENGTH_LONG).show();
        }
    });
}
...

This method passes back:

  • The name, description, and geometry of the Fence checked out from.
  • Which Zone the fence belongs to, including:
    • the name and description of the Zone.
    • the id of the Zone.
    • a reference to all the Fence and Beacon information within that Zone.
  • The duration that the user has remained within the fence.
  • The custom fields setup for the Custom Action in the Point Access web interface (refer to Point Access – Setting custom data fields for how to create and edit custom data fields in the web interface).

Beacon callback

@Override
public void onCheckedOutFromBeacon(BeaconInfo beaconInfo, ZoneInfo zoneInfo, int dwellTime, Map<String, String> customData){
    // This will be called when device leaves CheckOut Beacon area
    // Using handler bound to UI thread to interact with UI Elements
    handler.post(new Runnable() {
        @Override
        public void run() {
            Toast.makeText(getApplicationContext(), "Left: " + beaconInfo.getName() + " dwellTime,min=" + dwellTime, Toast.LENGTH_LONG).show();
        }
    });
}
...

This method passes back:

  • The name and description of the Beacon checked out from.
  • Which Zone the Beacon belongs to, including:
    • the name and description of the Zone.
    • the id of the Zone.
    • a reference to all the Fence and Beacon information within that Zone.
  • The duration that the user has remained within the range of the Beacon.
  • The custom fields setup for the Custom Action in the Point Access web interface (refer to Point Access – Setting custom data fields for how to create and edit custom data fields in the web interface).
Created by Bluedot DevOps on June 19, 2018