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 former, and explains how and when our mobile SDK enables an app to generate a beacon alert.

Overview of alerts

  • Alerts are actions/messages triggered on a user's phone when the application is active in foreground
  • An alert can take many forms: text, url, image, webview...
  • The display of an alert can be - but does not have to be - associated with a specific beacon proximity zone (near, far, immediate)
  • You can configure when and how an alert is created using the Beacon Alert section in the Adtag Platform
  • You can implement your own rules and conditions to create and manage alerts using our mobile SDK and alert strategies.

Introduction to Alert Strategies

Our SDK provides a new approach to alert customization through the concept of Alert Strategies, which allow you to easily manage the alert lifecycle.

Alert strategies are sets of rules that you can implement, and which allow you to determine exactly when alerts are created and/or deleted by the SDK.

Our SDK provides two types of Alert Strategies:

  • Default Alert Strategies: 3 built-in, plug & play strategies are at your disposal to enable you to quickly and easily manage the action range(s) for the beacons
  • Custom Alert Strategies: allow you to define your own rules to manage the alert lifecycle, in terms of action range, timing...

Using a Default Alert Strategy

As a reminder, beacons have 3 action ranges that can be used to define when an alert is launched: IMMEDIATE, NEAR, and FAR.

Our SDK comes with three default strategies, or "range" conditions, to manage the specific beacon range(s) where the action associated to the alert will be triggered.

You can set up both the range and default strategy of your choice on the Adtag platform (see section below on the Adtag data model).

  • = / Equal: this first strategy allows to condition the launch of an alert only when the smartphone is within the exact range defined on the Adtag platform
    • E.g.: if the Adtag range is near, the alert will only be triggered when the smartphone is in "near" proximity of the beacon, but not when it is in the "immediate" or "far" range.
  • <= / Inferior or Equal: this second strategy allows to condition the launch of the alert when the smartphone is in a range that is inferior or equal to the value set in Adtag
    • E.g.: if the range set in Adtag is "near", then the alert will be triggered when the smartphone is either in "near" or "immediate" proximity of the beacon
  • >= / Superior or Equal: this last strategy allows to condition the launch of the alert when the smartphone is in a range that is superior or equal to the range defined in the Adtag platform
    • E.g.: if the Adtag range is near, then the alert will be triggered when the smartphone is either in "near" or "far" proximity of the beacon

Using a Custom Alert Strategy

With Custom Alert Strategies, you are free to implement your own alert process, lifecycle, and conditions to create or delete an alert.

You can associate a custom strategy to any beacon through the Adtag platform.

Let's now take a look at the Alert Management model.

Alert management model

The Adtag data model for beacon alerts

Our Adtag platform provides the following data model to work with beacon alerts:

  • Beacon Alert: set of attributes to configure the action/message displayed on a phone when a beacon is detected, when the application is in the foreground.

    • 4 fields can be configured:
      • Title: the title of the alert
      • Description: the description of the alert
      • 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: the thumbnail image associated to the alert
  • Beacon Alert Parameters: set of parameters to specify the conditions of the alert display

    • 4 fields can be configured:
      • Range: proximity zone applicable to the alert (the alert will only be triggered if the smartphone is in the right range around the beacon)
        • Predefined values: IMMEDIATE, NEAR, FAR
      • Action: action triggered when a beacon is detected in the right range
        • Examples:
          • popup: opens a popup and displays the title of the alert, as configured in Adtag. The user clicks on the popup to access additional content
          • webview: automatically opens a webview page when the device is in the right action range
      • Default alert strategy: see section above on Alert Strategies. Predefined values: "=" (default value), "<=", ">="
      • Your custom strategy: see section above on Alert Strategies. Simply make sure that you populate the field on Adtag with the key of your custom alert strategy in the SDK.
        • If you define a Custom Strategy, then the Default Alert Strategy parameter will be ignored.
        • If the SDK cannot find a Custom Strategy, it will default back to the Default Alert Strategy.
  • URL: URL of a mobile web page that can be used to display content inside a webview (e.g. “Action” = webview)

  • URI: URI of a mobile app page that can be used to trigger the launch of specific pages inside your application

