This article will guide you step by step on how you can integrate the spintly access sdk into your app.  Spintly do provide a sample app and sample app source code on how the app can integrate with the spintly access sdk, if you havent got the app please contact Spintly for the same, as the sample app will help you understand things faster. For this SDK integation to happen you need to either do the type2 or type3 integration.

Once the client is done integrating the sdk in thier app, the app needs to be sent to spintly for review, this review is needed so that the sdk  is properly used in the client app in accordance to spintly standard, Once spintly approves the app, the client can go ahead and release the app on playstore and appstore. 

Please note you cannot integrate spintly access sdk standalone, it will always go hand in hand with the api

1 Changes required in the client app to support Spintly SDK 

There are certain steps we need to follow at different stages of the app flow. Following are the locations where sdk-related changes need to be added. 

1. During app initialization 

2. After login 

3. Mandatory checks 

4. Getting a list of doors 

5. Starting Bluetooth scan 

6. Opening doors 

7. On notification 

8. Logout 

2 SDK Details 

Spintly integration requires the following SDKs to be used by the client app: 

1. OAuth SDK: This SDK is used for getting a Spintly access token in exchange for the user's client jwt token. 
2. Access control SDK: This SDK contains the actual access control functionality

3 High-Level Overview

Spintly uses Auth 2.0 Token Exchange, for more information please visit this site:

https://datatracker.ietf.org/doc/html/rfc8693

Here in the diagram you can see the JWT token is given to the OAuth SDK and in return, the OAuth SDK returns the access token. This access token is then passed to the Spintly access control SDK.

4 During App Initialization: OAuth SDK

Before using the SDK, the app developer needs to specify the clientId, providerId and environment. The clientId and providerId will be provided by the Spintly Support person to the app developer. The environment will be specified by the developer based on whether the developer is building the app for production or a sandbox environment. Different clientId and providerId will be provided for the production and sandbox environment.

import {SpintlyOauthManager} from ‘react-native-spintly-oauth’ 
var clientId = “778fa826-79ac-4325-be8b-c55f7b123ee0”; 
var provider = “6f2243f0-eeda-450c-bd96-c0b56bfcf04f”; 
var environment = SpintlyOuathManager.PRODUCTION //SANDBOX 
var spintlyOauthManager = new SpintlyOauthManager(clientId, provider, 
environment) 

5 During App Initialization: Access Control SDK 

Just like the OAuth SDK on the previous page, the environment needs to be set for the access control SDK after its instance is initialized.

import {EnvironmentManager} from ‘react-native-spintly-access-control’; 
EnvironmentManager.setEnvironment(EnvironmentManager.PRODUCTION) .then(_ => { 
//environment set 
}) 
.catch(error => { 
//thrown if invalid argument passed 
}) 
//To get current environment 
EnvironmentManager.getEnvironment() 
.then(environment => { 
console.log(environment) 
}) 

6 After login: OAuth SDK 

The user's client jwt token which was obtained after the user logged in to the app, needs to be passed to the OAuth SDK. The OAuth SDK in return will give back a Spintly access token.

Note: Here the user's client JWT token contains a unique Id that identifies a particular user, this unique Id must be added to Spintly using the Spintly backend APIs. 

import {AuthorizationCallback, AuthenticationDetails} from ‘react-native-spintly-oauth’ 
const callback: AuthorizationCallback = { 
onSuccess(session) { 
var accessToken = session.accessToken.token 
//To be passed to other Spintly services that make use of this token 
}, 
onFailure(error) { 
console.error("Error", error) 
}, 
getAuthenticationDetails(continuation) { 
// this is called when user is logged out or all tokens have been expired and // need login parameters again from client. 
// For Token Exchange grant type authorization: 
continuation.authenticationDetails = 
AuthenticationDetails.createWithTokenExchangeGrantType(_clientToken) 
continuation.continueTask() 
// If clientToken was not available when this function was called, 
// hold on to the continuation reference and once clientToken is acquired, 
// repeat the above steps. 
// Or call getSession again and repeat the process 
} 
} 
//to create a new session. It will generate new token on every call 
spintlyOauthManager.createSession(callback) 
//to get an existing session if exists. 
//It will return existing token if still valid otherwise create new token 
spintlyOauthManager.getOrCreateSession(callback) 

7 After login: Access Control SDK 

The Spintly access token that is generated by the OAuth SDK is then passed to the Spintly access control SDK. After this step succeeds, functionalities of the access SDK can be used.

import {CredentialManager} from ‘react-native-spintly-access-control’; 
CredentialManager.logIn(_accessToken) 
.then( 
_ => { 
console.log("Registration success") 
} 
) 
.catch( 
error => { 
console.log("Error", error) 
} 
) 
//Calling above function will first logout existing credential even on login failure credentialManager.logOut() //Logout existing credential if present 
//Note: an access token will have an expiry. Client is responsible to update access token on the event that it is expired. An event listener can be attached in the following way. This event is sent whenever an api call fails due to access token expiry 

