iOS Features – Check-out

Introduction

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

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

The check-out feature also allows your app to be notified in real-time at the point 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 own hardware and 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

Having 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™; entailing that the device will provide a check-out after the percentage is crossed by checking in to a fence but not provide a check-out if the device finally 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’s 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 the ‘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 behaviour 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 BDPLocationDelegate 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 willCheckOut 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 willCheckOut flag when driving UI elements and other behaviours 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 BDPLocationDelegate API specification.

Fence delegate callback

- (void)didCheckOutFromFence:inZone:onDate:withDuration:withCustomData:

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 date and time at which the trigger occurred
  • the number of minutes that the device has remained within the Fence
  • the custom fields setup for the Custom Action in Point Access web interface, refer to Point Access – Setting custom data fields for how to create and edit custom data fields in Point Access web interface

Beacon delegate callback

-(void)didCheckOutFromBeacon:inZone:withProximity:onDate:withDuration:withCustomData:

This method passes back:

  • the name, description of the Beacon checked out from
  • the point and proximity of the Beacon at which check-in occurred
  • 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 date and time at which the trigger occurred
  • the number of minutes that the device has remained within 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).
image

Interaction with the Enable / Disable zones feature

Note that if a Zone has already been ‘checked-in’ and is awaiting a ‘check-out’ event, then disabling the Zone at this point will not prevent the check-out callback from occurring.

If it is important to suppress check-out behaviours while a Zone is disabled by your application, we advise that you make use of the isZoneDisabledByApplication: method as part of your check-out callback.

Created by Bluedot DevOps on January 16, 2018

Start the discussion