Sanctum Key KYC SDK

A comprehensive React Native SDK for identity verification (KYC — Know Your Customer) with Expo support, featuring advanced camera capabilities powered by react-native-vision-camera.

🚀 Features

✅ Advanced Camera Integration with react-native-vision-camera
✅ Selfie Capture with face detection and overlay
✅ Document Capture with auto-focus and quality controls
✅ Orientation Video Processing for liveness detection
✅ File Upload with validation
✅ Custom Overlays and instructions
✅ Permission Management with graceful fallbacks
✅ Multi-Platform Support (iOS, Android, Web)
✅ TypeScript Support with full type definitions
✅ Expo Config Plugin for easy setup
✅ JSON Template System for configurable KYC flows
✅ Multilingual Support (French, English)
✅ GPS Location Capture
✅ Country Selection with region mapping
✅ Reusable UI Components

Installation

To avoid version conflicts, install the SDK and its peer dependencies in three distinct steps.

Prerequisites

Initialize a new Expo project with TypeScript (recommended):

npx create-expo-app@latest my-kyc-app --template blank-typescript
cd my-kyc-app

Step 1 — Install the SDK

npm install @sanctum-key/react-native-sdk --legacy-peer-deps

Step 2 — Install Native Expo Dependencies

Use npx expo install so Expo automatically resolves the correct versions for your SDK build (e.g., SDK 53 or 54):

npx expo install react-native-vision-camera expo-location expo-image-manipulator react-native-svg expo-file-system 

Step 3 — Install Standard NPM Dependencies

npm install axios i18n-js iconsax-react-nativejs zustand

Expo Configuration

Because this SDK uses the camera and location, add the plugin to your app.json (or app.config.js) to automatically inject the correct native permissions for iOS and Android.

{
  "expo": {
    "plugins": [
      [
        "react-native-vision-camera",
        {
          "cameraPermissionText": "This app uses the camera for KYC identity verification.",
          "enableMicrophonePermission": true,
          "microphonePermissionText": "This app uses the microphone for video recording."
        }
      ],
      [
        "@sanctum-key/react-native-sdk/plugin",
        {
          "visionCamera": {
            "cameraPermissionText": "This app uses the camera for KYC identity verification.",
            "microphonePermissionText": "This app uses the microphone for video recording."
          },
          "location": {
            "locationPermissionText": "This app uses location to verify your identity.",
            "locationWhenInUsePermissionText": "This app uses location to verify your identity.",
            "enableBackgroundLocation": false
          }
        }
      ]
    ]
  }
}

Important: After updating your app.json, you must generate a new native build (eas build --profile development or npx expo prebuild) for the permissions to take effect.

Building the App for Development

Since this SDK requires custom native code (camera and location permissions), you cannot use Expo Go. You must create a development build using Expo Application Services (EAS).

1. Install the EAS CLI:

   npm install -g eas-cli

2. Log in and configure the build:

   eas login
   eas build:configure

3. Run the build (select the development profile):

   eas build --profile development --platform android
   # or --platform ios

4. Once the build finishes, install the app on your device or emulator and start the local development server:

   npx expo start --dev-client

Quick Start

The recommended approach is to use the JSON template system to configure your KYC flow. Drop this into your App.tsx:

import React, { useState } from 'react';
import { Alert, View, StyleSheet } from 'react-native';
import { LaunchSanctumKeyKYC, VerificationState } from '@sanctum-key/react-native-sdk';

export default function App() {
  const [showKYC, setShowKYC] = useState(true);

  if (!showKYC) return <View style={styles.container} />;

  return (
    <View style={styles.container}>
      <LaunchSanctumKeyKYC
        onComplete={(data: VerificationState) => {
          Alert.alert('Success', 'KYC Verification Completed');
          setShowKYC(false);
          console.log('KYC Data:', JSON.stringify(data, null, 2));
        }}
        onCancel={() => {
          Alert.alert('Cancelled', 'User exited the KYC flow');
          setShowKYC(false);
        }}
        onError={(error) => {
          Alert.alert('Error', String(error));
          setShowKYC(false);
        }}
        language="en"
        API_KEY={undefined} // Leave undefined for test environments
        env="PRODUCTION"
      />
    </View>
  );
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
  },
});

Supported Document Types

| Key | Description | |---|---| | identity_card | Identity card | | passport | Passport | | drivers_licence | Driver's license | | health_insurance_card | Health insurance card | | permanent_residence | Permanent residence permit | | national_id | National ID card | | work_permit | Work permit |

Multilingual Support

The SDK currently supports French and English. Texts can be customized via the JSON template system using LocalizedText objects:

{
  "labels": {
    "en": "Upload your ID card",
    "fr": "Téléversez votre carte d'identité"
  }
}

Troubleshooting

Unable to resolve "@sanctum-key/react-native-sdk"
Metro has cached an old build. Stop your server and run:

npx expo start --clear

Unable to resolve "react-native-svg" / "expo-image-manipulator"
You are missing a peer dependency. Re-run the installation commands in Steps 2 and 3, then clear your Metro cache.

Camera or location crashes on launch
You likely haven't rebuilt your native app since adding the plugin to app.json. Run an EAS build to inject the permissions into your AndroidManifest.xml and Info.plist.

Development & Publishing

This section is intended for SDK maintainers.

Building Locally

When modifying the SDK, ensure all static assets (.gif, .svg) are correctly copied to the build folder:

npm install
npm run build

Publishing to NPM

Clean and build a fresh copy:

npm ci
npm run clean
npm run build

Bump the version:

# Choose one: patch | minor | major
npm version patch -m "release: %s"

Publish to the public registry:

npm publish --access public

Contributing

1. Fork the repository
2. Create your feature branch: git checkout -b feature/amazing-feature
3. Commit your changes: git commit -m 'Add some amazing feature'
4. Push to the branch: git push origin feature/amazing-feature
5. Open a Pull Request

License

This project is licensed under the MIT License — see the LICENSE file for details.

Support

For support, email [email protected] or open an issue on GitHub.

Built with ❤️ by the Sanctum Key Team