/instnt-react-js

Primary LanguageTypeScriptMIT LicenseMIT

Instnt React SDK

This documentation covers the basics of Instnt React SDK implementation. In simple terms, React is an open-source front-end developer library utilized by Instnt to create a more streamlined and elegant integration with your company's/institutions customer sign-up forms. For a more detailed look at this implementation, visit Instnt's documentation library.

npm version

Table of Contents

Prerequisites

  • Sign in to your account on the Instnt Accept's dashboard and create a customer signup workflow that works for your company. Refer to the Quick start guide and Developer guide for more information.

  • The integration of SDK depends on your workflow; read the Instnt Accept integration process, to understand the functionalities provided by Instnt and how to integrate SDK with your application.

Getting Started

  • Instnt React SDK is comprised of React components, Javascript library functions, and an event propagation mechanism to facilitate communication between applications, Instnt SDK, and Instnt's APIs.

  • Instnt React SDK is built on top of Instnt core JavaScript Library which provides the base functionality and event triggering mechanism that React SDK depends on. For more information please refer to this following article Instnt Core JavaScript Library.

Quick Start Setup

Step 1 : Install & Setup InstntSignupProvider component

To begin utilizing Instnt React SDK, open the terminal and enter the following command to install Instnt's React components:

npm i @instnt/instnt-react-js

After installing the Instnt npm package, import Instnt's React Workflow component called InstntSignupProvider.

import { InstntSignupProvider } from '@instnt/instnt-react-js'

The next thing to do will be to just wrap up your signup components with the InstntSignupProvider.

<InstntSignupProvider 
  formKey={'v626673100000'} 
  onEvent={onEventHandler} 
  serviceURL={'https://sandbox-api.instnt.org'}>

  {{ Your signup components can go here }}

</InstntSignupProvider>

NOTE: The above code snippet is a design recommendation. Developers can decide how they use this component to adjust to their use case.

Prop Description Type
formKey(Required) This is the Workflow ID you created in the Instnt dashboard, and you want to be powered by Instnt. string
onEvent(Optional) Used to provide event handling, it is invoked when various Instnt events occur onEventHandler(event). function
serviceURL(Required) Instnt's service URL to connect and access API. This API can point to instnt production, sandbox or pre-prod environments and as described here at Instnt Enviroments. string

  • InstntSignupProvider works as follows:

    1. connects to Instnt’s backend API on mount and initiates a new transaction identified by a unique transactionID.
    2. It also downloads additional scripts and client side APIs.
    3. The calling application should pass the formKey, serviceURL and an onEventHandler function to this component.

  • InstntSignupProvider invokes onEventHandler callback function on successful initialization, passing a globally available reference to instnt object and associated SDK functions listed here.

  • The application should store this instnt object and its context for referencing during the signup process and invoke the properties of the function of this object to communicate with Instnt API.

  • Once Instnt SDK is initialized, it binds the onEventHandler function and emits transaction.initiated event. The app can then render any subsequent components or act on the tasks associated with the signup process.

Step 2 : Submit your Signup data using submitSignupData

Once an end-user/applicant fills out the signup form, the application can invoke submitSignupData to process the signup request.

Submitting your data form is done by calling the submitSignupData function that we get from the instnt object after a transaction is initiated. The instnt object can be found when the event transaction.initiated is called. Please refer to Event Processing for more information about the different events.

const onEventHandler = (event) => {
  switch (event.type) {
    case "transaction.initiated":
      console.log("Instnt Object: ", event.data.instnt)
      event.data.instnt.submitSignupData(formData)
      break;
  }
}

Where as,

{
  "city" : "testCity",
  "country" : "usa",
  "email" : "test@gmail.com",
  "firstName" : "test",
  "mobileNumber" : "+18505903218",
  "physicalAddress" : "testAddress",
  "state" : "testState",
  "surName" : "testlastName",
  "zip" : "11230"
}

After submitting your data, you will receive an event of type transaction.processed (refer to Event Processing for more event types) located at event.type. This means your transaction was processed successfully by our backend.

At the same time, you will see a data object at event.data that contains the following:

  {
      "status": String,
      "formKey": String,
      "url": String,
      "success": Boolean,
      "instntjwt": String,
      "decision": String
  }

decsion will represent either: REJECT, REVIEW, or ACCEPT.

Additional Feature Integration

Document Verification

