Proximity

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

Supported Platforms

iOS™

Gimbal Proximity is available for iOS™ devices with BLE support. 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 architectures.

Android™

Gimbal Proximity is available for Android™ devices with BLE support running Android release version 5.0 and above.

Important Support for Android versions 4.4.3 and 4.4.4 can be enabled in Gimbal Manager.


Beacons

The Gimbal Proximity Beacon is a Bluetooth Smart powered device that provides context about proximity and ambient temperature. They broadcast a secure code to ensure only users with the correct privileges can identify the beacon. The beacons are configured to transmit at a rate that optimizes reactiveness on applications and battery-life of the beacons. To see form factors and features please visit our store at https://store.gimbal.com

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

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.

Understanding RSSI values

RSSI is measured in Decibel-milliwatts (dBm). Ignoring sources of interference (e.g. physical items in the line of sight, other sources of radio transmissions in the same range, etc.), there is an expected relationship between distance and detected RSSI. In short, the further away the mobile device is from the beacon the lower the RSSI detected by the mobile device will be. What is not intuitive is that this relationship is not on a linear scale but rather on a logarithmic scale.

The image below illustrates three implications of a logarithmic scale:

  1. The scale has ticks for every decrease of 10 dBM, you can see these that these ticks get closer together as you move to further away from the beacon
  2. Mobile Devices A and B have an RSSI difference of 10 dBM. Mobile Devices C and D also have an RSSI difference of 10 dBM. However, the Distance AB is much bigger than the Distance CD
  3. It’s harder to understand the precise distance of mobile devices as they get further away from the beacon. You can see that the distance of Mobile Device B from the beacon is nearly double the distance of Mobile Device A from the beacon. You can also see that the distance of Mobile Device C and Mobile Device D from the beacon is almost the same.


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 Server Rule

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

New Server Rule

The characteristics of a server 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. This URL will be tested upon Rule creation so must be a live and valid endpoint. Also see "Suspended Callback URL" below.
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".

Suspended Callback URL

A Sighting Callback URL defined within a Server Rule can intermittently fail to send and eventually be suspended if our servers have repeatedly failed to connect to the external server, received bad responses or the endpoint does not respond in a timely manner. A warning will be displayed on your application's rule page with regards to the current status. View Rules

Callback URL Statuses:




NOTE: This is an example Sighting Callback URL that have no current errors.



NOTE: This is an example Sighting Callback URL that have failed intermittently for the last couple of minutes.
This will result in 30 seconds to a minute of failures before a callback will be sent from our server.



NOTE: This is an example Sighting Callback URL that have continuously have failures for approximately 30 minutes to an hour.
This will result in 3 to 5 minutes of failures before a callback will be sent from our server.



NOTE: This is an example Sighting Callback URL that have large amount of failures for over an hour.
This will result in a permanent block on the endpoint. This can be reset by re-validating your endpoint.


Suspension of a URL results in our servers no longer attempting to send Sighting information (Arrival, Sighted, Departed events) to the Callback URL, however, server-side rules will still be generated based upon the other rule parameters.

To lift the suspension, visit the Gimbal Manager and navigate to the Server Rules section and validate/update the Rule with the suspended URL to have a valid endpoint. Once the rule has been saved with a valid endpoint it can take up to 10 minutes for the Sighting events to be sent to the valid endpoint.

Sightings in Background Mode

The 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:


Waking up a forced-closed app

The Gimbal SDK can wakeup if the application was forced killed by the user. The following is required in order for application wakeup to work correctly:

  1. The iOS device needs to be running iOS 7.1 or newer
  2. The Gimbal hardware should be configured with either:
    1. Type Gimbal with “foreground or background” detectionsetting. Note, the default configuration for Series 10 beacons is “Series 10 Recommended” which is a “foreground-only” configuration. Therefore, you will need to assign and apply a new configuration to Series 10 beacons to test waking up an app.
    2. Type iBeacon
  3. After you force close the app on the iOS device, the iOS device needs to depart from proximity of the beacon hardware. The next time the iOS device comes in proximity to the beacon the SDK will detect it and wake up the app in the background
    1. Note for Gimbal type you need to depart from proximity from all the Gimbal type beacons you are nearby. For iBeacon type you need to depart from proximity from all the iBeacon type beacons that have the same UUID you are nearby.
    2. If you are testing this functionality in your lab, it may be easiest to simulate a departure by removing the battery of the beacon. If you do so please note that when you re-insert a battery to a beacon it goes through a boot sequence for a few seconds prior to starting to transmit so you will experience a little longer delay in detecting the beacon than if you exited proximity and re-entered proximity
    3. Upon application startup, ensure that the proper delegates are setup so that the appropriate Gimbal Connector can deliver the place/communication event to your application.
