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 closed or running in the background, the SDK notifies the application and enables it to display a notification

This document focuses on the latter and explains how and when our mobile SDK communicates with an app to generate 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 beacon notifications

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

  • Notification: message displayed on a phone when a beacon is detected, when the application is closed or running in the background.
    • Five fields can be configured - none of them are mandatory:
      • Title: the title of the notification
      • Description: the description of the notification
      • Text To Speech: if the SDK is configured to work with Text to Speech, this field is used as the default text for Text To Speech.
      • Thumbnail: a thumbnail associated with the notification
      • Image: an image associated with the notification (compatible with Android 4+ and iOs 10+)
  • URL: URL of a mobile web page that can be used to display content, generally inside a webview
  • URI: URI or deep link of a mobile app page that can be used to trigger the launch of specific pages inside your application

Note:

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.

How notifications work

When in range of a beacon, and when your application is closed or running in the background, our SDK allows you to “awaken” your application and interact with users by triggering notifications.

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.

A notification is linked to a specific beacon. When the SDK detects a beacon zone entry, the application is informed and asked to generate the associated notification. This notification is automatically cancelled when the beacon becomes out of range.

Note:

You can set up specific rules to decide whether or not a notification has to be generated, based, in particular, on the user’s context see Notification Strategy chapter

The notification process is based on the beacon’s UUID (iBeacon) or Namespace (Eddystone). During the integration phase, the developer configures the SDK to work with specific UUIDs/Namespaces. Later on, when the SDK monitors for nearby Bluetooth devices, results are filtered based on these UUIDs/Namespaces, so the appropriate content and action can be retrieved from ADTAG. As a result, each time a user enters the range of a beacon, a notification can be triggered. When the user exits that range, the notification disappears, allowing a new notification to be displayed if another beacon is nearby.

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 smartphone with an app that is designed to trigger a notification for two ADTAG beacons: Beacon1 and Beacon2. Albert has either closed the app, or left it running in the background (inactive).

Notification sequencing when a single beacon is detected

Albert enters the action range of Beacon1.

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

Albert enters the range of Beacon1: the corresponding notification is triggered on his phone.

Notification sequencing when several beacons are detected

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

Albert is now standing in an area where both Beacon1 and Beacon2 are in range. Since Albert interacted with Beacon1 first, and is still within range, the notification linked to Beacon2 cannot be triggered yet.

Note:

When 2 beacons are in range, the SDK is configured to interact with the closest beacon first.

Figure 3: When Beacon1 becomes out of range, the notification linked to Beacon2 can be triggered

Albert walks out of Beacon1’s region.

The SDK detects a change - that Beacon1 is not within range anymore – and therefore cancels the notification associated with Beacon1.

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

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

Albert walks out of Beacon2’s region.

The SDK detects the exit of Beacon2’s region, and therefore deletes the corresponding notification.