iOS Version 2 API Developer Guide

The version 2 API of the iOS SDK offers a number of enhancements and features that simplifies the use of the SDK. This guide will provide examples for each of the available functions in our iOS SDK along with a step by step guide on how to create a gimbal sdk enabled application.

If this is your first time working with the Proximity Framework visit the  Proximity Overview »


Places Version 2 API introduces the concept of places. A Place can be represented by a single geofence and/or a series of beacons. Thus, when you create a Place in Gimbal Manager you can draw a geofence and/or choose a set of beacons to define the Place.​ Gimbal Analytics in v2 will be generated at place level. As a developer, you would add Communications or other triggers to occur on a Place Entry or Exit.

Create Your Developer Account

Go to the Gimbal Manager and sign up to create a new account.

Gimbal Manager »

Create Your iOS Application

The following steps will set up an application in Xcode ready for enabling Gimbal features.


Important If you are creating an Xcode project with Swift, place visit the  Swift Quickstart »

Confirm Your Environment

Make sure you are:

  • Using the latest Xcode
  • Targeting iOS 5.1.1 or higher. This example uses iOS 8.1
  • Using an iOS device with Bluetooth 4.0. Here is a list of the compatible devices:
    • iPhone 4S or newer
    • iPad 3 or newer
    • iPad mini
    • iPod touch (5th Generation)
  • Have a valid Apple Developer Account
  • Have a valid Apple Provisioning Profile

Create a new Xcode project

In Xcode choose File > New > Project and create a new Application

Please select the appropriate target from the list in the left column of the project editor

Adding Gimbal Framework

The Gimbal Framework can be added either by using CocoaPods or manually.

Adding Gimbal Framework with CocoaPods

Check out these guides for more information on installing CocoaPods and setting up your new or existing application with CocoaPods.

Add the following to your PodSpec file:

target 'MyApp' do
    pod 'Gimbal'
end

Find more info about the Gimbal pod here

Manually Adding Gimbal Framework to your project

Important Click on your workspace in the top left of xcode and then select the build target. At the bottom of the general tab, add Gimbal to "Embedded binary. This will also add Gimbal to "Linked Frameworks and Libraries"

  • Gimbal.framework

Note You will find this framework in the Frameworks folder inside the Gimbal SDK zip file.

Please select the checkbox for Copy items if needed.

It is strongly recommended to add the Gimbal Framework using this method to ensure that the Target Membership checkbox is enabled properly. If an alternate method is used, then the Target Membership of the frameworks must be verified and checked.

The 'Linked Frameworks and Libraries' in your General tab should now look like this:

Add Run Script to Build Phases for Release

Because Gimbal is a dynamic framework, a work around is required in order to push your app to the App Store because of a bug in Apple's submission process. In your app target's "Build Phases", add a new "Run Script Phase" with the following script:

bash "${BUILT_PRODUCTS_DIR}/${FRAMEWORKS_FOLDER_PATH}/Gimbal.framework/thin-frameworks.sh"

Verify Targets

Verify that the Gimbal Framework Target Membership checkbox is set. Also verify that your Deployment Target matches the iOS version of your device. While

Add Usage Descriptions to your plist

Gimbal SDK for iOS uses both Significant Location Change and Region Monitoring features of the iOS. In order to allow for this, multiple entries are required in the property list. In the Info.plist file located in the 'Supporting Files' folder, add new entries with keys 'NSLocationAlwaysAndWhenInUseUsageDescription', and 'NSLocationWhenInUseUsageDescription'. The values should contain a user visible string describing the app’s need for location permissions.

Starting in iOS 10, Apple requires addition permissions for using Bluetooth peripherals, such as Gimbal Beacons. Similar to before, add a new entry to your Info.plist with a key of 'NSBluetoothPeripheralUsageDescription' and value as the descriptions as to why you are using Bluetooth peripherals.

Starting in iOS 11, Apple will prompt users with the "Always" and "When In Use" location options. You can request only the "Always" location permission instead of "When In Use" on iOS 10 and below, which is managed by the "NSLocationAlwaysUsageDescription" property.

Key Type Value
NSLocationAlwaysAndWhenInUseUsageDescription String Location is used to monitor Gimbal Places
NSLocationWhenInUseUsageDescription String Location is used to monitor Gimbal Places
NSLocationAlwaysUsageDescription String Location is used to monitor Gimbal Places
NSBluetoothPeripheralUsageDescription String Bluetooth is used to listen for Gimbal Beacons

