React Native SDK

A cross-platform React Native SDK that wraps the native iOS and Android SDKs, providing a unified TypeScript API for identity verification.

GitHub Repository

View source code and examples on GitHub

npm Package

@didit-protocol/sdk-react-native

Native SDK: This is the recommended approach for React Native and Expo apps. The SDK wraps the native iOS and Android SDKs for the best user experience, optimized camera handling, and full NFC support.

Requirements

Requirement	Minimum Version
React Native	0.76+ (New Architecture / TurboModules)
Node.js	20+
TypeScript	5+

Platform Requirements

Platform	Minimum Version	Notes
iOS	13.0+	NFC passport reading requires iOS 15.0+
Android	API 23+ (6.0)	Kotlin 1.9+, Java 17+

Installation

Expo (Recommended)

npx expo install @didit-protocol/sdk-react-native

Then add the config plugin to your app.json (or app.config.js):

{
  "expo": {
    "plugins": ["@didit-protocol/sdk-react-native"]
  }
}

That’s it. The plugin automatically configures both platforms:

Android: Adds the Didit Maven repository to Gradle and packaging exclusions
iOS: Adds the DiditSDK podspec to the Podfile

This SDK uses native modules (camera, NFC) that are not available in Expo Go. You must use a development build or run npx expo prebuild to generate the native projects.

React Native CLI

npm install @didit-protocol/sdk-react-native
# or
yarn add @didit-protocol/sdk-react-native

iOS Setup

Add the DiditSDK pod to your Podfile (it’s not on CocoaPods trunk):

# In your ios/Podfile, inside the target block:
pod 'DiditSDK', :podspec => 'https://raw.githubusercontent.com/didit-protocol/sdk-ios/main/DiditSDK.podspec'

Then install dependencies:

cd ios
bundle exec pod install

Android Setup

Add the Didit Maven repository to your project-level settings.gradle:

dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
        maven { url "https://raw.githubusercontent.com/didit-protocol/sdk-android/main/repository" }
    }
}

Add a packaging exclusion to your app’s build.gradle to avoid build conflicts:

android {
    packaging {
        resources {
            excludes += "META-INF/versions/9/OSGI-INF/MANIFEST.MF"
        }
    }
}

Permissions

iOS

Add the following keys to your app’s Info.plist:

Permission	Info.plist Key	Description	Required
Camera	`NSCameraUsageDescription`	Document scanning and face verification	Yes
NFC	`NFCReaderUsageDescription`	Read NFC chips in passports/ID cards	If using NFC
Location	`NSLocationWhenInUseUsageDescription`	Geolocation for fraud prevention	Optional

NFC Configuration

To enable NFC reading for passports and ID cards with chips:

Add NFC Capability in Xcode:
- Select your target > Signing & Capabilities > + Capability > Near Field Communication Tag Reading
Add ISO7816 Identifiers to Info.plist:

<key>com.apple.developer.nfc.readersession.iso7816.select-identifiers</key>
<array>
    <string>A0000002471001</string>
</array>

Android

The following permissions are declared in the SDK’s AndroidManifest.xml and merged automatically:

Permission	Description	Required
`INTERNET`	Network access for API communication	Yes
`ACCESS_NETWORK_STATE`	Detect network availability	Yes
`CAMERA`	Document scanning and face verification	Yes
`NFC`	Read NFC chips in passports/ID cards	If using NFC

Camera and NFC hardware features are declared as optional (android:required="false"), so your app can be installed on devices without these features.

Quick Start

import { startVerification, VerificationStatus } from '@didit-protocol/sdk-react-native';

// Start verification with a session token from your backend
const result = await startVerification('your-session-token');

switch (result.type) {
  case 'completed':
    if (result.session.status === VerificationStatus.Approved) {
      console.log('Identity verified!');
    }
    break;
  case 'cancelled':
    console.log('User cancelled');
    break;
  case 'failed':
    console.log('Error:', result.error.message);
    break;
}

Integration Methods

The SDK supports two integration methods:

Method 1: Session Token (Recommended for Production)

Create a session on your backend using the Create Verification Session API, then pass the token to the SDK:

import { startVerification } from '@didit-protocol/sdk-react-native';

// Your backend creates a session and returns the token
const sessionToken = await yourBackend.createVerificationSession(userId);

// Pass the token to the SDK
const result = await startVerification(sessionToken);

This approach gives you full control over:

Associating sessions with your users (vendor_data)
Setting custom metadata
Configuring callbacks per session

Method 2: Workflow ID (Simpler Integration)

For simpler integrations, the SDK can create sessions directly using your workflow ID:

