Integrating the BlueID SDK for Mobile
Difference to older versions
In previous versions, it was required to add two separate frameworks (i.e. libraries) into your app to use ACaaS, and the APIs of these frameworks differed a lot compared to the ones of IDaaS. With version 4 of the BlueID SDK for iOS and Android, this changed as the standard SDKs integrate the ACaaS functionality using APIs that are close to the ones you might already know.
Please note: If want to update an app that used the Access SDK in an older version than 4, the lock list might be empty and you need to synchronize the app!
The SDK for Mobile offers both variants, IDaaS and ACaaS. Normally, the project scope defines which one to choose. From an SDK perspective, we leave you completely free hand in your choice, but please don't mix up both APIs in your application!
This documentation mainly covers BlueID ACaaS and its usage with BlueID onTouch, because the API of ACaaS and IDaaS are very similar. When there's a difference in the APIs, we will outline them.
Where to start from
The SDKs are bundled with an ACaaS example application which covers most topics of an BlueID-enabled app. If you feel more comfortable with code, simply dive into the code or continue reading this documentation if you want a more theoretical approach.
Differences to IDaaS
As you can see from the sample code, the entrance to BlueID is the class BlueIDAccess. If you use IDaaS, on iOS this is BlueIDMobileDevice and on Android SdkForAndroid.
The distribution of the BlueID SDK for Android contains an Android Archive (AAR) which can be directly included in your app project. Apart from that, it also contains a Gradle file which includes the third party libraries we depend on.
You don't have to declare any BlueID-related permissions yourself in the manifest, this is done by our library automatically. But you have to make sure to set the compatibility level of your application to Java 8.
The distribution of the BlueID SDK for iOS contains a framework which you simply have to add to your app project.
Apart from that, you have to declare some custom iOS target properties (see onTouch section)
The 3 basic functions
Every BlueID app, no matter if IDaaS or ACaaS, covers three basic functions: Initialization, synchronization and command execution.
Please note: All these three functions are implemented on iOS in a non-blocking way with a callback, while on Android, these are blocking and require you to run them in a thread other than the main thread!
To initialize an ACaaS-powered mobile device, you need a personalized one-time invitation code that is mapped to a specific resident and only valid for a certain amount of time.
This is done by sending an e-mail invitation to a resident in the ACaaS backend. This e-mail is customizable through the administrative area in the ACaaS frontend of the tenant where you cannot only change the text but also the URL scheme to match the app you want to use. It is necessary that you know this URL scheme and that your app listens to the correct URL scheme. When a user gets an invitation mail and clicks on the link inside it, the browser automatically redirects to your application and starts the initialization process.
During initialization, the SDK creates a cryptographic entity, registers the instance of the app at the BlueID backend and maps it to the resident that received the invitation. From now on, the resident is able to access locks with the permissions that were granted by the tenant.
The initialization of an app stays the same until either you - the developer - choose to destroy this BlueID instance, or the user decides to remove the app.
Differences to IDaaS
IDaaS does not know residents but only mobile devices, secured objects (i.e. locks) and tokens (i.e. permissions). When you use the IDaaS API and want to initialize a mobile device, you need an API key instead of an invitation. This API key is not personalized but valid for the whole ecosystem of that operator. Therefore, you require the knowledge of the mobile device ID that was generated during the initialization process in order to create tokens for that device.
It's also important to know that when using IDaaS, you can choose a keychain security level on iOS: BlueIDKeychainSecurityLevelBackgroundTasksEnabled matches the one used on ACaaS which gives you control over the BlueID SDK even if the app is in background (e.g. for synchronizing the app in the background) whereas BlueIDKeychainSecurityLevelHigh requires the app to be in the foreground.
App-specific configuration for initialization
For this part, we assume that the tenant configured that the app listens to the URL scheme my-blueid-app.
On Android, you have to specify an intent filter for your activity that includes a data tag with the scheme my-blueid-app.
On iOS, you have to configure it through Xcode by going to your app's "Info" settings and then adding a new URL Type with the appropriate URL scheme ("my-blueid-app" on the example above) and role "Viewer"
Testing initialization process for development
As already mentioned, you normally need an adapted tenant to match your personal URL scheme. Then you just send an invitation to your e-mail address and open that in your smartphone. If that's not possible for some reason, there are ways to emulate that.
The easiest one would be to install a QR code scanner app on your phone. Then
- copy your invitation link
- go to a QR code generator website
- paste your invitation link there
- change the URL from
- scan that URL which should open the app
On Android, you can also use ADB to send the changed URL like
adb shell am start -a android.intent.action.VIEW -d "my-blueid-app://invitation?code=<YOUR CODE>.
After a mobile was initialized, we need to synchronize it to fetch the permissions that were granted to us from the backend. We encourage you to trigger the synchronization regularly, so that the user always has the right information and doesn't wonder why a command execution failed.
Three ways of synchronization are:
- periodically while the app is in background
- automatically when the app enters foreground
- automatically by notifications from the backend
Currently, there's no support for either way in the SDK but the first two ones are trivial to implement. Please see Apple's UserNotifications framework and Google's Firebase Cloud Messaging in order to implement push notifications.
To keep things simple, in the BlueID Example App we only support manual synchronization.
Let's get to the part that BlueID was built for: Sending commands to an object, i.e. opening a lock! Now we synchronized our keys to the mobile device, we are able to use them to authorize ourselves to a lock.
In ACaaS, this is very simple: You just select an lock say "execute command!" with any additional info. Of course - if you want to for any good reason - you are free to define all parameters like channel and command yourself, but you don't have to. By default, BlueID chooses to use Bluetooth Smart as channel and the "tokn" command as this is the default command when creating a key in Access.
The command execution will either fail with an error (iOS) or exception (Android) or return a command execution response with a code and probably some data.
Differences to IDaaS
On IDaaS, the BlueIDMobileDevice instance is the mainstay of the SDK. So you also need to trigger a command execution by this API and you have to tell the SDK which channel and which command to use. You can iterate through the available (meaning: you have tokens for that that are now valid) ones using the SecuredObject interface.