Note 1:

The action, range, and alert strategy properties define what happens when a foreground application interacts with a beacon.

For example, if the range parameter is NEAR, the default strategy is '<=' (inferior or equal to the Range parameter), and the defined action is ‘popup’, then a popup appears in the application when the beacon is detected in the IMMEDIATE or NEAR range of the smartphone.

The ‘Action’ field accepts any values: ‘popup’ and ‘webview’ are just examples of what you can implement. The same applies for the 'custom strategy' field. It is up to developers to define the behaviors that will occur in their own applications, and the value they want to set in the Adtag platform.

Note 2:

All of these fields/parameters are manageable in the mobile SDK through the BeaconContent object. This object creates the link between the beacon and the associated content on the Adtag platform.

Note 3:

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.

Note 4:

Depending on the type of action that you want to trigger, you may or may not use all of the data model fields present on Adtag.

The SDK Model

The Beacon Alert Strategy Parameter object

The Beacon Alert Strategy Parameter object synchronizes and centralizes all of the information regarding a specific beacon and associated alerts. The Beacon Alert Strategy Parameter object manages the following parameters:

  • actionStatus: allows to flag if an action is in progress / has been performed with this beacon. 3 values exist:
    • waitingForAction: an action can be triggered with this beacon
    • inProgress: an action is in progress
    • done: an action has been carried out
  • isConditionValid: returns 'true' if the Alert Strategy conditions are met
  • isReadyForAction: returns 'true' if an action can be performed with the beacon
  • maxTimeBeforeResetingActionDone: when the Alert Strategies conditions are not valid anymore and when the actionStatus is "done", the Alert Strategy can reset the actionStatus back to waitingForAction after a given period of time: this is the maxTimeBeforeResetingActionDone value. By default in our Default Alert Strategies, this setting is set to 60 seconds.

Note:

An Alert Strategy can only update the actionStatus parameter from "done" to "waitingForAction".
The ATBeaconAlertConsumer object (presented in the next section) ensures that the actionStatus is updated from "waitingForAction" to "inProgress", and from "inProgress" to "done" when actions are being triggered.

The following section provides more detail on how to concretely generate alerts.

The Beacon Alert Consumer

The Beacon Alert Consumer object is responsible of:

  • choosing on which beacon to trigger an alert (beacon for which the isReadyForAction parameter is set to true in the Beacon Alert Strategy Parameter object)
  • notifying the application about triggering or removing the alert through the Beacon Alert Listener or Delegate

The Beacon Alert Consumer object triggers one alert at a time:

  • If several beacons are available to trigger an alert (isReadyForAction set to true), the Beacon Alert Consumer chooses the closest.
  • If you have decided not to trigger an alert in your code for this closest beacon, the Beacon Alert Consumer suggests the second closest available, and so on.

Note:

The SDK comes with its own implementation of the Beacon Alert Consumer object, but you can implement your own version to fit a specific need.

The Beacon Alert Listener/Delegate

The Beacon Alert Listener/Delegate notifies the application when:

  • A beacon is detected and meets the conditions to trigger an alert
  • An alert can be removed/deleted
  • A Network error has occurred

