Luciditi SDK

Supporting library to aid Age Assurance and ID Verification integration flows with the Luciditi platform. For more information about Luciditi, please visit the website.

Installation

npm i @arissian/luciditi-sdk

Initializing the SDK

In order to use the SDK you first need to initialize the SDK using a session token from your authenticated organization user.

There are two ways to initialize the SDK

Option 1: Using an SDK API Key (recommended)

import { initializeSdk, Session } from '@arissian/luciditi-sdk'

// This may change dependant upon which Luciditi environment you are integrating with. For example, UAT: https://sdk-uat3.luciditi-api.net/
const luciditiSdkApiUrl: string = 'https://sdk-live3.luciditi-api.net'

// Your unique org key for the SDK API
const apiKey: string = 'SOME_API_KEY_PROVIDED_BY_LUCIDITI'

initializeSdkWithApiKey(luciditiSdkApiUrl, apiKey)

You should keep your SDK API key secure and not expose it in client-side code.

Option 2: Using a Session Token

import { initializeSdk, Session } from '@arissian/luciditi-sdk'

// This may change dependant upon which Luciditi environment you are integrating with. For example, UAT: https://sdk-uat3.luciditi-api.net/
const luciditiSdkApiUrl: string = 'https://sdk-live3.luciditi-api.net'

// Your org user session values for the current session
const orgUserSession: Session = {}

initializeSdk(luciditiSdkApiUrl, orgUserSession)

Once you have initialized the SDK you can use the SDK methods to interact with the Luciditi platform.

Age Assurance Flow Steps

Before using an Age Assurance flow you must have created a sign-up code in Luciditi for the person whose age you wish to verify.

1. Creating a Sign-Up Code

Using the SDK

The addSignupCode method returns a promise containing the response for the request to create a sign-up code. The response include various bits of information including the StartupToken (which you will need for Age Assurance later):

import {
  AddSignupCodeDataRequest,
  AddSignupCodeDataResponse,
  addSignupCode,
} from '@arissian/luciditi-sdk'

// Your signup data to add
const signupCodeDataToAdd = {
    callbackUrl: 'https://your-callback-url.com', // The url for Luciditi's callback after age assurance
    signupType: SignupType.ageAssurance, // The type of signup being created
    requiredAge: 18, // The required age of the user for the age assurance check
    stepUpWithIdDocument: true, // Whether the user can perform an Id Document step-up if their selfie age assurance check is inconclusive
    stepUpWithData: false, // Whether the user can perform a data-driven step-up if their selfie age assurance check is inconclusive
    stepUpUserData: undefined, // Contains the user data to use for the data-driven step-up if stepUpWithData is true
    callerUserName: 'some-user-name', // A unique identifier for the user that is being age assured
    requireStepUp: false, // When set this will force the user to perform a step-up check after the initial selfie check. This could be used in scenarios where you need to always verify the user's age with an ID document
} as AddSignupCodeDataRequest

// Indicates that an SDK startup token should be included in the response - startup tokens are used to start the age assurance process from the front-end
const includeStartupTokenInResponse: boolean = true

// The response from the request to create the signup code
const response: AddSignupCodeDataResponse = await addSignupCode(signupCodeDataToAdd, includeStartupTokenInResponse)

2. Starting the Age Assurance process

The intended usage pattern for Age Assurance is to host/embed Luciditi's verification within a separate window or 'web view' hosted from your application.

The generateVerificationHtmlForStartupToken method is a helper method that will generate the required html to host the Luciditi age assurance process.

It is not a requirement to use this helper method, alternatively you could save the generated html as a static template and host this within your application.

Example html generated using generateVerificationHtmlForStartupToken:

import { generateVerificationHtmlForStartupToken } from '@arissian/luciditi-sdk'

// The startup token from the `addSignupCode` call earlier
const startupToken: string = ''

// If false, doesn't automatically add the required JS script that triggers the ID Verification UI - optional defaults to true
// Depending how you deploy the SDK you may need to add the script tag after you've rendered the generated html
const addLuciditiSdkJSScriptTag: boolean = true

const html: string = generateVerificationHtmlForStartupToken(
  startupToken,
  addLuciditiSdkJSScriptTag
)

3. Age Assurance Events

The Age Assurance process will dispatch various events to indicate the user's progress within the SDK:

1. luciditiVerificationFailed - The Age Assurance process failed to start (indicative of a server error or problem with the signup code and/or startup token)
2. luciditiVerificationStarted - The user has started the Age Assurance process (click through on the first screen)
3. luciditiVerificationAborted - The user cancelled/aborted the Age Assurance process
4. luciditiVerificationComplete - The user has completed the Age Assurance process
5. luciditiVerificationError - An error was encountered during the Age Assurance process (the CustomEvent detail includes the error message)
6. luciditiAgeEstimationSuccessful - The Age Assurance process was completed successfully

The event messages are also sent via postMessage.

ID Verification Flow Steps

Before using an ID Verification flow you must have created a 'pre-id' bundle in Luciditi for the person whose identity you wish to verify.

Although the SDK features the ability to create this pre-id data, it is not a requirement that you use the SDK to create it. You may wish to create the pre-id bundle outside of the flow of the SDK, for example using a REST API call to Luciditi.

1. Creating a Pre Id Data Bundle

Using the SDK

The addPreIdBundleData method returns a promise containing the response for the request to create a pre id bundle. The response include various bits of information including the BundleId (which you will need for ID Verification later):

import {
  AddPreIdDataRequest,
  AddPreIdDataResponse,
  addPreIdBundleData,
} from '@arissian/luciditi-sdk'

// Your pre-id data to add
const preIdDataToAdd: AddPreIdDataRequest = {}

// The response from the request to create pre-id bundle data, incl. the created bundle id
const response: AddPreIdDataResponse = await addPreIdBundleData(preIdDataToAdd)

Using a REST API call

Alternatively you can create a pre-id bundle using a REST API call to Luciditi. A Postman collection can be made available on request to help you get started with this.

2. Starting the ID Verification process

The intended usage pattern for ID Verification is to host Luciditi's verification within a separate window or 'web view' hosted from your application.

The generateVerificationHtml method is a helper method that will generate the required html to host the Luciditi verification process.

It is not a requirement to use this helper method, alternatively you could save the generated html as a static template and host this within your application.

Example html generated using generateVerificationHtml:

import { generateVerificationHtml } from '@arissian/luciditi-sdk'

// The bundle id from the `addPreIdBundleData` call earlier
const bundleId: string = ''

// The surname of the user associated with the bundle id
const surname: string = ''

// The url for Luciditi's verification callback
const callbackUrl: string = ''

// The data item type ids to request for existing Luciditi users - optional
const dataTypeIds: number[] = [1, 4, 5, 6, 7, 8, 17, 35, 40, 41]

// The profile id containing the data item types to request for existing Luciditi users - optional
const profileId: number = 0 // (if supplied, takes precedence over the supplied data type ids)

// Allows the 'Confirm Your Details' page to be skipped if already present in pre-id bundle data - optional defaults to true
const skipUserDataPage: boolean = true

// Allows the 'Checking for existing users' page to be skipped - optional defaults to false
// If true the user will not be able to use their existing data in Luciditi and will need to supply ID in the SDK
const skipExistingUserSearchPage: boolean = true

// If false, doesn't automatically add the required JS script that triggers the ID Verification UI - optional defaults to true
// Depending how you deploy the SDK you may need to add the script tag after you've rendered the generated html
const addLuciditiSdkJSScriptTag: boolean = true

const html: string = generateVerificationHtml(
  bundleId,
  surname,
  callbackUrl,
  dataTypeIds,
  profileId,
  skipUserDataPage,
  skipExistingUserSearchPage,
  addLuciditiSdkJSScriptTag
)

3. Handling ID Verification Events

The ID Verification process will dispatch various events to indicate the user's progress within the SDK:

1. luciditiVerificationFailed - The ID Verification process failed to start (indicative of a server error or problem with the pre-id bundle)
2. luciditiVerificationStarted - The user has started the ID Verification process (click through on the first screen)
3. luciditiVerificationAborted - The user cancelled/aborted the ID Verification process
4. luciditiVerificationComplete - The user has completed the ID Verification process
5. luciditiVerificationError - An error was encountered during the ID Verification process (the CustomEvent detail includes the error message)

The event messages are also sent via postMessage.

React Native WebView

Please see these React Native docs for more info on handling postMessage in a WebView.

Checking for Callbacks from the Luciditi API

When a user has completed an SDK flow a callback will be sent to the url that was registered with the pre-id bundle or signup code data.

In Age Assurance scenarios the callback will contain an indication of whether the user passed or failed the age assurance check.

Otherwise, for ID Verification flows, the content of the callback will differ depending upon whether or not the user has an active Luciditi account:

• For Luciditi users, the callback will contain the id of the user's accepted invitation - containing the verified identification.
• For non-Luciditi users, the callback will contain the identification documents that were verified by the user during the verification process.

Parsing the callback

The SDK contains a helper method that will allow you to parse the received callback into a readable format:

import {
  parseIdVerificationCallbackResponse,
  SignupResponseData,
  InviteResponseData,
  AgeEstimationResponseData,
} from '@arissian/luciditi-sdk'

// The data that was received from the callback
const callbackData: string = ''

// The data item type ids that were requested for existing Luciditi users - optional
const dataTypeIds: number[] = [1, 4, 5, 6, 7, 8, 17, 35, 40, 41]

// The profile id that was requested for existing Luciditi users - optional
const profileId: number = 0 // (if supplied, takes precedence over the supplied data type ids)

const parsed:
  | SignupResponseData
  | InviteResponseData
  | AgeEstimationResponseData
  | false = await parseIdVerificationCallbackResponse(
  callbackData,
  dataTypeIds,
  profileId
)

if (!parsed) {
  // The callback doesn't contain a valid response
} else {
  // Do something with the callback data
}

Please note that it is possible for a Luciditi user to accept an invitation and exclude one or more of the requested data types. For example, in a request for a user's name, date of birth and address the user may untick address in the request and just send name and date of birth.

The SDK will notify the user that they haven't supplied all of the requested data and they will be asked if they wish to re-send the invitation with all of the originally requested data. They may have subsequently changed their mind and decided they do wish to send all of the requested data.

In this particular scenario you may receive multiple callbacks from Luciditi so you may wish to check that the InviteResponseData callback has all of the data you requested:

const inviteResponse = parsed as InviteResponseData

const hasAllData: boolean = inviteResponse.HasAllRequestedData

Reading the callback (ID Verification flows only)

The parsed callback will contain all of the verified identification data that the user permitted to be sent. To aid working with this data the SDK has helper methods to read the data in a consistent format irrespective of the type of callback received.

Images can be retrieved from the callback using the getIdVerificationImage method:

import { getIdVerificationImage, SignupResponseData, InviteResponseData } from '@arissian/luciditi-sdk'

const parsed: SignupResponseData | InviteResponseData

// The data type for an image that you want to retrieve, in this example, the person's photo id image
const imageDataType: DataType = DataType.photoId

// Gets the image from the callback
const photoIdBase: string = await getIdVerificationImage(parsed, imageDataType)

Data values can be extracted from the callback using the getIdVerificationDataValue method:

import { getIdVerificationDataValue, SignupResponseData, InviteResponseData } from '@arissian/luciditi-sdk'

const parsed: SignupResponseData | InviteResponseData

// The data type for a data value that you want to retrieve, in this example, the person's name
const dataType: DataType = DataType.personName

// Gets the data value from the callback
const personNameValue: string = getIdVerificationDataValue(parsed, dataType)

Alternatively you can decrypt all of the available data in the callback in one go using the getAllIdVerificationData method.

Please be aware that this is retrieving everything that is available in the callback so will be slower than the decrypted the data individually if you're not interested in collecting the full callback response:

import { getAllIdVerificationData, DecryptedCallbackData } from '@arissian/luciditi-sdk'

const parsed: SignupResponseData | InviteResponseData

// Get all the available data from the callback in one go
const allCallbackData: DecryptedCallbackData = getAllIdVerificationData(parsed)

Id Verification Sequence Diagram Example

This Mermaid sequence diagram describes the ends to end process using the Luciditi SDK to initiate ID verification and read the callback response containing the verified user's ID verification data.