npm package: @instnt/instnt-react-native-sdk
Description: Instnt, Inc. React Native SDK
Author: Instnt Inc.
Latest version: 1.0.0-beta.10

# Instnt React Native SDK

This documentation covers the essential functionality of Instnt React-Native SDK. React-Native is an open-source library that helps create native apps for Android and iOS using React. Instnt React-Native SDK provides a streamlined and elegant integration with your company or institution's customer sign-up workflows built using the react-native library. For more information about Instnt's products and integrations, visit [Instnt's documentation library.](https://support.instnt.org/hc/en-us/articles/360055345112-Integration-Overview)

[![npm version](https://img.shields.io/npm/v/@instnt/instnt-react-native-sdk.svg?style=flat-square)](https://www.npmjs.com/package/@instnt/instnt-react-native-sdk)

### Table of Contents

- [Instnt React Native SDK](#instnt-react-native-sdk)
    - [Table of Contents](#table-of-contents)
- [Prerequisites](#prerequisites)
- [Getting Started](#getting-started)
  - [Step 1 - Import InstntSignupProvider from the Instnt SDK](#step-1---import-instntsignupprovider-from-the-instnt-sdk)
  - [Step 2 - Wrap your signup components](#step-2---wrap-your-signup-components)
  - [Step 3 - Submit your signup data](#step-3---submit-your-signup-data)
  - [InstntSignupProvider](#instntsignupprovider)
  - [submitSignupData](#submitsignupdata)
  - [TextInput](#textinput)
- [OTP (One-Time Passcode)](#otp-one-time-passcode)
  - [OTP flow](#otp-flow)
- [Troubleshooting](#troubleshooting)
  - [Android](#android)
    - [Issue: Incompatible Gradle versions](#issue-incompatible-gradle-versions)
      - [Solution](#solution)
    - [Issue: Permission issue](#issue-permission-issue)
      - [Solution](#solution-1)
- [Resource links](#resource-links)
- [License](#license)

# Prerequisites

To set up and use Instnt React-Native SDK, sign into your account on the Instnt Accept's dashboard and create a customer signup workflow that works for your company. For more information about workflows, visit [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).

The integration of SDK depends on your workflow. For more information about the functionalities offered by Instnt and how to integrate SDK with your application, visit [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.

# Getting Started

- Instnt React-Native SDK is a React component and a set of Javascript library functions to facilitate communication between your React-native application, Instnt SDK and APIs.

- To use Instnt React Native SDK, open the terminal and copy the following command to install Instnt's React components:

```sh
npm install @instnt/instnt-react-native-sdk
```
NOTE: Make sure to run ```pod install``` after installing.

- Please make sure you install the latest stable version in you package.json. For more information on the latest version please visit [npm](https://www.npmjs.com/package/@instnt/instnt-react-native-sdk?activeTab=versions).


## Step 1 - Import InstntSignupProvider from the Instnt SDK

```jsx
import { InstntSignupProvider } from '@instnt/instnt-react-native-sdk';
```

## Step 2 - Wrap your signup components
```java
<InstntSignupProvider
  workflowId="v1663827295407191"
  onInit={onInstntInit}
  serviceURL="https://sandbox-api.instnt.org">

  <<your signup components>>

</InstntSignupProvider>
```
| prop  | use |
| ---------- |:-------------:|
| workflowId | **id** of the workflow you created in the Instnt dashboard.     |
| onInit     | callback function on successful initialization.     |
| serviceURL | Instnt environment that you want your app to connect to.     |

> :warning: **WARNING**: Make sure that your **TextInputs** inside the **InstntSignupProvider** component has proper setup. Please refer to [TextInput](#textinput).

## Step 3 - Submit your signup data
```jsx
import { submitSignupData } from '@instnt/instnt-react-native-sdk';

const response = await submitSignupData(data);
if (response && response.data && response.data.decision) {
  // your code here after submission
  return;
}
```
- ***data*** will be your signup data object.
```
{ key: value }
```

## InstntSignupProvider

- **InstntSignupProvider**- provides the functions to render and initiate the signup process. Acts as a top-level container component responsible for session initiation and returns the accompanying Javascript functions. Use configurations to perform different actions with your application. It occurs during the mounting phase of this component.

- A preferable approach is to wrap up your signup components with **InstntSignupProvider**. In the reference app included in the SDK, the signup view component gets rendered under **InstntSignupProvider** component. This ensures that Instnt is initialized when any of your signup components render.

- **InstntSignupProvider** works as follows:

  1. Connects to Instnt’s backend API on mount and initiates a new signup session identified by a unique instnttxnid.
  2. The calling application should pass the **workflowId**, **serviceURL** and a callback handler function **onInit** to this component.

  **workflowId** - This is the id of the workflow you created in the Instnt dashboard, and you want to be powered by Instnt.

  Example: workflowId= ```"v766520100000"```

  **serviceURL** - This is the target Instnt environment that you want your app to connect to. You need to specify a target environment like sandbox or production API root URL. For more information, visit [Instnt Environments and Pilot Process
  ](https://support.instnt.org/hc/en-us/articles/5165465750797-Instnt-Environments-and-Pilot-Process).
  
  Example: serviceURL=```"https://sandbox-api.instnt.org"```

 **onInit** - callback function on successful initialization. 

   Example: onInit=```{onInitFunction}```
    
- InstntSignupProvider invokes **onInit** callback function on successful initialization, passing the reference to the workflow and transaction attributes. The calling application can store these attributes and reference them later. The key attribute is instnttxnid which is the reference id for this particular signup session.

- Once Instnt SDK is initialized, the app can then render any subsequent components or act on the tasks associated with the signup process.

## submitSignupData

- Once an end-user fills the signup form, the application can invoke Instnt JavaScript library function **submitSignupData** to process the signup request.

- Here the parameter data is a JavaScript object with a key:value pair of user-entered data such as firstName, surName, mobileNumber provided as a key, value pair. For more information about the supported fields, see [Field Data Dictionary](https://support.instnt.org/hc/en-us/articles/360045534591-Field-Data-Dictionary)

- Please refer to the reference application bundled with React-Native SDK for more detailed code examples.

## TextInput
TextInputs need additional setup within your signup workflow in order to track behavioral data.
```
<TextInput
    testID="mobileNumber"       
    nativeID="mobileNumber"
    accessibilityLabel="mobileNumber"
    accessible>
```

These props make it possible to map the **TextInput** to their native components on iOS and Android.

# OTP (One-Time Passcode)

One-Time Passcode (OTP) functionality can be enabled by logging into the Instnt dashboard and enabling the feature in your workflow. For more information, see [OTP](https://support.instnt.org/hc/en-us/articles/4408781136909#heading-5).

Instnt SDK provides two Javascript library functions to enable OTP.

1. sendOTP (mobileNumber)

2. verifyOTP(mobileNumber, otpCode)

Please refer to the Library function listing below for more details.

## OTP flow

- User enters mobile number as part of the signup screen.
- Your app calls send OTP() 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 verify the OTP() 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

# Troubleshooting

## Android

### Issue: Incompatible Gradle versions

```java
  The Android Gradle plugin supports only Kotlin Gradle plugin version 1.5.20 and higher.The following dependencies do not satisfy the required version:project ':instnt_instnt-react-native-sdk' -> org.jetbrains.kotlin:kotlin-gradle-plugin:1.5.10"
```

#### Solution

1. Open Android Studio
2. Go to plugins
3. Change Downloaded plugin to compatible version

### Issue: Permission issue

```jsx
   Error Failed to install the app. Make sure you have the Android development environment set up: https://reactnative.dev/docs/environment-setup.
```

#### Solution

1.  Go to android folder of project
2.  Run `chmod +x gradlew`
3.  Run `./gradlew clean`
4.  Run `react-native run-android`

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

# License

The instnt-react-native SDK is under MIT license.