API Reference

The react-native-sdk uses the event emitter and subscription model. Each LIVE Lock BLE process/function emits events upon successful or unsuccessful completion.

To add an event listener

addEventListener(eventName, callBackFn);

To remove a listener

removeEventListener(eventName);

Usage

    import { addEventListener, removeEventListener } from 'react-native-sdk';
    addEventListener('event-name', (event)=>{
        ... Do something.
    })

    // removes the listeners of particular event name
    removeEventListener('event-name');

List of supported events

Here is a list of supported events, their associated event parameters, and possible values. The event parameters consists of key value pairs as { Key : "Value"}.

• onDiscoveryStarted

  • type : "discoveryEvent"

• onDiscoveryStopped

  • type : "discoveryEvent"

• onDiscoveryFailed

  • type : "discoveryEvent"

• onLiveLockFound

  • type : "discoveryEvent"
  • name : <Device_name> as String
  • serialNumber : <Device_SerialNumber> as String

• onLiveLockExpired

  • type : "discoveryEvent"
  • name : <Device_name> as String
  • serialNumber : <Device_SerialNumber> as String

• onConnected

  • type : "liveLockEvent"
  • Name : <Lock_name> as String
  • serialNumber : <Lock_SerialNumber> as String

• onConnectionFailure

  • type : "liveLockEvent"
  • Name : <Lock_name> as String
  • serialNumber : <Lock_SerialNumber> as String

• onDisconnected

  • type : "liveLockEvent"
  • Name : <Lock_name> as String
  • serialNumber : <Lock_SerialNumber> as String

• onUnlockComplete

  • type : "liveLockEvent"
  • Name : <Lock_name> as String
  • serialNumber : <Lock_SerialNumber> as String
  • result : true or false as boolean

• onSetUnlockTimeoutComplete

  • type : "liveLockEvent"
  • Name : <Lock_name> as String
  • serialNumber : <Lock_SerialNumber> as String
  • result : true or false as boolean

• onSetAdvertisementRateComplete

  • type : "liveLockEvent"
  • Name : <Lock_name> as String
  • serialNumber : <Lock_SerialNumber> as String
  • result : true or false as boolean

• onPropertyReadComplete

  • type : "liveLockEvent"
  • Name : <Lock_name> as String
  • serialNumber : <Lock_SerialNumber> as String
  • result : true or false as boolean
  • advertisementRate : 250 to 5000 milliseconds
  • lockTimeout : 1 to 65535 milliseconds

• onLockStatusChange

  • type : "lockStatusEvent"
  • name : <Locks_name> as String
  • lockStatus as String : enum ['LockedAndLatched', 'UnLockingAndLatched', 'UnLockedAndLatched', 'UnLockedAndUnlatched', 'LockingAndUnlatched', 'LockingAndLatched', 'LockedAndUnLatched', 'LockingErrorAndLatched', 'LockingErrorAndUnlatched', 'LockingErrorLatchedAndStalled', 'UnlockingErrorAndLatched', 'UnlockingErrorAndUnlatched', 'UnlockingError', 'LockingError', 'UnknownState']

• onEnrollmentDataReadComplete

  • type : "liveLockEvent"
  • Name : <Lock_name> as String
  • result : true or false as boolean
  • Install: <install_key> as String
  • Serial: <Lock_serialNumber> as String

• onSetLockEnrolledComplete

  • type : "liveLockEvent"
  • Name : <Lock_name> as String
  • serialNumber : <Lock_SerialNumber> as String
  • result : true or false as boolean

Instance methods

A number of functionality and access points are provided by the SDK. The available methods are listed below.

1. initializeCustCertificate(customerCertificate: string)

Initializes Customer Certificate in the app.

The application must initialize the Customer Certificate before interacting with a lock.

@param customerCertificate - Customer Certificate in base64 encoded string
@returns - Object : {success: boolean, error: string}

error = ['CUST_CERT_NOT_FOUND',
         'INVALID_CUST_CERTIFICATE',
         'EXPIRED_CUST_CERTIFICATE',
         'SOMETHING_WENT_WRONG']

• Example:

import { initializeCustCertificate } from "react-native-sdk";
const isInitialized = await initializeCustCertificate(
  "base64 customerCertificate"
);

2. addDiscoveryManagerObserver()

Registers native discovery manager observer. This function is required for native API to emit events related to lock discovery.

• Example:

   import { startScan, addDiscoveryManagerObserver, removeDiscoveryManagerObserver } from 'react-native-sdk';
   await startScan(20000);
   // add the following event listeners to listen the scanning events
   addDiscoveryManagerObserver(); // to register native ble observers
   addEventListeners('onDiscoveryStarted', (event) => { ...do something with event})
   addEventListeners('onDiscoveryFailed', (event) => { ...do something with event})
   addEventListeners('onLiveLockFound', (event) => { ...do something with event}) // event tells you about the discovery of the livelock.
   removeDiscoveryManagerObserver(); // to remove native ble observers.

3. removeDiscoveryManagerObserver()

De-registers native discovery manager observer.

• Example:

import { removeDiscoveryManagerObserver } from "react-native-sdk";
removeDiscoveryManagerObserver(); // to remove native ble observers.

4. startScan(retentionPeriodMs: number)

Starts the scanning process.

@param {number} retentionPeriodMs - the duration of time in milliseconds that a discovered LIVE Lock will stay cached.

• Example:

   import { startScan } from 'react-native-sdk';
   await startScan(20000);
   // add the following event listeners to listen the scanning events
   addDiscoveryManagerObserver(); // to register native ble observers
   addEventListeners('onDiscoveryStarted', (event) => { ...do something with event})
   addEventListeners('onDiscoveryFailed', (event) => { ...do something with event})
   addEventListeners('onLiveLockFound', (event) => { ...do something with event}) // event tells you about the discovery of the livelock.
   removeDiscoveryManagerObserver(); // to remove native ble observers.