import { startVerificationWithWorkflow } from '@didit-protocol/sdk-react-native';

const result = await startVerificationWithWorkflow('your-workflow-id', {
  vendorData: 'user-123',
  contactDetails: { email: 'user@example.com' },
  config: { loggingEnabled: true },
});

Configuration

Customize the SDK behavior by passing a config object:

const result = await startVerification('your-session-token', {
  languageCode: 'es',       // Force Spanish language
  fontFamily: 'Avenir',     // Custom font
  loggingEnabled: true,     // Enable debug logging
});

For startVerificationWithWorkflow, pass config inside options.config:

const result = await startVerificationWithWorkflow('your-workflow-id', {
  vendorData: 'user-123',
  config: {
    languageCode: 'es',
    loggingEnabled: true,
  },
});

Configuration Options

Property	Type	Default	Description
`languageCode`	`string`	Device locale	ISO 639-1 language code (e.g. `"en"`, `"fr"`, `"ar"`)
`fontFamily`	`string`	System font	Custom font family name (must be registered natively)
`loggingEnabled`	`boolean`	`false`	Enable SDK debug logging

Theming & Colors: Colors, backgrounds, and intro screen settings are configured through your White Label settings in the Didit Console, not in the SDK configuration. This ensures consistent branding across all platforms.

Language Support

The SDK supports 40+ languages. If no language is specified, the SDK uses the device locale with English as fallback.

// Use device locale (default)
await startVerification(token);

// Force specific language
await startVerification(token, { languageCode: 'fr' });

View All Supported Languages →

Advanced Options

These options are only available with startVerificationWithWorkflow, where the SDK creates the session on your behalf.

Contact Details (Prefill & Notifications)

Provide contact details to prefill verification forms and enable email notifications:

const result = await startVerificationWithWorkflow('your-workflow-id', {
  contactDetails: {
    email: 'user@example.com',
    sendNotificationEmails: true,  // Send status update emails
    emailLang: 'en',               // Email language (ISO 639-1)
    phone: '+14155552671',         // E.164 format
  },
});

Expected Details (Cross-Validation)

Provide expected user details for automatic cross-validation with extracted document data:

const result = await startVerificationWithWorkflow('your-workflow-id', {
  expectedDetails: {
    firstName: 'John',
    lastName: 'Doe',
    dateOfBirth: '1990-05-15',     // YYYY-MM-DD format
    nationality: 'USA',            // ISO 3166-1 alpha-3
    country: 'USA',
  },
});

Custom Metadata

Store custom JSON metadata with the session (not displayed to user):

const result = await startVerificationWithWorkflow('your-workflow-id', {
  vendorData: 'user-123',
  metadata: '{"internalId": "abc123", "source": "mobile-app"}',
});

Handling Results

Both startVerification and startVerificationWithWorkflow return a Promise<VerificationResult>. The result is a discriminated union — use the type field to determine the outcome.

Result Cases

Case	Description
`completed`	Verification flow completed (check `session.status` for result)
`cancelled`	User cancelled the verification flow
`failed`	An error occurred during verification

SessionData Properties

Property	Type	Description
`sessionId`	`string`	Unique session identifier
`status`	`VerificationStatus`	`Approved`, `Pending`, or `Declined`

Error Types

Error	Description
`sessionExpired`	The session has expired
`networkError`	Network connectivity issue
`cameraAccessDenied`	Camera permission not granted
`notInitialized`	SDK not initialized (Android only)
`apiError`	API request failed
`unknown`	Other error with message

Complete Result Handling Example

import {
  startVerification,
  VerificationStatus,
  type VerificationResult,
} from '@didit-protocol/sdk-react-native';

async function verify(token: string) {
  const result: VerificationResult = await startVerification(token);

  switch (result.type) {
    case 'completed':
      switch (result.session.status) {
        case VerificationStatus.Approved:
          console.log('Approved! Session:', result.session.sessionId);
          // User is verified — grant access
          break;
        case VerificationStatus.Pending:
          console.log('Under review. Session:', result.session.sessionId);
          // Show "verification in progress" UI
          break;
        case VerificationStatus.Declined:
          console.log('Declined. Session:', result.session.sessionId);
          // Handle declined verification
          break;
      }
      break;

    case 'cancelled':
      console.log('User cancelled the verification.');
      // Maybe show retry option
      break;

    case 'failed':
      console.log(`Error [${result.error.type}]: ${result.error.message}`);
      // Handle error — show retry or contact support
      break;
  }
}

Complete Example

