This document is Copyright of VIZpin Inc, 2020. The contents of this document are Confidential and intended solely for the recipient. Reproduction of, or forwarding to anyone not directly sent this document is strictly forbidden.

Installation

iOS 13.0+ is required

VIZpinSDK.Framework provides necessary functions to communicate with the VIZPin Server and the VIZpin Readers. This SDK is compatible with all VP1 series readers. A third party developer will be able to easily integrate this into their project by just dragging the framework to the project.

Under your project Build Phases, make sure VIZpinSDK.Framework is included in Link Binary with Libraries. Also add it to Embed Frameworks.

After the VIZpinSDK.Framework is added to your project. You should be able to #import VIZpinSDK.h to your source to access the methods.

Version Caveats

VIZpinSDK.Framework requires minimum SDK to be 13.0+. The sdk is tested on iPhone 5, iPhone 6 and iPhone 7.

iOS Permissions

In order to use VIZpinSDK with an iOS app, your app should include following permissions in the plist.

Privacy - Bluetooth Peripheral Usage Description >> [App Name] uses bluetooth to unlock VIZpin powered locks.

Also set Project Capabilities: Background Modes ON > Uses Bluetooth LE accessories

Constants

There are four static constants that the developer requires to acquire from VIZpin prior to the starting of the project. You will set these constants with the VIZpinSDK soon after you initialize the library.

APP_ID is a 16 byte UUID
APP_KEY is a 16 byte UUID
APP_NAME is a random name unique to your app
APP_KEY_VERSION is the version of the protocol and must be set to 1.1
APP_VERSION is the version unique to your app (format of "x.y.z" where x is the major version, y is the minor version and z is the patch)

Please contact support@vizpin.com to get the uuid values for APP_ID and APP_KEY constants. APP_VERSION and APP_NAME can be chosen by developer.

Important: The uuids should be all in capitalized hex values

Initializing SDK

VIZpinSDK.Framework contains a class VIZpinSDK. Following code snippet shows creating an object and initializing your app with the app constants. APP_VERSION should display <major.minor.patch> in numeric format.

    sdk = [[VIZpinSDK alloc] init];
    sdk.apiServer = @"<https://YOUR_SANDBOX_HERE.force.com/VIZpin/services/apexrest/sdk";>
    sdk.APP_ID = @"YOUR_APP_ID_HERE";
    sdk.APP_NAME = @"OEM AppName";
    sdk.APP_KEY = @"YOUR_APP_KEY_HERE";
    sdk.APP_KEY_VERSION = @"1.1";
    sdk.APP_VERSION = @"1.0.0";

    VPUser* user = [[VPUser alloc] init];
    user.phone = @"USER_PHONE_NUMBER";
    user.password = @"USER_PASSWORD";
    user.bluetooth = VIZpinSDK.BLE_MODE;

    [sdk initialize:user]; // Use this on an app start where you have cached user credentials
    // or
    [sdk initialize:nil]; // Use this on a fresh install where you have no cached user credentials

The apiEndPoint parameter denotes which server or sandbox to use as the end point of the SDK calls.

Note: The string passed on to apiEndPoint is of the form https://YOUR_SANDBOX_HERE.force.com/VIZPin/services/appexrest/sdk. Please contact support@vizpin.com to get the exact URL for your sandbox.

Note: You can also call long timestamp = [sdk getServerTime]; to get the SDK"s current value for the server time. This is useful for validating VPCredentials and the states and expirations.

Initializing Bluetooth

Verifying the bluetooth subsystem on your user"s phone is ON is the responsibility of the developer.

CBCentralManager* _centralManager = [[CBCentralManager alloc] initWithDelegate:nil queue:dispatch_queue_create("com.company.app", DISPATCH_QUEUE_SERIAL)     options:@{CBCentralManagerOptionShowPowerAlertKey:@YES}];

.....

if( _centralManager.state != CBCentralManagerStatePoweredOn ) { 
    // alert user that bluetooth is required
}

