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
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 |
#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];
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.
#import <FYX/FYX.h> ... [FYX setAppId:@"your-app-id" appSecret:@"your-app-secret" callbackUrl:@"your-callback-url"];
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.
#import <FYX/FYX.h> ... [FYX startService:myServicedelegate];
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.
#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 }
This call will stop bluetooth scanning.
#import <FYX/FYX.h> ... [FYX stopService];
Important The SDK will no longer function properly until you call startService again.
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.
#import <FYX/FYX.h> ... [FYX deleteVisitsAndSightings];
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 }
The following configuration allows a developer to turn on the "Bluetooth is powered off" alert view. The default is to hide the alert view.
Note This value must be set into NSUserDefaults
before Gimbal Proximity is initialized.
Enabling the Bluetooth is powered off alert view
[[NSUserDefaults standardUserDefaults] setBool:NO forKey:@"gmbl_hide_bt_power_alert_view"];
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.
#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.
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.
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 |
#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.
This is the callback delegate for sighting notifications.
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 }
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). The value will be NSIntegerMax if no temperature sensor is present on this beacon. |
This call stops the callbacks to the delegate for sightings.
#import <FYX/FYXSightingManager.h> ... [self.sightingManager stopScan];
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.
Post sightings to the Gimbal Proximity service every ten seconds.
[[NSUserDefaults standardUserDefaults] setInteger:10 forKey:@"fyx_post_to_server_interval_preference"];
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.
#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.
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.
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 |
FYXVisitOptionBackgroundDepartureIntervalInSecondsKey | Number of seconds before the absence of a beacon triggers the didDepart
callback in background
|
NSTimeInterval | 300 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 |
#import <FYX/FYXVisitManager.h> #import <FYX/FYXSightingManager.h> ... @property (nonatomic) FYXVisitManager *visitManager; ... self.visitManager = [[FYXVisitManager alloc] init]; self.visitManager.delegate = self; NSMutableDictionary *options = [NSMutableDictionary new]; [options setObject:[NSNumber numberWithInt:FYXSightingOptionSignalStrengthWindowNone] forKey:FYXSightingOptionSignalStrengthWindowKey]; [options setObject:[NSNumber numberWithInt:5] forKey:FYXVisitOptionDepartureIntervalInSecondsKey]; [options setObject:[NSNumber numberWithInt:300] forKey:FYXVisitOptionBackgroundDepartureIntervalInSecondsKey]; [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.
This is the callback delegate for visit notifications.
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 }
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 |
This call stops the callbacks to the delegate for visits.
#import <FYX/FYXVisitManager.h> ... [self.visitManager stop];
Depending on your application's use case, the Gimbal Series 20 beacon can be configured to use iBeacon technology. To learn how to create a Gimbal beacon with iBeacon technology please read the Quickstart Guide with iBeacon. The Proximity framework makes it very easy to use both types of beacons from the SDK and lets you manage them through the Gimbal Manager Portal.
Quick Start Guide with iBeacon »
Important Gimbal SDK for iOS uses both Significant Location Change and Region Monitoring features of the iOS. In order to allow for this, an entry 'NSLocationAlwaysUsageDescription' is required. In the Info.plist file located in the 'Supporting Files' folder, add a new entry with key 'NSLocationAlwaysUsageDescription'. The value should contain a user visible string describing the app’s need for the “always” location permission.
Much like a standard Gimbal beacon, you can be notified of a proximate Gimbal beacon with iBeacon technology 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 sighting a Gimbal beacon with iBeacon technology.
Note The SDK will only look for beacons 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 beacons with iBeacon technology
Property Name | Description |
---|---|
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 |
iBeacon | FYXiBeacon being sighted |
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 |
Beacon Configurations allow you to customize hardware specific attributes such as antenna type, transmit power, etc, for a particular beacon. This results in having the SDK detect the presense of that beacon in different ways. For example, adjusting the transmit power of a beacon can result in a greator detection distance.
Here are the default beacon configurations:
Configuration Name | Behavior | Where should this configuration be used? |
---|---|---|
Recommended | Constant sightings in forground. Sightings in background come in at a rate of 3 per minute. | Apply this configuration when timely background sightings are critical to your application's function. |
Presence optimized | Same as Recommended, however sightings in background come in at a rate of 1 per minute. This results in a significant amount of battery savings when in constant proximity of a beacon. | Apply this configuration when the user's phone will be in prolonged proximity of that beacon. This configuration will minimize the impact on the user's phone battery life when in proximity of beacons that have this configuration. |
Assigning a configuration indicates to the server that you want to push that configuration to the specified beacon when possible. To do so navigate to Proximity > Beacons and edit a beacon.
In order to push configurations to a beacon you must use the Gimbal Beacon Manager application that can be found in the App Store℠ here. Open the Gimbal Beacon Manager application and log in using your Gimbal Manager credentials.
Once logged in hit the settings button to reveal the settings menu. Click on the "Configure" menu option.
Follow the directions on the screen and remove all batteries from your Gimbal Series 20 Beacon and then re-insert the batteries. This places the beacon in a configurable mode and the application will be able to push your configuration. When connected to the beacon you should see something like the following.
Notice that the configuration on the beacon does not match the configuration indicated from the Server. Push the update button to apply your configuration.
To properly receive Gimbal Proximity events in the background your application needs to enable the following iOS background modes.
bluetooth-central
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.
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 |
This call provides the following Gimbal Proximity application information.
FYXAppInfo
PropertiesProperty | 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. |
#import <FYX/FYX.h> #import <FYX/FYXAppInfo.h> ... FYXAppInfo *appInfo = [FYX currentAppInfo];
Add a transmitter for the authenticated user.
#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 the transmitters for the authenticated user.
#import <FYX/FYXTransmitterManager.h> ... [FYXTransmitterManager retrieveTransmittersSuccess:^(NSArray *transmitters) { // do something on success } failure:^(NSError *error) { // do something on failure }];
Edit a transmitter for the authenticated user.
#import <FYX/FYXTransmitter.h> #import <FYX/FYXTransmitterManager.h> ... [FYXTransmitterManager editTransmitter:myTransmitter success:^() { // do something on success } failure:^(NSError *error) { // do something on failure }];
Remove a transmitter for the authenticated user.
#import <FYX/FYXTransmitterManager.h> ... [FYXTransmitterManager removeTransmitter:myTransmitterIdentifier success:^() { // do something on success } failure:^(NSError *error) { // do something on failure }];
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.
#import <FYX/FYX.h> #import <FYX/FYXLogging.h> ... [FYX setAppId:@"your-app-id" appSecret:@"your-app-secret"]; [FYXLogging setLogLevel:FYX_LOG_LEVEL_VERBOSE];
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
#import <FYX/FYX.h> #import <FYX/FYXLogging.h> ... [FYX setAppId:@"your-app-id" appSecret:@"your-app-secret"]; [FYXLogging enableFileLogging];
Turn off file logging for SDK log calls. File logging is enabled by default.
#import <FYX/FYX.h> #import <FYX/FYXLogging.h> ... [FYX setAppId:@"your-app-id" appSecret:@"your-app-secret"]; [FYXLogging disableFileLogging];