Quick overview of the process

  • During the scanning process, all of the Beacon Alert Strategy Parameter objects associated with beacons are updated by the specific Beacon Alert Strategy configured on Adtag.

  • The beacons and their Beacon Alert Strategy Parameters are transmitted to the Beacon Alert Consumer object.

  • If for one beacon or more, the isReadyForAction parameter is set to true in the Beacon Alert Strategy Parameter object, the Beacon Alert Consumer object notifies the application of the closest beacon on which an action can be triggered (i.e. isReadyForAction parameter set to true), through the Beacon Alert Listener or Delegate

  • If the application triggers the alert, the beacon’s actionStatus switches from 'Waiting For Action' to 'In Progress'

  • While the actionStatus stays at 'In Progress', the Beacon Alert Consumer cannot notify the application to push other alerts.

  • The actionStatus can either be manually updated from 'In Progress' to 'Done', or it will automatically be switched by the Beacon Alert Consumer when it asks the application to remove the alert.

  • The Beacon Alert Consumer asks the application to remove an alert when:

    • the beacon associated with the alert is no longer detected
    • the beacon no longer meets the conditions defined in the corresponding Beacon Alert Strategy
  • Once the current alert is removed (and therefore the actionStatus switches from 'In Progress' to 'Done'), the Beacon Alert Consumer object looks if another beacon is available and meets the conditions to trigger a new action.

Note :

When the isReadyForAction parameter is set to true, this implies that:

  • the beacon meets the conditions of the corresponding Beacon Alert Strategy, as defined in the Adtag Platform
  • the actionStatus parameter is 'Waiting For Action'

If the actionStatus is 'In Progress' or 'Done', the isReadyForAction parameter automatically switches to false.

How alerts work

To sum up, our SDK allows you to trigger alerts in foreground applications, through beacons that match the rules defined in your Alert Strategy (whether custom or default).

Our SDK works with ‘BeaconContent’ and 'BeaconAlertStrategyParameter' objects, which create the link between the physical beacon and the information saved on the Adtag platform, and which you can manipulate in your code to launch alerts.

While it is very easy to technically configure beacons and the information that will be displayed to end users, what you must define prior to anything else is the overall customer experience and vision/model of interactions that you want to implement.

Among your entire fleet of beacons, you need to determine the type(s) of actions that you want to implement, and on which beacon(s) they apply. This implies preliminary reflection on questions such as:

  • What are your criteria to assign a specific action to a specific beacon? E.g. type of beacon location
  • How to manage possible beacon range overlaps?
  • What behavior do you want to implement when a user enters, exits, then re-enters the action zone of a beacon? / How do you ensure that the end user is not polluted by the same beacon action?

To help answer these questions, the first step is to understand the user journey, the various cases you can encounter, and what tools are at your disposal with our SDK and “BeaconContent” objects.

In the following examples, Beacon1 and Beacon2 have been set up to interact with your application, and have the following Adtag properties:

  • Range: near
  • Action: popup
  • Default strategy: = (Equal)
  • Custom strategy: none

This means that an alert will be displayed on a user's device when it enters the "near" zone of both Beacon1 and Beacon2.

Let us now call Albert, our SDK expert, to give you a few illustrations. Albert is walking around with a smartphone, has your application open in the foreground (active), and will be interacting with these 2 beacons.

Step 1

Albert enters the FAR region of both beacons.

Result:

  • No alert is displayed/no action is triggered because Albert is not in the right range of either beacon (“NEAR” vs. “FAR”).
  • In the SDK:
    • beacon1.isReadyForAction() = false, because the phone is in the “FAR” range of Beacon1, whereas the distance configured in the AdTag platform is “NEAR”.
    • beacon2.isReadyForAction() = false, for the same reason.

Step 2A

Albert moves closer to Beacon1 and Beacon2, and enters their “NEAR” region.

Result:

  • both beacons are available to perform an action.
  • In the SDK:
    • beacon1.isReadyForAction() = true, as the phone is now in the same region as Beacon1’s action range configured in AdTag.
    • beacon2.isReadyForAction() = true, for the same reasons.

In this case, the ATBeaconAlertConsumer object chooses the closest beacon, Beacon1, and notifies the application that an alert can be triggered. Depending on the decision-making process that you have implemented in your app, the SDK either proceeds with the alert display for Beacon1 (illustrated below), or moves on to Beacon2.