Note: Your app user could go into the settings and turn bluetooth on or off anytime during the operation of app. It is the developers responsibility to continue to monitor the bluetooth state and let user know to switch it back on.

Note: REQUEST_ENABLE_BT is a locally defined variable. It should be greated than 1.

Verify Connection

This function can be used to verify that your connection is valid and your credentials are correct. It also returns the current server time via timestamp. Like all functions there will be a VPError return object and a function specific callback to receive the results. Below is a sample use of this function:

Add User

New system Users are added to the server via the addUser function. This method takes only one parameter and that is a VPUser object. All properties of the VPUser except sms must be set for this function. As you can see below, all calls return a VPError object and you also specify a function specific callback object to handle the results of this function. The returned VPError object will only be non null when there is an issue with the parameters or the SDK configuration. Any errors that are encountered connecting to the server will be returned in the callback. The VPError returned in all callbacks will indicate success or failure. Each of the function specific callbacks will also echo back any VP**** objects that were passed in as parameters. Below is a sample use of this function:

Note: The country property of VPUser is in the [three letter iso code format] (https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3). The phone property of VPUser is the country code and the phone number concatenated together.

Verify User

Verification is used to have the User received an SMS to their phone number to prove they own this device. Only the phone, password and sms properties of the VPUser need set for this function. If you want to reset a users password, simply send a different password that the server has and it will be udpated. Like all functions there will be a VPError return object and a function specific callback to receive the results. Below is a sample use of this function:

Authenticate User

Authentication logs this User into the server to be able to perform other funtions. Once you have successfullly set everything up you can authenticate manually at startup or pass the same VPuser into the initialize function and the SDK will authenticate for you as needed. Only the phone and password properties of the VPUser need set for this function. Like all functions there will be a VPError return object and a function specific callback to receive the results. Below is a sample use of this function:

Note: If a mismatch of properties is detected, you may need to call resetUser to send a new SMS verification code to the User and then call verifyUser to verify it.

Reset User

Sometimes a User may get a new device or have a mismatch between the values in the SDK and the server. Calling resetUser will cause an SMS to be sent to this User"s phone so that their device information may be verified. This can also be used to resend an SMS if the User had trouble receiving it. This is also how you can initiate a password reset. Only the phone property of the VPUser needs set for this function. Like all functions there will be a VPError return object and a function specific callback to receive the results. Below is a sample use of this function:

Update User

Occassionally a User may need to change their bluetooth mode (BTC vs BLE) or User name. The User must be in an authenticated state and not in a pending verification state. Only the phone property of the VPUser must be set and the bluetooth, first and last properties are optional for this function. Like all functions there will be a VPError return object and a function specific callback to receive the results. Below is a sample use of this function:

Request Access

A User must complete registration before they can be granted access. This function provides a way to allow a User to notify the Account manager that they have finished registration and want access. Each Account on the server is given a unique seven character code that can be given to future Users to be entered when they finish. The User must be in an authenticated state and not in a pending verification state. This function only takes the location ID for this specific Account. Like all functions there will be a VPError return object and a function specific callback to receive the results. Below is a sample use of this function:

Get Credentials

We generally refer to our VPCredentials as VIZpins on the server but the SDK is designed to abstract that slightly. Each VPCredential has a private version that is stored in the SDK. This includes the encrypted token that allow for this VPCredential to unlock one of our VP1 or EZ1 Readers. This private version may also contain confiugration messages (called LINK messages) that will be sent automatically to a Reader during the unlock process. The VPCredentials you will receive from this function contain a lot of metadata describing this VPCredential. This will include address and contact information (entered in the Account on the server previously) and the name given to the Reader. It will also contain a number of timestamps which describe the current access window start/stop times, when it expires, the local time at the Reader, timezone of the Reader, etc. These are all integer seconds since January 1, 1970 and in UMT. Depending on the Account type on the server, some VPCredentials will have varying expiration and others may need reverified from the server every 4 hours. The getCredentials function will handle this for you automatically using local cache when it can and connecting to the server as needed but you can override this behavior. You have the ability to force retrieval from local cache; this is useful at startup or when the device has no connection. You also have the ability to force a refresh from the server; this is useful on a User requested refresh or if you want to force the download of LINK messages to send to the Reader.

