React Native Kalapa NFC Reader

A React Native library for reading NFC-enabled Vietnamese government issued documents and performing eKYC verification using Kalapa's advanced NFC reading technology.

Features

• ✅ NFC document reading for Vietnamese ID cards and passports
• ✅ Support for both UI and headless modes
• ✅ eKYC verification integration
• ✅ Customizable UI theming
• ✅ iOS and Android support
• ✅ TypeScript support

Requirements

iOS

• iOS 13.0 or later
• NFC capability enabled in your app
• Near Field Communication Tag Reading capability in your app's entitlements

Android

• Android API level 26 (Android 5.0) or later
• NFC hardware support
• NFC permission in AndroidManifest.xml

Installation

npm install react-native-kalapa-nfc-reader

iOS Setup

1. Add NFC capability to your iOS app:

<!-- ios/YourApp/Info.plist -->
<key>NFCReaderUsageDescription</key>
<string>This app uses NFC to read identity documents for verification purposes.</string>

<key>com.apple.developer.nfc.readersession.felica.systemcodes</key>
<array>
  <!-- Add your system codes here -->
</array>

<key>com.apple.developer.nfc.readersession.iso7816.select-identifiers</key>
<array>
  <!-- Add your application identifiers here -->
</array>

2. Enable Near Field Communication Tag Reading in your app's capabilities in Xcode.

3. Run pod install:

cd ios && pod install

Android Setup

1. Add NFC permissions to your AndroidManifest.xml:

<!-- android/app/src/main/AndroidManifest.xml -->
<uses-permission android:name="android.permission.NFC" />
<uses-feature android:name="android.hardware.nfc" android:required="true" />

2. Add the NFC intent filters to your main activity:

<activity
  android:name=".MainActivity"
  ...>
  <intent-filter>
    <action android:name="android.nfc.action.TECH_DISCOVERED" />
    <category android:name="android.intent.category.DEFAULT" />
  </intent-filter>
</activity>

Usage

Basic Usage

import {
  isNFCSupported,
  isNFCEnabled,
  startWithUI,
  startWithoutUI,
  configureSDK,
  getSDKVersion
} from 'react-native-kalapa-nfc-reader';

// Check if NFC is supported on the device
const nfcSupported = await isNFCSupported();
console.log('NFC Supported:', nfcSupported);

// Check if NFC is enabled
const nfcEnabled = await isNFCEnabled();
console.log('NFC Enabled:', nfcEnabled);

// Start NFC reading with UI
try {
  const result = await startWithUI();
  console.log('NFC Reading Result:', result);
} catch (error) {
  console.error('NFC Reading Error:', error);
}

Advanced Usage

// Configure SDK appearance
await configureSDK(
  '#FFFFFF', // backgroundColor
  '#007AFF', // mainColor
  '#000000', // textColor
  '#FFFFFF'  // btnTextColor
);

// Start NFC reading without UI (requires MRZ data)
const mrzData = "P<VNMEXAMPLE<<JANE<DOE<<<<<<<<<<<<<<<<<<<<<<<<1234567890VNM9001011F25123115<<<<<<<<<<<<<<04";
try {
  const result = await startWithoutUI(mrzData);
  console.log('Headless NFC Result:', result);
} catch (error) {
  console.error('Headless NFC Error:', error);
}

// Get SDK version
const version = await getSDKVersion();
console.log('SDK Version:', version);

React Component Example

import React, { useState, useEffect } from 'react';
import { View, Button, Text, Alert } from 'react-native';
import {
  isNFCSupported,
  isNFCEnabled,
  startWithUI,
  configureSDK
} from 'react-native-kalapa-nfc-reader';

