Skip to content

Integrating the SDK

Understanding how it works

Global introduction

This SDK has been created to help you interacting with GA SmartBuilding BLE Access Controllers. As a developer using this SDK, you will not have to handle any BLE interaction, but just call a few methods to give the SDK more context about your user, and a few listeners to handle some events.

Getting a badge number

Before being able to interact with controllers, you will need to register your user and device so they can receive a badge number that you will then be able to send to your backend to allow building managers to setup the user's access. Two flows are available:

  • A self-serve flow with the user requesting its own badge
sequenceDiagram
    Your App->>+SDK: Initializes with Application ID
    User->>+Your App: Signs in
    Your App->>+SDK: Sets the User ID
    Your App->>+SDK: Requests a badge number
    SDK->>+Badge Server: Requests a badge number
    Badge Server->>+SDK: Returns a badge number
    SDK->>+Your App: Returns a badge number
    Your App->>+Your Backend: Send the badge number
    Your Backend->>+Your Backend: Associates the badge number to the user
  • An invitation flow with the user getting its badge through an invitation
sequenceDiagram
    Your Backend->>+Badge Server: Requests a badge for a user
    Badge Server->>+Your Backend: Returns a badge number and an invitation token
    Your Backend->>+User: Sends the invitation token
    User->>+Your App: Opens
    Your App->>+SDK: Initializes with Application ID
    User->>+Your App: Signs in
    Your App->>+SDK: Sets the User ID
    User->>+Your App: Fills the invitation token
    Your App->>+SDK: Requests a badge number with invitation token
    SDK->>+Badge Server: Requests a badge number with invitation token
    Badge Server->>+SDK: Returns a badge number
    SDK->>+Your App: Returns a badge number

Exchanging with a controller

Contrary to what you might expect, it's not the mobile device that will initiate the connection to the controller, but the controller that will initiate the connection to the mobile device. The controller and the mobile device will then exchange a few security credentials before getting the result of the authentication.

sequenceDiagram
    Controller->>+Mobile Device: Initiates the connection
    Mobile Device->>+Controller: Returns credentials
    Controller->>+Mobile Device: Returns the authentication state (success / failure)
    Controller->>+Door: Opens or keeps closed

Strong authentication

Some controllers will be setup as sensitive and will request a confirmation from the user. While we strongly recommend using biometrics, it is up to the developer to choose what kind of authentication is best for its application. It could be biometrics, PIN code or user password.

sequenceDiagram
    Controller->>+Mobile Device: Initiates the connection
    Mobile Device->>+Controller: Accepts the connection
    Controller->>+Mobile Device: Requires a strong authentication
    Mobile Device->>+User: Prompts an authentication (biometrics, PIN...)
    Mobile Device->>+Controller: Returns the authentication state (success / failure)

Requirements

  • iOS: 13 / Android: 7

You will need the following informations provided by GA SmartBuilding:

  • An Application ID

Getting started

Here is a quick start on how to install and setup the SDK in your app. You can also require access to test apps with the SDK already integrated.

Installing the SDK

iOS

  • Import xcframework file on xCode to target's Framework, Libraries and Embedded Content as Embed and Sign
  • Add NSBluetoothAlwaysUsageDescription on your info.plist
  • Install Alamofire and PromiseKit on your iOS Project
  • For React Native apps, you could have to add use_frameworks! on your Podfile
  • Add on Xcode, Signing and Capabilities of your target the background mode: "Act as a Bluetooth LE accessory"

Android

  • Copy the .aar file in a /app/libs folder
  • Add the following inside dependencies of /app/build.gradle
  • implementation fileTree(dir: "libs", include: ["*.aar"])
  • Add the following permissions on your Manifest
    <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
    <uses-permission android:name="android.permission.BLUETOOTH_ADMIN" />
    <uses-permission android:name="android.permission.BLUETOOTH_ADVERTISE" />
    <uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />
    <uses-permission android:name="android.permission.BLUETOOTH_SCAN" />
    <uses-permission android:name="android.permission.BLUETOOTH" />
    <uses-permission android:name="android.permission.INTERNET" />

Initializing the SDK

First, you will need to initialize the SDK by providing your Application ID, User ID as well as a few options.

iOS

You just have to create an instance of GASmartAccessReaderSDK in a GASmartAccessReaderDemoDelegate class:

class YourClass: GASmartAccessReaderDemoDelegate {
    public static var SDKInstance: GASmartAccessReaderSDK!