VPCredential new field: keyStatus
VPCredential Status of the Key values can be: ACTIVE, INACTIVE or EXPIRED.

Periodically call getCredentials from your app to get the updated keys and status of the keys. Make sure that every time you do this, the user interface gets updated. Recommended frequency of call to getCredentials from the app is every minute.

Like all functions there will be a VPError return object and a function specific callback to receive the results.

Below is a sample use of this function:

Note: Each entry in the HashMap is for a different Reader and the key is their serial number (e.g. 8000001 or 4000001). The list that is the value for this entry will contain all the VPCredentials that this User has for this Reader. It most cases this will be a list of one item but certain modes allow for multiple VPCredentials per Reader.

Note: The VPCredential object has a function called getStatus that will interpret the timestamps concerning access for you. It takes a single parameter which is the time the SDK has that matches the server. You can get this time from the SDK via the getServerTime function. This function will return one of three statuses: VPCredential.EXPIRED (usually happens if you forceCache, requires a forceRefresh update call to the getCredentials function), VPCredential.INACTIVE (you have a valid VPCredential but are outside of its access window, this may be a 9-5 access but it is midnight), VPCredential.ACTIVE (you have valid VPCredential and can use it in a call to unlockReader)

Note: As the time is constantly changing, it is generally advised to set a timer for once a minute to call getCredentials with both parameters false to make sure you have the most up to date Credentials and statuses

Detect Readers

The SDK has the ability to scan continuosly for VP1 and EZ1 Readers while your app is running. This helpful as you can know what Readers are in range and available for unlocking and also to hide or disable VPCredentials in your UI for Readers that are not available. This function will start and also stop the scan. In general, you should expect the callback function to be called approximately every two seconds with the current list of VPReaders that are detected. The VPReader contains its serial number and other status information obtained from the bluetooth advertisements and has an indicator of signal strength will can be used for sorting, etc. Using this function is not a prerequsite for calling unlockReader but it makes for a better UX and will speed up your unlocks. You must supply the same callback object for the stop invocation that you sent for the start invocation. Like all functions there will be a VPError return object and a function specific callback to receive the results. Below is a sample use of this function:

Note: You must call detectReader with false to stop the scan when your application goes to the background. You can call it again with true when you application becomes active. You should not expect to receive continuous updates on the callback while your application is not active. The operating system will turn off our bluetooth access in the background as this is very costly to battery life.

Unlock Reader

Unlocking a Reader is one of the key functions of the SDK. You must supply a VPCredential that has the serial number of the VPReader that you want to unlock. If you have previously called detectReaders, the serial number of the reader you want to unlock must be in local cache or you will receive an error. If you haven"t called detectReaders, then the SDK will do a several second scan to try to detect the VPReader that you are trying to unlock. If it isn"t found in that time, you will receive a failure status in the callback. When the unlock has happened and the Reader object has informed us of success, you will receive the status in the callback. You can NOT unlock two VPReaders at the same time. You must wait for the one to complete before unlocking another one. You will receive an error in another unlock is still in progress. Keep in mind that part of the unlock process is to send configuration LINK messages to the Reader and to pull audits from the Reader which are then sent to the server.

UnlockReader now checks the status of the key, and cancels the unlock if the status of the key is EXPIRED or INACTIVE.

Like all functions there will be a VPError return object and a function specific callback to receive the results. Below is a sample use of this function:

Appendix: Objects

VPError

VPUser

VPCredential

VPReader

VIZpin Public Knowledge Base

VIZpin iOS SDK Documentation