Android Features – Beacon triggering

Point SDK provides indoor triggering capabilities using Bluetooth Low Energy (BLE) Beacons. This feature is only available on devices that have BLE hardware support and are running Android OS 4.3 and above.

Beacon can be registered and configured through the Point Access web interface. Point SDK must know the approximate geographical location and MAC address of each Beacon; these are required when registering Beacons in the ‘App and Beacon Management’ tab on the Point Access Dashboard.

Beacons function in a similar manner to GEOLINE™ and Geofences as they trigger Actions associated with a given Zone once discovered by an Android device. When a Beacon is triggered, a check-in notification is sent to Point Access, and the actions pertaining to the Zone containing the Beacon are executed; the Zone is then disabled for the duration of its configurable Minimum Retrigger Time (MRT).

Custom actions

If a Zone contains a Custom Action, then the onCheckIntoBeacon method within an implementation of ApplicationNotificationListener is called.

It is best practice to register the ApplicationNotificationListener callback in onBlueDotPointServiceStartedSuccess and remove it in onBlueDotPointServiceStop.  While in an Activity, it is recommended to add the ApplicationNotificationListener in onResume and unregister it in onPause.

image

Thread safety

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

Examples

The following is an example of how to use App Notifications in an Application. Alternatively, for integration with an Activity, Service or Fragment, examples are available here.

public class BDTestApplication extends Application implements ServiceStatusListener,ApplicationNotificationListener {
    private Handler handler;
    ...
    
    @Override
    public void onCreate() {
        super.onCreate();
  
        // Initializing Handler bound to UI Thread
        handler = new Handler(Looper.getMainLooper());
        ...
    }
 
    @Override
    public void onBlueDotPointServiceStartedSuccess() {
        mServiceManager.subscribeForApplicationNotification(this);
    }
    ...
    @Override
    public void onCheckIntoBeacon(BeaconInfo beaconInfo, ZoneInfo zoneInfo, LocationInfo location, Proximity proximity, Map<String, String> customData, boolean isCheckOut) {
        // This method will be called if the device checked into a Beacon
        // and the zone contains a custom action
        // Using a handler to pass Runnable into UI thread to interact with UI Elements
        handler.post(new Runnable() {
            @Override
            public void run() {
                Toast.makeText(getApplicationContext(),"Entered: " + beaconInfo.getName(),Toast.LENGTH_LONG).show();
            }
        });
    }
    ...
     
    @Override
    public void onBlueDotPointServiceStop() {
        mServiceManager.unsubscribeForApplicationNotification(this);
    }
}

The following is an example of how to use App Notifications in an Activity:

public class TestActivity extends Activity implements ApplicationNotificationListener {
     
    @Override
    protected void onResume() {
        super.onResume();
        mServiceManager.subscribeForApplicationNotification(this);
    }
    ...
     
    @Override
    public void onCheckIntoBeacon(BeaconInfo beaconInfo, ZoneInfo zoneInfo, LocationInfo location, Proximity proximity, Map<String, String> customData, boolean isCheckOut) {
        // This will be called if the trigger happened on a Beacon
        // and the zone contains a custom action
        // Using runOnUiThread to interact with UI Elements within UI Thread
        final String beaconName = beaconInfo.getName();
        runOnUiThread(new Runnable() {
            @Override
            public void run() {
                Toast.makeText(getApplicationContext(), "Entered: " + beaconName, Toast.LENGTH_LONG).show();
            }
        });
    }
    ...
     
    @Override
    protected void onPause() {
        super.onPause();
        mServiceManager.unsubscribeForApplicationNotification(this);
    }
}

This method passes back:

  • The name, description, and geometry of the triggered Beacon.
  • 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 location of the Beacon as specified on the Bluedot backend.
  • The proximity at which the trigger occurred.
  • The custom fields configured 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 the Point Access web interface.
  • Whether check-out callback should be expected.

If the isCheckOut flag is set to true, when the device leaves the checked-in area then a subsequent check-out callback will also be made:

@Override
public void onCheckedOutFromBeacon(BeaconInfo beaconInfo, ZoneInfo zoneInfo, int dwellTime, Map<String, String> customData) {
    // This method will be called when a device Checks out of a Beacon
}
...

The documentation section on the check-out feature discusses this behavior in detail.

Dealing with Bluetooth Low Energy (BLE) availability

Beacon-based triggering will not be possible if:

  • Bluetooth Low Energy (BLE) is not available on a particular device.
  • Bluetooth is switched off in the device settings.

Please refer to Android – Error handling for more details.

Created by Bluedot DevOps on June 19, 2018

Start the discussion