Theme
React Native
The package @clevibox/react-native is a thin layer over the native SDK of each platform. It shows no screen and no dialog: your app asks for the permissions, and your app shows the progress.
Requirements
- React Native 0.80 or later, with the New Architecture. Clevibox tests the package with React Native 0.84.
- Android: a phone with Android 7.0 or later, and Kotlin 2.1 or later in the Android build. React Native 0.84 brings Kotlin 2.1.20.
- iOS: an iPhone or iPad with iOS 15.0 or later. The simulator has no Bluetooth.
- An app with native code. In an Expo project, that is a development build: the package does not run in Expo Go.
Add the SDK
sh
npm install @clevibox/react-nativeFor iOS, install the pods after that:
sh
cd ios && pod installReact Native links the package by itself. It needs no line in your native projects.
Before the first release
The package is not on npm yet. Until then, Clevibox sends you the SDK files. Their README.md says how to install the package from a file.
Permissions on Android
The SDK declares its permissions in its own manifest, so your manifest needs no new line. Your app asks the member at run time. Ask when the member first comes to the screen of the locker, and say why.
ts
import { PermissionsAndroid, Platform } from 'react-native';
async function askForBluetooth() {
if (Platform.OS !== 'android') return;
const permissions =
Platform.Version >= 31
? [PermissionsAndroid.PERMISSIONS.BLUETOOTH_SCAN, PermissionsAndroid.PERMISSIONS.BLUETOOTH_CONNECT]
: [PermissionsAndroid.PERMISSIONS.ACCESS_FINE_LOCATION];
await PermissionsAndroid.requestMultiple(permissions);
}Android 12 and later have the two Bluetooth permissions. Android 11 and older need the location permission for a Bluetooth scan.
Bluetooth permission on iOS
Add the key NSBluetoothAlwaysUsageDescription to ios/<your app>/Info.plist, with a text that says why your app uses Bluetooth. Without it, iOS stops the app at its first use of Bluetooth.
xml
<key>NSBluetoothAlwaysUsageDescription</key>
<string>The app uses Bluetooth to open your locker.</string>iOS shows its Bluetooth dialog when an app creates its first Bluetooth manager. The SDK creates none before the member has allowed Bluetooth, so the SDK never causes that dialog. Your app picks the moment, with a small native module of its own. Add this file to your app target in Xcode, for example as BluetoothPrompt.m:
objc
#import <CoreBluetooth/CoreBluetooth.h>
#import <React/RCTBridgeModule.h>
@interface BluetoothPrompt : NSObject <RCTBridgeModule, CBCentralManagerDelegate>
@end
@implementation BluetoothPrompt {
CBCentralManager *_manager;
}
RCT_EXPORT_MODULE(BluetoothPrompt)
+ (BOOL)requiresMainQueueSetup
{
return NO;
}
- (dispatch_queue_t)methodQueue
{
return dispatch_get_main_queue();
}
// Creates one Bluetooth manager and keeps it. iOS then shows its dialog, when the member has
// not answered it yet. The manager never scans and never connects.
RCT_EXPORT_METHOD(raise)
{
if (_manager != nil) {
return;
}
_manager = [[CBCentralManager alloc] initWithDelegate:self
queue:nil
options:@{CBCentralManagerOptionShowPowerAlertKey : @NO}];
}
- (void)centralManagerDidUpdateState:(CBCentralManager *)central
{
}
@endCall it from JavaScript when the member first comes to the screen of the locker:
ts
import { NativeModules, Platform } from 'react-native';
function raiseBluetoothDialog() {
if (Platform.OS === 'ios') NativeModules.BluetoothPrompt?.raise();
}The answer of the member shows in checkReadiness.
Set up
Call configure once, at the start of your app. It starts no Bluetooth and no network activity.
ts
import { Clevibox } from '@clevibox/react-native';
Clevibox.configure();While you develop, Clevibox.configure({ logLevel: 'DEBUG' }) writes progress lines to the log of the platform.
Check before an opening
checkReadiness tells you if an opening can work now. It shows nothing, and it asks the member for nothing.
ts
const readiness = await Clevibox.checkReadiness();
if (!readiness.ready) {
// Bluetooth is off, or a permission is missing.
}| Field | Values |
|---|---|
ready | true when Bluetooth is on and no permission is missing. |
bluetooth | 'ON', 'OFF', 'UNAUTHORIZED', 'UNSUPPORTED' or 'UNKNOWN'. |
missingPermissions | On Android: 'BLUETOOTH_SCAN', 'BLUETOOTH_CONNECT' and 'LOCATION'. On iOS: 'BLUETOOTH'. |
On iOS, bluetooth is 'UNKNOWN' before the member has answered the dialog, and 'UNAUTHORIZED' after the member has blocked Bluetooth. iOS does not show the dialog a second time, so send the member to the settings of your app then.
The SDK makes the same check at the start of each call. A call that fails this check does not use up its grant.
Open the door
Get a grant from your server, and hand it to open. See Your server. The functions with a name like showProgress are your own.
ts
import { Clevibox } from '@clevibox/react-native';
const call = Clevibox.open(grant, { onPhase: (phase) => showProgress(phase) });
const result = await call.result;
if (result.type === 'opened') {
showOpened();
} else if (result.type === 'cancelled') {
showIdle();
} else {
showFailure(result.error);
}call.result never rejects. A failure is a result with the type failed.
The phases
| Phase | What the SDK does |
|---|---|
'REDEEMING' | It checks the grant with Clevibox. |
'CONNECTING' | It looks for the lock, and it connects. |
'VERIFYING' | It makes sure that it reached the right lock. |
'OPENING' | It sends the command that opens the door. |
'DONE' | The lock took the command. |
'CONNECTING' can come a second time in one call. When the link to the lock fails before the open command goes out, the SDK connects once more by itself.
The result
result.type | Meaning |
|---|---|
'opened' | The lock opened. The member can pull the door open now. |
'cancelled' | Your app cancelled the call. |
'failed' | The call failed. result.error has a code, a message for a developer, and retryable. See Error codes. |
Rules
- One grant serves one call. For a new attempt or a second opening, get a new grant from your server.
- One call runs at a time. A second call fails at once with
OPERATION_IN_PROGRESS. So lock your Open button while a call runs. - Keep your screen up until the result is there. iOS pauses an app in the background, and a paused call ends only when the app is back.
call.cancel()stops a running call. Its result has the typecancelled.- Accept an error code that your app does not know. A later version of the SDK can add one.
After the door opens
The latch comes back by itself after about 5 seconds. The member opens the door in that time, and pushes it shut later by hand. Then the door is locked again.
The lock cannot tell if its door is shut. So opened says that the lock opened, and it says nothing about the door after that. Tell your members to push the door shut.
Read the latch
readStatus connects to the lock, reads the state of the latch once, and disconnects. Most apps do not need it. It needs a grant of its own.
ts
const call = Clevibox.readStatus(grant);
const result = await call.result;
if (result.type === 'read') {
showLatch(result.status.latchOut);
} else {
showFailure(result.error);
}latchOut is true when the latch is out. That is its usual state: a door that is shut is locked then.