import { useState, useCallback } from 'react';
import {
  Text,
  View,
  TextInput,
  TouchableOpacity,
  Alert,
  ActivityIndicator,
  SafeAreaView,
} from 'react-native';
import {
  startVerification,
  VerificationStatus,
  type VerificationResult,
} from '@didit-protocol/sdk-react-native';

export default function App() {
  const [token, setToken] = useState('');
  const [loading, setLoading] = useState(false);

  const handleVerify = useCallback(async () => {
    if (!token.trim()) {
      Alert.alert('Error', 'Please enter a session token.');
      return;
    }

    setLoading(true);
    try {
      const result = await startVerification(token.trim(), {
        loggingEnabled: true,
      });

      switch (result.type) {
        case 'completed':
          Alert.alert(
            'Verification Complete',
            `Status: ${result.session.status}\nSession: ${result.session.sessionId}`
          );
          break;
        case 'cancelled':
          Alert.alert('Cancelled', 'The user cancelled the verification.');
          break;
        case 'failed':
          Alert.alert('Failed', `${result.error.type}: ${result.error.message}`);
          break;
      }
    } catch (error) {
      Alert.alert('Error', `Unexpected error: ${error}`);
    } finally {
      setLoading(false);
    }
  }, [token]);

  return (
    <SafeAreaView style={{ flex: 1, padding: 24, justifyContent: 'center' }}>
      <TextInput
        placeholder="Enter session token..."
        value={token}
        onChangeText={setToken}
        autoCapitalize="none"
        style={{
          borderWidth: 1,
          borderColor: '#ccc',
          borderRadius: 8,
          padding: 12,
          marginBottom: 16,
        }}
      />
      <TouchableOpacity
        onPress={handleVerify}
        disabled={loading}
        style={{
          backgroundColor: '#1a1a1a',
          borderRadius: 8,
          padding: 16,
          alignItems: 'center',
          opacity: loading ? 0.6 : 1,
        }}
      >
        {loading ? (
          <ActivityIndicator color="#fff" />
        ) : (
          <Text style={{ color: '#fff', fontWeight: '600' }}>
            Start Verification
          </Text>
        )}
      </TouchableOpacity>
    </SafeAreaView>
  );
}

Guides

Web SDKs

Native SDKs

Integrations

GitHub Repository

npm Package

Native SDK: This is the recommended approach for React Native and Expo apps. The SDK wraps the native iOS and Android SDKs for the best user experience, optimized camera handling, and full NFC support.

Requirements

Platform Requirements

Installation

Expo (Recommended)

React Native CLI

iOS Setup

Android Setup

Permissions

iOS

NFC Configuration

Android

Quick Start

Integration Methods

Method 1: Session Token (Recommended for Production)

Method 2: Workflow ID (Simpler Integration)

Configuration

Configuration Options

Language Support

Advanced Options

Contact Details (Prefill & Notifications)

Expected Details (Cross-Validation)

Custom Metadata

Handling Results

Result Cases

SessionData Properties

Error Types

Complete Result Handling Example

Complete Example

Guides

Web SDKs

Native SDKs

Integrations

GitHub Repository

npm Package

​Native SDK: This is the recommended approach for React Native and Expo apps. The SDK wraps the native iOS and Android SDKs for the best user experience, optimized camera handling, and full NFC support.

​Requirements

​Platform Requirements

​Installation

​Expo (Recommended)

​React Native CLI

​iOS Setup

​Android Setup

​Permissions

​iOS

​NFC Configuration

​Android

​Quick Start

​Integration Methods

​Method 1: Session Token (Recommended for Production)

​Method 2: Workflow ID (Simpler Integration)

​Configuration

​Configuration Options

​Language Support

​Advanced Options

​Contact Details (Prefill & Notifications)

​Expected Details (Cross-Validation)

​Custom Metadata

​Handling Results

​Result Cases

​SessionData Properties

​Error Types

​Complete Result Handling Example

​Complete Example

Native SDK: This is the recommended approach for React Native and Expo apps. The SDK wraps the native iOS and Android SDKs for the best user experience, optimized camera handling, and full NFC support.

Requirements

Platform Requirements

Installation

Expo (Recommended)

React Native CLI

iOS Setup

Android Setup

Permissions

iOS

NFC Configuration

Android

Quick Start

Integration Methods

Method 1: Session Token (Recommended for Production)

Method 2: Workflow ID (Simpler Integration)

Configuration

Configuration Options

Language Support

Advanced Options

Contact Details (Prefill & Notifications)

Expected Details (Cross-Validation)

Custom Metadata

Handling Results

Result Cases

SessionData Properties

Error Types

Complete Result Handling Example

Complete Example