Create A Gimbal Application

Create Your Gimbal Application in the Gimbal Manager.

Create Gimbal Application »

Add Application

You will be presented with a form where you will enter the following information: Name of your app, Platform (ios), App category, and Bundle ID.

Note This is where you would enter the Xcode application Bundle ID created in the previous section 'Create Your iOS Application'

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 Xcode App

Add Place

Create Gimbal Place »

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.

Add Communication

Create Gimbal Communication »

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.

Application Configuration


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.

Place detection with Beacons

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.

Arrival RSSI

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.

Departure RSSI

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

Departure interval in seconds

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.

Smoothing Window

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.

SDK Feature Enablement

These settings allow you to turn specific features on/off.

Geofence Monitoring

Allows you to turn on/off geofencing monitoring.
This may be desired if your application only uses beacon-based places.

Beacon Monitoring

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.

Communicate Delivery

Allows you to turn on/off Communicate delivery.
This may be useful if your application does not use the Communicate feature.

Manage Device ID for Advertising

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 AdSupport framework to use this feature.

Important Apple may reject your app if you include the AdSupport Framework without including ad functionality. Be sure to remove the AdSupport Framework if your app does not serve advertising.

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.

Communication Limit Frequency


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 CommunicationManagerDelegate implements communicationManager:presentLocalNotificationsForCommunications:forVisit:, you MUST handle frequency limit and delay (dwell) yourself.

Communication Delay


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 CommunicationManagerDelegate implements communicationManager:presentLocalNotificationsForCommunications:forVisit:, frequency limit and delay (dwell) are honored only for communications returned by that method to the Gimbal SDK. Only use communicationManager:presentLocalNotificationsForCommunications:forVisit: if you want to handle scheduling and delivery of communications yourself.

Push Notification Setup


This tutorial will walk you through how to set up your app to use Gimbal to send push notifications through the Apple Push Notification Service. Three things are required to set up push notifications: enabling your app to receive push notifications, creating a client SSL certificate, and uploading that SSL certificate to Gimbal.



To enable Push Notifications in Xcode, select your project, click on the capabilities tab, and toggle Notifications to ON.



To create a Push Notification Client SSL Certificate you must be a team agent or admin. Log into Apple Developer Member center at: https://developer.apple.com/membercenter



Select Certificates, Identifiers & Profiles.



Select Certificates.



Select all under the Certificates section then select the + button to create a new Certificate.



Select the Apple Push Notification service SSL (Sandbox & Production) radio button. Creating a certificate of this type will allow you to use a single certificate for both your Sandbox and Production environments.



Select your app's bundle identifier from the drop down menu.



Select Continue on the next page.



Before continuing you must create a Certificate Signing Request. You can do this through the KeyChain Access app on your Mac.



Locate the Keychain Access app on your Mac and click on it to open it. It may be under under the Other group in Launchpad.



Select Keychain Access > Certificate Assistant > Request a Certificate from a Certificate Authority.



Enter an appropriate support email for your company and a name for the certificate key that will be generated. Be sure to select the Saved to disk radio button. Select Continue to select a location to save your Certificate Request.



Select the Choose File button and select your Certificate Signing Request that you created in the last step.



Select the Generate button.



Select Download to download your apns certificate. Then open the downloaded file. The file should open in Keychain Access.



Select My Certificates on the left hand side and select your certificate.



Choose File > Export Items... from the Keychain Access menu.



Name your certificate and select a save location. The defaults should be fine. Enter a password for your combined certificate.



Enter your system password to and click Allow to confirm the export of the certificate. You may have to enter the password twice.



Log into Gimbal Manager at https://manager.gimbal.com. Select Applications on the left hand side.



Click on the link to edit your application.



Click on Push Configuration.



Click on the Choose File button to select your certificate for upload. Enter the password for your certificate that you set when you exported your password with Keychain Access. Select the environment in which you'd like to send Push Notifications. Your Universal Client SSL Certificate should work for all environments. Only disable the APNs Feedback Service if you intend to delete invalid ios Device Tokens yourself. Select Save.



You should now be able to send Instant Communications to your app.



Provisioning Profiles


