Skip to main content

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
    • serialNumber : <Lock_SerialNumber> as string
    • result : true or false as boolean
    • Dynamic enrollment data fields (varies by lock type)

  • 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 "@invue/react-native-sdk";
const result = await initializeCustCertificate("base64 customerCertificate");

if (result.success) {
  console.log("Certificate initialized successfully");
} else {
  console.error("Certificate initialization failed:", result.error);
}

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,
  addEventListener,
  LiveAccessSdkEvents,
  type DiscoveryStartedEvent,
  type DiscoveryFailedEvent,
  type LiveLockFoundEvent,
} from "@invue/react-native-sdk";

await startScan(20000);

// Register native BLE observers
await addDiscoveryManagerObserver();

// Add typed event listeners
addEventListener<DiscoveryStartedEvent>(
  LiveAccessSdkEvents.DISCOVERY_STARTED,
  (event) => {
    console.log("Discovery started");
  }
);

addEventListener<DiscoveryFailedEvent>(
  LiveAccessSdkEvents.DISCOVERY_FAILED,
  (event) => {
    console.log("Discovery failed");
  }
);

addEventListener<LiveLockFoundEvent>(
  LiveAccessSdkEvents.LIVE_LOCK_FOUND,
  (event) => {
    console.log("Found lock:", event.name, "Serial:", event.serialNumber);
  }
);

// Remove native BLE observers when done
await removeDiscoveryManagerObserver();

3. removeDiscoveryManagerObserver()​

De-registers native discovery manager observer.​

  • Example:
import { removeDiscoveryManagerObserver } from "@invue/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,
  addEventListener,
  LiveAccessSdkEvents,
  type DiscoveryStartedEvent,
  type DiscoveryFailedEvent,
  type LiveLockFoundEvent,
} from "@invue/react-native-sdk";

await startScan(20000);

// Add typed event listeners for scanning events
addEventListener<DiscoveryStartedEvent>(
  LiveAccessSdkEvents.DISCOVERY_STARTED,
  (event) => {
    console.log("Discovery started");
  }
);

addEventListener<DiscoveryFailedEvent>(
  LiveAccessSdkEvents.DISCOVERY_FAILED,
  (event) => {
    console.log("Discovery failed");
  }
);

addEventListener<LiveLockFoundEvent>(
  LiveAccessSdkEvents.LIVE_LOCK_FOUND,
  (event) => {
    console.log("Found lock:", event.name, "Serial:", event.serialNumber);
  }
);

5. stopScan()​

Stops the scanning process.

  • Example:
import { stopScan } from "@invue/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 (optional, defaults to 23).
@returns {Promise<ConnectUsingCertificateResult>} {success: 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 "@invue/react-native-sdk";

const result = await connectUsingCertificate(
  "lock serial",
  "base64 key certificate",
  250
);

if (result.success) {
  console.log("Connection successful");
} else {
  console.error("Connection failed:", result.error);
}

7. disconnect(serialNumber: string)​

Disconnects app from LIVE Lock.

@param {string} serialNumber - lock's serialNumber

  • Example:
import {
  disconnect,
  addEventListener,
  LiveAccessSdkEvents,
  type DisconnectedEvent,
} from "@invue/react-native-sdk";

await disconnect("lock-serial");

// Listen to disconnect events with typed events
addEventListener<DisconnectedEvent>(
  LiveAccessSdkEvents.DISCONNECTED,
  (event) => {
    console.log(
      "Disconnected from:",
      event.name,
      "Serial:",
      event.serialNumber
    );
  }
);

8. getLiveLockList()​

Returns a list of discovered LIVE Locks nearby.

  • Example:
import { getLiveLockList } from "@invue/react-native-sdk";
const nearByLocks = await getLiveLockList();

9. getLiveLock(serialNumber: string)​

Gets a nearby LiveLock by serial number.

@param {string} serialNumber - lock's serialNumber
@returns {Promise<LiveLock | null>} - Returns LiveLock object or null if not found

  • Example:
import { getLiveLock } from "@invue/react-native-sdk";

const liveLock = await getLiveLock("lock-serial");
if (liveLock && liveLock.serialNumber) {
  console.log("Found lock:", liveLock.name);
  console.log("Serial:", liveLock.serialNumber);
} else {
  console.log("Lock not found");
}

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

Sets the advertisement packet rate.

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

  • Example:
import {
  setAdvertisementRate,
  addEventListener,
  LiveAccessSdkEvents,
  type SetAdvertisementRateCompleteEvent,
} from "@invue/react-native-sdk";

await setAdvertisementRate("lock-serial", "250");

// Listen to set advertisement rate events with typed events
addEventListener<SetAdvertisementRateCompleteEvent>(
  LiveAccessSdkEvents.SET_ADVERTISEMENT_RATE_COMPLETE,
  (event) => {
    console.log("Set advertisement rate result:", event.result);
    console.log("Lock:", event.name, "Serial:", event.serialNumber);
  }
);

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,
  addEventListener,
  LiveAccessSdkEvents,
  type SetUnlockTimeoutCompleteEvent,
} from "@invue/react-native-sdk";

await setUnlockTimeout("lock-serial", 4000);

// Listen to set unlock timeout events with typed events
addEventListener<SetUnlockTimeoutCompleteEvent>(
  LiveAccessSdkEvents.SET_UNLOCK_TIMEOUT_COMPLETE,
  (event) => {
    console.log("Set unlock timeout result:", event.result);
    console.log("Lock:", event.name, "Serial:", event.serialNumber);
  }
);

12. readProperties(serialNumber: string)​

Read all current LIVE Lock properties.

@param {string} serialNumber - lock's serialNumber

  • Example:
import {
  readProperties,
  addEventListener,
  LiveAccessSdkEvents,
  type PropertyReadCompleteEvent,
} from "@invue/react-native-sdk";

await readProperties("lock-serial");

// Listen to read properties events with typed events
addEventListener<PropertyReadCompleteEvent>(
  LiveAccessSdkEvents.PROPERTY_READ_COMPLETE,
  (event) => {
    console.log("Read properties result:", event.result);
    console.log("Advertisement rate:", event.advertisementRate);
    console.log("Lock timeout:", event.lockTimeout);
    console.log("Lock:", event.name, "Serial:", event.serialNumber);
  }
);

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,
  addEventListener,
  LiveAccessSdkEvents,
  type UnlockCompleteEvent,
} from "@invue/react-native-sdk";

await unlock("lock-serial", 4000);

// Listen to unlock events with typed events
addEventListener<UnlockCompleteEvent>(
  LiveAccessSdkEvents.UNLOCK_COMPLETE,
  (event) => {
    console.log("Unlock result:", event.result);
    console.log("Lock:", event.name, "Serial:", event.serialNumber);
  }
);

14. getEnrollmentCode(serialNumber: string)​

Read the json-based enrollment code data from lock.

@param {string} serialNumber - lock's serialNumber

  • Example:
import {
  getEnrollmentCode,
  addEventListener,
  LiveAccessSdkEvents,
  type EnrollmentDataReadCompleteEvent,
} from "@invue/react-native-sdk";

await getEnrollmentCode("lock-serial");

// Listen to enrollment data read events with typed events
addEventListener<EnrollmentDataReadCompleteEvent>(
  LiveAccessSdkEvents.ENROLLMENT_DATA_READ_COMPLETE,
  (event) => {
    console.log("Enrollment data read result:", event.result);
    console.log("Lock:", event.name, "Serial:", event.serialNumber);
    // Dynamic enrollment data fields available in event
  }
);

15. setLockEnrolled(serialNumber: string)​

Sets the enrollment for the lock.

@param {string} serialNumber - lock's serialNumber

  • Example:
import {
  setLockEnrolled,
  addEventListener,
  LiveAccessSdkEvents,
  type SetLockEnrolledCompleteEvent,
} from "@invue/react-native-sdk";

await setLockEnrolled("lock-serial");

// Listen to set lock enrolled events with typed events
addEventListener<SetLockEnrolledCompleteEvent>(
  LiveAccessSdkEvents.SET_LOCK_ENROLLED_COMPLETE,
  (event) => {
    console.log("Set lock enrolled result:", event.result);
    console.log("Lock:", event.name, "Serial:", event.serialNumber);
  }
);

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,
  addEventListener,
  LiveAccessSdkEvents,
  type LockStatusChangeEvent,
} from "@invue/react-native-sdk";

await addLockStatusObserver(serialNumber);

// After observer is set for the current lock, listen to lock status changes with typed events
addEventListener<LockStatusChangeEvent>(
  LiveAccessSdkEvents.LOCK_STATUS_CHANGE,
  (event) => {
    console.log("Lock status changed:", event.lockStatus);
    console.log("Lock:", event.name);
  }
);
  • 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 "@invue/react-native-sdk";
await removeLockStatusObserver("remove lock status observer");
// remove the Lock Status observer of the current Lock.

Lock Status Helper Functions​

These helper functions make it easy to check lock status conditions. They allow you to determine the current state of a lock based on its status string. These functions are not part of the SDK but are provided as utility functions to simplify lock status checking in your applications.

18. isLocked(lockStatus: string)​

Checks if the lock is in a locked state.

@param {string} lockStatus - The lock status string from events @returns {boolean} - Returns true if the lock is locked

  • Example:
addEventListener<LockStatusChangeEvent>(
  LiveAccessSdkEvents.LOCK_STATUS_CHANGE,
  (event) => {
    if (isLocked(event.lockStatus)) {
      console.log("Lock is currently locked");
    } else {
      console.log("Lock is not locked");
    }
  }
);

Returns true for these statuses:

  • LockedAndLatched
  • LockedAndUnLatched
  • LockingErrorAndLatched

19. isLatched(lockStatus: string)​

Checks if the lock is in a latched state.

@param {string} lockStatus - The lock status string from events @returns {boolean} - Returns true if the lock is latched

  • Example:
addEventListener<LockStatusChangeEvent>(
  LiveAccessSdkEvents.LOCK_STATUS_CHANGE,
  (event) => {
    if (isLatched(event.lockStatus)) {
      console.log("Lock is currently latched");
    } else {
      console.log("Lock is not latched");
    }
  }
);

Returns true for these statuses:

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

20. isUnlatched(lockStatus: string)​

Checks if the lock is in an unlatched state.

@param {string} lockStatus - The lock status string from events @returns {boolean} - Returns true if the lock is unlatched

  • Example:
addEventListener<LockStatusChangeEvent>(
  LiveAccessSdkEvents.LOCK_STATUS_CHANGE,
  (event) => {
    if (isUnlatched(event.lockStatus)) {
      console.log("Lock is currently unlatched");
    } else {
      console.log("Lock is not unlatched");
    }
  }
);

Returns true for these statuses:

  • UnLockedAndUnlatched
  • LockingAndUnlatched
  • LockedAndUnLatched
  • LockingErrorAndUnlatched
  • UnlockingErrorAndUnlatched

21. isLockJammed(lockStatus: string)​

Checks if the lock is in a jammed or error state.

@param {string} lockStatus - The lock status string from events @returns {boolean} - Returns true if the lock is jammed or in error state

  • Example:
addEventListener<LockStatusChangeEvent>(
  LiveAccessSdkEvents.LOCK_STATUS_CHANGE,
  (event) => {
    if (isLockJammed(event.lockStatus)) {
      console.log("Lock is jammed or in error state");
      // Handle jammed lock scenario
    } else {
      console.log("Lock is functioning normally");
    }
  }
);

Returns true for these statuses:

  • LockingErrorAndUnlatched
  • UnlockingErrorAndUnlatched
  • LockingErrorAndLatched
  • LockingErrorLatchedAndStalled
  • UnlockingErrorAndLatched
  • UnknownState

Complete Example with Helper Functions​

import {
  addLockStatusObserver,
  addEventListener,
  LiveAccessSdkEvents,
  type LockStatusChangeEvent,
} from "@invue/react-native-sdk";

await addLockStatusObserver(serialNumber);

addEventListener<LockStatusChangeEvent>(
  LiveAccessSdkEvents.LOCK_STATUS_CHANGE,
  (event) => {
    console.log("Lock status changed:", event.lockStatus);

    // Use helper functions to determine lock state
    if (isLocked(event.lockStatus)) {
      console.log("Lock is locked");
    }

    if (isLatched(event.lockStatus)) {
      console.log("Lock is latched");
    }

    if (isUnlatched(event.lockStatus)) {
      console.log("Lock is unlatched");
    }

    if (isLockJammed(event.lockStatus)) {
      console.log("Lock is jammed - requires attention");
      // Handle jammed lock scenario
    }
  }
);

// Helper functions implementation
function isLocked(lockStatus: string) {
  return (
    lockStatus === "LockedAndLatched" ||
    lockStatus === "LockedAndUnLatched" ||
    lockStatus === "LockingErrorAndLatched"
  );
}

function isLatched(lockStatus: string) {
  return (
    lockStatus === "LockedAndLatched" ||
    lockStatus === "UnLockingAndLatched" ||
    lockStatus === "UnLockedAndLatched" ||
    lockStatus === "LockingAndLatched" ||
    lockStatus === "LockingErrorAndLatched" ||
    lockStatus === "LockingErrorLatchedAndStalled" ||
    lockStatus === "UnlockingErrorAndLatched"
  );
}

function isUnlatched(lockStatus: string) {
  return (
    lockStatus === "UnLockedAndUnlatched" ||
    lockStatus === "LockingAndUnlatched" ||
    lockStatus === "LockedAndUnLatched" ||
    lockStatus === "LockingErrorAndUnlatched" ||
    lockStatus === "UnlockingErrorAndUnlatched"
  );
}

function isLockJammed(lockStatus: string) {
  return (
    lockStatus === "LockingErrorAndUnlatched" ||
    lockStatus === "UnlockingErrorAndUnlatched" ||
    lockStatus === "LockingErrorAndLatched" ||
    lockStatus === "LockingErrorLatchedAndStalled" ||
    lockStatus === "UnlockingErrorAndLatched" ||
    lockStatus === "UnknownState"
  );
}