    init() {
        GASmartAccessReaderDemo.SDKInstance = GASmartAccessReaderSDK(delegate: GASmartAccessReaderDemoDelegate, logLevel: LogLevel?, userID: String, applicationId: String, iControlUrl: String)
    }
}

Android

Instanciate the SDK on your onCreate function

class YourClass {
    lateinit var sdk: GASmartAccessReaderSDK

    override fun onCreate(savedInstanceState: Bundle?) {
        ...
        sdk = GASmartAccessReaderSDK(context: Context, callbacks: GASmartAccessReaderDemoCallbacks, applicationId: String, iControlUrl: String, userID: String)
        ...
    }
}

Identifying a user

Once your SDK has been initialized, you will need to identify your user as soon as it is known. The badge generator does not need to know any personal information about your user. It will only require an ID that will allow your backend to reconciliate a badge number with a user.

Warning: You have to fetch the badge ID before using startBluetoothAdvertisingDemo.

iOS:

If you have already fetched it before, the badge will be send through onACSInitialized listener.

Else, there's a Public class with all the methods you need to use the SDK. You'll have to run Public.shared.fetchBadgeID to fetch it from ACS.

Then, the delegate onBadgeIDUpdated(_ badgeID: String) will return the badgeID.

Android:

If you have already fetched it before, the badge will be send through onACSInitialized listener.

Else, you'll have to run sdk.getBadgeId() to get it from ACS

Then, the listener onBadgeIDUpdated(badgeID: Int) will return the badgeID.

Listening to events

Setup

iOS

When you initialize the SDK, you'll have to inherit your class with GASmartAccessReaderDemoDelegate. Once done, you just have to add all the listeners on your class as functions. Example:

class YourClass: GASmartAccessReaderDemoDelegate {
    ...

    func onBadgeIDUpdated(_ id: String) {
        // Do something with id
    }

    ...
}

XCode will create all these functions for you (and cannot build if they're not present).

Android

You need to create a GASmartAccessReaderDemoCallback object with all the listeners then pass it to the instanciation of the SDK Example:

class YourClass {
    ...

    private var callbacks: GASmartAccessReaderDemoCallback = object : GASmartAccessReaderDemoCallback {
        override fun onBadgeIDUpdated(badgeID: Int) {
            // Do something with badgeID
        }
    }

    override fun onCreate(savedInstanceState: Bundle?) {
        ...

        sdk = GASmartAccessReaderSDK(context, callbacks, "appID", "userID")
    }
}

When BLE state changed

This event is called as soon as BLE state changed on your device

  • iOS: onBLEStateChanged(state: CBManagerState)
  • Android: onBLEStateChanged(state: Int)

When the recon starts / stops

This event is called as soon the BLE is made available and open / unavailable or closed to connections.

onLockReconStateChanged(isStarted: Bool)

When there are scanned SARs nearby

When the BLE is open, the SDK is scanning nearby SARs. This event return them.

  • iOS: onScannedSARUpdate(device: CBPeripheral)
  • Android: onScannedSARUpdate(device: BluetoothDevice)

Then you can use connectToSAR method to connect and unlock SAR

Example:

iOS
Public.shared.connectToSAR(device)
Android
sdk.centralManager.connectToSAR(applicationContext, device)

When a controller requires a user authentication

This event is called when the controller requires the user to authenticate because it has strong security. While we strongly recommend using biometrics, it is up the the developer to choose what kind of authentication is best for its application. It could be biometrics, PIN code or user password.

onLockAuthenticationRequest(callback: (isSuccess: Bool))

You'll have to use the callback parameter method to inform the SDK that the auth request is success or failure.

When scan state is updated

onScanStateUpdate(isScanning: Bool)

When everything went right

This event is called when the exchange with the controller has been completed and that the badge has been authorized by the controller.

onLockAuthStateUpdated(isSuccess: AuthState)

AuthState = { locked, loading, unlocked, error }

When there was an error

This event is called when there was an error during the BLE exchanges between the controller and the mobile device.

onLockError(errorKey: ErrorKey)

It can send the following errors:

  • API_ERROR: When the API throw an error
  • APPKEY_GENERATE_ERROR: When the app keys generation failed
  • BLE_ERROR: When a BLE error occured
  • DATA_LEN_NOT_MATCHING: When the data length of SAR request or response is not matching the documentation
  • INVALID_B64: When getting an invalid base 64 string
  • PROCESSOR_ERROR: When getting a frame processor error
  • UNKNOWN_FRAME_KEY: When getting an unknown frame keys during proccessing

When you need logs

An event is available to get SDK Logs: onLogUpdated(message: String)