Understanding how Connecthings’ SDK works

Apart from detecting beacons around a device, the role of the SDK is mainly two-fold:

  • When a device enters a beacon's action range, and the application is in the foreground, the SDK notifies the application and enables it to generate a specific alert/action
  • When a device enters the area of a beacon, and the application is in the background, the SDK notifies the application and enables it to display a notification

This document focuses on the second bullet point to explain how and when the mobile SDK communicates with an application to create a beacon notification.

Before we explore the notification process with a concrete example, let's start with a reminder of the Adtag data model for notifications.

The Adtag data model for BT beacons and notifications

Connecthings’ Adtag platform provides the following data model to work with beacons.

Note that this model is flexible: it may evolve in the future and incorporate new fields, or you may complete it with additional fields to fit your needs.

  • Notification: message displayed on a phone when a beacon is detected, when the application is in the background.
    • Two fields can be configured:
      • Title
      • Description
  • URL: URL of a mobile web page that can be used to display content inside the webview
  • URI: URI of a mobile app page that can be used to trigger the launch of specific pages inside your application

How notifications work

Our SDK allows devices that have your application in the background to trigger the display of notifications when they enter the correct beacon’s range.

Our SDK works with ‘BeaconContent’ objects, which create the link between the physical beacon and the information saved on the Adtag platform, and which you will be able to manipulate in your code to launch notifications.

Notifications are linked to a specific beacon. When the SDK detects a beacon zone entry, it informs the application and gets it to generate the associated notification. This notification will be automatically cancelled by the SDK when the beacon becomes out of range.

In the SDK, the notification process is based on the beacon’s UUID. An application will display a notification when a SDK monitors the bluetooth devices and identifies a beacon nearby to match the reference UUID.

When a device exits a beacon’s range and enters the range of another, then a new notification is triggered.

We will use Albert, our beacon expert, to illustrate a possible user journey and how the different steps are materialized in the SDK.

Albert has a device with the relevant application in the background (inactive or killed).

Notification sequencing when a single beacon is detected

Albert enters a beacon’s region.

Figure 1: First notification when Albert enters a beacon’s region

Albert enters the region of Beacon 1: a notification is triggered on his phone.

Notification sequencing when several beacons are detected

Figure 2: No additional notification appears while Beacon 1 is still in range

Albert is standing in an area where both Beacon 1 and Beacon 2 are in range. As such, the notification linked to Beacon 2 cannot be triggered yet.

Figure 3: When Beacon 1 becomes out of range, a new notification for Beacon 2 appears

Albert walks out of the region of Beacon 1.

The SDK detects a variation due to the exiting of Beacon 1’s region, and cancels the first notification associated to Beacon 1.

The SDK detects that there are other beacons around Albert’ device, and finds Beacon 2: this triggers the display of a new notification, linked to Beacon 2.

Figure 4: The new notification is deleted when Albert exits Beacon 2’s region

Albert walks out of the region of Beacon 2.

The SDK detects a variation due to the exiting of Beacon 2’s region, and deletes the corresponding notification.