Zum Inhalt

Implementing onTouch

BlueID onTouch

The onTouch technology allows the user to open a lock or pass through a turnstile just by presenting the phone to a reader. There is no need to open an app and to press a button anymore which leads to a shorter waiting time, a higher throughput and more convenience for the user.

Adding onTouch support to an app is fairly easy: Just start it and implement a callback that handles feedback. If you want, you can add some options.

Talking about locks, only permanently-powered readers that support both Bluetooth Smart and NFC communication with smartphones support the BlueID onTouch technology! Please ask your BlueID sales representive for more information.

Implementing the callback

When you implement your app for iOS, the callback is simply BlueIDAccessOnTouchDelegate which you can nicely integrate in your controller or elsewhere and directly access, for example, visual elements.

On Android it's a bit different and a bit more complicated due to Android's runtime architecture. Unfortunately, you can't simply implement the methods of AccessOnTouchCallback, but you have to create a separate class for this and hand this over to the BlueID SDK. This means that you need a mechanism to communicate with your activity. In the demo application, this is done using intents.

Common callback methods
devicesDiscovered

Once started, BlueID onTouch scans continuously for BlueID devices in your vicinity that you have got permissions for. By default, the SDK informs the callback every 500 ms about new devices. You change that by using setDeviceReportDelay (Android) or setting reportDelayMilliseconds (iOS).

selectCommandForLock

If this method returns null (Android) or nil (iOS), the default command "tokn" is taken. Normally, you don't have to adjust this but it makes sense to set it, for example, if you want to implement some maintenance functionality in your app.

commandExecutionStarted

This method gets called when an onTouch command execution is started in the background.

commandExecutionResult

This method gets called when an onTouch command execution was finished. If it was successful, you receive an command execution response (like if you executed the command manually) or an error object.

Android specific callback

If your app runs on a device with an Android version prior to 8, it's required to show a permanent notification to the user in order to keep the app alive. Though it's not guaranteed that the operating system will not kill the app,

By implementing the getLegacyForegroundNotification callback, the BlueID SDK can take care of showing this notification to the user.

Triggering a command execution

On iOS-based smartphones, Bluetooth Smart is the way to go whereas on Android, as long as the mobile device supports NFC, NFC is the preferred and required interface due to some serious performance bugs in the Android Bluetooth implementation. Although on Android, you as a developer can override the choice of the SDK when starting onTouch.

To do a command execution with onTouch, you have to put your phone near to the reader. While it is quite clear what that means for NFC, we have to dig a bit deeper to understand this using Bluetooth and the configuration options we have.

When using wireless communication protocols, like Bluetooth, the RSSI values indicates the signal strength, which gives a very rough estimation of the distance between a sender and a receiver. As a general rule, the signal strength value gets higher the nearer the objects come to each other and the possible values range from 0 (nearest distance) to -100 (farthest distance).

BlueID onTouch comes preconfigured with reasonable default values and sets the threshold for a command execution attempt via Bluetooth to -60 by default. This means, the RSSI value the smartphone measures must be -60 or higher. It then connects to the reader which itself reads the RSSI value to make sure the smartphone is really close to it and continues the command execution. Otherwise, it will just drop the connection.

If the threshold is configured to be very low, like -80 or even lower, it means that the smartphone tries to connect very early, even if it might be rejected by the reader, but this may lead to a shorter command execution duration. On the other hand if the threshold is too high, e.g. -40 or higher, it means that in worst case, the command execution will never happen because the reader is in a metallic case or the NFC antenna of the phone is positioned badly. So choosing the right threshold is always a tradeoff between distance and command execution speed and dependent on the use case.

Configuration options

BlueID onTouch gives you freedom to completely configure every aspect of it in order to meet your requirements. This table gives you an overview:

Function Android iOS Default value
set preferred communication channel for onTouch (BLE or NFC) setChannel not applicable depends on phone
set required RSSI threshold if app is in foreground setRSSIThresholdInForeground rssiThresholdInForeground -60
set required RSSI threshold if app is in background setRSSIThresholdInBackground rssiThresholdInBackground -60
set required RSSI threshold setRSSIThreshold rssiThreshold -60
enable/disable automatic onTouch command execution setOnTouchExecutionEnabled automaticOnTouchCommandExecution true
enable/disable scan for BlueID onTouch devices setScanForBlueIDonTouchDevicesEnabled scanForOnTouchDevices true
enable/disable scan for standard BlueID devices setScanForBlueIDDevicesEnabled scanForStandardDevices true
set interval for devicesDiscovered setDeviceReportDelay reportDelayMilliseconds 500
minimum delay after an onTouch command execution for the next one on the same lock setDelayAfterSuccess delaySecondsAfterSuccess 2000
minimum delay after a failed onTouch command execution for the next one on the same lock setDelayAfterFailure delayAfterFailureMilliseconds 500
mitigation for Android bug: minimum delay after successful onTouch execution in background with Bluetooth setDelayAfterSuccessBackground not applicable 20000
App-specific configuration for onTouch
Android

The BlueID SDK for Android library comes with a Manifest.xml that already contains all required settings. But when onTouch is started, it might fail with a MissingOnTouchRequirementException. It is then up to you as the app developer to ask the user for the appropriate permissions. The BlueID Example App gives you a blueprint of what you have to do.

iOS

iOS requires that your app declares that it always requires Bluetooth and that it requires it also in the background. These settings have to be done in the "Custom iOS Target Properties". Only if this was declared and the user accepts it, onTouch works flawlessly.

The following settings have to be done:

Name Key  Value
Privacy - Bluetooth Always Usage Description NSBluetoothAlwaysUsageDescription Required for BlueID to work
Required background modes UIBackgroundModes bluetooth-central