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.

Limit Frequency

Selecting 'Yes' in the 'Limit Frequency' drop-down displays additional options for setting the frequency interval.

Only Deliver Once Every

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 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.

Add Google/Firebase Server API Key to Gimbal Manager

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.

Add Google/Firebase Sender ID to Gimbal Enabled Application

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.

Description

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.

Sample

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.

Sample

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.

Receive Push Content

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
}

Description

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.

Sample

import com.gimbal.android.Gimbal;
...
public static final String GIMBAL_APP_API_KEY = "## PASTE YOUR API KEY HERE ##";
...
        Gimbal.setApiKey(this.getApplication(), GIMBAL_APP_API_KEY);

Important Gimbal.setApiKey must be invoked from your Application class's onCreate() method. In the Sample App, this is done within the GimbalIntegration class, which is invoked from SampleApplication.onCreate(). If using GimbalIntegration as a template, simply paste your API key into the value of its GIMBAL_APP_API_KEY variable.

Description

Returns the Gimbal services state. It will return false if start was not called, or stop was called, on PlaceManager, CommunicationManager and EstablishedLocationsManager

Sample

import com.gimbal.android.Gimbal;
...
        Gimbal.isStarted();

Description

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.

Sample

import com.gimbal.android.Gimbal;
...
        Gimbal.start();

Description

Stops all the Gimbal services. Its a method for stoping the PlaceManager, CommunicationManager and EstablishedLocationsManager.

Sample

import com.gimbal.android.Gimbal;
...
        Gimbal.stop();

Description

Check if place monitoring has started

Sample

import com.gimbal.android.PlaceManager;
...
        PlaceManager.getInstance().isMonitoring();

Description

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.

Sample

import com.gimbal.android.PlaceManager;
...
        PlaceManager.getInstance().startMonitoring();

Description

Stops the generation of events based on the users location and proximity to geofences and beacons.

Sample

import com.gimbal.android.PlaceManager;
...
        PlaceManager.getInstance().stopMonitoring();

Description

The following gets visits for places that you are currently AT. The array returned is ordered ascending by arrival date.

Sample

import com.gimbal.android.PlaceManager;
...
        PlaceManager.getInstance().currentVisits();

Description

This is the listener for place event notifications. One of the following methods will be invoked based on the place event.

Place Event Methods

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.
    }

Visit Accessor Methods

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

Place Accessor Methods

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

Beacon Sighting Accessor Methods

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

Description

Create and implement the PlaceEventListener interface. Add the PlaceEventListener to the PlaceManager instance.

Sample

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.

Description

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.

Communication Methods

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 the Notification presented to the user. To do so, return a custom Notification.Builder from
        // from this method. The SDK will use a default implementation if null is returned.
        // Note that you will need to set the Notification Channel on this builder when running on an Android 8.0 or
        // later device when your app targets API 26.
        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 the Notification presented to the user. To do so, return a custom Notification.Builder from
        // from this method. The SDK will use a default implementation if null is returned.
        // Note that you will need to set the Notification Channel on this builder when running on an Android 8.0 or
        // later device when your app targets API 26.
        return null;
    }

Communication Accessor Methods

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

Visit Accessor Methods

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

Place Accessor Methods

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

Attributes Interface

Method	Description
getAllKeys()	returns all the keys as type List<String>
getValue(String key)	returns the value of the key as type String

Description

Create and implement the CommunicationListener interface. Add the CommunicationListener to the CommunicationManager instance

Sample

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.

Description

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.

Sample

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.

Description

Stops beacon listening. No beacons will be sighted.

Sample

import com.gimbal.android.BeaconManager;
...
        BeaconManager manager = new BeaconManager()
        manager.stopListening();

Description

This is the listener for beacon sightings. The following method will be invoked upon beacon sighting.

Beacon Method

import com.gimbal.android.BeaconEventListener;
import com.gimbal.android.BeaconSighting;
...
    public void onBeaconSighting(BeaconSighting sighting) {
        // This will be invoked upon beacon sighting
    }

BeaconSighting Accessor Methods

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

Beacon Accessor Methods

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.

Description

Create and implement the BeaconEventListener interface. Add the BeaconEventListener to the BeaconManager instance

Sample

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);

Description

Check if established locations has been enabled.

Sample

import com.gimbal.android.EstablishedLocationsManager;
...
        EstablishedLocationsManager.getInstance().isMonitoring();

Description

Enables the passive collection of Established Locations.

Sample

import com.gimbal.android.EstablishedLocationsManager;
...
        EstablishedLocationsManager.getInstance().startMonitoring();

Description

Disables the passive collection of Established Locations.

Sample

import com.gimbal.android.EstablishedLocationsManager;
...
        EstablishedLocationsManager.getInstance().stopMonitoring();

Description

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.

Sample

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());
        }

Established Location Accessor Methods

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

Circle Accessor Methods

A geographical circle.

Method	Description
getCenter()	returns the Coordinate representing the center of the Circle
getRadius()	returns the radius of the Circle, in meters

Coordinate Accessor Methods

The Coordinate class represents a latitude and longitude.

Method	Description
getLatitude()	returns the latitude of the Coordinate
getLongitude()	returns the longitude of the Coordinate

Important Only use this API if you intend to reset the Application Instance Identifier for this SDK instance. Normally this is not required.

Description

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.

Sample

import com.gimbal.android.Gimbal;
...
        Gimbal.resetApplicationInstanceIdentifier();

Description

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 in order to avoid any unexpected behaviour or crash. Gimbal SDK is not responsible for requesting permissions runtime. Learn more about Requesting Permissions at Run Time.

Important Applications using the Gimbal SDK must implement the runtime permissions checks in their application if their targetSdkVersion is 23 or above. The Gimbal SDK will not request runtime permissions.

Note Gimbal uses the android.permission.ACCESS_FINE_LOCATION "dangerous" permission for location services and sighting beacons. This permission is merged by default into your application's manifest from the SDK AAR manifest. If location services are not required for your use of the Gimbal SDK, it is possible to operate with just beacon sighting with the android.permission.ACCESS_COARSE_LOCATION "dangerous" permission.

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();

Runtime Permissions Checks

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.

Checking for permissions

        // 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.

Requesting for permissions

        ActivityCompat.requestPermissions(thisActivity, new String[] { Manifest.permission.ACCESS_FINE_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.

Rationale for the permissions usage

        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.

What will happen if permissions is revoked while application is in background?

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.

Description

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.

Sample

        GimbalDebugger.enableBeaconSightingsLogging();

Description

Disables beacon sighting logs

Sample

        GimbalDebugger.disableBeaconSightingsLogging();

Description

Checks if sightings logging is enabled

Sample

        GimbalDebugger.isBeaconSightingsLoggingEnabled();