Gimbal SDK V3 for Android is here! If your app currently uses Gimbal SDK V2, you will need to migrate to V3 in order for it to operate properly on Android 8.0 devices. Please refer to our V2 to V3 Migration Guide for details.
Go to the Gimbal Manager and sign up to create a new account.
The following steps will guide you through setting up a new application. As part of the Gimbal SDK download, we include a sample app which demonstrates all the basic SDK features such as place and communication events.
While we prefer Gimbal to be intergrated into an application built in Android Studio, our SDK can still be used with applications built in Eclipse. Included in this guide are instructions for getting Gimbal up and running in your app for both development tools.
Note To get started quickly and easily, please visit the Android Studio Quickstart »
The Quickstart provides a link for a sample application built with Android Studio and automatically creates the necessary Gimbal Application for Android.
In Android Studio under Quickstart choose "Start a new Android Studio Project"
Fill out your "Application Name", "Company Domain", and "Project location" fields.
Important The "Minimum SDK" should be set to at least API 14. Finish up by adding and customizing the appropriate activity for your app and press "Finish".
Add Maven Central to the repositories section of your application's build.gradle file.
repositories {
...
mavenCentral()
...
}
Add the following artifacts from Maven Central Repository to the dependencies section of your application's build.gradle file.
dependencies {
...
compile 'org.slf4j:slf4j-api:1.7.13'
compile group: 'com.gimbal.android.v2', name: 'gimbal-sdk', version: '+'
compile group: 'com.gimbal.android.v2', name: 'gimbal-slf4j-impl', version: '+'
...
}
Note You can exclude the gimbal-slf4j-impl artifact if your project already includes a slf4j-api implementation library (i.e slf4j-log4j12).
Add these aars to your project
Note You will find these aars in the ibs folder inside the Gimbal SDK zip file.
Add AARs to your Android application by copy and pasting them into the libs folder of your android project. After adding them, add the following lines to your build.gradle file.
repositories {
flatDir {
dirs 'libs'
}
}
dependencies {
...
compile 'org.slf4j:slf4j-api:1.7.13'
compile(name:'gimbal', ext:'aar')
compile(name:'gimbal-slf4j-impl', ext:'aar')
...
}
Your project should now look similar to this.
Note A dependency was added to the slf4j-api library in addition to our library files.
To allow Gimbal Services to function, you need to add a few elements to your AndroidManifest.xml file.
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
<uses-permission android:name="android.permission.WAKE_LOCK" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED" />
<uses-permission android:name="android.permission.BLUETOOTH" />
<uses-permission android:name="android.permission.BLUETOOTH_ADMIN" />
To allow for Gimbal Services to run in the background, you will need to add two services and a receiver entry to your manifest file
Important Please replace the "com.gimbal.android.sample" in the first service intent filter with your app package name as appropriate - but leave the ".service.GIMBAL_SERVICE" at the end. Gimbal will create the name at runtime to start it's service and it's important that the name that it generates matches the name in the manifest
<service
android:name="com.gimbal.internal.service.GimbalService"
android:exported="false" >
<intent-filter>
<action android:name="com.gimbal.android.sample.service.GIMBAL_SERVICE" />
</intent-filter>
</service>
<receiver
android:name="com.gimbal.internal.service.GimbalServiceStartStopReceiver"
android:enabled="true" >
<intent-filter>
<action android:name="android.intent.action.BOOT_COMPLETED" />
</intent-filter>
<intent-filter>
<action android:name="android.intent.action.ACTION_SHUTDOWN" />
</intent-filter>
</receiver>
<service
android:name="com.gimbal.android.jobs.JobManagerService"
android:exported="false" >
<intent-filter>
<action android:name="com.gimbal.android.jobs.WakeupJob" />
</intent-filter>
</service>
Because the Gimbal Service runs in the background, it will generate place events and communicates even when the user isn't using the app.
Important For your app to respond to those events, it needs listeners that are active whenever Gimbal might detect an event. If you have a PlaceEventListener or a CommunicationListener, you should initialize your listeners (and hold a reference to them) in the onCreate() method of your Application class. You will also need to specify this class in the "android:name="..." property of your Application in the manifest file.
The sample app that's included with the Gimbal SDK includes a SampleApplication class that you can use for reference and a manifest that shows how to specify that SampleApplication so that it gets initialized whenever the app starts.
If you will be using ProGuard to shrink your APK, add these rules to your proguard-project.txt file in Eclipse
-keep public interface com.gimbal.proguard.Keep { }
-keep public class ** implements com.gimbal.proguard.Keep { *; }
-keep public class **.protocol.** { public protected *; }
-keepattributes Signature
-keep public class org.codehaus.jackson..** { public protected *; }
-dontwarn org.codehaus.**,com.fasterxml.**,org.simpleframework.**,com.google.**,org.apache.**
If you forget to do this initially, LogCat will show warnings once you turn ProGuard on. You must add this configuration before Gimbal will work correctly when you are using ProGuard
Create Your Gimbal Application in the Gimbal Manager.
You will be presented with a form where you will enter the following information: Name of your app, Platform (android), App category, Package name. Enter the package name you set in your Eclipse New Application. You will also need to select option for Android 4.4.3 and 4.4.4 (Kitkat support).
Important If you are testing with an Android device with version 4.4.3 or 4.4.4, you must allow for Kitkat support when using proximity features.
Hit the Generate button. Once finished, your app will have a Gimbal API Key.
Important You will need to set the API Key in your Android app.
You will be presented with a form where you will enter information about your Place. A Place represents both Geofence and Proximity. For example, a place can be represented by a geofence (circular or polygonal) or a series of beacons.
Please enter your Place information. For example, you can enter a Place name and enter your activated beacon(s). You can always update your Place by adding a Geofence or add/delete your beacons.
Note This is where you would enter the Place(s) where you will look for Place Events in your app.
You will be presented with a form where you will enter information about your communication. For example a Communication can be entered for a place and when an app enters the specified place, a notification will be received. Please select 'Save & Publish' to activate your communication.
There are a number of application settings that you can configure. These can can be found by clicking on the Application’s Bundle ID / Package Name within Gimbal Manager.
The following settings control how place events are triggered. Note: any of the similar settings you set for a Place take precedence over these app-wide settings.
The 'Arrival RSSI' setting allows you to specify a specific RSSI (signal strength) to be used in determining if a beacon sighting should be processed as an arrival to a beacon. Signals weaker than 'Arrival RSSI' will be ignored.
Default = null, such that whenever a beacon is first detected it will cause a sighting and an arrival.
You may wish to modify this value if you wish to decrease the range of when a beacon trigger an arrival.
The 'Departure RSSI' setting allows you to specify a specific RSSI (signal strength) to be used in determining if a beacon sighting should be processed as a departure. Signals weaker than 'Departure RSSI' will be ignored.
Note that the Departure RSSI must be at least 10dBm lower than the 'Arrival RSSI'. This is done to avoid excessive bouncing (where arrival and departures events are triggered repeatedly, even when both the mobile device and beacon are standing still).
The ‘Departure interval’ is the number of seconds that must elapse where the SDK does not see a beacon RSSI level stronger than the Departure RSSI before processing the departure.
The smoothing algorithm processes RSSI signal strengths from sightings to make them less jumpy. The larger the smoothing window the more steady the output RSSI readings will be.
This setting allows you to enable beacon support on Android 4.4.3 and 4.4.4 devices. Please note, these versions of Android have known performance issues. Learn more
These settings allow you to turn specific features on/off.
Allows you to turn on/off geofencing monitoring.
This may be desired if your application only uses beacon-based places.
Allows you to turn off beacon monitoring. This will affect both beacon-based Place detection and beacon detection.
This may be useful if your application only uses geofence-based places.
Allows you to turn on/off Communicate delivery.
This may be useful if your application does not use the Communicate feature.
Allows you to turn on/off whether Gimbal records the device advertising identifier and limit ad tracking state for devices. Turning this on is necessary if you wish to correlate your advertising data with the data collected by the Gimbal SDK. This functionality is off by default. Your application must include the Google Play Services to use this feature.
Note For privacy reasons, when a device's advertising identifier is reset, the device is re-registered with Gimbal and receives a new application instance identifier.
The configuration for communication limit frequency can be found in the 'Communicate' tab then the 'Triggers' section in Gimbal Manager.
The following settings are used to limit frequency when triggering communications for place events.
Selecting 'Yes' in the 'Limit Frequency' drop-down displays additional options for setting the frequency interval.
The 'Only Deliver Once Every' setting allows you to specify the value in hours, days or weeks for the communication frequency. Please note, one day specifies a 24hr period. One week specifies a 168hr period. For example, if the frequency limit is set for one day, then a user who initially receives a communication at 4pm won't get that same communication until after that 24hr period, no matter how often the user comes back in and out of the triggering place.
Important
If your CommunicationListener implements presentNotificationForCommunications, you MUST handle frequency limit and delay (dwell) yourself.
The configuration for communication delay can be found in the 'Communicate' tab under the 'Triggers' section in Gimbal Manager.
Setting delay on a communication allows the communication to be delivered with some delay after a person has entered or exited a place. If a communication is scheduled to be delivered with some delay after a person has entered a place and the person exits that place before the communication is delivered, then the communication will be canceled. Similarly, if a communication is scheduled to be delivered some time after a person leaves a place and that person re-enters the place, the communication will be canceled.
Keep in mind that if delay causes a communication to be scheduled after the expiry date of the communication, it will not be delivered.
Important
If your CommunicationListener implements presentNotificationForCommunications, frequency limit and delay (dwell) are honored only for communications returned by that method to the Gimbal SDK. Only use presentNotificationForCommunications if you want to handle scheduling and delivery of communications yourself.
Gimbal allows you to send instant (push) communications using Google/Firebase Cloud Messaging (GCM/FCM).
Gimbal uses Google/Firebase Cloud Messaging (GCM/FCM) for enabling push on Android. In order to use GCM/FCM you'll have to setup your application on Firebase Console and obtain a GCM/FCM Sender ID and the Server key for the GCM/FCM Service.Please refer to Firebase Cloud Messaging and follow the steps to create a new FCM project to obtain these keys. Here's an overview of the steps you'll have to follow:
From Firebase Console
Note Before moving forward make sure that you have obtained the Server key and Sender ID from Firebase Console.
On Gimbal Manager, select your existing Android application and scroll down to the Google/Firebase Cloud Messaging Key section to setup Android push. Enter the Server API Key (created from Firebase Console) and hit save. Now your application is set to send push messages.
In your application, add the Sender ID to the registerForPush method.
For details on how to register your app to receive push messages, look at section Register For Push.
Google Play service is used on the client to enable receiving push messages. Please follow the directions from Google for Setting Up Google Play Services.
Edit your application's AndroidManifest.xml file and add the following declaration within the <application> element. This embeds the version of Google Play services that the app was compiled with.
<meta-data
android:name="com.google.android.gms.version"
android:value="@integer/google_play_services_version" />
Also add the following permission to allow Google to send push messages to your application.
<!-- FOR PUSH -->
<uses-permission android:name="com.google.android.c2dm.permission.RECEIVE" />
There are two ways to register with GCM/FCM to send messages to your app.
The first method is by using the Sender ID (generated from creating the Firebase project) to register for Push.
import com.gimbal.android.Gimbal;
...
Gimbal.registerForPush("## PLACE YOUR Sender ID # HERE ##");
The second method is by using the Registration Token (obtained from calling the GoogleCloudMessaging register method) to register for Push.
import com.gimbal.android.Gimbal;
...
Gimbal.setPushRegistrationToken("## PLACE YOUR Google Messaging Registration Token # HERE ##");
Note If both methods are used within the same application, only the last method is used to register for Push.
Whenever a push is sent to the client, Gimbal will call the CommunicationListener methodshouldPresentNotificationForCommunications. Your application can now decide whether or not to raise a notification to the User or allow the Gimbal SDK to raise the notification on your behalf.
public Collection<Communication> presentNotificationForCommunications(Collection<Communication> communications, Push push) {
// This will be invoked when there is a Push based communication. The communications
// returned from this method will be presented as a Notification (collapsed notifications if more than one)
// on behalf of the developer before applying frequency limit and delay.
return filteredCommunications
}
Instant Pushes are pushes that are sent immediately. To send instant pushes, go to the Communicate tab on Gimbal Manager, and click on + New.
On the resulting Communication Detail page, fill in an identifying name for your Communication. Select "TIME TRIGGERED: NOW (INSTANT)" in the Triggering Event dropdown box. The Start Date and End Date entries will disappear.
Fill in the details of your push message and click on Save & Publish to send your Instant Communication to your device.
Time Triggered Push Notifications are Push Notifications that are sent at a specified time. To send instant pushes, go to the Communicate tab on Gimbal Manager, and click on + New.
On the resulting Communication Detail page, fill in an identifying name for your Communication. Select "TIME TRIGGERED: SPECIFIC TIME" in the Triggering Event dropdown box. Enter a start and end date, and any time filters as needed.
This call sets the API key for your Gimbal application. When you register an application on the Developer Portal the API key is generated and supplied to you.
This was done in the previous section Create Gimbal Application.
import com.gimbal.android.Gimbal;
...
Gimbal.setApiKey(this.getApplication(), "## PLACE YOUR API KEY HERE ##");
Note You can add this code in the onCreate method in your MainActivity source file or in your Service class if providing your own custom implementation of Gimbal to run in background state. Be sure to insert your API Key here.
The Gimbal defines the interface for starting all the services like PlaceManager, CommunicationManager and EstablishedLocationsManager, stopping the services and finding the status.
Returns the Gimbal services state. It will return false if start was not called, or stop was called, on PlaceManager, CommunicationManager and EstablishedLocationsManager
import com.gimbal.android.Gimbal;
...
Gimbal.isStarted();
Starts all the Gimbal services which includes the generation of events based on the users location and proximity to geofences and beacons, receive communications associated to place entry and exit events and generation of established locations based on the users locations. Its a method for starting the PlaceManager, CommunicationManager and EstablishedLocationsManager. These features can also be controlled server side anytime for a specific application using advanced configuration at Gimbal Manager.
import com.gimbal.android.Gimbal;
...
Gimbal.start();
Stops all the Gimbal services. Its a method for stoping the PlaceManager, CommunicationManager and EstablishedLocationsManager.
import com.gimbal.android.Gimbal;
...
Gimbal.stop();
The PlaceManager defines the interface for delivering place entry and exits events to your Gimbal SDK enabled application. You use this class to start or stop place monitoring and to check whether monitoring is enabled.
Check if place monitoring has started
import com.gimbal.android.PlaceManager;
...
PlaceManager.getInstance().isMonitoring();
Starts the generation of events based on the users location and proximity to geofences and beacons.
Important Please check the following section if you are targetting android SDK 23 and above for runtime permissions checks.
import com.gimbal.android.PlaceManager;
...
PlaceManager.getInstance().startMonitoring();
Stops the generation of events based on the users location and proximity to geofences and beacons.
import com.gimbal.android.PlaceManager;
...
PlaceManager.getInstance().stopMonitoring();
The following gets visits for places that you are currently AT. The array returned is ordered ascending by arrival date.
import com.gimbal.android.PlaceManager;
...
PlaceManager.getInstance().currentVisits();
This is the listener for place event notifications. One of the following methods will be invoked based on the place event.
import com.gimbal.android.PlaceEventListener;
import com.gimbal.android.Place;
import com.gimbal.android.Visit;
...
public void onVisitStart(Visit visit) {
// This will be invoked when a place is entered
}
public void onVisitStartWithDelay(Visit visit, int delayTimeInSeconds) {
// This will be invoked when the user entered the specified place and remained at the specified place with out
// exiting for the delay time period assigned to the place in manager.gimbal.com. Places with no assigned delay
// will invoke the method immediately upon entry.
}
public void onVisitEnd(Visit visit) {
// This will be invoked when a place is exited
}
public void onBeaconSighting(BeaconSighting sighting, List<Visit> visits) {
// This will be invoked when a beacon assigned to a place within a current visit is sighted.
}
public void locationDetected(Location location) {
// This will be invoked when Gimbal has detected a reliable location.
}
The Vist class defines the period of time which a User dwelled at a place. A Visit without a departure time represents an active visit where the User is still dwelling at a place.
| Method | Description |
|---|---|
| getPlace() | returns the place the visit is associated to |
| getArrivalTimeInMillis() | returns time in milliseconds at which the User arrived at a Place |
| getDepartureTimeInMillis() | returns time in milliseconds at which the User was considered to be departed from a Place |
| getDwellTimeInMillis() | returns dwell time in milliseconds |
The Place class defines a place which is represented by a geofence (circular or polygonal) or a series of beacons. A place is defined in the Gimbal Manager portal.
| Method | Description |
|---|---|
| getIdentifier() | return the unique identifier for this place |
| getName() | returns the name assigned to this place |
| getAttributes() | returns the attributes of this place |
The Place class defines a BeaconSighting which is represented by a sighting information of a beacon.
| Method | Description |
|---|---|
| getRSSI() | return the rssi value for the beacon sighted |
| getTimeInMillis() | returns the beacon sighting date i milliseconds |
| getBeacon() | returns beacon object with beacon attributes |
Create and implement the PlaceEventListener interface. Add the PlaceEventListener to the PlaceManager instance.
import com.gimbal.android.PlaceManager;
import com.gimbal.android.PlaceEventListener;
...
private PlaceEventListener placeEventListener;
...
placeEventListener = new PlaceEventListener(){
// Add PlaceEventListener methods here
}
...
PlaceManager.getInstance().addListener(placeEventListener);
Note PlaceEventListener methods are implemented by default. To customize, please provide your own implementation for the desired PlaceEventListener methods.
The CommunicationManager defines the interface for delivering communications to your Gimbal SDK enabled application. You use this class to start or stop receiving communications.
Enables the SDK to receive communications.
import com.gimbal.android.CommunicationManager;
...
CommunicationManager.getInstance().startReceivingCommunications();
Stops all communication delivery. This includes both local and instant(push) communications.
import com.gimbal.android.CommunicationManager;
...
CommunicationManager.getInstance().stopReceivingCommunications();
This is the listener for communications. One of the following methods will be invoked based on the communication event.
Important Gimbal does not support posting Notifications for versions below 3.0 for Visits & Instant Communications. Developers must override one or more of the following methods in CommunicationListener and post notifications.
import com.gimbal.android.CommunicationListener;
import com.gimbal.android.Communication;
import com.gimbal.android.Place;
...
public Collection<Communication> presentNotificationForCommunications(Collection<Communication> communications, Visit visit) {
// This will be invoked when there is a communication associated with a Place Entry or Exit. The communications
// returned from this method will be presented as a Notification (collapsed notifications if more than one)
// on behalf of the developer after applying any frequency limit and delay.
// If you implement this method to filter communications, you MUST handle frequency limiting and delay yourself.
return filteredCommunications;
}
public Collection<Communication> presentNotificationForCommunications(Collection<Communication> communications, Push push) {
// This will be invoked when there is a Push based communication. The communications
// returned from this method will be presented as a Notification (collapsed notifications if more than one)
// on behalf of the developer after applying any frequency limit and delay.
// If you implement this method to filter communications, you MUST handle frequency limiting and delay yourself.
return filteredCommunications
}
public void onNotificationClicked(List<Communication> communications) {
// This method will be invoked when a user has clicked on a presented notification. The first Communication in the list is the
//notification visible to the end user and the rest were collapsed.
}
public Notification.Builder prepareCommunicationForDisplay(Communication communication, Visit visit, int notificationId) {
// This method will be invoked when a communicate is received for place event. The caller is given a chance to customize
// this notification. Caller should return a customized Notification.Builder so that the SDK uses this for notification.
// sdk will use the default implementation if null is returned from this method
return null;
}
public Notification.Builder prepareCommunicationForDisplay(Communication communication, Push push, int notificationId) {
// This method will be invoked when a communicate is received for push. The caller is given a chance to customize
// this notification. Caller should return a customized Notification.Builder so that the SDK uses this for notification.
// sdk will use the default implementation if null is returned from this method.
return null;
}
A Communication is defined in the Gimbal Manager portal.
| Method | Description |
|---|---|
| getAttributes() | returns the attributes of this communication |
| getDescription() | returns the description for this communication |
| getIdentifier() | returns the identifier for this communication |
| getExpiryTimeInMillis() | returns the expiration time for this communication |
| getTitle() | returns the title for this communication |
| getURL() | returns the url for this communication |
| getDeliveryDate() | returns the delivery date for this communication |
The Vist class defines the period of time which a User dwelled at a place. A Visit without a departure time represents an active visit where the User is still dwelling at a place.
| Method | Description |
|---|---|
| getPlace() | returns the place the visit is associated to |
| getArrivalTimeInMillis() | returns time in milliseconds at which the User arrived at a Place |
| getDepartureTimeInMillis() | returns time in milliseconds at which the User was considered to be departed from a Place |
| getDwellTimeInMillis() | returns dwell time in milliseconds |
| getVisitID | returns unique ID for visit |
The Place class defines a place which is represented by a geofence (circular or polygonal) or a series of beacons. A place is defined in the Gimbal Manager portal.
| Method | Description |
|---|---|
| getIdentifier() | return the unique identifier for this place as type String |
| getName() | returns the name assigned to this place as type String |
| getAttributes() | returns the attributes of this place as type Attributes |
| Method | Description |
|---|---|
| getAllKeys() | returns all the keys as type List<String> |
| getValue(String key) | returns the value of the key as type String |
Create and implement the CommunicationListener interface. Add the CommunicationListener to the CommunicationManager instance
import com.gimbal.android.CommunicationManager;
import com.gimbal.android.CommunicationListener;
...
private CommunicationListener communicationListener;
...
communicationListener = new CommunicationListener(){
// Add CommunicationListener methods here
}
...
CommunicationManager.getInstance().addListener(communicationListener);
Note CommunicationListener interface and methods are implemented by default. To customize (ie: by receving event callbacks), please provide your own implementation for the desired communication listener methods.
The BeaconManager defines the interface for delivering beacon sightings to your Gimbal SDK enabled application. You use this class to start or stop listening for beacon sightings.
Allows the BeaconManager to start listening for beacon sightings.
Important Please check the following section if you are targetting android SDK 23 and above for runtime permissions checks.
import com.gimbal.android.BeaconManager;
...
BeaconManager manager = new BeaconManager()
manager.startListening();
Note PlaceManager and BeaconManager works independently of each other. For example, to just get place events, you'll need to start monitoring on PlaceManager only.
Stops beacon listening. No beacons will be sighted.
import com.gimbal.android.BeaconManager;
...
BeaconManager manager = new BeaconManager()
manager.stopListening();
This is the listener for beacon sightings. The following method will be invoked upon beacon sighting.
import com.gimbal.android.BeaconEventListener;
import com.gimbal.android.BeaconSighting;
...
public void onBeaconSighting(BeaconSighting sighting) {
// This will be invoked upon beacon sighting
}
A Beacon is activated in the Gimbal Manager portal.
| Method | Description |
|---|---|
| getRSSI() | returns the RSSI for the beacon sighted as type Integer |
| getTimeInMillis() | returns the time for the beacon sighted as type Long |
| getBeacon() | returns the beacon sighted as type Beacon |
| Method | Description |
|---|---|
| getIdentifier() | returns the unique identifier (factory ID) for this beacon as type String |
| getUuid() | returns the 32-character UUID for this beacon as type String. This value corresponds to the beacon ID returned by the Gimbal Manager. |
| getName() | returns the name assigned to the beacon as type String |
| getIconURL() | returns the url of the icon assigned to the beacon as type String |
| getBatteryLevel() | returns the battery level of the beacon as type Integer |
| getTemperature() | returns the temperature of the beacon in Farenheit as type Integer. The value will be Integer.MAX_VALUE if no temperature sensor is present on this beacon. |
Create and implement the BeaconEventListener interface. Add the BeaconEventListener to the BeaconManager instance
import com.gimbal.android.BeaconEventListener;
import com.gimbal.android.BeaconManager;
...
private BeaconEventListener beaconEventListener;
private BeaconManager beaconManager = new BeaconManager();
...
beaconEventListener = new BeaconEventListener(){
// add BeaconEventListener method here
}
...
beaconManager.addListener(beaconEventListener);
For information on default beacon configurations and how to assign and push a configuration, please refer to the link provided
The EstablishedLocations Manager defines the interface for enabling the Established Locations feature in the Gimbal SDK. Once enabled, Gimbal will passively monitor for locations commonly visited by the user. Each location inferred in this way is scored by a relevance value.
Check if established locations has been enabled.
import com.gimbal.android.EstablishedLocationsManager;
...
EstablishedLocationsManager.getInstance().isMonitoring();
Enables the passive collection of Established Locations.
import com.gimbal.android.EstablishedLocationsManager;
...
EstablishedLocationsManager.getInstance().startMonitoring();
Disables the passive collection of Established Locations.
import com.gimbal.android.EstablishedLocationsManager;
...
EstablishedLocationsManager.getInstance().stopMonitoring();
Retrieve the Established Locations inferred by the Gimbal SDK for the user. Each Established Location contains a boundary represented by a geographical Circle (with a center latitude/longitude and radius in meters). In addition, each location is accompanied by a score representing the relevance of the location to the user. A higher score value dictates higher relevancy.
import com.gimbal.android.EstablishedLocationsManager;
import com.gimbal.android.EstablishedLocation;
...
private EstablishedLocationsManager establishedLocationsManager;
...
establishedLocationsManager = EstablishedLocationsManager.getInstance();
...
for (EstablishedLocation establishedLocation : establishedLocationsManager.getEstablishedLocations()) {
Log.i("Established Location", establishedLocation.toString());
}
The EstablishedLocation class defines a commonly visited location of the user. It contains a relevancy score and a boundary defining the geographical features.
| Method | Description |
|---|---|
| getScore() | returns the score of the EstablishedLocation; a higher score value indicates that this location is more relevant to the user |
| getBoundary() | returns the Circle representing the boundary of the EstablishedLocation |
| toString() | returns the attributes of the EstablishedLocation and its boundary in a String |
A geographical circle.
| Method | Description |
|---|---|
| getCenter() | returns the Coordinate representing the center of the Circle |
| getRadius() | returns the radius of the Circle, in meters |
The Coordinate class represents a latitude and longitude.
| Method | Description |
|---|---|
| getLatitude() | returns the latitude of the Coordinate |
| getLongitude() | returns the longitude of the Coordinate |
Requires SDK 2.63+ The Device Attribute Manager allows you to associate attributes specific to the user of that individual device.
Attributes can be set by passing in a map to setDeviceAttributes:. The passed in map will replace existing attributes. Passing in null or an empty map will remove the attributes associated with specific device.
import com.gimbal.android.DeviceAttributesManager;
....
Map<String,String> attributes = new HashMap<String,String>();
attributes.put("key1","value1");
attribytes.put("key2","value2");
DeviceAttributesManager.getInstance().setDeviceAttributes(attributes);
The current attributes for a device can be retrieved through getDeviceAttributes.
import com.gimbal.android.DeviceAttributesManager;
....
Map<String,String> attributes = DeviceAttributesManager.getInstance().getDeviceAttributes();
Important Only use this API if you intend to reset the Application Instance Identifier for this SDK instance. Normally this is not required.
This call dissociate a device and data (place events) reported by the application running on that device. The open place sightings gets closed on server. Data on device also gets cleared due to this API invocation.
import com.gimbal.android.Gimbal;
...
Gimbal.resetApplicationInstanceIdentifier();
Runtime permissions are a new feature in Android 6.0 Marshmallow that allows you to request permissions at runtime, when it matters rather than at install time. Your application which uses Gimbal SDK need to integrate runtime permissions inorder to avoid any unexpected behaviour or crash. Learn how to request permissions from the user while the app is running here . Gimbal SDK is not responsible for requesting permissions runtime. Gimbal uses following permissions which requires it to be enabled during runtime for geofencing and beacon sighting.
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
Important Application developers of Gimbal have to implement the runtime permissions checks in their application if their targetSdkVersion is 23 and above. Gimbal SDK will not request runtime permissions.
The runtime permissions checks need to be made before making the startMonitoring call in PlaceManager. The PlaceManager defines the interface for delivering place entry and exits events to your Gimbal SDK enabled application and uses the location access.
import com.gimbal.android.PlaceManager;
...
//check runtime permissions
PlaceManager.getInstance().startMonitoring();
The runtime permissions checks need to be made before making the startListening call in BeaconManager. While the bluetooth permissions are enough to allow your legacy app to scan for beacons on Android 6.0, these permissions only allow it to do so in the foreground. Background scanning for bluetooth devices in Android 6.0, including beacons, now requires locations permission. Also, it is important to note that the location permission does not replace the need to request BLUETOOTH and BLUETOOTH_ADMIN permission
import com.gimbal.android.BeaconManager;
...
//check runtime permissions
BeaconManager manager = new BeaconManager()
manager.startListening();
Depending on where you are calling the Gimbal SDK api's specifically the above mentioned(place monitoring and beacon monitoring) you will have to add some extra code in your Activity to handle the runtime permissions. The Sample application which is packaged with the SDK has a helper class which shows you how to handle it, but here's some details on what apis are available and how to achieve it.
// Assume thisActivity is the current activity
ContextCompat.checkSelfPermission(thisActivity, Manifest.permission.ACCESS_FINE_LOCATION);
Make sure you use the above api to check the permissions are granted to you. If the permissions are already granted then you need not check anything else and go ahead and use the gimbal apis. If the permissions is not granted , you will have to go ahead and request it as below.
ActivityCompat.requestPermissions(thisActivity, new String[] { Manifest.permission.ACCESS_FINE_LOCATION,
Manifest.permission.ACCESS_COARSE_LOCATION }, MY_LOCATION_PERMISSION_REQUEST_CODE);
This is an asynchronous call and make sure the Activity is handling the onRequestPermissionsResult callback. If you want to give a rationale or explaination to the users about why you need these runtime permissions you could use another api to leverage it. We have to make sure the user is convinced that we need runtime permissions for Gimbal SDK to function correctly.
ActivityCompat.shouldShowRequestPermissionRationale(thisActivity, Manifest.permission.ACCESS_FINE_LOCATION))
This method returns true if the app has requested this permissions previously and the user denied the request. Show an explanation to the user asynchronously. Don't block this thread waiting for the user's response. After the user sees the explanation, try again to request the permissions.
Permissions can be revoked anytime through the phone's "Settings" application. When the Manifest.permission.ACCESS_FINE_LOCATION permission is revoked, PlaceManager will not be able to generate any place events in foreground or in the background. Whereas the BeaconManager will be able to generate events only when the application is in the foreground. Applications using Gimbal SDK should check for Manifest.permission.ACCESS_FINE_LOCATION permission when the application comes in the foreground and request for the permission to be granted and handle gracefully if the permissions are denied. Please follow "Permissions Best Practices" guide provided by Google here for more information.
Enables beacon sighting logs. These logs gives more information about beacon sightings your application is currently seeing. Use 'SIGHTINGS' keyword as a filter in your LOGCAT to see the relevant logs.
GimbalDebugger.enableBeaconSightingsLogging();
Disables beacon sighting logs
GimbalDebugger.disableBeaconSightingsLogging();
Checks if sightings logging is enabled
GimbalDebugger.isBeaconSightingsLoggingEnabled();
In Eclipse choose File > New > Project and search for "Android Application Project".
Fill out your "Application Name", "Project Name", and "Package Name" fields.
Important The "Minimum Required SDK" should be set to API 14, "Target SDK" and "Compile With" fields should be set to API 21 or higher. Then click through the rest of the "New Android Application" setup wizard.
Add the following artifacts from Maven Central Repository to the dependencies section of your application's POM file.
<dependencies>
...
<dependency>
<groupId>com.gimbal.android.v2</groupId>
<artifactId>gimbal-sdk</artifactId>
<version>RELEASE</version>
</dependency>
<dependency>
<groupId>com.gimbal.android.v2</groupId>
<artifactId>gimbal-slf4j-impl</artifactId>
<version>RELEASE</version>
</dependency>
...
</dependencies>
Note You can exclude the gimbal-slf4j-impl artifact if your project already includes a slf4j-api implementation library (i.e slf4j-log4j12).
Add these jars to your project
Note You will find these jars in the gimbal-sampleapp/libs folder inside the Gimbal SDK zip file.
Add jars to your Android application by copy and pasting them into the libs folder of your android project.
Your project should now look similar to this. You may need to select 'File' then 'Refresh' in Eclipse to see the added jar files.
