A - Principles:

The main principle of Insiteo proximity interaction framework is to trigger Actions that your application’s end-user will actually experience. Actions can be as straightforward as a simple Notification but can also cover much richer interactions such as providing contextual information, customizing a UI or triggering a remote server based on location contexts.

Once an Action is created, you need to define:

• when it is allowed to occur (see Action Scheduling and Groups)
• when it actually occurs, based on a set of Action proximity Triggers

B - Actions:

Insiteo SDK provides several types of “Actions”, among which:

• Notifications
• Webviews
• Custom Actions

Notifications:

Notifications can exist as a standalone Action or can optionally be associated to the other types of Actions

Notification main properties are a Title and a Text which are displayed to the end-user.

By default, Insiteo SDK redirects Notification events to the OS local notification provider. You can intercept and change this default behaviour if you wish.

Would you like to embed any meta-data in a Notification for further use by your application, we provide anExtra Datacontainer. We recommend using JSON or an equivalent structured format in this container.

Webviews:

Webview Actionscarry an URL resource which is intended to be opened as webview in your app or in a browser.

Custom Actions:

Custom Actions allow you to pass any specific content you would like to your application. Use the data container associated to a Custom Action to convey a String. We recommend using JSON or an equivalent structured format in this container. Our system does not interfere with the information you include in this container, it just handles the proper triggering and delivery of this data to your Application.

Typical actions falling under this category are:

• In-App redirections
• calling webservices
• calling interactivity platforms such as IFTTT

We provide sample schemes for enabling any of these services. You may also define your own schemes and interpret them accordingly in your app.

C - Action Scheduling and Groups:

You can define rules controlling when any Action is allowed to be triggered or re-triggered:

• to handle this from a Time and Date perspective, use our Scheduling rules,
• to handle avoidance of too many Actions triggering on given periods of time, use our Groups and Action re-triggering rules.

Action Scheduling:

Scheduling defines when an Action is allowed to be triggered in terms of Date and Time. When an underlying proximity trigger occurs, an Action will actually be triggered only if the current Date and Time match with an Active Period of the Action

The most basic Scheduling rule defines a Validity Period which has:

• a Start Date
• an End Date
• active WeekDays
• optionally, active Hoursfor each given day.

Note: For a given Action, multiple Validity Periods can be defined

You may also define Exception Periods in order to either enable or disable the action during specific periods, on specific days or specific hours.

Groups and re-triggering rules:

These rules allow you to control when an action is allowed to trigger, based on previous occurrences of itself or of other related Actions

Action re-triggering period:

At the individual Action level, the Re-triggering period is the duration during which an action is inhibited after being triggered. When set to zero, the re-triggering period check is removed, the action may trigger without any limitation.

Action Re-triggering Period example:

An Action is executed a first time. A Trigger for this Action happens a short while after, but the re-triggering period has not yet expired. The Action is therefore not executed again. If a third Trigger happens right after the re-triggering period expires, the Action is then executed.

Group triggering rules:

You can define Action Groups and link multiple Actions to them.

An Action Group has its own re-triggering rules with the following settings:

• Maximum number of occurencesin the group
• Re-triggering period of the group.

Group level rules apply on top of individual Action re-triggering. They ensure that no more than Maximum number of occurences Action from the group are triggered in any given Re-triggering period of time.

Action Group triggering rules example: Action A and Action B belong to the same Group

Group rules are:

• Re-triggering period = 4 minutes
• Maximum number of occurrences = 2

When two actions have been executed, a 3rd one is not executed while the two previous ones are less than 4 minutes old.

If another Action is triggered slightly later, only one action already occurred in the previous 4 minutes: the new Action can be executed:

D - Action Triggers:

Action Triggers define on which proximity criteria an Action needs to be triggered. An Action may have multiple Action Triggers, which run independantly from each other.

Note: Although multiple triggers may be associated to a given Action, previously explicited Scheduling and Re-triggering rules apply at the Action level, whatever the underlying triggers are.

Event types:

iBeacon® Region event:

As per Apple’s iOS documentation, iBeacon Regions are groups of iBeacons. depending on configuration, these Regions may cover one unique iBeacon or thousands of iBeacons.

iBeacon Region events happen:

• INwhenever a device first enters the coverage of any iBeacon belonging to a given iBeacon Region. This event is typically triggered a few seconds after entering the region, if not immediately most of the time.

• OUT: whenever a device leaves to coverage of any iBeacon belonging to the region. This event is typically triggered 30 seconds after leaving the region area.

