Proximity iOS Quick Start

Get Gimbal up and running in your iOS App.

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

Create Your Developer Account

Go to the Gimbal Manager and create an account.

Gimbal Manager »

Create Your iOS Application

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

Confirm Your Environment

Make sure you are:

  • Using Xcode 4.4 or higher
  • Targeting iOS 5.1.1 or higher
  • 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

Add these iOS Frameworks and Libraries to your project

  • CoreBluetooth.framework
  • CoreLocation.framework
  • CoreData.framework
  • libz.dylib
  • MapKit.framework
  • Security.framework

Having trouble adding these to your project? Here's some help

Add these Gimbal Frameworks to your project

Important Right click the Frameworks folder and choose the "Add files to ..." option to add these frameworks.

It is strongly recommended to add the Gimbal Frameworks 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.

  • Common.embeddedframework
  • ContextCore.embeddedframework
  • ContextLocation.embeddedframework
  • FYX.framework
  • NetworkServices.embeddedframework

Note You will find these frameworks in the Frameworks folder inside the Gimbal SDK zip file.

Your frameworks directory should now look like this:

Verify Target Membership

For each Gimbal Framework, verify the Target Membership checkbox is set:

Verify your deployment target version

Verify your deployment target matches the iOS version of your device:

Add Proximity

The following steps will allow you to use Gimbal Proximity features in your application.

Create Your Gimbal Application

Create Your Gimbal Application in the Gimbal Manager.

Create Gimbal Application »

You will be presented with a form where you will select the iOS platform and enter a bundle ID.

Hit the 'Generate' button. Once finished, your app will have a Proximity Application ID, Secret and Callback URL.

Important You'll need your Proximity Application ID, Secret and Callback URL to run your app.

Register Your URL Scheme

For example if you registered test-app://authcode as your Callback URL, you would add test-app as your application URL Scheme. It should look like this.

Note For further information on Implementing Custom URL Schemes, please consult the Apple Documentation.

Set Your Proximity API Key and Secret

Add this code to the top of your AppDelegate implementation (.m) file.


#import <FYX/FYX.h>
        

Add this code to your didFinishLaunchingWithOptions: method, inserting your specific App ID, App Secret, and Callback URL.


[FYX setAppId:@"your-app-id" appSecret:@"your-app-secret" callbackUrl:@"your://app-url"];
        

Important The values you use for App ID, App Secret, and Callback URL should match the values from the Proximity API Key you created in the Developer Portal.

Start Proximity Service

This call registers the application with the server and starts bluetooth scanning.


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

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 The SDK will not function properly until the service has successfully started. If you attempt further calls into the SDK before receiving a callback indicating the service has successfully started, they will be rejected by the server.


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

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

Initialize the FYXVisitManager

This call creates a FYXVisitManager 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.


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

Implement The FYXVisitDelegate protocol

At this point the SDK will be scanning for Bluetooth transmission. In order for your app to received sightings, implement the following.

To receive sightings you must add the <FYXVisitDelegate> protocol to your class and set the delegate on your FYXVisitManager object.


    #import <FYX/FYXVisitManager.h>
    #import <FYX/FYXTransmitter.h>
    ...
    - (void)didArrive:(FYXVisit *)visit;
    {
        // this will be invoked when an authorized transmitter is sighted for the first time
        NSLog(@"I arrived at a Gimbal Beacon!!! %@", visit.transmitter.name);
    }
    - (void)receivedSighting:(FYXVisit *)visit updateTime:(NSDate *)updateTime RSSI:(NSNumber *)RSSI;
    {
        // this will be invoked when an authorized transmitter is sighted during an on-going visit
        NSLog(@"I received a sighting!!! %@", visit.transmitter.name);
    }
    - (void)didDepart:(FYXVisit *)visit;
    {
        // this will be invoked when an authorized transmitter has not been sighted for some time
        NSLog(@"I left the proximity of a Gimbal Beacon!!!! %@", visit.transmitter.name);
        NSLog(@"I was around the beacon for %f seconds", visit.dwellTime);
    }
        

Activate Your Beacon

Activation tells Gimbal to associate the Beacon with your account.

Note You'll need to open the Beacon to find the ID.

Activate Beacon »

Proximity Success

Once Gimbal Proximity detects the beacon you activated in the Gimbal Manager you will see a log entry that looks like this.


    2013-03-28 11:17:58.947 myproduct[11532:907] I received a FYX sighting!!! MyBeacon
                

Learn More

For additional details on how to leverage the SDK functionality, refer to the sample applications and documentation included in the zip file provided.

Gimbal Proximity iOS Guide »