Proximity

Based on Bluetooth Low Energy (BLE) beacons that provide finer grain proximity context.

Supported Platforms

iOS™

Gimbal Proximity is currently available for iOS™ and is supported by all iOS™ devices that support BLE. This includes iPhone 4s or later, iPad 3rd gen and later, and iPod 5th gen and later. It also supports both 32-bit and 64-bit architecture.

Android™

Work is actively in progress on Android™ and Gimbal Proximity will release an SDK for Android™ soon.


Beacons

The Gimbal Proximity Beacon is a BLE powered device that provides context about proximity and also ambient temperature. They broadcast a rolling encrypted code to ensure only users with the correct privileges can see the beacon's information. The beacons are configured to transmit at a rate that optimizes reactiveness on applications and battery-life of the beacons. They come in two form factors: Series 10 and Series 20.

Note Across all documentation and SDKs the terms 'Beacon' and 'Transmitter' are interchangeable

Series 10

Series 10 Image

Series 10 are small devices measuring no more than 1" x 0.125" x 1.5" (L x W x H). These beacons are powered by a 3V CR2032 cell battery that lasts for about 3 months. These by default transmit at a rate of 645ms.

Series 20

Series 20 Image

Series 20 are meant to be affixed to a location with industrial tape or screws. These beacons are much larger, 3.75" x 3.125" x 0.875" (L x W x H) than the Series 10 and are powered by 4 x AA batteries which last up to a year without replacement. These beacons can be affixed inside or outside as they are weather proof and by default transmit at a rate of 100ms.

Proximity Enabled Applications

Applications that are using the Gimbal Proximity SDK are able to detect beacons which are in close proximity. Depending on the visibility level of the application and ownership of the beacon, more information about the beacon (including a given name, temperature and RSSI value) can be displayed. Below are some terms and information to give you a solid background on the Proximity Development Environment so you can provide a quality user experience.

The Big Picture

Proximity Environment Image

Sightings

A sighting occurs when a Proximity Enabled Application receives a BLE packet from a proximate beacon. Depending on the visibility of the application, the Gimbal Proximity SDK notifies the application of the sighting. It will contain information about the event such as: RSSI value, Beacon Name, Icon Url, Battery Level, and Temperature. The application can then react to the sighting by showing a coupon deal, displaying information about the current location, or giving a customized greeting.

The Gimbal Proximity SDK, in addition to notifying the application, also notifies the Gimbal Manager Servers periodically of all sightings. The Gimbal Manager Servers can then provide analytics data to third-party developer servers through a REST interface.

Sightings passed to the application are real-time and can be referred to as client-side sightings. Sightings received by the Gimbal Manager Servers can be referred to as server-side sightings. These sightings are not real-time and are meant for analytics, such as historical sightings of beacons.


Visits

A common use case of Proximity is to treat a beacon as a micro-fence that triggers arrival and departure events. This allows a developer to know when a user is near a particular location and for how long they dwelled. This concept is referred to as a Visit in the SDK.

The life cycle of a visit is:

  1. Arrival (First sighting)
  2. Sighted (One or more sightings)
  3. Departure (No longer sighted)
After receiving an arrival event, the application will be updated about the ongoing visit every time a new sighting is received. The update will contain the current dwell time and RSSI of the most current sighting. When the application no longer sights the beacon after a certain amount of time, the departure event is triggered.

A visit has the following characteristics that affect the life cycle:

  • Arrival RSSI
  • Departure RSSI
  • Departure Interval

Arrival RSSI
This value affects the arrival event. Only sightings that have an RSSI value of "Arrival RSSI" or higher is considered an arrival. If this value is not set, any RSSI value will trigger an arrival event.
Departure RSSI
This value affects the departure event. Sightings with an RSSI value greater than the "Departure RSSI" are considered proximate. Sightings with an RSSI value of "Departure RSSI" or lower are not considered to be in proximity. Although the SDK may still detect the beacon, it considers the beacon 'out of range' with respect to the visit. If this value is not set, the SDK will consider any beacon it detects as in-range, regardless of the RSSI value.
Departure Interval
This value determines how long a beacon is 'out of range' to be considered departed. When the beacon has been 'out of range' for longer than this interval, the visit's life cycle ends and a departure event is triggered. Any new sightings for this beacon will start a new visit.

Much like sightings, there are client-side visits and server-side visits. Client-side visits are real-time events. The visit characteristics can be configured via the SDK. Server-side visits are not real-time as the SDK periodically posts sightings to the Gimbal Server to preserve battery life. They can further be impacted by the device's network connectivity. A developer can tune server-side visits via rules.


Rules

A rule gives a developer the ability to receive notifications of server-side visits. Depending on the application's visibility, when the SDK sights a beacon, it sends this sighting to the Gimbal Manager Server. It will then determine if the sighting matches a developer's rule. Upon a rule match, the Gimbal Manager Server notifies the developer's server of visit events through the configured "Sighting Callback URL."


Creating a Rule

To create a rule, visit the Gimbal Manager and navigate to the Proximity->Rules section. Click on "New Rule" to see the screen below:

New Rule

The characteristics of a rule are as follows:

