If you haven't done it yet be sure to check out the Android Quick Start Guide to get the SDK installed and running Android Quick Start »
The Gimbal Proximity platform enables proximity services within your application. This guide will provide examples for each of the available functions in our Android SDK for Gimbal Proximity.
This call sets up the SDK with the application ID and Secret. When you register an application on the Developer Portal the ID and Secret are generated and supplied to you.
import com.gimbal.proximity.Proximity;
...
Proximity.initialize(yourApplicationContext,
"your-application-id",
"your-application-secret");
This call registers the application with the server and starts bluetooth scanning.
import com.gimbal.proximity.Proximity;
...
Proximity.startService(yourServiceCallback);
Note You must implement the ProximityListener
interface.
Once the service start has been attempted by calling startService above, one of the
following methods will be invoked on your delegate object to indicate the status of the service.
import com.gimbal.proximity.ProximityListener;
...
void serviceStarted()
{
// this will be invoked if the service has successfully started
// bluetooth scanning will be started at this point
}
import com.gimbal.proximity.ProximityListener;
...
void serviceFailed(int errorCode, String message)
{
// this will be called if the service has failed to start
}
This call will stop bluetooth scanning.
import com.gimbal.proximity.Proximity;
...
Proximity.stopService();
Important The SDK will no longer function properly until you call startService again.
This call creates a VisitManager object and will trigger the listeners to your
VisitListener implementation using the default options. Using this call you will be notified of
visit arrivals, sightings, and departures of proximity devices that are registered to the application developer
import com.gimbal.proximity.VisitManager;
import com.gimbal.proximity.Visit;
import com.gimbal.proximity.VisitListener;
...
VisitManager visitManager = ProximityFactory.getInstance().createVisitManager();
visitManager.setVisitListener(yourVisitListener);
visitManager.start();
Note Be sure to implement the Visit Listener interface.
This call creates a VisitManager object and will trigger the listeners to your
VisitListener implementation using the provided options. Using this call you will be notified of
visit arrivals, sightings, and departures of proximity devices that are registered to the application developer.
| Option Key | Description | Data Type | Default |
|---|---|---|---|
| VisitOptionSignalStrengthWindowKey | Smoothing of signal strengths using historic sliding window averaging | int | VisitOptionSignalStrengthWindowLarge |
| VisitOptionForegroundDepartureIntervalInSecondsKey | Number of seconds before the absence of a beacon triggers the didDepart
callback
|
Integer | 10 seconds |
| VisitOptionBackgroundDepartureIntervalInSecondsKey | Number of seconds before the absence of a beacon triggers the didDepart
callback
|
Integer | 300 seconds |
| VisitOptionArrivalRSSIKey | An RSSI value of the beacon sighting that must be exceeded before a didArrive
callback is triggered
|
Integer | None |
| VisitOptionDepartureRSSIKey | If an RSSI value of the beacon sightings is less than this value and the departure interval
is exceeded a didDepart callback is triggered
|
Integer | None |
import com.gimbal.proximity.VisitManager;
import com.gimbal.proximity.Visit;
import com.gimbal.proximity.VisitListener;
import com.gimbal.proximity.ProximityOptions;
...
ProximityOptions options = new ProximityOptions();
options.setOption(ProximityOptions.VisitOptionSignalStrengthWindowKey,
ProximityOptions.VisitOptionSignalStrengthWindowNone);
options.setOption(ProximityOptions.VisitOptionForegroundDepartureIntervalInSecondsKey,
5);
options.setOption(ProximityOptions.VisitOptionBackgroundDepartureIntervalInSecondsKey,
5);
options.setOption(ProximityOptions.VisitOptionArrivalRSSIKey,
-75);
options.setOption(ProximityOptions.VisitOptionDepartureRSSIKey,
-90);
VisitManager visitManager = visitManager = ProximityFactory.getInstance().createVisitManager();
visitManager.setVisitListener(yourVisitListener);
visitManager.start();
visitManager.startWithOptions(options);
Note Be sure to implement the VisitListener interface in your class.
This is the listener for visit notifications.
The following listeners will be invoked when a visit event occurs.
import com.gimbal.proximity.VisitListener;
...
public void didDepart(Visit visit) {
// This will be invoked when a visit starts
}
public void receivedSighting(Visit visit, Date updateTime, Integer RSSI) {
// This will be invoked when a sighting comes in during a visit
}
void didDepart(ProximityVisit visit) {
// This will be invoked when a visit ends
}
| Property Name | Description |
|---|---|
| transmitter | Transmitter being sighted |
| startTime | Time at which the visit starts |
| lastUpdateTime | Last time which the trasmitter was sighted |
| dwellTime | Time interval between the visit start time and the last update time |
This call stops the callbacks to the delegate for visits.
import com.gimbal.proximity.VisitManager;
...
visitManager.stop();
This interface provides the following Gimbal Proximity application information.
ProximityAppInfo Methods| Property | Description |
|---|---|
| getReceiverId | The unique identifier for this receiver application. Null if the receiver has not registered yet. |
import com.gimbal.proximity.Proximity;
import com.gimbal.proximity.ProximityAppInfo;
...
ProximityAppInfo appInfo = Proximity.currentAppInfo();
String receiverId = appInfo.getReceiverId();
The SDK behaviour will change based on the supplied Application object. The SDK will determine based on the supplied Application instance whether the application is in foreground or background and change the bluetooth scanning interval. It will scan more frequently in the foreground than in background
import com.gimbal.proximity.Proximity
...
Proximity.optimizeWithApplicationLifecycle(yourApplicationInstance);
Set the logging level for the Gimbal Proximity SDK. The available levels are DEBUG, INFO, WARN, ERROR, ASSERT. The default logging level is ERROR.
import com.gimbal.logging.GimbalLogConfig;
import com.gimbal.logging.GimbalLogLevel;
...
GimbalLogConfig.setLogLevel(GimbalLogLevel.DEBUG);
Turn on file logging for SDK log calls. File logging is enabled by default and requires the device has an sdcard.
To view the logs:
Open a terminal
Make sure 'adb' is in your current sessions library path
Type the following command: adb pull /<path-to-phones-sdcard>/com.gimbal.proximity/proximity.log <destination-of-log-file>
import com.gimbal.logging.GimbalLogConfig;
import com.gimbal.logging.GimbalLogLevel;
...
GimbalLogConfig.enableFileLogging(yourApplicationContext);
Turn off file logging for SDK log calls. File logging is enabled by default.
import com.gimbal.logging.GimbalLogConfig;
import com.gimbal.logging.GimbalLogLevel;
...
GimbalLogConfig.disableFileLogging();