Please note on iOS, running in the background and seeing your app listed in the “app-switcher” are different states:
  • Detecting the beacon and waking the app in the background does not mean you will see the app it in the “app-switcher” screen but it is running in the background
  • Detecting the beacon, waking the app in the background and presenting a notification via the Communicate feature does not mean you will see the app it in the “app-switcher” screen but it is running in the background
  • Detecting the beacon, waking the app in the background, presenting a notification via the Communicate feature targeted to cause the app to open in the foreground and the user clicking on the notification does mean you will see the app it in the “app-switcher” screen and your app will be running in the foreground


Beacon Sharing

Beacon Sharing enables developers to share their beacons with other developers. In order for you to share some or all of your beacons, the following steps must be taken:

  • You create a sharing key with the set of beacons to be shared
  • You provide the sharing key to the developer that you want to share beacons with
  • The developer imports the shared beacons into his account by using the sharing key
Note: sharing keys are one-time use codes to prevent re-use without your permission

Generate Sharing Keys

To generate a Sharing Key, visit the Gimbal Manager and navigate to the Beacon Sharing section. Click on "Generate Sharing Key" to see the screen below:

Manager Create Sharing Key


Enter a name for your sharing key.
If you wish to set start and expiration times for the key, check the box. You can then enter dates and times.
Note: These dates and times are in the UTC timezone for version 1.x SDK clients and will be automatically adjusted to local timezone for version 2.x SDK clients.

If you wish to share all your beacons, leave the "Share All Beacons" checkbox checked and click "Create Sharing Key".
Note: This will automatically share all beacons in your organization, including ones you activate in the future.

If you wish to share only some of your beacons, de-select the "Share All Beacons" checkbox and you will presented with a list of beacons to select from as illustrated below. Select the sub-set you want to share and click "Create Sharing Key".

Manager Create Sharing Key Not All Beacons


Import Shared Beacons

If you have received a Sharing Key, you can import the shared beacons by visiting the Gimbal Manager and navigate to "Beacon Sharing". Click on the "Activate Sharing Key" buton. This will bring up the dialog box where you enter the Sharing Key and then click "Submit".
Note: This will automatically create a place for each of the shared beacon.

Manager Import Sharing Key Dialog


The newly activated key will appear in the "Imported Sharing Keys" table. You can click on the key to see a list of all the beacons that were imported.

Important v2 introduces the concept of places. A Place can be represented by a single geofence and/or a series of beacons. When you import a shared beacon, a corresponding place isn't created automatically. Please manually create a Place for your beacon as needed.

Manager Imported Sharing Keys Listing


Beacon Installation

Default Beacon Configurations


Beacon Configurations allow you to customize hardware specific attributes such as antenna type, transmit power, etc, for a particular beacon. This results in having the SDK detect the presense of that beacon in different ways. For example, adjusting the transmit power of a beacon can result in a greator detection distance.

Here are the default beacon configurations:

Configuration Name Behavior Where should this configuration be used?
Recommended Constant sightings in forground. Sightings in background come in at a rate of 3 per minute. Apply this configuration when timely background sightings are critical to your application's function.
Presence optimized Same as Recommended, however sightings in background come in at a rate of 1 per minute. This results in a significant amount of battery savings when in constant proximity of a beacon. Apply this configuration when the user's phone will be in prolonged proximity of that beacon. This configuration will minimize the impact on the user's phone battery life when in proximity of beacons that have this configuration.

Assigning a Configuration to Beacon


Assigning a configuration indicates to the server that you want to push that configuration to the specified beacon when possible. To do so navigate to Proximity > Beacons and edit a beacon.

Push Configuration To Beacon


In order to push configurations to a beacon you must use the Gimbal Beacon Manager application that can be found in the App Store℠ here. Open the Gimbal Beacon Manager application and log in using your Gimbal Manager credentials.

Once logged in hit the settings button to reveal the settings menu. Click on the "Configure" menu option.

Follow the directions on the screen and remove all batteries from your Gimbal Series 20 Beacon and then re-insert the batteries. This places the beacon in a configurable mode and the application will be able to push your configuration. When connected to the beacon you should see something like the following.

Notice that the configuration on the beacon does not match the configuration indicated from the Server. Push the update button to apply your configuration.