Note: The Spintly access token will have an expiry. Client is responsible to update Spintly access token on the event that it is expired. The refreshAuthentication() trigger means that the access SDKs token has expired. When this trigger is received:

1. The AuthorizationCallback() of the OAuth SDK that was used earlier can be used.
2. A fresh clientToken needs to be passed to the getAuthenticationDetails() of the AuthorizationCallback.
3. spintlyOauthManager.getOrCreateSession(callback); can be used instead of the createSession()
4. Upon receiving the Spintly access token in onSuccess() of AuthorizationCallback use it in the next step.
5. With the new access token client app completes the refreshAuthentication() function’s callback i.e. completionCallback.complete(newAccessTokenString);
6. If the AuthorizationCallback gave a failure, still client app should complete this function’s callback i.e. completionCallback.failed(error);

An event listener can be attached in the following way. As mentioned, this event is sent whenever an API call fails due to access token expiry.

import {CredentialManager} from ‘react-native-spintly-access-control’; 
import {DeviceEventEmitter} from ‘react-native’ 
CredentialManager.EVENT_ACCESS_TOKEN_EXPIRED 
//To add subscription 
let subscription = DeviceEventEmitter.addListener(CredentialManager.EVENT_ACCESS_TOKEN_EXPIRED, _ =>{ 
//Update the token now or at later time 
}) 
//Remove subscription when component is unmounted to avoid memory leaks 
subscription.remove() 
//Once new token is available 
CredentialManager.updateAccessToken(_newAccessToken) 
.then( 
_ => { 
console.log("Updated") 
} 
) 
.catch( 
error => { 
console.log("Error", error) 

We have noticed that the SDK login can fail due to server or network errors. In this case the app is responsible to retry login to the SDK for the following cases. 

1. Check on every app launch 
2. Schedule a job that fires on internet access availability 
3. Check on permission update notifications (if implemented) 

Please check if the user is already logged in the app first before calling the SDK login. This is important as the login process first performs an internal logout which can cause a logged-in user to get logged out if there are network issues.

8 Getting list of access points

This snippet of the code explains how to get all the devices to which a particular user has permission to.

import {PermissionManager} from ‘react-native-spintly-access-control’; 
PermissionManager.getAccessPoints() 
.then(accessPoints => { 
//To get id, name of specific access point 
var id = accessPoints[n].id 
var name = accessPoints[n].name 
}) 
// This is a list of Access Point the user has access to. 
// To get update of when this list changes, attach an event listener in the following way //To add subscription 
let subscription = DeviceEventEmitter.addListener(PermissionManager.EVENT_PERMISSIONS_UPDATED, _ =>{ 
// call PermissionManager.getAccessPoints again and refresh your view (if present) }) //Remove subscription when component is unmounted to avoid memory leaks 
subscription.remove() 

9 Starting the Bluetooth Scan 

Once the user is logged in or once the user has opened the app and got the app in foreground, a check has to be made to use bluetooth based functionality i.e.

• For all Android versions, the bluetooth of the phone needs to be turned on for access to work via BLE.
• For Android version less than equal to 11: Check if bluetooth and location permissions are granted and prompt the user to turn on bluetooth and location. Here Nearby devices permission is not required.
• For Android version greater than equal to 12: Check if Nearby devices permission is granted and prompt the user to turn on bluetooth. Here the location permission and the tuning on of location is not required for access to work.

For android 6.0 and above till android 11.0, BLUETOOTH permission is required for bluetooth communication to work and the BLUETOOTH_ADMIN permission to scan for BLE devices and to be able to turn on the phone’s bluetooth.

Also, in these versions (android 6.0 and above till android 11.0), ACCESS_COARSE_LOCATION or ACCESS_FINE_LOCATION permission is required and location (network mode) is to be turned on.

Along with that, for android 10.0 and above till android 11.0, the background location ACCESS_BACKGROUND_LOCATION permission is necessary for proximity/tap to access to work in the background.

For android 12.0 and above, the Nearby devices permission is required while the location permission or location turn on is not required. The Nearby devices permission in UI translates in code to BLUETOOTH_SCAN, BLUETOOTH_ADVERTISE and BLUETOOTH_CONNECT permissions, all of which are required. For the BLUETOOTH_SCAN permission a flag needs to assert that the scan is not for deriving physical location. See below how to mention it:
https://developer.android.com/develop/connectivity/bluetooth/bt-permissions#assert-never-for-location 

This is a mandate required by android for scanning close by BLE devices. See more about requesting location permissions from the customer at runtime below:
https://developer.android.com/develop/sensors-and-location/location/permissions#request-location-access-runtime 

Since BLUETOOTH, BLUETOOTH_ADMIN and the location related permissions are required only upto android 11.0, the maxSdkVersion needs to be set to 30 (android 11) for these permissions. See below how to use it:
https://developer.android.com/develop/connectivity/bluetooth/bt-permissions 

Note: These permissions need to be requested from the user and granted along with turn on of bluetooth (and location in respective versions) before the next step of starting bluetooth scan of the access SDK. Since granting of these permissions requires user interactions it is left to the client app to implement it. However, for better understanding, below are examples of the dialogs 

that should be presented to the customer to grant access in the respective scenarios. The client app can rely only on the system generated pop ups to get permissions from the user and to turn on the bluetooth and location. However, in-app pop ups with custom messages give the user more context on why the permissions and service turn on are required for access to work.

Bluetooth turn on in app prompt:

Bluetooth turn on system dialog:

Bluetooth Nearby Devices in app permission prompt:

Nearby Devices system permission dialog:

Location access permission in app prompt:

Location access permission system prompt:

Background location permission shown by app (for android 10 and 11):

Background location permission system settings (allow all the time should be selected below):

Location turn on in app prompt:

Location turn on system dialog:

The below snippet of code explains how to start the bluetooth scan.

Note: Without this step, the customer won't be able to access the doors to which they have access. 

import {AccessManager} from ‘react-native-spintly-access-control’; 
AccessManager.startBleScan() 
.then( 
_ => { 
console.log("ble start") 
} 
).catch( 
error => { 
console.log("Error ble", error) 
} 
) 

Note: Along with starting of the scan each of these checks should be done each time the app comes in the foreground (not just when the app is opened) to account for the fact that the user might have turned off one of the required services or might have removed one of the permissions.

10 On Notifications 

This snippet of the code explains the function that needs to be called whenever the access point permissions are updated in the backend (from the client backend to Spintly backend). When such permission changes happen, it’s the job of the client backend to alert the client app that permissions have changed. When the app receives the notification, it needs to call the poll data function. This will cause the SDK to receive the new permissions from the Spintly backend.

import {CloudSyncManager} from ‘react-native-spintly-access-control’; 
CloudSyncManager.pollData() 
.then( 
_ => { 
console.log("Polled succesfully") 
} 
) 
.catch( 
error => { 
console.log("Error", error) 
} 
) 

11 Opening the Doors 

Spintly provides 3 options to open the doors:
Click to Access: This works well for use cases of listing all the doors in the app UI such that the customer can see them, and click on a specific door to unlock it
Tap to Access: Here user just needs to tap the phone on the unit and the door will open
Proximity Access: Here the phone needs to be within the proximity of the device 

The tap to access and proximity access can be enabled or disabled in the Spintly backend.

Click to Access
If he wants to list the doors and wants to open the door by click to access, then he needs to use the following snippet. 

import {AccessManager} from ‘react-native-spintly-access-control’; 
var requestedPoint = accessPoints[n]; // Requested access to a specific access point 
AccessManager.bleUnlockAccessPoint(requestedPoint.id, 
(accessPointId, tag) => { 
//Called on successful unlock 
//accessPoint id indicates the id of access point which is same as what was passed to the function //tag represents which device was unlocked out of the multiple devices attached to the access point }, 
(errorName, errorMessage) => { 
//Called on any error or timeout encountered 
console.log(errorName, errorMessage) 
} 
) 
// To unlock closest access point call the following function 
AccessManager.bleUnlockClosestAccessPoint( 
(accessPointId, tag) => { 
//Called on successful unlock 
//accessPoint id indicates the id of access point which was unlocked 
//tag represents which device was unlocked out of the multiple devices attached to the access point }, 
(errorName, errorMessage) => { 
//Called on any error or timeout encountered 
console.log(errorName, errorMessage) 
} 
) 
// Only one unlock at a time is supported as of this moment so please avoid calling this function again without the previous one returning success/error. 

12 Mobile NFC access 

The Spintly access SDK supports NFC based access for mobile phones which have NFC hardware. For NFC access to work, it is the responsibility of the client app to show the user prompts to turn on the mobile’s NFC if the mobile has NFC hardware. If these requirements are fulfilled then NFC based tap to access will work if access SDK login is done. However, NFC based access only supports tap to access and will not support other modes via pure NFC.

Tap to access can then be used only via NFC and turning off bluetooth. However, it is advised to suggest the users to use both NFC and bluetooth for seamless access.

For better understanding, below are the dialogs that should be presented to the customer to grant access to phone NFC.
NFC turn on in app prompt:
 

NFC system settings:

Note: Each time the app comes into the foreground, it is the responsibility of the client app to show a prompt to the user if the NFC is not turned on which has to be independent of and parallel to BLE pop ups.

15 On logout

When the user logs out of the app, it is also important that the app first stops the BLE scan and then logs out from both the SDK i.e. the OAuth SDK and Access Control SDK. The following snippet of code does the job. 

AccessManager.stopBleScan() 
credentialManager.logOut() 
spintlyOauthManager.clearSession();