Understanding how HEROW’ SDK works

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

  • When a device enters a zone's action range, and the application is in the foreground, the SDK notifies the application and enables it to generate a specific in-app action
  • When a device enters the area of a zone, 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 local notification.

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

The Herow data model for notifications

HEROW's platform provides the following data model to work with zones.

  • Notification: message displayed on a phone when a zone is detected, while the application is closed or running in the background.
    • Four fields can be configured - none of them are mandatory:
      • Title: the title of the notification
      • Description: the description of the notification
      • Thumbnail: a thumbnail associated with the notification
      • Image: an image associated with the notification (compatible with Android 4+ and iOS 10+)
  • 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 zone, 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 an interface called PlaceNotification while in background, which create the link between the physical zone and the information saved Herow. You will be manipulating those objects in your code while launching notifications.

A notification is linked to a specific zone. When the SDK detects a zone entry, the application is informed and asked to generate the associated notification. This notification is automatically cancelled when the zone 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 the NotificationFilter chapter for more information)

We will use Albert, our zone 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 Herow zones: zone1 and zone2. Albert has either closed the app, or left it running in the background (inactive).

Notification sequencing when a single zone is detected

Albert enters the action range of zone1 with his phone.

Result: the notification associated with zone1 is triggered

Notification sequencing when several zones are detected

Step 1

Albert is now standing in an area where both zone1 and zone2 are in range.

Result: Albert’s phone is still within range of zone1, and the corresponding notification still displayed on his phone. As a result, the notification linked with zone2 cannot be triggered yet.

Note:

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

Step 2

Albert walks out of zone1’s region, remaining in zone2’s range.

Result:

  • The SDK detects a change - that zone1 is not within range anymore – and therefore cancels the notification associated with it.
  • The SDK scans for zones around Albert’ device, and detects zone2: this triggers the display of a new notification, linked with zone2.

Step 3

Albert walks out of zone2’s region.

Result:

  • The SDK detects the exit of zone2’s region, and therefore deletes the second notification.
  • Since there are no other zones nearby, the phone does not receive any additional notifications.