App Title
Required: The title of an application owned by the developer.
Sighting Message Frequency
Required: This is the interval, in seconds, at which the Gimbal Manager will send a Sighting event to the server at "Sighting Callback URL."
Exit Interval
Required: This is the elapsed time, in seconds, that determines when a visit is closed. If no sighting reaches the Gimbal Server within the Exit Interval, the visit is considered departed. The departure event is then sent to the callback URL.
Entry Signal Strength
Optional: If supplied, only sightings whose values are "Entry Signal Strength" or larger will trigger an arrival event.
Exit Signal Strength
Optional: If supplied, sightings whose values are "Entry Signal Strength" or smaller will be ignored for visit processing and will act similar to have not being sighted.
Sighting Callback URL
Optional: This is the URL to the Sighting Callback endpoint hosted by the developer to which all visit events are sent.
As mentioned earlier, the SDK sights every beacon in proximity but the beacons are filtered up to the app by their visibility. Although the sightings are filtered at the application level, the SDK still sends all sightings to the Gimbal Manager Server. Therefore it is possible for a sighting to match against multiple rules on the Gimbal Manager Server, even across applications by different developers. This means that server-side visits can be generated from sightings posted by other applications. To limit rule-matching to sightings that originate only from the same application, select the check box labeled "Only notify when sightings is from the app selected".

Visibility

After creating a new iOS Gimbal Application, under Show Advanced Options, you can set your application's visibility options. These options determine the ability of your application to sight beacons and also how the server matches rules for server-side visits.

API Key Create Form

Clicking 'Show Advanced Options' will reveal the advanced form.

Visibility Options Image

Note When creating an iOS Gimbal Application, the default setting for Visibility is Private and the default for allowing anonymous users to detect your (the developer's) beacons is checked. You can always edit these settings after creation.


There are three visibility options (Private, Authorized, Public) and for these visibilities you have the option of allowing anonymous users to detect your (the developer's) beacons. The roles involved in understanding visibility are: Developer, OAuthed User, Anonymous User. Here are some useful terms to help understand how visibility impacts an application.

Application Types

  • OAuth Enabled Application: A Gimbal Proximity Enabled application that creates an OAuth Session with the Gimbal Manager.
  • Non-OAuth Application: A Gimbal Proximity Enabled application that does not create an OAuth Session with the Gimbal Manager.

User Roles

  • Developer: The Gimbal Account that created and owns the Proximity API Key used to initialize the application
  • OAuthed User: A user of an OAuth Enabled Application that successfully creates an OAuth session.
  • Anonymous User: A user of an Non-OAuth Application

Beacon Types

  • Developer's Beacon: A beacon that is owned by the developer of an application.
  • User's Beacon: A beacon that is owned by the OAuthed User who is currently logged in to the running application.
  • OAuthed Beacon: A beacon that is owned by an OAuthed User of an application other than the currently logged in user.
  • Other Beacon: A beacon which is nether a Developer Beacon nor an OAuthed Beacon.

Visibility Types

  • Private: This visibility allows an Non-OAuth Application to sight the Developer's Beacons and match Rules for Developer's beacons. An OAuth Enabled Application can sight the Developer's beacons and the User's beacons.
  • Authorized: In addition to Private Visbility, an OAuth Enabled Application can also see the OAuthed Beacons of any OAuthed User, not just the OAuthed User logged in to the application.
  • Public: In addition to Authorized Visibility, rules can be matched when applications developed by another developer are in proximity to a Developer's beacon and an OAuthed Beacon.

Allow Anonymous Users To Detect Your Beacons

This checkbox ensures that a Developer's beacon can be sighted by the application being created whether or not the application uses an OAuth Session.

Important If you are creating an Non-OAuth Application you will likely want to check this option so that your application will see your beacons.

Non-OAuth Applications

The following tables describe the possible scenarios when an Non-OAuth Application is in proximity to a beacon.

Visibility
Developer's   Beacon Private Authorized Public
Client-Side Sightings Yes* Yes* Yes*
Server-Side Visits Yes Yes Yes
Visibility
Other Beacon Private Authorized Public
Client-Side Sightings No No No
Server-Side Visits No No No

Important The "Yes*" assumes that the "Allow Anonymous Users to Detect Your Beacons" checkbox is enabled

OAuth Enabled Applications

The following tables describe the possible scenarios when an OAuth Enabled Application is in proximity to a beacon.

Visibility
Developer's   Beacon Private Authorized Public
Client-Side Sightings Yes Yes Yes
Server-Side Visits Yes Yes Yes
Visibility
User Beacon Private Authorized Public
Client-Side Sightings Yes Yes Yes
Server-Side Visits Yes Yes Yes
Visibility
OAuthed Beacon Private Authorized Public
Client-Side Sightings No Yes Yes
Server-Side Visits No Yes Yes
Visibility
Other             Beacon Private Authorized Public
Client-Side Sightings No No No
Server-Side Visits No No No

Other Gimbal Proximity Enabled Applications

When a Gimbal Proximity Enabled application created by another developer sees your beacon, the application will not be able to sight your beacon but it may create a server-side visit if the application chose Public visibility. Here is a table to describe these scenarios:

Visibility
Developer's   Beacon Private Authorized Public
Client-Side Sightings No No No
Server-Side Visits No No Yes
Visibility
OAuthed Beacon Private Authorized Public
Client-Side Sightings No No No
Server-Side Visits No No Yes

Sightings in Background Mode

They Gimbal Proximity SDK is designed to work while applications are in the background, however, behavior in background mode is platform dependent.

Platform specific steps to enable background mode and test results can be found here: