@instnt/instnt-react-native-sdk

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.

Table of Contents

• Instnt React Native SDK
  • Table of Contents
• Prerequisites
• Getting Started
  • Step 1 - Import InstntSignupProvider from the Instnt SDK
  • Step 2 - Wrap your signup components
  • Step 3 - Submit your signup data
  • InstntSignupProvider
  • submitSignupData
  • TextInput
• OTP (One-Time Passcode)
  • OTP flow
• Troubleshooting
  • Android
    • Issue: Incompatible Gradle versions
      • Solution
    • Issue: Permission issue
      • Solution
• Resource links
• 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 and Developer guide.

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, 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:

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.

Step 1 - Import InstntSignupProvider from the Instnt SDK

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

Step 2 - Wrap your signup components

<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: Make sure that your TextInputs inside the InstntSignupProvider component has proper setup. Please refer to TextInput.

Step 3 - Submit your signup data

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 .

  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

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

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

  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

   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
• Developer guide
• Instnt support

License

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