Shortcut Labs

Stockholm, Sweden

Powered By Flic - iOS Tutorial

Set up Xcode

The first thing that we need to do before we can start writing code is configure Xcode to properly use fliclib. This example will show you how to set up a very basic application with background execution enabled. However, this example only shows a small portion of the available functionality, so make sure to read the full API documentation as well.

  1. Import the fliclib.framework file to your project.
  2. Under Project Settings -> Build Settings, set the flag Allow Non-modular includes in Framework Modules to Yes.
  3. Under Settings -> General, remove fliclib.framework from Linked frameworks and Binaries since it will be automatically added in the next step.
  4. Now, on the same view, press the + sign under Embedded Binaries and add fliclib.framework from the list. This should add fliclib.framework to Linked frameworks and Binaries as well.
  5. Since we are making an application that will need to communicate with buttons in the background we need to tell iOS that we want those kinds of permissions. We do this by checking the Uses Bluetooth LE accessories option under the Capabilities tab of our project settings.
  6. While this next step is optional we strongly recommend that you do it. As stated in the Implementation Guidelines document, there are a few scenarios where your app will not be woken up by bluetooth related events despite using the background capabilities for it. By subscribing to significant location changes your application will be able to function properly even after these scenarios. This will allow your application to be woken up on Bluetooth resets such as when the user toggles Flight Mode, but also after system reboot. In order to do this you have to enter descriptive strings to your plist file that explains the reason for the use of significant location changes. The strings are for the keys NSLocationAlwaysUsageDescription and NSLocationUsageDescription.

    In this case I just simply added Better use of bluetooth, but Apple will review this so you should add something that fits your application better.

Integrate PBF

We will now go through the steps needed in order to fully integrate PBF in your code. We will do it in a blank Xcode project.

  1. Import fliclib/fliclib.h wherever it suits your application the best. In this basic example we will just add it to the view controller header file. We also went ahead and added the both Button and Manager delegate protocols.
  2. In the implementation file we need to configure the manager singleton that will be used throughout the application. In this case we did so in the viewDidLoad method. The appID and appSecret parameters are unique to your application and will be provided to you by Shortcut Labs. The background execution flag specifies whether or not you intend to use the buttons in the background. Since we in this example will use background execution, we will set it to YES.
    You must declare the variables appID and appSecret somewhere.
  3. Since the manager is configured and ready to use we will now try and discover new buttons by starting a scan. You most likely will want the scan of buttons to only start on some sort of user interaction. In this example we will assume that you have created a UI element that is tied to the IBAction startScanAction.

    Once that action is called we first start by checking if we already have a button available. This is of course not necessary if you want your application to handle more than one button. After that we start the scan by calling the startScan method of the manager singleton. It is always a good idea to automatically stop the scan after a while to avoid that it is running for longer periods of time by mistake. It this example we automatically turn it off after 15 seconds. We also turn off the scan in the button discovery callback since it does not make sense to keep it running after that point. Since we want to start using the button immediately we also connect it here.
    Please notice that this is just a very basic example on how to scan for buttons. If you would like an example on how to implement this scan flow in a proper way then take a look at the linked files
  4. The delegate methods that we have implemented up to this point are essentially the only ones that are required in order to start communicating with a button. However, you will probable want to add at least a few more, such as the ones displayed below.
    Please take a look at the API documentation to get a more complete overview of how the framework works and what it has to offer.
  5. If you decided to use significant location changes then we also have to add code for that in the project.
    The above example shows an example on how to add significant location changes to your App Delegate file.

Thats it! You now have now implemented all the required methods in order to start experimenting with your buttons.

Last updated: 2016-04-19