Provisioning Profiles control which devices can run your app and which services your app can access. Provisioning Profiles are embedded in an app's bundle and then installed on a device before the app is run. If the information in the Provisioning Profile doesn't match certain criteria, your app won't launch.

A Provisioning Profile contains three things:

  • An App ID
  • A list of Public Keys used to sign your app
  • A list of Devices which your app can be run on

Each unique combination of these three things requires its own Provisioning Profile.

App ID

The App ID can be an id for a specific app or it can be a wildcard which matches all apps. A specific App ID is required if your app enables any services such as Push Notifications or Game Center. Therefore, if you add services to your app later during development, you may be prompted to create a new non-wildcard Provisioning Profile or to add the new service to your App ID.


If prompted in XCode, click the Fix Issue button.


Public Keys

Each Provisioning Profile contains a List of Public Keys that can be used to sign the app. When a new developer begins work on the app her public key must be added to the provisioning profile. Similarly, if you revoke a developer's signing certificate you may need to create or update your provisioning profile.


If prompted in XCode, click the Fix Issue button.



Similarly, you may see an error message like this:


Devices

Each Provisioning Profile contains a List of Devices that can run the app. When you want to run the app on a new device, you must add that device to the Provisioning Profile.


Usually XCode can add your device if you connect it to your Mac.


Management

There are two ways to manage your Provisioning Profiles:

  • Through XCode
  • Through the Apple Member Center

XCode can create and manage Provisioning Profiles for you and by default it creates a type of Provisioning Profile called a Team Provisioning Profile which allows your app to by signed and run by all team members on all team member's devices. XCode will use the Provisioning Profile that uses the wildcard for the App ID if your app doesn't use any Apple services (like Push Notification or Game Center). If your app does use Apple Services, XCode will create a Team Provisioning Profile specific to that app.

To create a Provisioning Profile manually, log into the Apple Member Center, click on Certificates, Identifiers & Profiles



Click under the Provisioning Profiles section and then either select a profile to edit or click the "+" button.



Select the type of Profile you need (Development or Distribution) and associate the Profile with an App, a List of Certificates, and a List of Devices.



Set API key


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 <Gimbal/Gimbal.h>
    ...
    [Gimbal setAPIKey:@"PUT_YOUR_GIMBAL_API_KEY_HERE" options:nil];
                    

Custom Location Authorization

setAPIKey also prompts the user for access to their location. By default the user will be prompted with the options "Always", "While in use" or "Never". You can manage this request on your own in the options parameter by setting the key MANAGE_PERMISSIONS with a value of NO. You will then need to ask for location access on your own.


    #import <Gimbal/Gimbal.h>
    ...
    [Gimbal setAPIKey:@"PUT_YOUR_GIMBAL_API_KEY_HERE" options:@{@"MANAGE_PERMISSIONS":@NO}];
                    
Note You can add this code in your AppDelegate implementation (.m) file in the didFinishLaunchingWithOptions: method, inserting your specific API Key

Gimbal Started

The Gimbal defines the interface for starting all the services like GMBLPlaceManager, GMBLCommunicationManager and GMBLEstablishedLocationsManager , stopping the services and finding the status.


Check Gimbal Started


Description

Returns the Gimbal services state. It will return false if start was not called, or stop was called, on GMBLPlaceManager, GMBLCommunicationManager and GMBLEstablishedLocationsManager

Sample


    #import <Gimbal/Gimbal.h>
    ...
    [Gimbal isStarted];
                

Gimbal Start


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 GMBLPlaceManager, GMBLCommunicationManager and GMBLEstablishedLocationsManager. These features can also be controlled server side anytime for a specific application using advanced configuration at Gimbal Manager

Sample


    #import <Gimbal/Gimbal.h>
    ...
    [Gimbal start];

                

Gimbal Stop


Description

Stops all the Gimbal services. Its a method for stopping the GMBLPlaceManager, GMBLCommunicationManager and GMBLEstablishedLocationsManager..

Sample


    #import <Gimbal/Gimbal.h>
    ...
    [Gimbal stop];

                

Place Manager

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 Monitoring


Description

Check if place monitoring has started

Sample


    #import <Gimbal/Gimbal.h>
    ...
    [GMBLPlaceManager isMonitoring];
                

Start Monitoring


Description

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

