Kalapa NFC SDK for React Native

Overview

The Kalapa NFC Reader SDK allows reading data from NFC chips on identity documents that support NFC such as Passports and Chip-enabled ID Cards. The SDK supports two main operating modes:

• UI Mode: Displays guide screens and MRZ scanning
• Headless Mode: Direct NFC reading from MRZ string

Prerequisites

iOS

• iOS: 13.0+
• Xcode: 12.0+
• Swift: 5.0+
• Device: iPhone with NFC support (iPhone 7 and later)

Android

• MinSDK: 24
• Device: Android device with NFC support
• Activity: ComponentActivity or AppCompatActivity

Implementation

1. Install the Package

Add SDK to Project

npm install kalapa-nfc-sdk-react-native
# or
yarn add kalapa-nfc-sdk-react-native

2. iOS setup

• Enable Near Field Communication Tag Reading capability in your project
• Add to ios/YourApp/Info.plist:

<key>NFCReaderUsageDescription</key>
<string>App needs NFC Scan Usage</string>
<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>App will use your camera to take a selfie photo.</string>

3. Android setup

Add to android/app/src/main/AndroidManifest.xml:

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

4. Configuration interfaces

Appearance

You can set the correspond UI config background_color , mainColor , textColor , btnTextColor as follow by calling the configureSDK function as below:

configureSDK("#FFFFFF", "#62A583", "#65657B", "#FFFFFF", "vi","smartpay", "Nunito-Regular", "Nunito-Medium", "Nunito-Bold")

-> Remember to call this function before call start.

Custom Font Style

Android

• From your app-project, relocate to your android folder and create directory font. Relative path: android/app/src/main/res/font
• Drop .ttf files into your font folder:

  - app/main/res
    |_ font
      |- nunito_bold.ttf
      |- nunito_regular.ttf
      |_ nunito.xml

• Create an xml file name nunito.xml and defines its content:

<?xml version="1.0" encoding="utf-8"?>
<font-family xmlns:android="http://schemas.android.com/apk/res/android">
   <font
           android:fontStyle="normal"
           android:fontWeight="400"
           android:font="@font/nunito_regular" />
   <font
           android:fontStyle="normal"
           android:fontWeight="600"
           android:font="@font/nunito_bold" />
</font-family>

• In your values directory, edit the content of styles.xml, adding following line:

    <style name="AppTheme" parent="Theme.AppCompat.DayNight.NoActionBar">
        <item name="fontFamily">@font/nunito</item>
    </style>

• In order to justify the font size, you add the follow lines to your dimens.xml file in your values folder:

    <dimen name="klp_text_banner">30sp</dimen> <!-- Text size for screen title-->
    <dimen name="klp_text_sub_banner">26sp</dimen> <!-- Text size for screen sub title-->
    <dimen name="klp_text_title">24sp</dimen> <!-- Text size for snackbar title-->
    <dimen name="klp_text_h1">20sp</dimen> <!-- Text size for popup title-->
    <dimen name="klp_text_h2">18sp</dimen> <!-- Text size for popup sub-title-->
    <dimen name="klp_text_btn">16sp</dimen> <!-- Text size for button-->
    <dimen name="klp_text_h3">16sp</dimen> <!-- Text size for pop up button -->
    <dimen name="klp_text_normal">14sp</dimen> <!-- Text size for normal content -->
    <dimen name="klp_text_description">11sp</dimen> <!-- Text size for description -->
    <dimen name="klp_text_sub_description">10sp</dimen> <!-- Text size for hint / note -->

iOS

• You have to add .ttf file and config it into info.plist file in your app/ios folder
• Then just pass the font name like below:

 configureSDK("#FFFFFF", "#62A583", "#65657B", "#FFFFFF", "vi","smartpay", "Nunito-Regular", "Nunito-Medium", "Nunito-Bold")

Basic Usage

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

// 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
  'vi', // language
  'YOUR_CUSTOMER_LANGUAGE', // customer name
  'regular_font_name', // regular font name
  'medium_font_name', // medium font name
  'bold_font_name', // bold font name
);

// 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 'kalapa-nfc-sdk-react-native';

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 ( '#FFFFFF', // backgroundColor
          '#007AFF', // mainColor
          '#000000', // textColor
          '#FFFFFF',  // btnTextColor
          'vi', // language
          'YOUR_CUSTOMER_LANGUAGE', // customer name
          'regular_font_name', // regular font name
          'medium_font_name', // medium font name
          'bold_font_name', // bold font name
        );
    } 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

1.0.2

• Bug fixes

1.0.3

• Bug fixes
• UI / UX maintainace
• Support custom language, font style, language settings

1.0.4

• Provide full example and docs

1.0.5

• Bug fixes

1.0.6

• Support minSDK from 24
• Support 16KB page sizes

1.0.7

• Change config MRZ, NFC to Fragment
• UI / UX optimized

1.0.8

• Bugs fixed: MRZ screen sometimes retained; double-click issue handled.
• UI / UX optimized

1.0.9

• Android:
  • Bugs fixed, UI/ UX maintaned.
  • Rarely crash happened when enter MRZ fixed