Upgrading the Gimbal SDK for Android to v2.x Beta

22. February 2015 Android 13


In a previous article, the Gimbal SDK v1.x Beta for Android as it pertains to proximity beacons was explored. Topics covered included going over the concept of beacons, contextual location awareness, beacon arrivals & departures, potential beacon use cases, and creating the necessary classes to setup an Android application to work with the SDK to discover and react accordingly with beacons. It is assumed that the previous article was followed and upgrading from 1.x Beta of the Gimbal SDK to v2.x Beta is desired. The new features of the Gimbal SDK will be discussed along with modifying the classes previously created to work with the new API. It is important to keep in mind that Gimbal is constantly changing the SDK by adding and removing features. Because of this, it is possible this article may not be relevant to every situation. Other areas of confusion may be the differences between the Beta and non-Beta versions. Gimbal may introduce a feature into the Beta version of the SDK and then later move it to the non-Beta version. In addition, Gimbal used to previously label the v1.x SDK as one with Proximity and one without (two separate versions). This is no longer the case with v2.x of the SDK as all features have been consolidated into it. Thus, due to the rapid development rate of the SDK newer versions may not 100% align with the material contained within this article. Therefore, it is recommended that the reader refer to the official Gimbal Documentation in those situations and as good practice. This article complements the official documentation.

Note: This article only covers the features of the SDK that involve beacons. Not all features involving beacons will be covered so be sure to explore the various Gimbal classes and their methods. Also, before beginning make sure to read this article on properly setting up the v2.x Beta SDK with Android Studio as it is slightly different than the v1.x Beta SDK. A final thing to keep in mind is that earlier versions of Android (4.4.3 and 4.4.4) are disable the Gimbal service by default. In order to enable these Android versions to work with the new SDK please visit the Gimbal Developer Account and view the application settings page shown in next section.

Abstracting Location Providers with Places

Previously, individual beacons were discovered and acted upon independently. Each disparate beacon would trigger an arrival or departure event when within the appropriate range. Things would get tricky when adding multiple beacons into a large room and trying to get them to react to an event logically as one beacon. This is no longer the case in v2.x Beta of the Gimbal SDK. To fix this and make it easier to work with the various location providers (beacons, geofences, etc.), the concept of Places was introduced. Places abstract away the location provider so that the developer only needs to be concerned with a Place itself. The Place can trigger an arrival or departure, now called Entry and Exit, just like an individual beacon did. However, a Place can have a combination of one or more beacons and geofences. Creating and managing Places is done from the Gimbal Developer Account. As long as beacons have been registered and added to the account, when creating a Place they will be usable. The same thing goes for geofences. This has greatly reduced the complexity of working with location providers and now it is possible for a group of beacons to logically appear as one.

Updating the Gimbal Helper Class

Gimbal Place Settings
Gimbal Place Settings

The concept of Places has changed the way the SDK works. The Proximity class is no longer present. Manually setting options such as the signal smoothing window has changed and Gimbal recommends setting this from within the Gimbal Developer Account (see image). The SDK will phone home and get these settings from the backend. This certainly makes things easier.

Other things that have changed are the removal of the interfaces ProximityListener and VisitListener. There is now the introduction of new classes that can be extended to provide callback mechanisms for Entries, Exits, and beacon sightings. These classes are PlaceEventListener and BeaconEventListener. They are not interfaces that require implementation but rather abstract classes.

Below is the updated helper class which is implemented as a singleton. Please compare this to the code from the previous article.

Implementing the new PlaceEventListener

The new PlaceEventListener abstract class must be implemented to provide the onEntry and onExit callback methods. This will be triggered when a Place is entered or exited (previously called arrivals and departures). Below is the implementation of the PlaceEventListener.

Implementing the new BeaconEventListener

The new BeaconEventListener abstract class must be implemented to provide the onBeaconSighting callback method. This will be triggered when a beacon is sighted (within detectable range). Below is the implementation of the BeaconEventListener.


This article focused on the changes made to the new Gimbal SDK v2.x Beta for Android. Along with the knowledge from the previous article, the Gimbal Helper class was updated and the new event listeners were implemented. The new SDK is easier to use with the concept of Places which is a welcome abstraction. The changes made to the Gimbal Developer Account make it easy to set options which were previously defined in a custom method.  With this new knowledge updating to the v2.x Beta SDK should be easier to perform. As always, if any help is desired please post in the comments section below. Happy Gimbaling.

Daniel Eagle

Currently residing in the Austin area, Daniel Eagle is an avid gamer, writer, technology/science enthusiast, software developer, and educator. He takes great pride in spreading knowledge and helping others.

More Posts - Website

Follow Me: