Proximity iOS Developer Guide

The Gimbal Proximity platform enables proximity services within your application. This guide will provide examples for each of the available functions in our iOS SDK for Gimbal Proximity.

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

To get the SDK installed and running checkout the  iOS Quick Start »



Note Across all documentation and SDKs the terms 'Beacon' and 'Transmitter' are interchangeable

Enable and Disable Location Updates


Description

These calls allow for enabling and disabling the location updates which are used to provide extra information to a sighting callback. By default location updates are enabled and need to be explicitly disabled.

Important If you want to guarantee that end-users are not prompted to enable Location Services, make sure you disable location updates before you set the application ID.

Note You can also use options to set different location modes when enabling location updates. The following modes are supported. .

Key Value Description
FYXLocationModeKey FYXLowPowerLocation Uses the cached location from the location Manager. Default Mode
FYXLocationModeKey FYXHighAccuracyLocation Queries location manager for location Updates
FYXLocationModeKey FYXNoLocation No location updates

Sample


    #import <FYX/FYX.h>
    ...
    //disable location udpates
    [FYX disableLocationUpdates];
    
    //enable location updates. Uses Low Power location by default. 
    [FYX enableLocationUpdates];

    //enable location updates with options
    NSMutableDictionary *options = [[NSMutableDictionary alloc] init];
    [options setObject:[NSString stringWithString:FYXHighAccuracyLocation] forKey:FYXLocationModeKey];
    [FYX enableLocationUpdatesWithOptions:options];
       
                    

Set Application ID, Secret, and Callback URL


Description

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.

Sample


    #import <FYX/FYX.h>
    ...
    [FYX setAppId:@"your-app-id" 
        appSecret:@"your-app-secret"
      callbackUrl:@"your-callback-url"];
                    

Start Service and Authorize


Description

This call starts an OAuth session with the server. OAuth allows the user to authorize your application to work with your Gimbal Proximity resources. This includes identifying your proximity devices and management of those devices. A UIWebView will be pushed onto your view controller where the user can complete the Oauth process and a token can be stored in the Core Client.

The FYXSessionDelegate methods will be called to indicate status of the Oauth process. If the process fails or a user chooses not to authorize your application, then sessionCreateFailed will be called.

Sample

Note This code assumes your application's UIView is embedded in a UINavigationController. Depending on your application GUI you will access the currently displayed view in a different manner.

Important Do not forget to handle the open URL to finish OAuth flow.

        
    #import <FYX/FYX.h>
    ...
    UINavigationController *navigationController = (UINavigationController*) self.window.rootViewController;
    UIViewController *myViewController = [[navigationController viewControllers] objectAtIndex:0];
    [FYX startServiceAndAuthorizeWithViewController:myViewController delegate:mySessionDelegate];
                

Deprecated The following API starts an OAuth session via the Safari browser and has been deprecated in favor of using the UIWebView API above.

        
    #import <FYX/FYX.h>
    ...
    [FYX startServiceAndAuthorize:mySessionDelegate];
                

FYXSessionDelegate Methods

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

Once the session start has been attempted by calling startSession: above, one of the following methods will be invoked on your delegate object once the status of the session has been determined.

Important The SDK will not function properly until a session has successfully started. If you attempt further calls into the SDK before receiving a callback indicating the session has successfully started, they will be rejected as Unauthorized.


    #import <FYX/FYX.h>
    ...
    - (void)sessionStarted
    {
        // this will be invoked if the session has successfully started
        // further calls into the SDK should be allowed at this point
    }
                

    #import <FYX/FYX.h>
    ...
    - (void)sessionCreateFailed:(NSError *)error
    {
        // this will be called if the session has failed to start
        // further calls into the SDK will be rejected by the server as Unauthorized
    }
                

Handle Open URL


Description

This call will handle the URL scheme that was registered with the application to complete the OAuth token retrieval. The intention is to pass the callback URL registered with the service directly into the SDK from your AppDelegate callback function.

Important Be sure that you have registered your URL scheme within your application Info.plist file.

Sample


    #import <FYX/FYX.h>
    ...
    - (BOOL)application:(UIApplication *)application handleOpenURL:(NSURL *)url
    {
        [FYX handleOpenURL:url];
        return YES;
    }
                

Stop Service and Deauthorize


Description

This call ends the OAuth session with the server and revokes the token. It also disassociates this application instance from the user's account. This receiver will no longer show up on the portal under that user. Bluetooth scanning will be stopped.

Sample


    #import <FYX/FYX.h>
    ...
    [FYX stopServiceAndDeauthorize];
                

FYXSessionDelegate Methods

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

Once the session stop has been attempted by calling stopServiceAndDeauthorize: above, one of the following methods will be invoked on your delegate object once the status of the session end has been determined.

Important sessionEnded will be called anytime the SDK is not able to authenticate. This can occur if the token has been revoked by calling stopServiceAndDeathorize, if a token is revoked outside of the SDK, or if an expired token is not able to be refreshed. sessionEnded will be invoked for each failed server call, so it can be invoked more than once for the same session.


    #import <FYX/FYX.h>
    ...
    - (void)sessionEnded
    {
        // this will be invoked if the session has successfully ended and the user is deauthorized
    }
                

    #import <FYX/FYX.h>
    ...
    - (void)sessionEndFailed:(NSError *)error
    {
        // this will be called if the session has failed to end
    }
                

Delete User Proximity Data


Description

This call dissociate a device and data (visits and sightings) reported by the application running on that device. The open visits and sightings gets closed on server. Data (visits and sightings) on device also gets cleared due to this API invocation.

Sample


    #import <FYX/FYX.h>
    ...
    [FYX deleteVisitsAndSightings];
                

FYXSessionDelegate Methods

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

Once the deletion visit and sightings data has been attempted by calling deleteVisitsAndSightings above, one of the following methods will be invoked on your delegate object once the status of the service invocation has been determined.

Important Visit and Sightings created before invocation of API will be cleared from device. The data on server gets anonymized due to this API invocation. The application should start a session before invocation of delete data API. The application needs to be authorized before using this API.


    #import <FYX/FYX.h>
    ...
    - (void)sessionDataDeleted
    {
        // this will be invoked if the visits and sighting data has been successfully deleted
        // 
    }
                

    #import <FYX/FYX.h>
    ...
    - (void)sessionDataDeleteFailed:(NSError *)error
    {
        // this will be invoked if the visits and sighting data has not been successfully deleted
    }
                

Start Service


Description

This call registers the application with the server and starts bluetooth scanning. It does NOT authorize the user of the app. The authorization protected APIs will not function unless you use "authorize" instead.

Sample


    #import <FYX/FYX.h>
    ...
    [FYX startService:myServicedelegate];
                

FYXServiceDelegate Methods

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

Once the service start has been attempted by calling startService: above, one of the following methods will be invoked on your delegate object once the status of the service has been determined.

Important Start service does NOT start a session. Do not expect all features of the SDK to function as expected. If you attempt calls into the SDK which require an OAuth Session, they will be rejected as Unauthorized.


    #import <FYX/FYX.h>
    ...
    - (void)serviceStarted
    {
        // this will be invoked if the service has successfully started
        // bluetooth scanning will be started at this point
    }
                

    #import <FYX/FYX.h>
    ...
    - (void)startServiceFailed:(NSError *)error
    {
        // this will be called if the service has failed to start
    }
                

Stop Service


Description

This call will stop bluetooth scanning.

Sample


    #import <FYX/FYX.h>
    ...
    [FYX stopService];
                

Important The SDK will no longer function properly until you call startService again.

Scan for Sightings


Description

This call creates a sightingManager object and will trigger the callback to your delegate of sightings using the default scanning options. Using this call you will be notified of sightings for proximity devices your application is authorized for.

If the user is not authorized, you can still register for the callback, but will only see beacons that are registered to the application developer.

Sample


    #import <FYX/FYXSightingManager.h>
    ...
    @property (nonatomic) FYXSightingManager *sightingManager;
    ...
    self.sightingManager = [[FYXSightingManager alloc] init];
    self.sightingManager.delegate = myDelegate;
    [self.sightingManager scan];
                

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

Scan for Sightings With Options


Description

This call creates a sightingManager object and will trigger the callback to your delegate of sightings using the provided scanning options. Using this call you will be notified of sightings for proximity devices your application is authorized for.

Scanning Options

Signal Strength Window

This option allows for a window of historic signal strengths to be used for a given device to "smooth" them out to remove quick jumps in signal strength. The larger the window the less the signal strength will jump but the slower it will react to the signal strength changes.

Key Value Description
FYXSightingOptionSignalStrengthWindowKey FYXSightingOptionSignalStrengthWindowNone No window of historic signal strengths is used
FYXSightingOptionSignalStrengthWindowKey FYXSightingOptionSignalStrengthWindowSmall A small window of historic signal strengths is used
FYXSightingOptionSignalStrengthWindowKey FYXSightingOptionSignalStrengthWindowMedium A medium window of historic signal strengths is used
FYXSightingOptionSignalStrengthWindowKey FYXSightingOptionSignalStrengthWindowLarge A large window of historic signal strengths is used

Sample


    #import <FYX/FYXSightingManager.h>
    ...
    @property (nonatomic) FYXSightingManager *sightingManager;
    ...
    NSMutableDictionary *options = [[NSMutableDictionary alloc] init];
    [options setObject:[NSNumber numberWithInt:FYXSightingOptionSignalStrengthWindowNone]
                forKey:FYXSightingOptionSignalStrengthWindowKey];

    self.sightingManager = [[FYXSightingManager alloc] init];
    self.sightingManager.delegate = myDelegate;
    [self.sightingManager scanWithOptions:options];
                

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

Sighting Delegate


Description

This is the callback delegate for sighting notifications.

Sample FYXSightingDelegate Methods

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

The following callback will be invoked when an authorized transmitter is sighted.


    #import <FYX/FYXSightingManager.h>
    ...
    - (void)didReceiveSighting:(FYXTransmitter *)transmitter time:(NSDate *)time RSSI:(NSNumber *)RSSI
    {
        // this will be invoked when an authorized transmitter is sighted
    }
                

FYXTransmitter Properties

Property Name Description
identifier Unique identifier for this transmitter
name Name assigned to this transmitter
ownerId Unique identifier of the owner of the transmitter
iconUrl URL to an icon image (optional)
battery Battery level indication. 0=LOW, 1=MED/LOW, 2=MED/HIGH, 3=HIGH (optional)
temperature Temperature of transmitter in fahrenheit (optional)

Stop Scanning for Sightings


Description

This call stops the callbacks to the delegate for sightings.

Sample


    #import <FYX/FYXSightingManager.h>
    ...
    [self.sightingManager stopScan];
                

Post To Service Configuration


Description

The following configuration allows a developer to adjust the interval in seconds at which sightings are posted to the Gimbal Proximity service. The default is 5 minutes.

Note This value must be set into NSUserDefaults before Gimbal Proximity is initialized.

Sample

Post sightings to the Gimbal Proximity service every ten seconds.


    [[NSUserDefaults standardUserDefaults] setInteger:10 forKey:@"fyx_post_to_server_interval_preference"];
                

Start Visit Manager


Description

This call creates a FYXVisitManager object and will trigger the callback to your delegate of visits using the default options. Using this call you will be notified of visit arrive, sightings and depart for proximity devices your application is authorized for.

If the user is not authorized, you can still register for the callback, but will only see beacons that are registered to the application developer.

Sample


    #import <FYX/FYXVisitManager.h>
    ...
    @property (nonatomic) FYXVisitManager *visitManager;
    ...
    self.visitManager = [[FYXVisitManager alloc] init];
    self.visitManager.delegate = self;
    [self.visitManager start];
                

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

Start Visit Manager With Options


Description

This call creates a FYXVisitManager object and will trigger the callback to your delegate of visits using the provided options. Using this call you will be notified of visit arrive, sightings and depart for proximity devices your application is authorized for.

Options

Option Key Description Data Type Default
FYXSightingOptionSignalStrengthWindowKey Smoothing of signal strengths using historic sliding window averaging int FYXSightingOptionSignalStrengthWindowLarge
FYXVisitOptionDepartureIntervalInSecondsKey Number of seconds before the absence of a beacon triggers the didDepart callback NSTimeInterval 5 seconds
FYXVisitOptionArrivalRSSIKey An RSSI value of the beacon sighting that must be exceeded before a didArrive callback is triggered NSNumber None
FYXVisitOptionDepartureRSSIKey If an RSSI value of the beacon sightings is less than this value and the departure interval is exceeded a didDepart callback is triggered NSNumber None

Sample


    #import <FYX/FYXVisitManager.h>
    ...
    @property (nonatomic) FYXVisitManager *visitManager;
    ...
    self.visitManager = [[FYXVisitManager alloc] init];
    self.visitManager.delegate = self;

    NSMutableDictionary *options = [NSMutableDictionary new];
    [options setObject:[NSNumber numberWithInt:5] forKey:FYXVisitOptionDepartureIntervalInSecondsKey];
    [options setObject:[NSNumber numberWithInt:FYXSightingOptionSignalStrengthWindowNone] forKey:FYXSightingOptionSignalStrengthWindowKey];
    [options setObject:[NSNumber numberWithInt:-75] forKey:FYXVisitOptionArrivalRSSIKey];
    [options setObject:[NSNumber numberWithInt:-90] forKey:FYXVisitOptionDepartureRSSIKey];
    [self.visitManager startWithOptions:options];
                

Note Be sure to add the FYXVisitDelegate protocol to your class.

Visit Delegate


Description

This is the callback delegate for visit notifications.

Sample FYXVisitDelegate Methods

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

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


    #import <FYX/FYXVisitManager.h>
    ...
    - (void)didArrive:(FYXVisit *)visit {
        // This will be invoked when a visit starts
    }

    - (void)receivedSighting:(FYXVisit *)visit updateTime:(NSDate *)updateTime RSSI:(NSNumber *)RSSI {
        // This will be invoked when a sighting comes in during a visit
    }

    - (void)didDepart:(FYXVisit *)visit {
        // This will be invoked when a visit ends
    }
                

FYXVisit Properties

Property Name Description
transmitter FYXTransmitter 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

Stop Visit Manager


Description

This call stops the callbacks to the delegate for visits.

Sample


    #import <FYX/FYXVisitManager.h>
    ...
    [self.visitManager stop];
                

iBeacon™


Overview

If your application's use case requires you to use iBeacon technology, the Gimbal Series 20 beacon can be configured to broadcast iBeacon compatible BLE packets. To learn how to configure a beacon to be iBeacon compatible please read the Gimbal iBeacon Quickstart Guide. The Proximity framework makes it very easy to use both iBeacons and Gimbal beacons from the SDK and lets you manage them through the Gimbal Manager Portal.

Gimbal iBeacon Quick Start Guide »

Visits

Much like a Gimbal beacon, you can be notified of a proximate iBeacon by creating a VisitManager and set any options that suit your use case. The only difference is that you need to implement and set a FYXiBeaconVisitDelegate. Below you can see the needed callbacks for receiving iBeacon sightings.

Note The SDK will only look for iBeacons that are managed in the Gimbal Manager Portal.


    #import <FYX/FYXVisitManager.h>
    ...
    - (void)didArriveIBeacon:(FYXiBeaconVisit *)visit;
    - (void)receivedIBeaconSighting:(FYXiBeaconVisit *)visit updateTime:(NSDate *)updateTime  RSSI:(NSNumber *)RSSI;
    - (void)didDepartIBeacon:(FYXiBeaconVisit *)visit;
                

You can set this delegate on the VisitManager like this:


    #import <FYX/FYXVisitManager.h>
    ...
    FYXVisitManager visitManager = [FYXVisitManager new];
    visitManager.delegate = gimbalBeaconDelegate;    //To receive visits from Gimbal beacons
    visitManager.iBeaconDelegate = iBeaconDelegate;  //To receive visits from managed Gimbal iBeacons
                

FYXiBeaconVisit Properties

Property Name Description
iBeacon FYXiBeacon being sighted
startTime Time at which the visit starts
lastUpdateTime Last time which the beacon was sighted
dwellTime Time interval between the visit start time and the last update time

FYXiBeacon Properties

Property Name Description
uuid The Proximity UUID of the beacon
major The Major being broadcast by the beacon
minor The Minor being broadcast by the beacon
rssi The RSSI broadcasted for the current sighting
proximity The Proximity Enumeration provided by iOS as a string
accuracy The Accuracy of the proximity and rssi values in terms of meters

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
  • Location updates location

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 devices running different iOS versions.

iOS 7

Beacon Transmit Rate Average Time to Arrival Standard Deviation
100 milliseconds 7 seconds 10 seconds
645 milliseconds 15 seconds 6 seconds

iOS 6

Beacon Transmit Rate Average Time to Arrival Standard Deviation
100 milliseconds 20 seconds 11 seconds
645 milliseconds 85 seconds 59 seconds

Application Information


Description

This call provides the following Gimbal Proximity application information.

FYXAppInfo Properties

Property Description
receiverId The unique identifier for this receiver application. Null if the receiver has not registered yet.
receiverOwnerId The unique identifier for this receiver's authenticated user. Null if the user has not authenticated yet.
oauthToken The OAuth2 token used for authenticated requests against the Gimbal Proximity Service. Empty string if the user has not authorized yet.

Sample


    #import <FYX/FYX.h>
    #import <FYX/FYXAppInfo.h>
    ...
    FYXAppInfo *appInfo = [FYX currentAppInfo];

                

Add a Transmitter


Description

Add a transmitter for the authenticated user.

Sample


    #import <FYX/FYXTransmitter.h>
    #import <FYX/FYXTransmitterManager.h>
    ...
    [FYXTransmitterManager addTransmitter:myTransmitter
                                  passcode:myTransmitterPasscode
                                   success:^() {
                                       // do something on success
                                   }
                                   failure:^(NSError *error) {
                                       // do something on failure
                                   }];
                

Retrieve Transmitters


Description

Retrieve the transmitters for the authenticated user.

Sample


    #import <FYX/FYXTransmitterManager.h>
    ...
    [FYXTransmitterManager retrieveTransmittersSuccess:^(NSArray *transmitters) {
                                                    // do something on success
                                                }
                                                failure:^(NSError *error) {
                                                    // do something on failure
                                                }];
                

Edit Transmitter


Description

Edit a transmitter for the authenticated user.

Sample


    #import <FYX/FYXTransmitter.h>
    #import <FYX/FYXTransmitterManager.h>
    ...
    [FYXTransmitterManager editTransmitter:myTransmitter
                                    success:^() {
                                        // do something on success
                                    }
                                    failure:^(NSError *error) {
                                        // do something on failure
                                    }];
                

Remove Transmitter


Description

Remove a transmitter for the authenticated user.

Sample


    #import <FYX/FYXTransmitterManager.h>
    ...
    [FYXTransmitterManager removeTransmitter:myTransmitterIdentifier
                                      success:^() {
                                          // do something on success
                                      }
                                      failure:^(NSError *error) {
                                          // do something on failure
                                      }];
                

Set Log Level


Description

Set the logging level for the Gimbal Proximity SDK. The available levels are FYX_LOG_LEVEL_VERBOSE, FYX_LOG_LEVEL_INFO, FYX_LOG_LEVEL_WARN, FYX_LOG_LEVEL_ERROR. The default logging level is ERROR. setLogLevel must be called after setting the app id, secret, and callback.

Sample


    #import <FYX/FYX.h>
    #import <FYX/FYXLogging.h>
    ...
    [FYX setAppId:@"your-app-id" appSecret:@"your-app-secret"];
    [FYXLogging setLogLevel:FYX_LOG_LEVEL_VERBOSE];
                

Enable File Logging


Description

Turn on file logging for SDK log calls. File logging is enabled by default.

To view the logs:
Open organizer
Select 'applications' under the device you are using in the organizer
Select 'download'
In Finder, control-left click the file, click 'show package contents'
Open AppData->Library->Caches->Logs-> (your log file) in some text viewer or console

Sample


    #import <FYX/FYX.h>
    #import <FYX/FYXLogging.h>
    ...
    [FYX setAppId:@"your-app-id" appSecret:@"your-app-secret"];
    [FYXLogging enableFileLogging];
                

Disable File Logging


Description

Turn off file logging for SDK log calls. File logging is enabled by default.

Sample


    #import <FYX/FYX.h>
    #import <FYX/FYXLogging.h>
    ...
    [FYX setAppId:@"your-app-id" appSecret:@"your-app-secret"];
    [FYXLogging disableFileLogging];