Document verification feature is applicable if you have enabled it during the workflow creation.

When this feature is enabled, the physical capture and verification of selfies and Government-issued identification documents such as Passports and Driver's Licenses are available.

Read the Document Verification section of the Quickstart guide to understand better how to enable the feature.

Document Verification Pre-requisites

  • Web applications running on mobile-react can utilize Document Verification.

  • Latest iOS and Android mobile devices with Chrome or Safari browsers and good quality camera are supported for document verification.

  • Desktop devices (laptops, PCs) are unsupported due to the poor quality of embedded cameras and lack of gyroscopes for orientation detection. While the feature will work on devices running Chrome or Safari browsers, the experience can vary.

  • Do not include HTML tags with IDs containing the prefix 'aid.' e.g. <div id=’aidFooter’> in your web app as this prefix is reserved to be used by the toolkit.

  • Document verification requires end-to-end communication over SSL to get permission to use the device camera. If you with to generate a self-signed certificate for testing purposes please take a look at this basic guide: How to Create SSL Certificates for Development.

Setup for InstntDocumentProcessor component

1. import Instnt's React components:

  import { InstntDocumentProcessor } from '@instnt/instnt-react-js'

2. Create the document capture settings with documentSettings prop.

const documentSettings = {
    documentType: "License",
    documentSide: "Front",
    frontFocusThreshold: 30,
    frontGlareThreshold: 2.5,
    frontCaptureAttempts: 4,
    captureMode: "Manual",
    overlayText: "Align ID and Tap <br/> to Capture.",
    overlayTextAuto: "Align ID within box and Hold.",
    overlayColor: "yellow",
    enableFaceDetection: true,
    setManualTimeout: 8,
    backFocusThreshold: 30,
    backGlareThreshold: 2.5,
    backCaptureAttempts: 4,
    isBarcodeDetectedEnabled: false,
    enableLocationDetection: false,
}

NOTE: The above configuration is an example for scanning the front side of a license.

3. Use InstntDocumentProcessor component with documentSettings prop.

<InstntDocumentProcessor
    documentSettings={documentSettings}/>

IMPORTANT: We recommend the follwing settings for enhanced image capture:
captureMode: "Auto"
enableFaceDetection: true
isBarcodeDetectedEnabled: true

Thats it your're done!

If you wish to know more about the settings configuration please visit our DocumentSettings section.

Example configuration

Set-up the workflow steps:

  const steps = [
    <GettingStarted />, //Step 0 == activeStep
    <EnterName data={formData} errorMessage={errorMessage} onChange={onSignupFormElementChange}/>,
    <EnterContact data={formData} errorMessage={errorMessage} onChange={onSignupFormElementChange} mobileNumberOnBlur={mobileNumberOnBlur}/>,
    <EnterOtpCode errorMessage={errorMessage} setOtpCode={otpCodeEntered} onChange={onSignupFormElementChange}/>,
    <ShowProgress message={otpVerifyProcessingMessage}/>, //step 4
    <EnterAddress data={formData} errorMessage={errorMessage} onChange={onSignupFormElementChange}/>,
    <ChooseDocument customDocCaptureSettings={customDocCaptureSettings} onToggleDocCaptureSettings={onToggleDocCaptureSettings} onDocumentTypeChanged={onDocumentTypeChanged} />, // step 6
    <InstntDocumentProcessor documentSettings={frontLicenseSettings} />, //DL front
    <ReviewCapture documentSettings={documentSettingsApplied} captureResult={captureResult} />, // step 8
    <InstntDocumentProcessor documentSettings={backLicenseSettings} />, //DL back
    <ReviewCapture documentSettings={documentSettingsApplied} captureResult={captureResult} />, // step 10
    <InstntSelfieProcessor selfieSettings={selfieSettings}/>, //selfie
    <ReviewCapture documentSettings={documentSettingsApplied} captureResult={captureResult} />, // step 12
    <ShowProgress message={formSubmitProcessingMessage}/>,
    <ShowDecision decision={decision} restart={restart}/>,
  ];

