Set up Android Studio

The first thing that we need to do before we can start writing code is configure Android Studio to properly use the SDK. 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, both to get an overview but also as a reference.

1. Create a new or use an existing Android project in Android Studio. Select Android KitKat (4.4) or higher as the minimum SDK (API version 19).
2. Unzip the provided SDK to some directory and then import the SDK by navigating to File -> New -> Import Module -> Select the unzipped directory. Then click File -> Project Structure -> Modules -> app -> Dependencies and press the green + button on the right -> Select module dependency and select the imported library module.
3. Now we will select Android Lollipop (API version 22) as the target SDK. Open build.gradle for the app module. Inside defaultConfig inside the android block, change targetSdkVersion to 22.

Integrate PBF

We will now go through the steps needed in order to fully integrate PBF in your code. All provided classes in the SDK are located inside the io.flic.poiclib package.

To make things easier, we have created a sample project that will be used as a base for this tutorial.

1. To be able to use the SDK, it must be initialized with the appId and appSecret you have retrieved from us that are unique to your application. To make sure this is done as the first thing when your app is started, it's recommended you subclass the Application class in Android. Then the code for initializing the library is placed inside the onCreate method: The AndroidManifest.xml must then be changed to use this new Application class, by adding the android:name attribute to the application tag:
2. The SDK is now ready to be used! The entry point for all functionality is through the FlicManager class, which is obtained by calling FlicManager.getManager(). We will now add functionality for scanning and adding new buttons. While SDK has support for simply scanning for available buttons, the highly recommended approach when creating a UI for adding buttons is to use the FlicScanWizard utility class that uses the manager to scan for buttons. Once a button has been found, a connection attempt will automatically be made and once everything is done, a new FlicButton object is passed on to the user of the SDK. It also deals with the possible timeouts and errors. Progress status is also reported which can be shown to the user. Code like this can be put into an activity to start the scan wizard: and since activities can be abruptly destroyed, scanning should be stopped if that happens:
3. To get all further events from the button, such as connected, disconnected and button presses, a listener must be assigned to the button object: Here we listen for button down / up events but we could also listen for click, double click or hold. Check out the available callback methods that can be overridden! If you want to have multiple event listeners you want to attach and detach you can also use the methods addEventListener and removeEventListener. If you intend to update UI in the callbacks, it's recommended to add an event listener that updates the UI when the UI is created and remove the event listener when the UI is destroyed. Note that all callbacks in this SDK are run on the UI thread.
4. All added buttons can at a later point be obtained from the manager by invoking getKnownButtons() or getButtonByBdAddr(String bdAddr), for example when the app has been restarted.
5. When the SDK is initialized, it will not attempt to connect to any buttons. You must yourself call the connect() on those buttons you want to be connected to. (The only exception is when a button object is given to you from the scan wizard, which internally calls connect() on the button object before it is given to you.) Then it will be put in a state where the SDK will automatically attempt to connect to the button when it disconnects (for example due to it gets out of range or Bluetooth has been restarted). To disconnect from a button, the disconnect() method can be called on a button object. Then it will no longer attempt to connect to the button. In order to connect to all previously paired buttons when the app is started, you can place this code in your Application class's onCreate method:

Working in the background

1. To avoid that the app is being killed by the system when one of its activities is not currently running, we need to have a foreground service. As long as a foreground service is running in the app process, the system should not kill the process. The service doesn't need to do anything - the important thing is that it is running.
2. We also have to add it in the AndroidManifest.xml file inside the application element. To start the service when the app boots, we could add the following code inside the onCreate() method on our PbfTestApplication class: Another possibility which should be used in reality would be to start the service when the user has a button he is listening to, and stop it once the user isn't interested any more in the button events.
3. A good thing for the user is to have the app start automatically when the device boots up or when the app is updated, so that bluetooth connections can be set up. Otherwise the user must start the app every time the device reboots for the buttons to work. This can be implemented with some broadcast receivers. We place these as inner classes inside our service: AndroidManifest.xml must be updated as well. First we add the used permissions inside the manifest element: we also add the new receivers inside the application element:

Thats it! You now have now implemented all the required methods in order to start experimenting with your buttons. You are encouraged to take a look at the PbfTest sample project that implements the code above and a little more. A recommendation is that, if you would like to have multiple things happening once the button is pressed, to register and deregister button listeners, just like how it's partly done in the sample project. That way you could have multiple UI elements that is updated on button presses as well as background actions. Note that when you add a FlicButtonListetner directly inside an activity whose callback methods directly changes UI, be sure the listener is removed when the activity is destroyed.