npm package: @instnt/instnt-angular-sdk
Description: Angular SDK for Instnt Forms
Author: Claudio Teles
Latest version: 2.1.0

# Instnt Angular SDK

This documentation covers the basics of Instnt Angular SDK implementation. Angular is an open-source front-end developer library utilized by Instnt to create a more streamlined and elegant integration with your company's customer sign-up forms. For a more detailed look at this implementation, visit
[Instnt's documentation hub.](https://support.instnt.org/hc/en-us/articles/360055345112-Integration-Overview)

### Table of Contents

### Table of Contents
- [Prerequisites](#Prerequisites)
- [Getting Started](#Getting-Started)
- [Quick Start Setup](#Quick-Start-Setup)
  - [Step 1 : Install & Setup InstntSignupProvider component](#Step-1-:-Install-&-Setup-InstntSignupProvider-component)
  - [Step 2 : Submit your Signup data using submitSignupData](#Step-2-:-Submit-your-Signup-data-using-submitSignupData)
- [Additional Feature Integration](#Additional-Feature-Integration)
  - [Document Verification](#Document-Verification)
  - [Setup for InstntDocumentProcessor component](#Setup-for-InstntDocumentProcessor-component)
  - [Setup for InstntSelfieProcessor component](#Setup-for-InstntSelfieProcessor-component)
  - [OTP (One-Time Passcode)](#OTP-(One-Time-Passcode))
  - [Instnt Verifiable Credentials](#Instnt-Verifiable-Credentials)
  - [Instnt Verification](#Instnt-Verification)
    - [Setup for Instnt Verify Provider component](#Setup-for-Instnt-Verify-Provider-component)
    - [Submit your verification data using submitVerifyData](#Submit-your-verification-data-using-submitVerifyData)
- [Event processing](#Event-processing)
- [Instnt's core library objects, functions, and events](#Instnts-core-library-objects,-functions,-and-events)
- [Instnt's Sandbox](#Instnts-Sandbox)
- [Resource links](#Resource-links)
- [License](#License)

# 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](https://support.instnt.org/hc/en-us/articles/4408781136909) and [Developer guide](https://support.instnt.org/hc/en-us/articles/360055345112-Integration-Overview) for more information.

* The integration of SDK depends on your workflow; read the [Instnt Accept integration process](https://support.instnt.org/hc/en-us/articles/4418538578701-Instnt-Accept-Integration-Process), to understand the functionalities provided by Instnt and how to integrate SDK with your application.

**Note:** Your implementation with Instnt's SDK may diverge from the integration shown in the sample app. Please contact the Instnt support team for additional questions related to Integration.

# Getting Started

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

* Instnt Angular SDK is built on top of Instnt core JavaScript Library which provides the base functionality and event triggering mechanism that Angular SDK depends on. For more information please refer to this following article [Instnt Core JavaScript Library](https://support.instnt.org/hc/en-us/articles/4997119804301).

# Quick Start Setup

  # Step 1 : Install & Setup InstntSignupProvider component

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

```sh
npm i @instnt/instnt-angular-sdk
```

After installing the package, import the **InstntAngularModule** to your app.module.ts. 
If using the **InstntAngularService** make sure to add it to your providers.
<sup style="position: relative; top: 24px; left: 8px;">**app.module.ts**</sup>
```ts
import { InstntAngularModule, InstntAngularService } from '@instnt/instnt-angular-sdk';

@NgModule({
  imports: [
    InstntAngularModule,
    ...
  ],
  providers: [InstntAngularService],
})
```

Now you can insert your **instnt-signup-provider** into your template and pass the required values;
<sup style="position: relative; top: 24px; left: 8px;">**app.component.html**</sup>

```html
<instnt-signup-provider [formKey]="formKey" [serviceURL]="serviceURL" [onEvent]="onEvent"> </instnt-signup-provider>
```
<br>

| 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```     |
| serviceURL (Required)     | Instnt's service URL to connect and access the API. This API can point to instnt's environments. See [Instnt Enviroments](https://support.instnt.org/hc/en-us/articles/5165465750797#h_01GXZYPZEH2JW528C926BW3EGY) for more information.     | ```string```     |
| onEvent (Optional)    | Used to provide event handling, it is invoked when various Instnt events occur `onEventHandler(event)`.   | ```function```     |

  

* **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.  

After the initiation, you get the [Instnt Object.](https://support.instnt.org/hc/en-us/articles/4997119804301-Instnt-Core-JavaScript-Library-#h_01G9QM0XM2YEZ9ZBH5GC1GJM62) This object has all the necesaary function and event deatils for you to work with.
### Instnt service
You can also access the Instnt Object through the `InstntAngularService` by calling the `getInstnt()`. This function will return an `Observable<Instnt>` that you can subscribe to.
<sup style="position: relative; top: 24px; left: 8px;">**app.component.ts**</sup>
```ts
  instnt?: Instnt;
  constructor(private instntService: InstntAngularService) {
    this.instntService.getInstnt().subscribe((instnt) => {
      this.instnt = instnt;
    });
  }
```

# 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](https://support.instnt.org/hc/en-us/articles/4997119804301-Instnt-Core-JavaScript-Library-#h_01G9QKPB5315XFKZ7FAG093NK8) for more information about the different events.

  ```javascript
  const onEventHandler = (event) => {
    switch (event.type) {
      case "transaction.initiated":
        console.log("Instnt Object: ", event.data.instnt)
        event.data.instnt.submitSignupData(formData)
        break;
    }
  }
  ```
If using the **InstntAngularService** to retrieve the `instnt` object, you can simply call the function from there.
```ts
    submitApplication() {
      this.instnt?.submitSignupData(formData);
  }
  ```


  Where as,

  * The **instnt** object is [instnt object](https://support.instnt.org/hc/en-us/articles/4997119804301#h_01G9QM0XM2YEZ9ZBH5GC1GJM62)

  * **formData** is like

  ```javascript
  {
    "city" : "testCity",
    "country" : "usa",
    "email" : "test@gmail.com",
    "firstName" : "test",
    "mobileNumber" : "+18505903218",
    "physicalAddress" : "testAddress",
    "state" : "testState",
    "country": "testCountry",
    "surName" : "testlastName",
    "zip" : "11230"
  }
  ```
  After submitting your data, you will receive an event of type `transaction.processed ` (refer to [Event Processing](#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:
  ```javascript
    {
        "status": String,
        "formKey": String,
        "url": String,
        "success": Boolean,
        "instntjwt": String,
        "decision": String
    }
  ```
  `decision` 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](https://support.instnt.org/hc/en-us/articles/4408781136909#h_01GXC1F0V6A29QWRRHD3FHZ0YM) section of the Quickstart guide to understand better how to enable the feature.

### Document Verification Pre-requisites

* Web applications running on mobile devices 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.
    


### Setup for InstntDocumentProcessor component

1\. Create the document capture settings with `documentSettings` prop.
```ts
documentSettings: 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.

2\. Use `instnt-document-processor` component with `documentSettings` prop.
<sup style="position: relative; top: 24px; left: 8px;">**app.component.html**</sup>
```html
<instnt-document-processor [documentSettings]="documentSettings"></instnt-document-processor>
```
Alternatively you can use the `InstntAngularService` to initiate the Document Processor with the function `instntDocumentProcessor(this.documentSettings);`
```ts
constructor(private intntService: InstntAngularService) { }
  startCamera(target: string) {
      this.documentSettings.documentSide = target as 'Front' | 'Back';
      this.intntService.instntDocumentProcessor(this.documentSettings);
    }
```


#### The Document Processor
* The `<instnt-document-processor>` can get initialized multiple times to capture both the **front** and **back** sides of a **license**, or it can be used in conjunction with a `*ngIf` statement. 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](https://support.instnt.org/hc/en-us/articles/4997119804301-Instnt-Core-JavaScript-Library-#h_01G9QKPB5315XFKZ7FAG093NK8). 

* 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.

#### Properties


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


For more details on the settings configuration please visit our [DocumentSettings section](https://support.instnt.org/hc/en-us/articles/8277032114829-Document-Verification-#h_01GXZZFZXKSNJA56DK65DVB3FF).

## Setup for InstntSelfieProcessor component

Similar to the Instnt Document Processor, the Instnt Selfie Processor also needs the `selfieSettings ` 

1\. Create the selfie capture settings with `selfieSettings` prop.
```ts
selfieSettings: 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,
}
```

2\. Use `instnt-selfie-processor` component with `selfieSettings` prop.
<sup style="position: relative; top: 24px; left: 8px;">**app.component.html**</sup>
```html
<instnt-selfie-processor [selfieSettings]="selfieSettings"></instnt-selfie-processor>
```
* Alternatively you can use the `InstntAngularService` and call the `instntSelfieProcessor(this.selfieSettings)` to initiate the Document Processor
```ts
constructor(private intntService: InstntAngularService) { }
  startCamera() {
      this.intntService.instntSelfieProcessor(this.selfieSettings);
    }
```

* 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](https://support.instnt.org/hc/en-us/articles/4408781136909#h_01GFKXKDFW0D8HQXND70K0CYCY) section of the Quickstart guide for more information.

Instnt SDK provides two Javascript library functions to enable OTP `sendOTP()` and `verifyOTP()`.

1. Get the Instnt Object using `InstntAngularService` or from your own event handler `event.data.instnt`
```ts
constructor(public instntService: InstntAngularService) {
    this.instntService.getInstnt().subscribe((instnt) => {
      this.instnt = instnt;
    });
  }
```

2. sendOTP (mobileNumber)
```ts 
this.instnt?.sendOTP('+17371234567');
```
3. verifyOTP(mobileNumber, otpCode)
```ts 
this.instnt?.verifyOTP('+17371234567', '123456');
```
These function will generate respective events that your `eventHandler = (event: InstntEvent) => {}` can handle:
* `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

See [Instnt Events](https://support.instnt.org/hc/en-us/articles/4997119804301#h_01G9QKPB5315XFKZ7FAG093NK8) for more details.

### 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

## Instnt Verifiable Credentials
To use the Verifiable Credentials, your workflow must have Portable KYC/SSI enabled. (See step 8 in [Create a Workflow](https://support.instnt.org/hc/en-us/articles/16806199709709#h_01HAA0YR2V7Y0YH1CB2GYCQB91))

Verifiable Credentials has two main functionality. It can issue a verified credential that your user can store in his digital wallet and it can also accept verified credentials when performing a login into your application.
* Use the `invitationType = 'issuer'` and `action = 'signup'` to generate a URL with the user's verified credentials that he can store in his wallet.
* Use the `invitationType = 'verifier'` and `action = 'authenticate'` to generate a URL that the user can scan and login to your application with his credentials.
* These will generate an `invitation` that contains the `url` that you can be used to generate a QR code for your users to scan.

To use it, simply add the `<instnt-verifiable-credential>` to your Template.

```ts
<instnt-verifiable-credential [serviceURL]="serviceUrl" [invitationType]="invitationType" [action]="action"></instnt-verifiable-credential>
```

After that you can use the Instnt Service to call the function `getCredentialInvitation()` which will return an `Observable<InvitationResponse>`.
```ts
this.instntService.getCredentialInvitation().subscribe((invitation) => {
      const url = invitation.invitation_url
    });
```

#### Properties


| Prop | Description | Type |
| -------- | -------- | -------- |
| serviceURL (Required)     | Instnt's service URL to connect and access the API. This API can point to instnt's environments. See [Instnt Enviroments](https://support.instnt.org/hc/en-us/articles/5165465750797#h_01GXZYPZEH2JW528C926BW3EGY) for more information.     | ```string```     |
| invitationType (Optional)    | Used to select the invitation type to be used, the default value is `issuer`   | ```'issuer'\|'verifier'```     |
| action (Optional)    | Used to select the action that should be performed, the default value is `signup`.   | ```'authenticate'\|'signup'```     |




## Instnt Verification

Instnt verification feature is applicable if you have enabled it during the workflow creation. After Instnt Verify™ is enabled on a workflow, the Instnt Verify™ SDK seamlessly captures the user's biometric information and device intelligence. By comparing this data to the baseline established during onboarding, Instnt Verify confirms that the person using the system is the same individual without causing any disruption or inconvenience to the user experience. This ensures the system's security and confirm that it is still the same person using the system.

Read the [Instnt Verification](https://support.instnt.org/hc/en-us/articles/9093717531405-Instnt-Verify-#h_01GZEEKNKRCRC264AV5W74X422) section of the Quickstart guide to understand better how to enable the feature.

### Instnt Verification Pre-requisites

*  Before Calling or Initiating InstntVerfiyProvider, Ensure that the [instnt](https://support.instnt.org/hc/en-us/articles/4997119804301#h_01G9QM0XM2YEZ9ZBH5GC1GJM62) object has been successfully initiated. this will give you the `instnttxnid` 
``` ts
const instnttxnid = this.instnt?.instnttxnid;
```

### Setup for Instnt Verify Provider component

* **`<instnt-verify-provider>`**- This component provides the functions to render and initiate the verification process.

Similar to the `<instnt-signup-provider>` this to the acts as a top-level container component responsible for initiating the verification processs and returning the accompanying Javascript functions and configurations that your application can use to perform different actions. It occurs during the mounting phase of this component. Unlike the instnt-signup-provider, in the `<instnt-verify-provider>` you pass in the `instnttxnid` instead of the `formKey`
   ```ts
  <instnt-verify-provider instnttxnid="xxxx-yyyyy-zzzz" [onEvent]="onVerifyEventHandler"
    serviceURL="https://sandbox-api.instnt.org">
  </instnt-verify-provider>
  ```
**instnttxnid**- This value should be the previously submitted transaction ID (`instnttxnid`).

**onEvent** - Optional. Used to provide event handling, it is invoked when various Instnt events occur `onVerifyEventHandler(event)`.

**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](https://support.instnt.org/hc/en-us/articles/5165465750797#h_01GXZYPZEH2JW528C926BW3EGY).

### Submit your verification data using submitVerifyData
 * Once an end-user/applicant fills out the signup form, the application can invoke **submitVerifyData** to process the signup request.

 * Submitting your data form is done by calling the **submitVerifyData** 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](#event-processing) for more information about the different events.

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

If using the `InstntAngularService` to get the [instnt](https://support.instnt.org/hc/en-us/articles/4997119804301#h_01G9QM0XM2YEZ9ZBH5GC1GJM62) object you can simply call the `submitVerifyData(formData)`
```ts
this.instnt?.submitVerifyData(formData);
```

An example of the `formData`:

```ts
  {
    "city" : "testCity",
    "country" : "usa",
    "email" : "test@gmail.com",
    "firstName" : "test",
    "amount": 10000,
    "mobileNumber" : "+18505903218",
    "physicalAddress" : "testAddress",
    "state" : "testState",
     "country": "testCountry",
    "surName" : "testlastName",
    "zip" : "11230"
  }
```
After submitting your data, you will receive an event of type `transaction.processed ` (refer to [Event Processing](#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:
```javascript
  {
    "status": String,
    "formKey": String,
    "success": Boolean,
    "decision": String
  }
```
```decision``` will represent either: `VERIFIED` and many more.

# 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](https://support.instnt.org/hc/en-us/articles/4997119804301#h_01G9QKPB5315XFKZ7FAG093NK8)


# Instnt's core library objects, functions, and events
>**NOTE:**
>Please refer to [Instnt's Core JavaScript Library ](https://support.instnt.org/hc/en-us/articles/4997119804301) 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, county, zip)
*	IP address

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


# Resource links 
- [Quick start guide](https://support.instnt.org/hc/en-us/articles/4408781136909)
- [Developer guide](https://support.instnt.org/hc/en-us/articles/360055345112-Integration-Overview)
- [Instnt API endpoints](https://api.instnt.org/doc/api/)
- [Instnt support](https://support.instnt.org/hc/en-us/requests/new)

# License

The instnt-angular-sdk is under MIT license.