React Native SDK - Integration Guide

This guide provides step-by-step instructions for integrating the HyperKYC React Native SDK into your project.

Additional Resource

• Complete Sample Project: A ready to use example project with all the code you need to get started with the React Native SDK quickly.

Prerequisites

Before starting the integration, please ensure you meet all the requirements listed in the Prerequisites for React Native SDK Integration section.

Integration Steps

The following steps will guide you through implementing the HyperKYC React Native SDK in your application:

Step 1: Add the SDK to your Project

Install using npm or yarn

1. Install the React Native wrapper:

Bash

# Install the RN wrapper
npm install react-native-hyperkyc-sdk
# or
yarn add react-native-hyperkyc-sdk

Platform-Specific Installation

After installing the package, platform-specific setup is required:

Android:

• For projects using React Native 0.60+ with auto-linking enabled, no additional installation steps are required. The native dependencies are automatically linked.
• For older React Native versions, follow the wrapper's README for manual linking configuration.

iOS:

• Install native dependencies by running pod install in the iOS directory:

  cd ios && pod install && cd ..

• For detailed iOS configuration (including static framework setup for version 0.6.0+), see the iOS Configuration section in Step 2.

Step 2: Platform Setup

Android Configuration

1. Ensure minSdkVersion 21 in android/app/build.gradle:

Gradle

android {
    defaultConfig {
        minSdkVersion 21
        // ... other configurations
    }
}

2. Add only required permissions in AndroidManifest.xml:

AndroidManifest.xml

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.CAMERA" />

<!-- Optional -->
<!-- <uses-permission android:name="android.permission.RECORD_AUDIO" /> -->
<!-- <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" /> -->

3. Remove unused permissions if needed:

AndroidManifest.xml

<uses-permission android:name="android.permission.RECORD_AUDIO"
  tools:node="remove" />

iOS Configuration

⚠️ Integration from Version 0.6.0 on iOS

Why the Change?

By default, all frameworks in React Native are built as dynamic frameworks when USE_FRAMEWORKS is set to false. Since HyperKYC is a static library, we need to explicitly configure it as a static framework

Compatibility

• For Xcode versions ≥ 15.2 (required for HyperKYC 0.22.0 & above)

Steps to Implement

1. Install the required plugin

   Install the cocoapods-user-defined-build-types plugin:

   gem install cocoapods-user-defined-build-types

2. Clear the Pod cache

   Run the following command:

   pod cache clean --all

3. Modify the Podfile

   • Add the following lines to enable static frameworks:

     plugin 'cocoapods-user-defined-build-types'
     enable_user_defined_build_types!
     
     pod 'HyperKYC', :build_type => :static_framework

4. Apply the changes

   Save the Podfile and run:

   pod install

Following the steps above ensures compatibility with different Xcode versions while preventing Swift compiler-related issues.

1. Add required permission descriptions in Info.plist:

Info.plist

<key>NSCameraUsageDescription</key>
<string>Camera required for KYC</string>
<key>NSMicrophoneUsageDescription</key>
<string>Microphone required for video KYC</string>
<key>NSLocationWhenInUseUsageDescription</key>
<string>Location required for KYC workflow</string>

Step 3 (Optional): Prefetch Resources and Configs

To improve performance, prefetch resources and configs configuration before launch:

Prefetch timing requirement

Call prefetch() well before launch(), not right before it. Calling it immediately before launch() can leave the workflow stuck in a loading state. Prefetch duration depends on network bandwidth; allow enough time for it to complete before the user starts the workflow.

TypeScript

Hyperkyc.prefetch('<APP_ID>', '<WORKFLOW_ID>');

• appId: Your assigned App ID
• workflowId: Workflow configured in the HyperVerge dashboard

Step 4: Optional Configurations

Create and customize the HyperKYC configuration to match your specific requirements and workflow needs.

Step 4.1: Create the HyperKYC Config

HyperKYC React Native SDK supports two authentication methods for configuration: appID and appKey for straightforward integration, or access tokens for token-based authentication. Both approaches are demonstrated below, with access token generation steps available on the Authentication page.

(Recommended Method) Using Access Tokens

The following integration code creates a configuration instance based on the accessToken.

Typescript

var configDictionary = {};
configDictionary["accessToken"] = accessToken

(Legacy Method) Using Credentials

The following integration code creates a configuration instance based on the appID and the appKey provided by HyperVerge:

TyperScript

var configDictionary = {};
configDictionary["appId"] = appID;
configDictionary["appKey"] = appKey;
)

Step 4.2: Customize the Config

List of workflow configuration options in the HyperVerge React Native SDK:

a. Set Custom Inputs

• Use the Set Inputs function when your workflow requires an external input for its functionality.

   configDictionary["inputs"] = inputsDictionary

b. Set Default Language Code

• Provide an alpha 2 language code to the Set Default Language Code function to set a default language for the workflow's user interface.

• The defaultLangCode parameter accepts the language code value as a string datatype (e.g., "en" for English, "vi" for Vietnamese). Pass it as a part of the configDictionary.

  configDictionary["defaultLangCode"] = "<the_alpha_2_language_code>" 

c. Set Use Location

Enable the Set Use Location function to mandatorily require users to grant location permission to the SDK. When enabled, the SDK prevents capturing of the user's face or identity document until the location permission is granted and updated correctly to the SDK.

• The useLocation parameter accepts a boolean datatype (true or false). By default, it’s set to false (location is optional).

• If set to true, the SDK won’t let the user proceed unless location permission is granted and shared correctly.

• If the permission is not provided or updated to the SDK, it throws a 106-PERMISSIONS_ERROR.

  configDictionary["useLocation"] = <true/false>