Sample


    #import <Gimbal/Gimbal.h>
    ...
    [GMBLPlaceManager startMonitoring];

                

Stop Monitoring


Description

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

Sample


    #import <Gimbal/Gimbal.h>
    ...
    [GMBLPlaceManager stopMonitoring];

                

Current Visits


Description

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

Sample


    #import <Gimbal/Gimbal.h>
    ...
    [GMBLPlaceManager currentVisits];

                

Initialize PlaceManager


Description

The following creates a placeManager object and will trigger the callback to your delegate of place events. Thereafter, you will be notified of events for places your application is authorized for.

Sample


    #import <Gimbal/Gimbal.h>
    ...
    @property (nonatomic) GMBLPlaceManager *placeManager;
    ...
    self.placeManager = [GMBLPlaceManager new];
    self.placeManager.delegate = self;
    [GMBLPlaceManager startMonitoring];

                

Note Be sure to add the PlaceManager Delegate protocol to your class.

PlaceManager Delegate


Description

This is the callback delegate for place events.

Sample GMBLPlaceManagerDelegate Methods

Note You must add the <GMBLPlaceManagerDelegate> protocol to your class.

The following callbacks will be invoked when a place event occurs.


    #import <Gimbal/Gimbal.h>
    ...
    - (void)placeManager:(GMBLPlaceManager *)manager didBeginVisit:(GMBLVisit *)visit
    {
        // this will be invoked when a place is entered
    }

    - (void)placeManager:(GMBLPlaceManager *)manager didBeginVisit:(GMBLVisit *)visit withDelay:(NSTimeInterval)delayTime
    {
        // this will be invoked when a place is entered and one has remained in that place
        // longer than the specified dwell time.
    }

    - (void)placeManager:(GMBLPlaceManager *)manager didEndVisit:(GMBLVisit *)visit
    {
        // this will be invoked when a place is exited
    }

    - (void)placeManager:(GMBLPlaceManager *)manager didDetectLocation:(CLLocation *)location
    {
        // This will be invoked when Gimbal has detected a reliable location.
    }

    - (void)placeManager:(GMBLPlaceManager *)manager didReceiveBeaconSighting:(GMBLBeaconSighting *)sighting forVisits:(NSArray *)visits
    {
        // this will be invoked when a beacon assigned to a place within a current visit is sighted.
    }

                

GMBLVisit Properties

The GMBLVisit class defines a visit to a place. It includes the place, the arrival date and the departure date to the place. If the visit is currently on-going, the departure date will be nil.

Property Name Type Description
arrivalDate NSDate Arrival date for the visit
departureDate NSDate Departure date for the visit
place GMBLPlace Place associated with visit
dwellTime NSTimeInterval Dwell time for the visit
visitID NSString Unique ID for visit

GMBLPlace Properties

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

Property Name Type Description
identifier NSString Unique identifier for this place
name NSString Name assigned to this place
attributes GMBLAttributes Attributes of this place

GMBLBeaconSighting Properties

The GMBLBeaconSighting class defines a beacon sighting.

Property Name Type Description
RSSI NSInteger The rssi value for the beacon sighted
date NSDate The field representing the beacon sighted date
beacon GMBLBeacon The beacon object with beacon attributes

Region Monitoring Implications

The Gimbal SDK uses CLLocationManager region monitoring to track when a user enters a Gimbal Geofence or iBeacon. Because the application and the SDK both use the same CLLocationManager, this can create the possibility of an application's location's stepping on Gimbal's locations. If you do choose to monitor your own regions in addition to Gimbal places, be sure when removing your regions from CLLocationManager that they are your own regions and not regions owned by Gimbal. Deleting regions incorrectly will result in missed place events in the Gimbal SDK.

Communication Manager

The CommunicationManager defines the interface for delivering communications to your Gimbal SDK enabled application. You use this class to start or stop receiving communications.

Start Receiving Communications


Description

Enables the SDK to receive communications.

Sample


    [GMBLCommunicationManager startReceivingCommunications];
                

Stop Receiving Communications


Description

Stops all communication delivery. This includes both local and instant(push) communications.

Sample


    [GMBLCommunicationManager stopReceivingCommunications];
                

Initialize CommunicationManager


Description

The following creates a communicationManager object and will trigger the callback to your delegate of communications. Thereafter, you will be notified of communications for places your application is authorized for.

