@trustchex/react-native-sdk

React Native SDK for KYC and identity verification with document scanning, facial recognition, liveness detection, and NFC eID support.

⚠️ Commercial License Required - Contact [email protected] for licensing.

Features

• 📄 Document scanning (passport, ID cards) with OCR
• 🔍 MRZ processing for travel documents
• 📱 NFC eID card reading
• 👤 Facial recognition and liveness detection
• 🌐 Multi-language support (English, Turkish)
• 🎨 Customizable branding
• 🔗 Deep link support
• 📊 Privacy-compliant analytics (GDPR, KVKK, PCI-DSS)

Installation

npm install @trustchex/react-native-sdk

Required Dependencies

npm install @react-navigation/native@^7.1.14 \
  @react-navigation/native-stack@^7.3.21 \
  lottie-react-native@^7.2.4 \
  react-native-compressor@^1.12.0 \
  react-native-device-info@^13.0.0 \
  react-native-fs@^2.20.0 \
  react-native-get-random-values@^1.11.0 \
  react-native-nfc-manager@^3.16.2 \
  react-native-safe-area-context@^5.5.2 \
  react-native-screens@^4.18.0 \
  react-native-svg@^15.12.0 \
  react-native-tts@^4.1.1 \
  react-native-video@^6.16.1 \
  react-native-webview@^13.15.0

Setup

Babel Configuration (babel.config.js)

module.exports = {
  presets: ['module:@react-native/babel-preset'],
};

iOS (Info.plist)

<!-- Permissions -->
<key>NSCameraUsageDescription</key>
<string>The app captures images of your ID, passport, and face, and records a video for
  secure identity verification and ensure compliance with KYC regulations.</string>
<key>NSMicrophoneUsageDescription</key>
<string>The app records a video with audio for secure identity verification and ensure
  compliance with KYC regulations.</string>
<key>NFCReaderUsageDescription</key>
<string>The app securely reads ID or passport data using NFC to verify your identity and
  ensure compliance with KYC regulations.</string>

<!-- NFC Configuration -->
<key>com.apple.developer.nfc.readersession.formats</key>
<array>
  <string>NDEF</string>
  <string>TAG</string>
</array>
<key>com.apple.developer.nfc.readersession.iso7816.select-identifiers</key>
<array>
  <string>A0000002471001</string>
  <string>E80704007F00070302</string>
  <string>A000000167455349474E</string>
  <string>A0000002480100</string>
  <string>A0000002480200</string>
  <string>A0000002480300</string>
  <string>A00000045645444C2D3031</string>
</array>

<!-- Deep Link (optional) -->
<key>CFBundleURLTypes</key>
<array>
  <dict>
    <key>CFBundleURLSchemes</key>
    <array>
      <string>your-app-scheme</string>
    </array>
  </dict>
</array>

<!-- Portrait Only -->
<key>UISupportedInterfaceOrientations</key>
<array>
  <string>UIInterfaceOrientationPortrait</string>
</array>
<key>UISupportedInterfaceOrientations~ipad</key>
<array>
  <string>UIInterfaceOrientationPortrait</string>
</array>

Android (AndroidManifest.xml)

<!-- Permissions -->
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.CAMERA" />
<uses-permission android:name="android.permission.NFC" />
<uses-permission android:name="android.permission.RECORD_AUDIO" />
<uses-permission android:name="android.permission.VIBRATE" />

<!-- Hardware -->
<uses-feature android:name="android.hardware.camera" android:required="true" />
<uses-feature android:name="android.hardware.nfc" android:required="false" />

<application android:allowBackup="false">
    <activity
        android:name=".MainActivity"
        android:screenOrientation="portrait"
        android:launchMode="singleTask"
        android:exported="true">

        <!-- App Launcher -->
        <intent-filter>
            <action android:name="android.intent.action.MAIN" />
            <category android:name="android.intent.category.LAUNCHER" />
        </intent-filter>

        <!-- NFC -->
        <intent-filter>
            <action android:name="android.nfc.action.TECH_DISCOVERED" />
        </intent-filter>

        <!-- Deep Link (optional) -->
        <intent-filter>
            <action android:name="android.intent.action.VIEW" />
            <category android:name="android.intent.category.DEFAULT" />
            <category android:name="android.intent.category.BROWSABLE" />
            <data android:scheme="your-app-scheme" />
        </intent-filter>
    </activity>
</application>

Usage

Basic

import Trustchex, { type DocumentReadResult } from '@trustchex/react-native-sdk';

<Trustchex
  baseUrl="https://your-server.com"
  sessionId="session-id"
  onDocumentRead={(result: DocumentReadResult) => {
    const { document } = result;
    console.log(document.documentType);   // "P" | "I"
    console.log(document.lastName);       // "MÜLLER"
    console.log(document.firstName);      // "JÜRGEN KARL"
    console.log(document.dateOfBirth);    // "1985-03-10" (ISO 8601)
    console.log(document.dateOfExpiry);   // "2030-11-05" (ISO 8601)
  }}
  onCompleted={() => console.log('Completed')}
  onError={(error) => console.error(error)}
/>

With Branding

<Trustchex
  baseUrl="https://your-server.com"
  sessionId="session-id"
  branding={{
    logoUrl: 'https://your-logo.png',
    primaryColor: '#1E3A8A',
    secondaryColor: '#F3F4F6',
    tertiaryColor: '#EF4444'
  }}
  locale="en" // 'en' | 'tr'
  enableAnalytics={true}
  onCompleted={() => console.log('Completed')}
  onError={(error) => console.error(error)}