d. Cross Platform Resume (CPR)

The CPR functionality allows users to seamlessly resume their workflow journey across platforms by using a consistent uuid.

• Generate the uniqueId and pass it as the part of configDictionary

  // Generate unique ID
          Hyperkyc.createUniqueId(uniqueId) =>{
              console.log(uniqueId)
              configDictionary["uniqueId"] = uniqueId;  

Parameter Reference

Property	Purpose	Example	Notes
inputs	Pass dynamic inputs	{panNumber: "ABCDE1234F"}	Pre-fill workflow fields
useLocation	Request location consent	true	Denial prevents workflow execution
defaultLangCode	Set default workflow language	"en"	Defaults to first configured language
createUniqueId	Add unique ID for CPR	"12345-abc"	Used with transactionId for retry flows

Step 5: Launch the workflow and Implement a Results Handler

Create a results handler to process the outcome of the workflow. The example below shows how to register a launcher to handle the results from the SDK:

TypeScript

//  Launch HyperKyc using launch() function
Hyperkyc.launch(configDictionary, function(result){
    console.log(result)
    //  Handle result (refer this for more info)
    switch(result.response.status) {
        case "auto_approved":
        case "auto_declined":
        case "needs_review":
            // Handle Success Workflow
            break;
        case "user_cancelled":
            // Handle User Cancelled
            break;
        case "error":
            // Handle Failure Scenario
            break;
    }
}) 

Step 6 (Optional): Implement Real-Time Event Notifications

The real-time event notification system provides immediate insights into user journeys through event-based architecture. These events are triggered when users complete major milestones in their journey, allowing you to track progress and implement trigger-based interventions.

To implement real-time event notifications in your React Native app, refer to the React Native implementation guide.

Step 7: Launch the SDK

Call the launch method to initiate the SDK workflow:

TypeScript

 // Launch HyperKYC
      Hyperkyc.launch(config, (response: any) => {
        console.log('HyperKYC Response:', response);
     });
   

• transactionId must be unique per session.
• Handles both success (with response) and failure (with error codes).
• In production, prefer token-based authentication instead of embedding appKey.

Important

Avoid repeated SDK initialization. Ensure your app prevents multiple button presses or asynchronous triggers to avoid multiple invocations of the SDK.

You are now ready to build and run your React Native app!

Your React Native application is now successfully integrated with the HyperKYC SDK. You can build and test your application to ensure everything works as expected.

SDK Responses

For detailed information about React Native SDK responses, see the SDK Response Documentation.

Error Response Details

The React Native SDK normalizes internal errors into standardized error codes.

Code	Name	Android	iOS	Description
101	SDK_CONFIG_ERROR	✓	✓	Config errors (empty/invalid appId, workflowId, transactionId, accessToken, defaultLangCode)
102	SDK_INPUT_ERROR	✓	✓	Invalid/missing inputs, file inaccessible
103	USER_CANCELLED_ERROR	✓	✓	User closed/cancelled workflow
104	WORKFLOW_ERROR	✓	✓	Workflow execution errors (doc, face, API, encryption)
105	SDK_VERSION_ERROR	✓	✓	SDK version not supported by workflow
106	PERMISSIONS_ERROR	✓	✓	Required permission not granted (camera, mic, location)
107	HARDWARE_ERROR	✓	✓	Device hardware/camera failure
108	GPS_ACCESS_DENIED	✓	✓	Location permission denied
109	QR_SCANNER_ERROR	✓	(reserved)	QR scanner submodule missing (Android)
110	SSL_CONNECT_ERROR	✓	✓	SSL handshake/pinning failure
111	NETWORK_ERROR	✓	✓	Connectivity/server errors (timeouts, 4xx/5xx, token expired)
112	SIGNATURE_FAILED_ERROR	✓	✓	Response signature mismatch
113	FACE_NOT_DETECTED	✓	✓	Face not detected or blurry
114	DEVICE_ROOTED_ERROR	✓	–	Android only (rooted/jailbroken device check)
115	SECURITY_ERROR	(reserved)	✓	iOS only — screenshot or screen recording detected
117	ACTIVITY_DESTROYED_ERROR	✓	–	Android only — Activity destroyed / low memory
118	LOW_STORAGE_ERROR	✓	–	Android only — storage < 1 MB
119	NFC_INVALID_ERROR	✓	–	Android only — NFC SDK not integrated
120	NFC_UNAVAILABLE_ERROR	✓	✓	NFC not available on device
121	NFC_AUTHENTICATION_ERROR	✓	✓	NFC chip authentication failed
122	NFC_CONNECTION_ERROR	✓	✓	NFC card disconnected mid-scan
123	WEB_FORM_ERROR / FORM_V2_ERROR	✓	✓	Web form integration/config errors
124	BROWSER_NOT_SUPPORTED	✓	✓	No supported browser available
125	NFC_INCOMPLETE_SCAN_ERROR	✓	✓	NFC scan incomplete (missing DGs)
126	PRIVACY_CONSENT_DENIED_ERROR	✓	✓	User denied privacy consent
127	WEBCORE_NOT_SUPPORTED	✓	–	Android only — missing Play Services / WebView
128	SDK_EXIT_ERROR	✓	✓	SDK closed unexpectedly / backgrounded
140	SDK_INTERNAL_ERROR	✓	–	Android only — unexpected state
141	PERMISSION_REVOKED_ERROR / DATE_FORMAT_ERROR (iOS)	✓	✓	Android: permission revoked mid-flow; iOS: invalid date format
151	CHECK_SESSION_ERROR	✓	✓	Session validation failed