Context iOS Developer Guide

If you haven't done it yet be sure to check out the iOS Quick Start Guide to get the SDK installed and running.

iOS Quick Start »

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

Using QLContextCoreConnector


Description

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


Enable the connector

The enableFromViewController:success:failure: method is used to enable the SDK for use by the end user.

Note: This call is asynchronous and use objective-c blocks to return results when they are available.


    QLContextCoreConnector *contextCoreConnector = [QLContextCoreConnector new]; 
    [contextCoreConnector enableFromViewController:self.window.rootViewController
      success:^{
         NSLog(@"Gimbal enabled");
      }
      failure:^(NSError *error) { 
        NSLog(@"Failed to initialize gimbal %@", error);
      }];
    

Check the Status

The checkStatusAndOnEnabled:disabled: method allows your application to ensure that it has been previously enabled.

Note: This call is asynchronous and use objective-c blocks to return results when they are available.


    [contextCoreConnector checkStatusAndOnEnabled: ^(QLContextConnectorPermissions *contextConnectorPermissions) { 
      NSLog(@"Already enabled");
    } 
    disabled:^(NSError *error) { 
      NSLog(@"Is not enabled");
    }];
    

Delete a User's Data and Disable Gimbal


    [contextCoreConnector deleteAllUserDataAndOnSuccess:^{ 
      NSLog(@"User data deletion SUCCESS");
    } 
    failure:^(NSError *error) { 
      NSLog(@"User data deletion FAILURE: %@", error ); 
    }];
    

Custom Opt-in and Privacy


Description

By default, when you enable the SDK using enableFromViewController:success:failure: 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: YES to UserContext.plist 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 SHOW_DEBUG_PANELS: YES to UserContext.plist file.


    Place monitoring

    Initialize connector

    
         self.contextPlaceConnector = [[QLContextPlaceConnector alloc] init]; 
        

    Listening for place event

    Implement didGetPlaceEvent method to listen for place events. Gimbal SDK will call this method when it detects Entry/Exit for a place

    
          - (void)didGetPlaceEvent: (QLPlaceEvent *)placeEvent 
          {
            // do something with the place event
          }
        

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

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

    Check if place monitoring is available

    The Gimbal SDK does not support place monitoring on devices such as the iPhone 3GS due to the hardware not being battery efficient to continually monitor geofences in the background. To determine if the device supports place monitoring, call the "isPlaceMonitoringAvailable" on the QLContextPlaceConnector to see if the current device supports place monitoring.

    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.