react-native-kalapa-ekyc 1.1.3 → 1.2.1

package/README.md

@@ -1,195 +1,591 @@
-# react-native-kalapa-ekyc
+# Kalapa eKYC React Native SDK Documentation
 
-React Native SDK for Kalapa eKYC integration, providing a seamless way to implement eKYC functionality in your React Native applications.
+Complete guide for integrating Kalapa eKYC functionality into your React Native applications.
+---
+## Changelog
 
-## Installation
+### 1.2.1
+- **successColor / failureColor**: Now can be configured via sdkConfig
+### 1.2.0
+- **Documentation**: Complete overhaul of KalapaResult class documentation
+- **Documentation**: Added comprehensive property documentation for all root-level fields
+- **Documentation**: Added AddressEntities, MrzData, and QrCode object documentation
+- **Documentation**: Enhanced usage examples with all available properties
+- **Documentation**: Fixed package name references throughout documentation
+- **Documentation**: Added examples for accessing MRZ data, QR code data, and address entities
 
-Using npm:
-```bash
-npm install react-native-kalapa-ekyc
+### 1.1.3
+- **Android**: Removed GIF dependencies to satisfy Google Play requirement (16KB pages size)
+- **Stable version**
+
+### 1.1.2
+- **Android**: Removed unnecessary jitpack.io repository
+- **Android**: Updated animation to avoid GIF usage
+
+### 1.1.1
+- **Android**: Removed unnecessary jcenter repository
+
+### 1.1.0
+- **Android**: Support target SDK version 35 & edge-to-edge display
+- **Android**: Support base64 library
+- **UI & UX**: General optimization improvements
+
+### 1.0.7
+- **General**: Applied new flow for both Android & iOS platforms
+- **iOS**: UI & UX optimization
+- **Android**: UI & UX optimization
+
+---
+
+## Requirements
+
+### React Native
+
+```json
+"react": "17.0.2"
+"react-native": "0.66.3"
 ```
 
-Using yarn:
-```bash
-yarn add react-native-kalapa-ekyc
+### Android
+
+**Minimum SDK Requirements:**
+- `minSdkVersion = 24`
+- `targetSdkVersion = 33`
+- `android.useAndroidX = true`
+- `Kotlin = 1.8.0+`
+
+**Compile Options:**
+```xml
+compileOptions {
+    sourceCompatibility JavaVersion.VERSION_1_8
+    targetCompatibility JavaVersion.VERSION_1_8
+}
 ```
 
-## iOS Setup
+### iOS
+
+- iOS Development Target >= 13.4
+
+---
+
+## Getting Started
+
+### Install the SDK
+
+#### Using Yarn
 
-Add the following to your Podfile:
-```ruby
-pod 'react-native-kalapa-ekyc', :path => '../node_modules/react-native-kalapa-ekyc'
+```bash
+yarn add react-native-kalapa-ekyc
 ```
 
-Then run:
+#### Using npm
+
 ```bash