const NFCReaderComponent = () => {
  const [nfcSupported, setNfcSupported] = useState(false);
  const [nfcEnabled, setNfcEnabled] = useState(false);

  useEffect(() => {
    checkNFCStatus();
    configureSdkTheme();
  }, []);

  const checkNFCStatus = async () => {
    try {
      const supported = await isNFCSupported();
      const enabled = await isNFCEnabled();
      setNfcSupported(supported);
      setNfcEnabled(enabled);
    } catch (error) {
      console.error('Error checking NFC status:', error);
    }
  };

  const configureSdkTheme = async () => {
    try {
      await configureSDK('#F8F9FA', '#007AFF', '#212529', '#FFFFFF');
    } catch (error) {
      console.error('Error configuring SDK:', error);
    }
  };

  const handleStartNFC = async () => {
    if (!nfcSupported) {
      Alert.alert('Error', 'NFC is not supported on this device');
      return;
    }

    if (!nfcEnabled) {
      Alert.alert('Error', 'Please enable NFC in your device settings');
      return;
    }

    try {
      const result = await startWithUI();
      Alert.alert('Success', `NFC Reading completed: ${result}`);
    } catch (error) {
      Alert.alert('Error', `NFC Reading failed: ${error.message}`);
    }
  };

  return (
    <View style={{ padding: 20 }}>
      <Text>NFC Supported: {nfcSupported ? 'Yes' : 'No'}</Text>
      <Text>NFC Enabled: {nfcEnabled ? 'Yes' : 'No'}</Text>
      <Button
        title="Start NFC Reading"
        onPress={handleStartNFC}
        disabled={!nfcSupported || !nfcEnabled}
      />
    </View>
  );
};

export default NFCReaderComponent;

API Reference

Methods

isNFCSupported(): Promise<boolean>

Checks if the device supports NFC functionality.

Returns: Promise that resolves to true if NFC is supported, false otherwise.

isNFCEnabled(): Promise<boolean>

Checks if NFC is currently enabled on the device.

Returns: Promise that resolves to true if NFC is enabled, false otherwise.

startWithUI(): Promise<string>

Starts the NFC reading process with the built-in UI interface.

Returns: Promise that resolves to a string containing the reading result.

startWithoutUI(mrz: string): Promise<string>

Starts the NFC reading process without UI using provided MRZ data.

Parameters:

• mrz (string): Machine Readable Zone data from the document

Returns: Promise that resolves to a string containing the reading result.

configureSDK(backgroundColor: string, mainColor: string, textColor: string, btnTextColor: string): Promise<boolean>

Configures the visual appearance of the SDK UI.

Parameters:

• backgroundColor (string): Background color in hex format
• mainColor (string): Main theme color in hex format
• textColor (string): Text color in hex format
• btnTextColor (string): Button text color in hex format

Returns: Promise that resolves to true if configuration was successful.

getSDKVersion(): Promise<string>

Gets the current version of the SDK.

Returns: Promise that resolves to the SDK version string.

hello(): string

Test function that returns a hello message.

Returns: String containing hello message.

Error Handling

The library provides detailed error messages for common issues:

• NFC not supported on device
• NFC disabled in device settings
• Document reading errors
• Invalid MRZ data
• Configuration errors

Always wrap NFC operations in try-catch blocks to handle potential errors gracefully.

Supported Documents

• Vietnamese National ID Cards (CCCD)
• Vietnamese Passports
• Other NFC-enabled government documents (based on Kalapa's supported format)

Troubleshooting

iOS Issues

1. "NFC is not available": Ensure your device supports NFC and has iOS 11.0 or later.
2. "NFC permission denied": Add the required NFC usage description to Info.plist.
3. Build errors: Make sure to run pod install after installation.

Android Issues

1. "NFC not supported": Verify the device has NFC hardware.
2. "NFC disabled": Guide users to enable NFC in Android settings.
3. Permission errors: Ensure NFC permissions are added to AndroidManifest.xml.

Contributing

We welcome contributions! Please read our contributing guidelines before submitting pull requests.

License

This project is licensed under a proprietary license. See the LICENSE file for details.

Support

For technical support and questions:

• Email: [email protected]
• Documentation: Kalapa Developer Portal

Changelog

1.0.1

• Initial release
• Basic NFC reading functionality
• iOS and Android support