NOTE: The above code snippet is for demostration purposes and users can choose how they integrate the InstntDocumentProcessor component.

  • As in the above example, InstntDocumentProcessor gets initialized multiple times to capture both the front and back sides of a license. In case of license, the front capture is required with back capture can be optional. In case of passport, one time initialization to capture the front info page of the passport is sufficient.

  • The component has an auto-upload feature which is turned on by default. It uploads the image to Instnt cloud storage once the image gets captured successfully.

  • This component triggers different events based on the capture success, please review: Instnt Events.

  • On successful capture, it returns the captured image and the related configurations to your application so that the application can decide to use the captured image or retake.

  • The customers are only expected to use the first two settings documentType and documentSide in general to setup this component.

  • For more details about Document verification workflow steps please refer to this article Document Verification

Properties

Prop Description Type
documentSettings(Required) Document capture configuration. Object
autoupload(Optional) Enables automatic uploads. boolean
captureFrameworkDebug(Optional) Enables debuging logs. boolean

Setup for InstntSelfieProcessor component

1. import Instnt's React components:

import { InstntSelfieProcessor } from '@instnt/instnt-react-js'

2. Create the selfie capture settings with selfieSettings prop.

const selfieSettings = {
    enableFarSelfie: true,
    selfieCaptureAttempt: 4,
    captureMode: "Auto",
    compressionType: "JPEG",
    compressionQuality: "50",
    useBackCamera: false,
    overlayText: "Align Face and Tap button</br> to Capture.",
    overlayTextAuto: "Align Face and Hold",
    overlayColor: "#808080",
    orientationErrorText:
      "Landscape orientation is not supported. Kindly rotate your device to Portrait orientation.",
    enableFaceDetection: true,
    setManualTimeout: 8,
    enableLocationDetection: false,
}

3. Use InstntSelfieProcessor component with selfieSettings prop.

<InstntSelfieProcessor 
    selfieSettings={selfieSettings}/>

IMPORTANT: We recommend the follwing settings for enhanced image capture:
captureMode: "Auto"
enableFaceDetection: true

Thats it your're done!

  • Please refer to the reference application bundled with React SDK for more detail code examples Example App.

  • The SDK by default loads a optimized set of configurations based on the device family for well known devices.

Properties

Prop Description Type
selfieSettings(Required) Selfie capture configuration. Object
autoupload(Optional) Enables automatic uploads. boolean
captureFrameworkDebug(Optional) Enables debuging logs. boolean

OTP (One-Time Passcode)

OTP functionality can be enabled by logging in Instnt dashboard and enabling OTP in your workflow. Refer to the OTP section of the Quickstart guide for more information.

Instnt SDK provides two Javascript library functions to enable OTP.

  1. sendOTP (mobileNumber)
event.data.instnt.sendOTP('+17371234567')
  1. verifyOTP(mobileNumber, otpCode)
event.data.instnt.verifyOTP('+17371234567', '123456')

These function will generate respective events like:

  • otp.sent: OTP sent by our SDK.
  • otp.verified: OTP verified against the code received to the mobile number
  • otp.error: Any errors regarding OTP

OTP flow

  • User enters mobile number as part of the signup screen.
  • Your app calls sendOTP() SDK function and pass the mobile number.
  • Instnt SDK calls Instnt API and returns the response upon successful OTP delivery.
  • Your app shows the user a screen to enter the OTP code.
  • User enters the OTP code which they received.
  • Your app calls verifyOTP() SDK function to verify the OTP and pass mobile number and OTP code.
  • Instnt SDK calls Instnt API and returns the response upon successful OTP verification

Example App

This repo contains a simple example of how to implement the Instnt SDK. If you wish to run the example project please do the following:

From the root folder do:

cd /examples/forms/

Then, install npm packages with:

npm i

Lastly, just run the project by running the following command:

npm start

From here you will see the server startup and open up the sample project. Usually at: http://localhost:3000/

Event processing

Your application can listen to the events emitted by Instnt's SDK and respond to it. Please refer to our support site for more information: Instnt SDK events

Instnt's core library objects, functions, and events

NOTE: Please refer to Instnt's Core JavaScript Library for details regarding the Instnt's core Javascript library objects, functions, and events.

Instnt's Sandbox

Instnt's Sandbox is a static environment that assesses provisioned synthetic identities that we give you for onboarding and testing purposes. The provisioned identities contain:

  • Email address
  • First name
  • Last name
  • Phone number
  • Physical address (city, state, zip)
  • IP address

Please contact support@instnt.org for more information concerning access to the sandbox environment.

Resource links

License

The instnt-reactjs SDK is under MIT license.