/>

With Custom Analytics Tracking

import {
  trackButtonClick,
  trackScreenView,
  analyticsService
} from '@trustchex/react-native-sdk';

// Track custom events
await trackButtonClick('custom_button', 'custom_screen');
await trackScreenView('custom_screen');

// Access analytics service directly
await analyticsService.clear(); // Right to be forgotten

Deep Links

handleDeepLink parses a verification link into [baseUrl, sessionId], which you feed into <Trustchex> to start (or resume) the flow:

import { handleDeepLink } from '@trustchex/react-native-sdk';

const [baseUrl, sessionId] = handleDeepLink({
  url: 'scheme://verification-session/abc123/app-url/api.server.com'
});

To drive the flow from a link, wire the React Native Linking API and pass the result into the component:

import { AppState, Linking } from 'react-native';
import Trustchex, { handleDeepLink } from '@trustchex/react-native-sdk';

const App = () => {
  const appState = React.useRef(AppState.currentState);
  const [baseUrl, setBaseUrl] = React.useState('https://your-server.com');
  const [sessionId, setSessionId] = React.useState('');
  const lastHandledUrl = React.useRef<string | null>(null);

  const processDeepLink = React.useCallback((url: string | null) => {
    if (!url || url === lastHandledUrl.current) return;
    const [bUrl, sId] = handleDeepLink({ url });
    if (bUrl && sId) {
      lastHandledUrl.current = url;
      setBaseUrl(bUrl);
      setSessionId(sId);
    }
  }, []);

  React.useEffect(() => {
    // Cold start (app launched by the link).
    Linking.getInitialURL().then(processDeepLink);

    // Warm start (link arrives while the app is running).
    const urlSub = Linking.addEventListener('url', ({ url }) =>
      processDeepLink(url)
    );

    // Android New Architecture (bridgeless) can drop the warm-start 'url' event
    // ("Tried to access onNewIntent while context is not ready"). Re-read the
    // launch intent whenever the app returns to the foreground to recover it.
    const appStateSub = AppState.addEventListener('change', (next) => {
      if (appState.current.match(/inactive|background/) && next === 'active') {
        Linking.getInitialURL().then(processDeepLink);
      }
      appState.current = next;
    });

    return () => {
      urlSub.remove();
      appStateSub.remove();
    };
  }, [processDeepLink]);

  return <Trustchex baseUrl={baseUrl} sessionId={sessionId} /* ... */ />;
};

Android — required for warm-start deep links. When a link arrives while the app is already open, override onNewIntent in your MainActivity to store the fresh intent. Without setIntent(intent), Linking.getInitialURL() keeps returning the original launch URL and the foreground re-check above cannot recover the link — the user gets stuck on the first screen.

// MainActivity.kt
import android.content.Intent

override fun onNewIntent(intent: Intent) {
  setIntent(intent)
  super.onNewIntent(intent)
}

Also keep android:launchMode="singleTask" on the activity (see the manifest setup above) so the link is delivered to the existing instance.

iOS — required for warm-start deep links. Register your scheme under CFBundleURLTypes (see the Info.plist setup above) and forward incoming URLs to RCTLinkingManager in your AppDelegate. Without this the 'url' event never fires while the app is open. (getInitialURL() still returns the cold-start link, so the foreground re-check above does not help on iOS — the forwarding is what makes warm-start links work.)

// AppDelegate.swift
import React // exposes RCTLinkingManager

func application(
  _ app: UIApplication,
  open url: URL,
  options: [UIApplication.OpenURLOptionsKey: Any] = [:]
) -> Bool {
  return RCTLinkingManager.application(app, open: url, options: options)
}

// Universal Links (https://…):
func application(
  _ application: UIApplication,
  continue userActivity: NSUserActivity,
  restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void
) -> Bool {
  return RCTLinkingManager.application(
    application, continue: userActivity, restorationHandler: restorationHandler)
}

API

| Prop | Type | Description | | ---- | ---- | ----------- | | baseUrl | string? | Server URL | | sessionId | string? | Verification session ID | | branding | object? | Theme colors and logo | | locale | 'en' \| 'tr'? | UI language | | enableAnalytics | boolean? | Enable analytics (default: true) | | onDocumentRead | (result: DocumentReadResult) => void | Called when document is read via NFC or OCR | | onCompleted | () => void | Success callback | | onError | (error) => void | Error callback |

Analytics

The SDK includes privacy-compliant analytics that respects GDPR, KVKK, and PCI-DSS regulations.

Key Features

• ✅ No PII collected - No names, emails, addresses, or personal data
• ✅ Data anonymization - Device identifiers excluded
• ✅ Right to deletion - Users can clear their data

Analytics Configuration

Analytics is enabled by default. To customize:

<Trustchex
  enableAnalytics={true}           // Enable/disable analytics
  {...otherProps}
/>

For complete analytics documentation, see ANALYTICS.md.

Requirements

• React Native ≥ 0.79.5
• iOS ≥ 15.6 / Android ≥ API 31
• Camera required for document scanning
• NFC optional for eID cards

Troubleshooting

• Camera issues: Check permissions and device capability
• NFC not working: Enable NFC in device settings (optional feature)
• Build errors: Verify all peer dependencies are installed

License

Commercial license required. Contact [email protected] for pricing.