This document explores the beacon alert process, from the data model to the actual implementation of alerts, and ends on a concrete use case.
Overview of Connecthings’ SDK
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 running in the background, the SDK notifies the application and enables it to display a notification
This document focuses on the first type of behavior, and explains how and when the 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 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 to 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 stategies, or "range" conditions, to manage the specific beacon range(s) where the action associated to the alert can be triggered.
You can set up both the range and default strategy of your choice on the Adtag plaform (see section below on the Adtag data model).
- = - Equal: this first strategy allows to condition the launch of an alert only when the beacon 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 phone, 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 from the beacon 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 and lifecycle, and conditions to create or delete an alert.
You can associated 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 BT beacon alerts
Connecthings’ 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.
- 2 fields can be configured:
- 2 fields can be configured:
Beacon Alert Parameters : set of parameters to specify the context of the display of an alert 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 area around the beacon)
- Predefined values: IMMEDIATE, NEAR, FAR
Action: action triggered when a beacon is detected, and is in the right range/proximity zone
- Examples: - popup: could open a popup and display the title of the alert, as configured in Adtag. The user could click on the popup to access additional content - webview: could automatically open a webview page when the device is in the right beacon’s 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
The action, the range and the 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.
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.
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: means that 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.
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, the Beacon Alert Consumer chooses the closest.
- If you have decided not to trigger an alert in your code, the Beacon Alert Consumer proposes, if available, the second closest available beacon (for which the isReadyForAction parameter is set to true) and so on.
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 to 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. the closest beacon for which the isReadyForAction parameter is set to true), through the Beacon Alert Listener or Delegate
If the application triggers the alert, the actionStatus of the Beacon Alert Strategy Parameter object associated to the beacon 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 to the alert is not detected anymore
- the beacon does not satisfy the conditions defined in the corresponding Beacon Alert Strategy anymore
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 satisfies the conditions to trigger a new action.
When the isReadyForAction parameter is set to true in a Beacon Alert Strategy Parameter, this implies that:
- the beacon satisfies the conditions of the corresponding Beacon Alert Strategy, as defined in the Adtag Platform
- the actionStatus parameter is at ''Waiting For Action'
If the actionStatus is at 'In Progress' or 'Done', the isReadyForAction parameter automatically switches to false.
How alerts work
To sum up, our SDK allows you to trigger alerts on open applications, through beacons that match the rules defined in your Alert Strategy, whether custom or standard.
Devices that have your application in the foreground can display alerts, through beacons that match the rules defined in the Alert Strategy (<=, = or >=) associated to the beacon on Adtag.
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. location of the beacon
- 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, Beacon 1 and Beacon 2 have been set up to interact with your application, and have the following Adtag properties:
- Range: immediate
- 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 "immediate" zone of both Beacon 1 and Beacon 2.
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, and will be interacting with these 2 beacons.
Albert enters the near region of both beacons.
Figure 1: No alert when Albert enters the “near” region of the beacons*
Result: No alert is displayed / no action is triggered because Albert is not in the right range of either beacon (“near” vs. “immediate”).
- beacon1.isReadyForAction() = false, because Beacon 1 is in “near” proximity of the phone, whereas the distance configured in the Adtag platform is “immediate”.
- beacon2.isReadyForAction() = false, for the same reason.
Albert moves closer to Beacon 1 and Beacon 2, and enters their “immediate” region.
Figure 2: First alert when Albert moves to the “immediate” region of the two beacons
Result: Both beacons are available to perform an action
- beacon1.isReadyForAction() = true, as Beacon 1 is now in the same region as the range configured in Adtag.
- beacon2.isReadyForAction() = true, for the same reasons.
In this case, the ATBeaconAlertConsumer object chooses the closest beacon, Beacon 1, and notifies the application that an alert can be triggered.
Depending on the decision-making process that has been implemented in your app, either the alert for Beacon 1 is displayed, or the ATBeaconAlertConsumer object can move on to Beacon 2.
In this case, let's imagine that the implemented process is to trigger the alert for Beacon 1.
Result: An alert is triggered on Albert’s device for Beacon 1.
- The ATBeaconAlertConsumer object flags Beacon 1 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 Beacon 2 is still in “immediate" proximit” of Albert’s device
Because an action is in progress on Beacon 1, the ATBeaconAlertConsumer object will not send any additional notification to the application about Beacon 2, even though it is "ready for action".
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.
Let's assume now that Albert closes the popup. Beacon 1 is flagged with "action is done", and the SDK can now notifty the application that Beacon 2 is available for action.
The SDK will now notify the application that Beacon 2 is available to trigger an action.
You have now two options for your code:
- Either you can decide to launch Beacon 2’s action now (in which case, the same behavior will occur as for Beacon 1)
- 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 Beacon 2’s alert as well. We now have:
- Beacon 1:
- beacon1.isReadyForAction() = false
- beacon1.actionIsInProgress() = false
- beacon1.actionIsDone() = true
- Beacon 2:
- beacon2.isReadyForAction() = false
- beacon2.actionIsInProgress() = true
- beacon2.actionIsDone() = false
Albert moves away from Beacon 1: Beacon 1 is now in the “near” range of his device, and Beacon 2 is still in its “immediate” range.
Figure 3: Albert moves away from Beacon 1
Because Albert’s device is now outside the “immediate” region of Beacon 1, 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 timining in the Default Alert Strategy - ou can choose another value if you implement a Custom Alert Strategy).
- beacon1.isReadyForAction() = false, because Beacon 1 is now in the “near” region of the device (vs. immediate)
- beacon1.actionIsDone() = false, because Albert just exited the beacon's action range so the value was reset to "false"
- beacon2.isReadyForAction() = false, because Beacon 2 was previously flagged with beacon2.actionIsInProgress(), and it is still in the “immediate” region of Albert’s device.
- beacon2.actionIsInProgress() is still set to true since the alert has been triggered on Albert's phone.
Albert closes the popup associated to Beacon 2. Beacon 2 is flagged with "action is done" using the BeaconContent.actionIsDone() method.
Albert walks back within the “immediate” region of Beacon 1.
Figure 4: New alert when Albert comes back to the “immediate” region of Beacon 1
- beacon1.isReadyForAction() turn back to true, because Albert’s device is back in the correct action range of Beacon 1, and the “action is done” flag has just been reset to false.
- beacon2.isReadyForAction() is false, and beacon2.isInProgress() is false as well.
As Beacon 2 is now flagged with "action is done", the ATBeaconAlertConsumer object informs the application that an alert related to Beacon 1 can be displayed.
- An alert can only be triggered when a beacon matches 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 a new value (e.g. 'action is done') to trigger or delete alerts.