5. stopScan()

Stops the scanning process.

• Example:

import { stopScan } from "react-native-sdk";
await stopScan();

6. connectUsingCertificate(serialNumber: string, keyCertificate: string, mtu: number)

Verifies the key certificate with customer certificate and initiates connection with a lock.

@param {string} serialNumber - lock's serialNumber
@param {string} keyCertificate - Key Certificate in base64 encoded format for lock to initiate connection. This certificate can be acquired when a lock is provisioned.
@param {number} mtu - maximum transmission unit.
@returns {Object} {verified: boolean, error: string}

error = ['CUST_CERT_NOT_FOUND',
         'KEY_NOT_FOUND',
         'INVALID_KEY',
         'INVALID_CUST_CERTIFICATE',
         'EXPIRED_CUST_CERTIFICATE',
         'SOMETHING_WENT_WRONG']

• Example:

import { connectUsingCertificate } from "react-native-sdk";
const isConnected = await connectUsingCertificate(
  "lock serial",
  "base64 key certificate",
  250
);

7. disconnect(serialNumber: string)

Disconnects app from LIVE Lock.

@param {string} serialNumber - lock's serialNumber

• Example:

import { disconnect } from "react-native-sdk";
await disconnect("lock-serial");
// to listen to the events of disconnect use "onDisconnected"

8. getLiveLockList()

Returns a list of discovered LIVE Locks nearby.

• Example:

import { getLiveLockList } from "react-native-sdk";
const nearByLocks = await getLiveLockList();

9. getLiveLock(serialNumber: string)

Gets a nearby LiveLock by serial number.

@param {string} serialNumber - lock's serialNumber

• Example:

import { getLiveLock } from "react-native-sdk";
const liveLock = await getLiveLock("lock-serial");

10. setAdvertisementRate(serialNumber: string, rate: number)

Sets the advertisement packet rate.

@param {string} serialNumber - lock's serialNumber
@param {number} rate - Advertisement rate in milliseconds (Min = 250, Max = 5000, Default = 250)

• Example:

import { setAdvertisementRate } from "react-native-sdk";
await setAdvertisementRate("lock-serial", 250);
// to listen to the events of set advertisement rate use "onSetAdvertisementRateComplete"

11. setUnlockTimeout(serialNumber: string, timeOut: number)

Sets the unlock timeout in the LIVE Lock, which controls how long a lock will stay unlocked before it automatically locks itself.

@param {string} serialNumber - lock's serialNumber
@param {number} timeOut - Unlock timeout in milliSeconds

• Example:

import { setUnlockTimeout } from "react-native-sdk";
await setUnlockTimeout("lock-serial", 4000);
// to listen to the events of set unlock timeout use "onSetUnlockTimeoutComplete"

12. readProperties(serialNumber: string)

Read all current LIVE Lock properties.

@param {string} serialNumber - lock's serialNumber

• Example:

import { readProperties } from "react-native-sdk";
await readProperties("lock-serial");
// to listen to the events of read properties use "onPropertyReadComplete"

13. unlock(serialNumber: string, timeOut: number)

Sends the unlock command to the LIVE Lock.

@param {string} serialNumber - lock's serialNumber
@param {number} timeOut - Unlock Timeout in milliSeconds

• Example:

import { unlock } from "react-native-sdk";
await unlock("lock-serial", 4000);
// to listen to the events of unlock use "onUnlockComplete"

14. getEnrollmentCode(serialNumber: string)

Read the json-based enrollment code data from lock.

@param {string} serialNumber - lock's serialNumber

• Example:

import { getEnrollmentCode } from "react-native-sdk";
await getEnrollmentCode("lock-serial");
// to listen to the events of get enrollment code use "onEnrollmentDataReadComplete"

15. setLockEnrolled(serialNumber: string)

Sets the enrollment for the lock.

@param {string} serialNumber - lock's serialNumber

• Example:

import { setLockEnrolled } from "react-native-sdk";
await setLockEnrolled("lock-serial");
// to listen to the events of set enrolment flag use "onSetEnrolmentFlagComplete"

16. addLockStatusObserver()

Start lock status native observer for the current lock.

• Note: why do we need it? While performing any activity with The lock it is essential to consistently monitor the lock's State
  based on the lock state we handle the screen state in the application accordingly.

@param {string} serialNumber

• Example:

   import { addLockStatusObserver } from 'react-native-sdk';
   addLockStatusObserver(SerialNumber);
   // after observer is set for the current lock, we have set an event "onLockStatusChange" listener for that lock.
   addEventListener('onLockStatusChange', params => { ... params will give the lock state})

• Event Parameters
  • type : "lockStatusEvent",
  • name : <Locks_name> as String.
  • lockStatus as String

Below is a list of possible lock states.

Locked:

• LockedAndLatched
• LockedAndUnLatched
• LockingErrorAndLatched

Latched:

• LockedAndLatched
• UnLockingAndLatched
• UnLockedAndLatched
• LockingAndLatched
• LockingErrorAndLatched
• LockingErrorLatchedAndStalled
• UnlockingErrorAndLatched

Unlatched:

• UnLockedAndUnlatched
• LockingAndUnlatched
• LockedAndUnLatched
• LockingErrorAndUnlatched
• UnlockingErrorAndUnlatched

17. removeLockStatusObserver()

Stop lock status native observer for the current lock

• Example:

import { removeLockStatusObserver } from "react-native-sdk";
removeLockStatusObserver("remove lock status observer");
// remove the Lock Status observer of the current Lock.