Overview

SDK's

info

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

SDK Details

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

1. OAuth SDK

   • Indented item
   • Indented item

2. Access control SDK

   • Indented item
   • Indented item

High-Level Overview

• Spintly uses Auth 2.0 Token Exchange, for more information please visit this site.Spintly Doc
• 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.

During app initialization: OAuth SDK

Context context = getApplicationContext()
String clientId = "aabbasssd....";
String provider = "assaa....";
String environment = SpintlyOauthManager.PRODUCTION //or
SpintlyOauthManager.SANDBOX
SpintlyOauthManager spintlyOauthManager = new SpintlyOauthManager(context,
clientId, provider,environment)

• Before using the SDK, the developer needs to specify the clientid , provider, and environment. The clientid and provider id will be provided by Spintly Support person to the 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 providers will be provided for the production and sandbox environment.

During app initialization: Access Control SDK

String environment = EnvironmentManager.PRODUCTION // or
EnvironmentManager.SANDBOX
EnvironmentManager environmentManager =
serviceProviser.getEnvironmentManager(environment)
environmentManager.setEnvironment(environment)
//This function will throw error if unknown environment is passed
//If you want to know the current environment
String currentEnvironment = environmentManager.getEnvironment()

Just like the OAuth SDK in the previous slide, the environment needs to be set for the access control SDK

After login: OAuth SDK

Authorization callback = new AuthorizationCallback() {
@Override
public void onSuccess(SpintlyOauthSession session) {
String accessToken = session.accessToken.getJWTToken();
//To be passed to other Spintly services that make use of this token
}
@Override
public void getAuthenticationDetails(AuthenticationContinuation
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:
AuthenticationDetails authenticationDetails =
AuthenticationDetails.createWithTokenExchangeGrantType(clientToken);
continuation.setAuthenticationDetails(authenticationDetails)
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
}
@Override
public void onFailure(Exception exception) {
// Any error including network errors will come here;
}
}
spintlyOauthManager.createSession(callback);
//This will create new token on every call

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 an 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 SpintlyBackend Apis.

After login: Access Control SDK

//Supports only one credential at this moment
CredentialManager credentialManager =
serviceProvider.getCredentialManager();
credentialManager.logIn(accessToken, new CompletionCallback<Void>() {
@Override
public void completed(Void result) {
//login success
}
@Override
public void failed(Throwable exc) {
//login failure
}
}
//Calling above function will first logout existing credential even on
login failure
credentialManager.logOut() //Logout existing credential if present
//Note: a token refresh handler must be registered prior to logging in any
user. This should be
added in application onCreate itself.

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

note

The Spintly access token will have an expiry. Client is responsible to update Spintly 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.

//In application onCreate()
CredentialManager credentialManager =
serviceProvider.getCredentialManager();
credentialManager.setTokenRefreshHandler() {
@Override
public void refreshAuthentication(CompletionCallback<String>
completionCallback) {
asyncUpdateAccessTokenByCustomAppLogic(
newAccessToken -> completionCallback.complete(String),
error -> completionCallback.failed(error)
);
}
@Override
public void onRefreshFailed() {
// Will be called if re-authentication failed and a manual call to
// credentialManag

Mandatory Checks

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 see if Bluetooth and location are on. If Bluetooth and location are not on then access functionality won't work. A check has to be made by the app to see if the SDK is logged in when the app comes to the foreground or when the app is opened along with bluetooth and location check.

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.