Context Android Developer Guide

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 »

This document describes how to use the Gimbal APIs to develop Android applications that can benefit from contextual Services.


Using ContextCoreConnector

The ContextCoreConnector must be enabled prior to using any other Gimbal features.

All calls to the API will return failures with a disabled status message until this step is complete.


Obtain an Instance

First, you need to obtain an instance of ContextCoreConnector and enable it.

The first time it is enabled, it tries to register with the Gimbal server using your applications package name and API Key.


    private ContextCoreConnector contextCoreConnector; 
    
    @Override 
    public void onCreate(Bundle savedInstanceState) {
      super.onCreate(savedInstanceState);
      contextCoreConnector = ContextCoreConnectorFactory.get(this);
    }
    

Enable the connector

The enable() method is used to enable the SDK for use by the end user.


    contextCoreConnector.enable(this, new Callback() { 
      @Override
      public void success(Void responseObject) { 
        NSLog(@"Gimbal enabled");
      }

      @Override       
      public void failure(int statusCode, String errorMessage) {  
        NSLog(@"Failed to initialize gimbal %@", error);
      }
    });
    

Check Permission

The isPermissionEnabled() method allows your application to ensure that it has been previously enabled.


    if (contextCoreConnector.isPermissionEnabled()) { 
      startService();
      setupListeners(); 
    } 
    else{
      ContextCoreStatus status = contextCoreConnector.getStatus(); 
      toastAndLogError(status.getStatusMessage()); 
      enableCoreConnector(); 
    }
  

Notify the connector with the current activity

To allow Gimbal to optimize location detection and balance battery consumption based on users’ current interaction with your application, use the method setCurrentActivity() on ContextCoreConnector to notify Gimbal when the current activity changes.

In your onResume() call


    contextCoreConnector.setCurrentActivity(this); 
    

In your onPause() call


    contextCoreConnector.setCurrentActivity(null);   
    

Delete a User's Data and Disable Gimbal


    contextCoreConnector.deleteAllUserData(new Callback() { 
    
      @Override
      public void success(Void responseObject) {
        LOG.info("Delete User Data COMPLETE"); 
      } 
    
      @Override
      public void failure(int statusCode, String errorMessage) {
        LOG.info("Delete User Data FAILED"); 
      }
    });
    

Custom Opt-in and Privacy


Description

By default, when you enable the SDK using enable(), a Gimbal branded dialog containing the end user consent, privacy notice and terms of service will be presented to the end user.

However, you have the choice to display your own privacy notice and end user opt-in consent in lieu of the Gimbal branded dialog.

Important You will be bound by the "White Label Mode" terms within the Gimbal Developer Agreement.

Custom Opt-in Mode

To use this feature, simply add the property custom.opt.in.flow=true to usercontext.properties file.


Enable Debug Mode


Developer can use this option to enable debug mode which will add a debug user interface on the privacy panel. Debug panel will give you access to the following.

  • Visualize existing Place Events
  • Currenlty Monitored Geofences
  • Simulate Place Events
  • Important Please do not enable this in your production application.

    You will be able to use this feature by adding a property debug.panel=true to usercontext.properties file.


    Listening for geofence events

    Obtain an Instance

    
          contextPlaceConnector = ContextPlaceConnectorFactory.get(this);
        

    Start Listening

    
          PlaceEventListener placeEventListener = new PlaceEventListener() { 
            @Override 
            public void placeEvent(PlaceEvent placeEvent) { 
                // do something with the place event 
            } 
          }; 
          contextPlaceConnector.addPlaceEventListener(placeEventListener);
        

    The following fields are available in the PlaceEvent passed to the listener:

    Field Name Description
    placeType PLACE_TYPE_ORGANIZATION refers to places created in Context Console and applies to all of your users.
    PLACE_TYPE_PERSONAL is created locally on the phone and only applies to a single user.
    eventType PLACE_EVENT_TYPE_AT means that the user has arrived at the place
    PLACE_EVENT_TYPE_LEFT means that the user has just left the place.
    Place The Place object associated tot he event.
    Time The time of the event in milliseconds since 1970 (See System.currentTimeMillis())

    Stop Listening

    
          contextPlaceConnector.removePlaceEventListener(placeEventListener);
        

    Handling Leave Events

    We detect "AT" events more quickly than "Leave" events. The system needs sufficient evidence to promote a "Leave" event to be statistically accurate. False "Leave" events happen because location fixes on today’s smartphones tend to bounce around. (Open a map application on your phone and watch the blinking cursor bounce around.) We work to eliminate these inaccuracies to ensure your end-user does not receive multiple incorrect events.


    Enable Push on Client

    Register for Push

    Tell Gimbal that your application is interested in receivnig Push Notifications

    
          ContextPushNotificationsConnector.registerForRemoteNotification(context, SENDER_ID);
        

    Receiving Push

    In order to receive Push Content, create an instance of ContextCoreConnector and add an implementation of ContentListener to it. Whenever a push is sent to the client, Gimbal will call your application on ContentListener.contentEvent. Your application can now decide whether or not to raise a notification to the User. This is the same mechanism as listenting for content based on Place events.

                    
        ContextCoreConnector contextCoreConnector = ContextCoreConnectorFactory.get(context);
            contextCoreConnector.addContentListener(new ContentListener() {
            @Override
            public void contentEvent(ContentEvent contentEvent) {
                // Push Content Received
            }
        });
                      

    Note If you want your Listener to survive service/device restart, then make sure you have an Android Service in your application that is started as STICKY and the above code is executed in onCreate of the service.

    Receiving Push Based on Location

    In order to enable Push to target Users present at certain Geofences, you'll have to set the following property to usercontext.properties in you application.

    
        place.state.available.on.server=true