iBeacon Region example: Multiple iBeacons belong to the same Region. IN and OUT events are triggered when the Region coverage area is entered or left.

iBeacon Region events have the capability of waking an iOS application up, even when it has been killed from the multi-task menu.

Using this kind of event is therefore very well suited for “Application wake-up” use cases.

Notes:

iBeacon Region triggering distance: Region events are provided by iOS and there is no way to ask the region to trigger at a given distance or signal power. In order to physically reduce the area of a region, the actual power of iBeacons needs to be reduced accordingly. For flexible & programmable proximity interactions, the following iBeacon Proximity event is well suited and recommended.

iBeacon® Proximity event:

iBeacon Proximity is based on iBeacon “ranging”, which estimates the signal power and thus the distance between a device and surrounding iBeacons.

The principle of iBeacon Proximity event is to check if the user’s device is within a given distance of one specific iBeacon. The distances at which an iBeacon Proximity event occurs are called Proximity Thresholds

Insiteo’s proximity interaction framework provides you with full flexiblity in defining Proximity Thresholds

There are predefined proximity thresholds:

• Far: 40 meters
• Near: 2.5 meters
• Immediate: 0.25 meters

and you can define your own custom thresholds such as:

• Not so Far: 25 meters
• Not so Near: 10 meters

As for the iBeacon Region event, iBeacon Proximity events can be used when entering (IN) or leaving (OUT) a proximity area.

iBeacon Proximity example: The picture below illustrates iBeacon Proximity Events, when the In event is set to Near and the Outevent set to Far

Notes:

iBeacon Ranging: iBeacon Proximity is only available when a device has entered a Region. Proper Regions covering all the beacons used for proximity triggering must therefore be declared. As mentioned above, one single iBeacon Region can cover thousands (and even hundreds of thousand iBeacons), in most cases one single Region is sufficient to ensure all your iBeacons are available for iBeacon Proximity triggering.

Ranging availability in Foreground and Background: To be described

Geofencing Region event:

Geofences are circular areas defined their center’s GPS coordinates and a radius. The smartphone OS is able to detect whenever the device enters or leaves this area. Geofencing areas are mostly suitable for medium to low accuracy triggers (from a few 100 to a few 1000 of meters)

Triggering rules:

For any given Event type, the following Triggering rules apply:

• Number of occurrences: defines how many occurences of the event are required to trigger
• Triggering Period: defines in which maximum period of time the events need to happen
• Event filtering Period: defines a “short-term” period during which not more than one event is actually taken into account. Two or multiple events within a given Event filtering Period only count as one event occurence.

When the Number of occurrences is reached during a given Triggering Period, the Action Triggeris executed and results in the Action being taken (if it is valid from a Scheduling and re-triggering rules perspective)

Trigger reset:

Whenever an Action Trigger is executed after its conditions are met, it is reset: the count of event occurrences is brought back to zero. From that point, the trigger is available to take new input events and be executed another time if conditions are met.

Triggering rule examples:

The examples below show how triggering rules affect the behaviour of Action triggering. In the three described cases, the sequence of Events is exactly the same (Pink triangles on the timeline) With different sets of triggering rules, different seqeuences of actions are obtained for the same event inputs.

Number of occurrences and event count reset:

• Number of occurrences = 3
• Triggering Period = 4 minutes
• No other rule or restriction applies.

When the 3rd event happens, since all 3 occured in less than 4 minutes, the Action is triggered a first time. The event counter is also reset. Subsequent events are counted again and the action triggers another time.

Event filtering Period:

• Number of occurrences = 3
• Triggering Period = 4 minutes
• Event filtering Period= 1 minute

Here, the Event filtering Periodinhibits some events which happen too soon after a previous one. As a consequence, the Action is taken later, when three valid Event have occured.

Triggering Period:

• Number of occurrences = 3
• Triggering Period = 3 minutes
• Event filtering Period= 1 minute

In this example, the Triggering Period is reduced down to 3 minutes. The 3rd valid Event happens slightly too late, at this stage there are still only 2 valid event in the last 3 minutes. The action is therefore not initiated. A 4th occurrence of the trigger happens later-on, at a time when there were still 2 valid Events in the last 3 minutes: the Event counter reaches 3 and the Action is initiated.

E - Architecture overview:

The diagram below illustrates our platform’s architecture and how it integrates to your own system.

Getting started

Access to the SDK download and How-to