Result:

  • An alert is triggered on Albert’s device for Beacon1.
  • In the SDK:
    • The ATBeaconAlertConsumer object flags Beacon1 with action in progress. Automatically, this changes beacon1.isReadyForAction() to false, as the action has already been launched.
    • Therefore, you have now the following situation:
      • beacon1.isReadyForAction() = false
      • beacon2.isReadyForAction() = true, because Beacon2 is still in “near" proximity of Albert’s device
    • Because an action is in progress on Beacon1, the ATBeaconAlertConsumer object will not send any additional notification to the application about Beacon2, even though it is "ready for action".

Tip:

You can use the BeaconContent.actionIsDone() method to flag that the action associated to an alert is complete (for example, when the user closes the pop up). This allows the SDK to propose new content associated to another beacon, if one is nearby and meets the launch conditions.

Step 2B

Let's assume now that Albert closes the popup. Beacon1 is flagged with "action is done", and the SDK can now notify the application that Beacon2 is available for action.

The SDK will now notify the application that Beacon2 is available to trigger an action.

You have now two options for your code:

  • Either you can decide to launch Beacon2’s action now (in which case, the same behavior will occur as for Beacon1)
  • Or you can decide not to trigger any additional action until Albert moves away from the beacons and changes zone

Let’s say that you choose to trigger Beacon2’s alert as well. We now have:

  • Beacon1:
    • beacon1.isReadyForAction() = false
    • beacon1.actionIsInProgress() = false
    • beacon1.actionIsDone() = true
  • Beacon2:
    • beacon2.isReadyForAction() = false
    • beacon2.actionIsInProgress() = true
    • beacon2.actionIsDone() = false

Step 3

Albert moves away from Beacon1: Beacon1 is now in the “far” range of his device, and Beacon2 is still in its “near” range.

Tip:

Because Albert’s device is now outside the “near” region of Beacon1, the beacon's characteristics do not match the Default Strategy criteria anymore. The corresponding “action status“, which was at "done", is therefore automatically reset to "waitingForAction" by the Alert Strategy after 60 seconds (default timing in the Default Alert Strategy).

Result:

  • beacon1.isReadyForAction() = false, because Beacon1 is now in the “far” region of the device (vs. near)
  • beacon1.actionIsDone() = false, because Albert just exited the beacon's action range so the value has been reset to "false"
  • beacon2.isReadyForAction() = false, because Beacon2 was previously flagged with beacon2.actionIsInProgress(), and is still in the “near” region of Albert’s device.
  • beacon2.actionIsInProgress() is still set to true since the alert has been triggered on Albert's phone.

Step 4

Albert closes the popup associated to Beacon2. Beacon2 is flagged with "action is done" using the BeaconContent.actionIsDone() method.

Albert walks back within the “near” region of Beacon1.

Result:

  • beacon1.isReadyForAction() turns back to true, because Albert’s device is back in the correct action range of Beacon1, and the “action is done” flag has just been reset to false.
  • beacon2.isReadyForAction() is false, and beacon2.isInProgress() is false as well.

As Beacon2 is now flagged with "action is done", the ATBeaconAlertConsumer object informs the application that an alert related to Beacon1 can be displayed.

Recap

  • An alert can only be triggered when a beacon meets the conditions of the associated Alert Strategy.
    • In the SDK, this means that the method BeaconContent.isReadyForAction() is set to true
  • When several beacons are "ready for action":
    • The ATBeaconAlertConsumer notifies the application when an alert/action can be triggered on the nearest beacon
    • If no action is carried out with this beacon, the application can trigger the alert on the second closest beacon
  • When the application pushes an alert:
    • The ATBeaconAlertConsumer object flags this beacon with "action is in progress", and no additional alert can be pushed until it switches to "action is done"
  • The ATBeaconAlertConsumer object notifies the application when an alert can be deleted:
    • When the beacon is flagged with 'action is in progress'
    • When the beacon doesn't match the conditions of the corresponding Alert Strategy anymore
  • When the application removes the alert, the ATBeaconAlertConsumer object automatically flags the beacon with "action is done"

Note:

If needed, you can modify the behavior of the ATBeaconAlertConsumer and force the action status to take on a new value (e.g. 'action is done') to trigger or delete alerts.