-cd ios && pod install
+npm install react-native-kalapa-ekyc
 ```
 
-## Basic Usage
+#### Manual Installation
 
-```typescript
-import KalapaEkyc from 'react-native-kalapa-ekyc';
-
-// Initialize the SDK
-const ekyc = new KalapaEkyc({
-  clientId: 'YOUR_CLIENT_ID',
-  clientSecret: 'YOUR_CLIENT_SECRET',
-  environment: 'sandbox' // or 'production'
-});
-
-// Start eKYC flow
-try {
-  const result = await ekyc.startEkyc();
-  console.log('eKYC Result:', result);
-} catch (error) {
-  console.error('eKYC Error:', error);
+Add to your `app/package.json`:
+
+```json
+"dependencies": {
+    "react-native-kalapa-ekyc": "^1.2.0"
 }
 ```
 
-## WebView Integration
+---
 
-The SDK provides a WebView-based implementation:
+## iOS Configuration
 
-```typescript
-import { WebViewScreen } from 'react-native-kalapa-ekyc';
-
-// In your navigation/component
-<WebViewScreen
-  clientId="YOUR_CLIENT_ID"
-  clientSecret="YOUR_CLIENT_SECRET"
-  onComplete={(result) => {
-    console.log('WebView eKYC completed:', result);
-  }}
-  onError={(error) => {
-    console.error('WebView eKYC error:', error);
-  }}
-/>
-```
+### Declare Camera and NFC Permissions
 
-## API Reference
+Update your `Info.plist` with the following:
 
-### KalapaEkyc Class
+```xml
+<key>NFCReaderUsageDescription</key>
+<string>This eKYC app needs NFC reader to scan chip</string>
 
-#### Constructor Options
-```typescript
-interface KalapaEkycOptions {
-  clientId: string;
-  clientSecret: string;
-  environment: 'sandbox' | 'production';
-  timeout?: number;
-  language?: 'en' | 'vi';
-}
+<key>com.apple.developer.nfc.readersession.iso7816.select-identifiers</key>
+<array>
+    <string>A0000002471001</string>
+    <string>A0000002472001</string>
+    <string>00000000000000</string>
+</array>
+
+<key>NSCameraUsageDescription</key>
+<string>This eKYC app needs to use camera to scan document</string>
 ```
 
-#### Methods
+### Enable NFC Capability
 
-- `startEkyc()`: Starts the eKYC flow
-- `getSessionStatus(sessionId: string)`: Get status of an eKYC session
-- `validateSession(sessionId: string)`: Validate an eKYC session
+Add the **Near Field Communication Tag Reading** capability to your project target in Xcode.
 
-### WebViewScreen Component
+[View Xcode capability documentation](https://help.apple.com/xcode/mac/current/#/dev88ff319e7)
 
-#### Props
-```typescript
-interface WebViewScreenProps {
-  clientId: string;
-  clientSecret: string;
-  onComplete: (result: EkycResult) => void;
-  onError: (error: Error) => void;
-  language?: 'en' | 'vi';
-  theme?: 'light' | 'dark';
+---
+
+## Implementation Guide
+
+### 1. Initialize a Session
+
+Each eKYC profile requires a unique session ID (JWT access token). The SDK uses this session ID to perform all eKYC steps.
+
+**Important Notes:**
+- Failure to provide a valid session ID results in an unauthorized error
+- Sessions are valid for 10 minutes by default (adjustable)
+- Each session ID should be used for a single eKYC flow
+
+Check the [API documentation](https://www.notion.so/Init-session-820a772b8402499887e3cc983aaab148?pvs=21) for creating a new session.
+
+---
+
+### 2. Define SDK Configuration
+
+#### Basic Configuration Structure
+
+```jsx
+let configInfo = {
+    domain: <BASE_URL>,
+    main_color: <MAIN_COLOR>,
+    main_text_color: <MAIN_TEXT_COLOR>,
+    btn_text_color: <BTN_TEXT_COLOR>,
+    background_color: <BG_COLOR>,
+    success_color: <SUCCESS_COLOR>,
+    failure_color: <FAILURE_COLOR>,
+    language: <LANGUAGE>,
+    liveness_version: <LIVENESS_VERSION>,
+    face_data: <FACE_DATA>,
+    mrz: <INPUT_MRZ>,
+    qr_code: <INPUT_QR_CODE>,
+    allow_mrz_rescan_on_nfc_mismatch: <ALLOW_MRZ_RESCAN_ON_NFC_MISMATCH>
 }
 ```
 
-## Response Types
+#### Configuration Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `BASE_URL` | String | Base URL for SDK API requests. Example endpoints: `<BASE_URL>/api/kyc/scan-front`, `<BASE_URL>/api/kyc/scan-back` |
+| `BG_COLOR` | String | Hex color code for SDK background |
+| `MAIN_COLOR` | String | Hex color code for buttons and functional texts |
+| `MAIN_TEXT_COLOR` | String | Hex color code for main text elements |
+| `BTN_TEXT_COLOR` | String | Hex color code for text inside filled buttons |
+| `SUCCESS_COLOR` | String | Hex color code for text and view that indicated for success state |
+| `FAILURE_COLOR` | String | Hex color code for text and view that indicated for failure state |
+| `LIVENESS_VERSION` | Integer | Liveness detection version:<br/>• `3` - Requires 3 random actions (turn left/right/up/down, tilt left/right)<br/>• `2` - Move face towards camera<br/>• `1` - No action required |
+| `LANGUAGE` | String | UI language: `"vi"` (Vietnamese) or `"en"` (English) |
+| `FACE_DATA` | String | Base64 face data. If valid, skips liveness step and uses this for comparison with NFC portrait or document portrait |
+| `INPUT_MRZ` | String | Pre-filled MRZ data. If valid, skips MRZ scan step. Invalid input throws `INVALID_MRZ` error |
+| `INPUT_QR_CODE` | String | Pre-filled QR code. If valid, skips QR scan step. Invalid input throws `INVALID_QR` error |
+| `ALLOW_MRZ_RESCAN_ON_NFC_MISMATCH` | Boolean | If `true`, allows user to rescan MRZ when chip data doesn't match input MRZ |
+
+---
+
+### 3. Define the SDK Flow
+
+#### Available eKYC Steps
+
+1. Scan the document
+2. Scan the face
+3. Scan the NFC chip
+
+#### Flow Types
+
+| Flow Type | Scan Document | Scan Face | Scan NFC Chip |
+|-----------|---------------|-----------|---------------|
+| `ekyc` | ✓ | ✓ | ✗ |
+| `nfc_ekyc` | ✓ | ✓ | ✓ |
+| `nfc_only` | ✗ | ✓ | ✓ |
+
+#### Flow Selection Guidelines
+
+The SDK flow typically matches the flow set during session creation. However, there are special use cases:
+
+**Example Use Case for `nfc_only`:**
+If users completed the basic `ekyc` flow but failed to scan the NFC chip, you can:
+- Reuse the same session ID
+- Set flow to `nfc_only`
+- Allow NFC chip scanning without re-scanning document and face
+
+**Best Practice:** Use separate sessions for different flows to simplify data management.
+
+---
+
+### 4. Start the SDK
+
+```jsx
+import KalapaEkyc, { KalapaResult } from 'react-native-kalapa-ekyc';
+
+let sessionId = yourSessionInitFunc();
+let sdkFlow = "<YOUR_SDK_FLOW>"; // ekyc / nfc_ekyc / nfc_only
+let configInfo = {...};
+
+KalapaEkyc.start(sessionId, sdkFlow, configInfo)
+    .then((rawResult) => {
+        try {
+            // You can use either the constructor or static method
+            const result = KalapaResult.fromRawResult(rawResult);
+            // Or: const result = new KalapaResult(rawResult);
+            handleSuccessfulResult(result);
+        } catch (error) {
+            console.error("Result parsing error:", error);
+        }
+    })
+    .catch((error) => {
+        switch (error.code) {
+            case "EXPIRED":
+                console.warn("Session expired:", error.message);
+                break;
+            case "CANCELED":
+                console.warn("User canceled:", error.message);
+                break;
+            case "PERMISSION_DENIED":
+                console.error("Permission denied:", error.message);
+                break;
+            case "DEVICE_NOT_ACCEPTABLE":
+                console.error("Device not acceptable:", error.message);
+                break;
+            case "MRZ_INVALID":
+                console.error("Invalid MRZ:", error.message);
+                break;
+            case "NFC_NOT_MATCH":
+                console.error("NFC mismatch:", error.message);
+                break;
+            case "UNSUPPORTED":
+                console.error("Unsupported device:", error.message);
+                break;
+            case "CONFIG_ERROR":
+                console.error("Configuration error:", error.message);
+                break;
+            case "OTHER":
+            default:
+                console.error("Unknown error:", error.message);
+                break;
+        }
+    });
+```
+
+---
+
+## Exception Handling
+
+### Error Codes
+
+| Error Code | Description |
+|------------|-------------|
+| `EXPIRED` | Session expired (10 minutes timeout) |
+| `CANCELED` | User canceled the eKYC process |
+| `PERMISSION_DENIED` | Camera or NFC permission denied |
+| `DEVICE_NOT_ACCEPTABLE` | Emulator, rooted, or jailbroken device detected |
+| `MRZ_INVALID` | Input MRZ is invalid |
+| `NFC_NOT_MATCH` | MRZ doesn't match NFC chip data |
+| `UNSUPPORTED` | Device doesn't support required features (usually NFC) |
+| `CONFIG_ERROR` | Configuration error |
+| `OTHER` | Unexpected error |
+
+---
+
+## Result Objects
+
+### KalapaResult Class
+
+The SDK provides a `KalapaResult` class for type-safe data access:
 
 ```typescript
-interface EkycResult {
-  sessionId: string;
-  status: 'completed' | 'pending' | 'failed';
-  data?: {
-    idCard?: IdCardData;
-    face?: FaceData;
-    verification?: VerificationResult;
-  };
-}
+import { KalapaResult } from 'react-native-kalapa-ekyc';
 
-interface IdCardData {
-  type: string;
-  number: string;
-  name: string;
-  dob: string;
-  // ... other ID card fields
-}
+// Create instance using static method (recommended)
+const result = KalapaResult.fromRawResult(rawResult);
+
+// Or use constructor directly
+const result = new KalapaResult(rawResult);
 ```
 
-## Error Handling
+#### Core Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `decision` | DecisionType | Decision result: `"APPROVED"`, `"MANUAL"`, `"REJECTED"`, or `"UNKNOWN"` |
+| `selfie_data` | SelfieData | Face matching results |
+| `nfc_data` | NfcData | NFC chip data |
+| `session` | string | Session JWT token |
+| `rawResult` | any | Original unprocessed response |
+
+#### Root-Level Personal Information
 
-The SDK throws typed errors that you can handle:
+| Property | Type | Description |
+|----------|------|-------------|
+| `name` | string | Full name from the verification result |
+| `id_number` | string | ID card number |
+| `birthday` | string | Birth date |
+| `gender` | string | Gender information |
+| `country` | string | Country information |
+| `national` | string | Nationality |
+| `ethnicity` | string | Ethnicity information |
+| `religion` | string | Religious information |
+| `features` | string | Personal identification marks or features |
+| `poi` | string | Place of issue |
+
+#### Date Information
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `doe` | string | Date of expiry |
+| `doi` | string | Date of issuance |
+
+#### Address Information
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `home` | string | Home address (full text) |
+| `home_entities` | AddressEntities | Parsed home address entities (district, ward, province, unknown) |
+| `resident` | string | Residential address (full text) |
+| `resident_entities` | AddressEntities | Parsed residential address entities (district, ward, province, unknown) |
+
+#### Document Data
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `mrz_data` | MrzData \| null | Machine Readable Zone data with parsed fields |
+| `qr_code` | QrCode \| null | QR code data from document |
+| `type` | string | Document type |
+
+---
+
+### SelfieData Object
+
+#### Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `is_matched` | boolean | Face matching result |
+| `matching_score` | number | Matching confidence score (0-100) |
+
+#### Usage Example
 
 ```typescript
-try {
-  await ekyc.startEkyc();
-} catch (error) {
-  if (error instanceof KalapaEkycError) {
-    // Handle SDK-specific errors
-    console.error(error.code, error.message);
-  } else {
-    // Handle other errors
-    console.error(error);
-  }
+if (result.selfie_data.is_matched) {
+    console.log(`Face matched with ${result.selfie_data.matching_score}% confidence`);
 }
 ```
 
-## Configuration Options
+---
 
-| Option | Type | Description | Default |
-|--------|------|-------------|---------|
-| clientId | string | Your Kalapa client ID | Required |
-| clientSecret | string | Your Kalapa client secret | Required |
-| environment | string | 'sandbox' or 'production' | 'sandbox' |
-| timeout | number | Request timeout in ms | 30000 |
-| language | string | 'en' or 'vi' | 'en' |
+### NfcData Object
 
-## Development
+#### Personal Information
 
-1. Clone the repository
-2. Install dependencies:
-```bash
-yarn install
-```
-3. Run the example app:
-```bash
-yarn example
-```
+| Property | Type | Description |
+|----------|------|-------------|
+| `name` | string | Full name from NFC chip |
+| `id_number` | string | ID card number |
+| `old_id_number` | string | Previous ID number (if any) |
+| `date_of_birth` | string | Birth date in DD/MM/YYYY format |
+| `date_of_expiry` | string | ID expiry date in DD/MM/YYYY format |
+| `date_of_issuance` | string | ID issuance date in DD/MM/YYYY format |
+| `gender` | string | Gender information |
+| `nationality` | string | Nationality |
+| `nation` | string | Nation/ethnicity information |
 
-## Contributing
+#### Address Information
 
-See the [contributing guide](CONTRIBUTING.md) to learn how to contribute to the repository and the development workflow.
+| Property | Type | Description |
+|----------|------|-------------|
+| `address` | string | Current residential address |
+| `hometown` | string | Hometown/place of origin |
 
-## License
+#### Family Information
 
-MIT
+| Property | Type | Description |
+|----------|------|-------------|
+| `father_name` | string | Father's full name |
+| `mother_name` | string | Mother's full name |
+| `spouse_name` | string | Spouse's full name |
 
-## Support
+#### Additional Information
 
-For support, please contact [support@kalapa.vn](mailto:support@kalapa.vn) or visit our [documentation](https://docs.kalapa.vn).
+| Property | Type | Description |
+|----------|------|-------------|
+| `religion` | string | Religious information |
+| `personal_identification` | string | Personal identification marks or features |
 
-## Changelog
-** 1.0.7
-  - General: Apply new flow for both Android & iOS
-  - iOS: UI & UX optimization
-  - Android: UI & UX optimization
-** 1.1.0
-  - Android: Support target version sdk 35 & edge to edge
-  - Android: Support base64 library
-  - UI & UX optimize
-** 1.1.1
-  - Android: Remove unnecesary jcenter
-** 1.1.2
-  - Android: Remove unnecesary jitpack.io 
-  - Android: Update animation avoid gif
-  - Stable version
-** 1.1.3
-  - Android: Remove gif dependencies to sastify the google play requirement (16KB pages size)
+#### Technical Data
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `face_image` | string | Base64 encoded face image from NFC chip |
+| `mrz` | string | Machine Readable Zone data (raw string) |
+
+---
+
+### AddressEntities Object
+
+Represents parsed address components:
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `district` | string | District name |
+| `ward` | string | Ward name |
+| `province` | string | Province name |
+| `unknown` | string | Unparsed address components |
+
+---
+
+### MrzData Object
+
+Contains MRZ (Machine Readable Zone) information:
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `data` | MrzDataFields \| undefined | Parsed MRZ fields |
+| `error` | MrzDataError \| undefined | Error information if parsing failed |
+
+#### MrzDataFields
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `birthday` | string \| undefined | Birth date from MRZ |
+| `doe` | string \| undefined | Date of expiry from MRZ |
+| `gender` | string \| undefined | Gender from MRZ |
+| `id_number` | string \| undefined | ID number from MRZ |
+| `name` | string \| undefined | Name from MRZ |
+| `raw_mrz` | string \| undefined | Raw MRZ string |
+
+#### MrzDataError
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `code` | number | Error code |
+| `message` | string | Error message |
+
+---
+
+### QrCode Object
+
+Contains QR code information:
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `data` | QrCodeData \| undefined | Decoded QR code data |
+| `error` | { code: number, message: string } \| undefined | Error information if decoding failed |
+
+#### QrCodeData
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `decoded_text` | string \| undefined | Decoded QR code text |
+| `stage` | number \| undefined | Processing stage |
+
+---
+
+## Convenience Methods
+
+### Decision Methods
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `isApproved()` | boolean | Returns `true` if decision is `"APPROVED"` |
+| `isManualReview()` | boolean | Returns `true` if decision is `"MANUAL"` |
+| `isRejected()` | boolean | Returns `true` if decision is `"REJECTED"` |
+
+### Face Matching Methods
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `isFaceMatched()` | boolean | Returns `true` if face matched successfully |
+| `getFaceMatchingScore()` | number | Returns face matching confidence score |
+
+### Formatted Getters
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `getDisplayName()` | string | Returns formatted name or `"N/A"` if empty |
+| `getIdNumber()` | string | Returns formatted ID number or `"N/A"` if empty |
+| `getDateOfBirth()` | string | Returns formatted birth date or `"N/A"` if empty |
+| `getFaceImage()` | string | Returns base64 face image from NFC chip |
+
+### Utility Methods
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `toJSON()` | object | Returns clean object for storage/transmission |
+| `fromRawResult(rawResult)` | KalapaResult | Static method to create KalapaResult from raw response |
+
+---
+
+## Complete Usage Example
+
+```typescript
+import KalapaEkyc, { KalapaResult } from 'react-native-kalapa-ekyc';
+
+const handleEkyc = async () => {
+    try {
+        const rawResult = await KalapaEkyc.start(sessionId, "nfc_only", configInfo);
+        const result = KalapaResult.fromRawResult(rawResult);
+        
+        // Check decision
+        if (result.isApproved()) {
+            console.log("eKYC Approved");
+        } else if (result.isManualReview()) {
+            console.log("Manual review required");
+        }
+        
+        // Check face matching
+        if (result.isFaceMatched()) {
+            console.log(`Face matched: ${result.getFaceMatchingScore()}%`);
+        }
+        
+        // Access root-level data
+        console.log(`Name: ${result.name}`);
+        console.log(`ID Number: ${result.id_number}`);
+        console.log(`Birthday: ${result.birthday}`);
+        
+        // Access NFC data
+        const userData = {
+            name: result.nfc_data.name,
+            idNumber: result.nfc_data.id_number,
+            birthDate: result.nfc_data.date_of_birth,
+            faceImage: result.nfc_data.face_image
+        };
+        
+        // Access address entities
+        if (result.home_entities) {
+            console.log(`Home: ${result.home_entities.province}, ${result.home_entities.district}`);
+        }
+        
+        // Access MRZ data if available
+        if (result.mrz_data?.data) {
+            console.log(`MRZ Name: ${result.mrz_data.data.name}`);
+            console.log(`Raw MRZ: ${result.mrz_data.data.raw_mrz}`);
+        }
+        
+        // Access QR code data if available
+        if (result.qr_code?.data) {
+            console.log(`QR Code: ${result.qr_code.data.decoded_text}`);
+        }
+        
+        // Export to JSON for storage/transmission
+        const jsonData = result.toJSON();
+        await saveUserData(jsonData);
+        
+    } catch (error) {
+        handleEkycError(error);
+    }
+};
+```
+
+---
+
+## Summary
+
+The Kalapa eKYC React Native SDK provides comprehensive identity verification with document scanning, face matching, and NFC chip reading capabilities. Key features include:
+
+- Three flexible flow types for different verification needs
+- Customizable UI with color and language options
+- Multiple liveness detection versions
+- Type-safe result objects with convenience methods
+- Robust error handling with detailed error codes
+- Support for pre-filled data to skip certain steps
+
+For API documentation and session creation, refer to the [Kalapa API documentation](https://kalapa-no.notion.site/eKYC-API-SDK-document-2a2a4ccfa1184a789cb4513fade351e4?pvs=74)