Note By default Gimbal Place Events will be presented as UILocalNotifications if the GMBLCommunicationManager is initialized. You can change this behavior by using the GMBLCommunicationManagerDelegate

Sample


    #import <Gimbal/Gimbal.h>
    ...
    @property (nonatomic) GMBLCommunicationManager *communicationManager;
    ...
    self.communicationManager = [GMBLCommunicationManager new];
    self.communicationManager.delegate = self;
    [GMBLCommunicationManager startReceivingCommunications];

                

Note Be sure to add the CommunicationManager Delegate protocol to your class.

Receiving Remote Notifications


Description

Registering to receive Remote Notifications is a three step process that your app should take every time it is launched.

  • Register the User Interaction Types your app supports
  • Receive a Device Token from Apple by registering for Remote Notifications
  • Pass the Device Token received by each application instance to Gimbal

Sample


    #import <Gimbal/Gimbal.h>
    ...

    - (void)applicationDidFinishLaunching:(UIApplication *)app
    {
      // other setup tasks here....

      // Register the supported interaction types.
        UIUserNotificationType types = UIUserNotificationTypeBadge |
                    UIUserNotificationTypeSound | UIUserNotificationTypeAlert;
        UIUserNotificationSettings *mySettings =
                    [UIUserNotificationSettings settingsForTypes:types categories:nil];
        [[UIApplication sharedApplication] registerUserNotificationSettings:mySettings];

      // Register for remote notifications.
        [[UIApplication sharedApplication] registerForRemoteNotifications];
    }

    // Handle remote notification registration.
    - (void)application:(UIApplication *)app
            didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)deviceToken
    {
        [Gimbal setPushDeviceToken:deviceToken];
    }

    - (void)application:(UIApplication *)app
            didFailToRegisterForRemoteNotificationsWithError:(NSError *)err
    {
        NSLog(@"Error in registration. Error: %@", err);
    }

            

You can read more about this process in the Apple Documentation.

Note The Apple Documentation includes more advanced topics such as how to schedule Actionable Notifications.

Communication from Local Notification


Description

This call parses a GMBLCommunication from a UILocalNotification. When a Gimbal Place Event generates a UILocalNotification and the user clicks on it you can use this call to parse out the Gimbal Communication.

Deprecated in iOS 10 Please use the UserNotificaiton Framework in iOS 10 and up.

Sample


    #import <Gimbal/Gimbal.h>
    ...

    - (void)application:(UIApplication *)application didReceiveLocalNotification:(UILocalNotification *)notification
    {
        GMBLCommunication *communication = [GMBLCommunicationManager communicationForLocalNotification:notification];
    }
            

Communication from Remote Notification


Description

This call parses a GMBLCommunication from a Remote Notification. When a remote notification is generated by the Gimbal Manager and the user clicks on it, you can use this call to parse out the Gimbal Communication.

Deprecated in iOS 10 Please use the UserNotificaiton Framework in iOS 10 and up.

Sample


    #import <Gimbal/Gimbal.h>
    ...
    - (void)application:(UIApplication *)application didReceiveRemoteNotification:(NSDictionary *)userInfo
    {
        GMBLCommunication *communication = [GMBLCommunicationManager communicationForRemoteNotification:userInfo];
    }
        

Communication from User Notification Response


Description

This call parses a GMBLCommunication from a Notification Response. When a User Notification in iOS 10 is generated by the Gimbal Manager and the user clicks on it you can use this call to parse out the Gimbal Communication.

Sample


    #import <Gimbal/Gimbal.h>
    #import <UserNotifications/UserNotifications.h>

    ...

    UNUserNotificationCenter *center = [UNUserNotificationCenter currentNotificationCenter];
    center.delegate = self;
    ...

    - (void)userNotificationCenter:(UNUserNotificationCenter *)center didReceiveNotificationResponse:(UNNotificationResponse *)response
                withCompletionHandler:(void(^)())completionHandler {
        GMBLCommunication *communication = [GMBLCommunicationManager communicationForNotificationResponse:response];
        completionHandler();
    }

        

CommunicationManager Delegate


Description

This is the callback delegate for communication notifications.

Sample GMBLCommunicationManagerDelegate Method

Note You must add the <GMBLCommunicationManagerDelegate> protocol to your class.

The following callback will be invoked when a place communication event occurs. The callback provides the opportunity to filter which communications will be presented as local notifications.


    #import <Gimbal/Gimbal.h>
    ...
    - (NSArray *)communicationManager:(GMBLCommunicationManager *)manager
presentLocalNotificationsForCommunications:(NSArray *)communications
                             forVisit:(GMBLVisit *)visit
    {
        // This will be invoked when a user has a communication for the place that was entered or exited.
        // Return an array of communications you would like presented as local notifications.
        // If you implement this method to filter communications, you MUST handle frequency limiting and delay yourself.

        return communications;
    }

    - (UILocalNotification *)communicationManager:(GMBLCommunicationManager *)manager
                    prepareNotificationForDisplay: (UILocalNotification *)notification
                                 forCommunication:(GMBLCommunication *)communication

    {
        // Deprecated in iOS 10! Please use the UserNotifications Framework in iOS 10 and up.

        // This method will be invoked when a communicate is received for a place event and after the communications
        // have been returned from communicationManager:presentLocalNotificationsForCommunications:forVisit:
        // if implemented. The caller is given a chance to customize this notification.
        // Caller should return a customized UILocalNotification for the SDK to use for the notification.
        // SDK will use the default notification if null is returned from this method.

        return notification;
    }

    - (UNMutableNotificationContent *)communicationManager:(GMBLCommunicationManager *)manager
                      prepareNotificationContentForDisplay:(UNMutableNotificationContent *)notificationContent
                                          forCommunication:(GMBLCommunication *)communication
                                                  forVisit:(GMBLVisit *)visit;
    {

        // This method will be invoked when a communicate is received for a place event and after the communications
        // have been returned from communicationManager:presentLocalNotificationsForCommunications:forVisit:
        // if implemented. The caller is given a chance to customize this notification.
        // Caller should return a customized UNMutableNotificationContent for the SDK to use for the notification.
        // SDK will use the default notification if null is returned from this method.

        return notificationContent;
    }



                

GMBLVisit Properties

The GMBLVisit class defines a visit to a place. It includes the place, the arrival date and the departure date to the place. If the visit is currently on-going, the departure date will be nil.

Property Name Type Description
arrivalDate NSDate Arrival date for the visit
departureDate NSDate Departure date for the visit
place GMBLPlace Place associated with visit

GMBLPlace Properties

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

Property Name Type Description
identifier NSString Unique identifier for this place
name NSString Name assigned to this place
attributes GMBLAttributes Attributes of this place

GMBLCommunication Properties

The GMBLCommunication class defines a communication that was defined on the Gimbal Manager Portal.

Property Name Type Description
identifier NSString Unique identifier for this communication
title NSString Title for this communication
descriptionText NSString Description for this communication
URL NSString URL for this communication
deliveryDate NSDate Scheduled Delivery Date for this communication
expiryDate NSDate Expiry date for this communication
attributes GMBLAttributes Attributes of this communication

Initialize Beacon Manager


Description

This call creates a beaconManager object and assigns the delegate class.

Sample


    #import <Gimbal/Gimbal.h>
    ...
    @property (nonatomic) GMBLBeaconManager *beaconManager;
    ...
    self.beaconManager = [GMBLBeaconManager new];
    self.beaconManager.delegate = self;

                

Note Be sure to add the BeaconManager Delegate protocol to your class.

Beacon Sightings


Description

Starts listening to beacon sighting which would generate events based on the users proximity to beacons. You will be notified of sightings for beacons your application is authorized for.

Sample


    #import <Gimbal/Gimbal.h>
    ...
    [self.beaconManager startListening];
                

Stops listening to beacon sightings which would generate events based on the users proximity to beacons.

Sample


    #import <Gimbal/Gimbal.h>
    ...
    [beaconManager stopListening];
                

BeaconManager Delegate


Description

This is the callback delegate for beacon manager.

Sample GMBLBeaconManagerDelegate Methods

Note You must add the <GMBLBeaconManagerDelegate> protocol to your class.

The following callbacks will be invoked when a beacon sighting occurs.


    #import <Gimbal/Gimbal.h>
    ...
    - (void)beaconManager:(GMBLBeaconManager *)manager didReceiveBeaconSighting:(GMBLBeaconSighting *)sighting
    {
        //This will be invoked when a user sights a beacon
    }

                

GMBLBeaconSighting Properties

The GMBLBeaconSighting class defines a beacon sighting.

Property Name Type Description
RSSI NSInteger The rssi value for the beacon sighted
date NSDate The field representing the beacon sighted date
beacon GMBLBeacon The beacon object with beacon attributes

GMBLBeacon Properties

The GMBLBeacon class defines a beacon that was defined on the Gimbal Manager Portal.

Property Name Type Description
identifier NSString A unique string identifier (factory id)
uuid NSString A universally unique identifier (uuid)
name NSString The name for the GMBLBeacon that can be assigned via the Gimbal Manager
iconURL NSString The iconUrl
batteryLevel GMBLBatteryLevel The battery level
temperature NSInteger The ambient temperature surrounding the Beacon in Fahrenheit. The value will be NSIntegerMax if no temperature sensor is present on this beacon.

Established Locations Manager

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 Monitoring

Description

Check if established locations has been enabled.

Sample


    #import <Gimbal/Gimbal.h>
    ...
    GMBLEstablishedLocationManager.isMonitoring;
                

Start Monitoring

Description

Enables the passive collection of Established Locations.

Sample


    #import <Gimbal/Gimbal.h>
    ...
    GMBLEstablishedLocationManager.startMonitoring;
                

Stop Monitoring

Description

Disables the passive collection of Established Locations.

Sample


    #import <Gimbal/Gimbal.h>
    ...
    GMBLEstablishedLocationManager.stopMonitoring;
                

Retrieve Established Locations

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 <Gimbal/Gimbal.h>
    ...
    for (GMBLEstablishedLocation *establishedLocation in GMBLEstablishedLocationManager.establishedLocations) {
        NSLog.info(@"Established Location: %@", [establishedLocation description]);
    }
                

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
score returns the score of the EstablishedLocation; a higher score value indicates that this location is more relevant to the user
boundary returns the Circle representing the boundary of the EstablishedLocation
description returns the attributes of the EstablishedLocation and its boundary in a String

Circle Accessor Methods

A geographical circle.

Method Description
center returns the Coordinate representing the center of the Circle
radius returns the radius of the Circle, in meters

Coordinate Accessor Methods

The Coordinate class represents a latitude and longitude.

Method Description
latitude returns the latitude of the Coordinate
longitude returns the longitude of the Coordinate

Device Attribute Manager


Requires SDK 2.62+ The Device Attribute Manager allows you to associate attributes specific to the user of that individual device.

Set Device Attributes


Attributes can be set by passing in a dictionary to setDeviceAttributes:. The call will return "true" if setting was successful, or "false" if there was a problem with encoding one of the elements. The passed in dictionary will remove and override the existing attributes. Passing in nil or an empty dictionary will remove the attributes associated with specific device.

#import <Gimbal/Gimbal.h>
...
NSDictionary *attributes = @{
    @"key1":@"value1",
    @"key2":@"value2",
};
GMBLDeviceAttributeManager *attributeManager = [GMBLDeviceAttributeManager new];
[attributeManager setDeviceAttributes:attributes];
            

Get Device Attributes


The current attributes for a device can be retrieved through getDeviceAttributes.

#import <Gimbal/Gimbal.h>
...
GMBLDeviceAttributeManager *attributeManager = [GMBLDeviceAttributeManager new];
NSDictionary *attributes = [attributeManager getDeviceAttributes];
        

Reset Application Instance Identifier


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 dissociates 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 <Gimbal/Gimbal.h>
...
[Gimbal resetApplicationInstanceIdentifier];
            

Beacon Configuration

For information on default beacon configurations and how to assign and push a configuration, please refer to the link provided

Beacon Configuration »

Background


Background Modes

To properly receive Gimbal Proximity events in the background your application needs to enable the following iOS background modes.

  • Uses Bluetooth LE accessories bluetooth-central

Background Behavior

In the foreground your application should be notified for most Gimbal Proximity Events that originate from a beacon. In the background this is not the case. In the background the device receives Bluetooth LE events much less frequently.

Expected Time to Arrival

The following table shows how long it takes to receive an Arrive event from our VisitManager based on the testing we've done on iOS devices.

Beacon Configuration Average Time to Arrive (seconds) Standard Deviation (seconds)
S21 Recommended Config 12 7
US5 Recommended Config 12 7