Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.didit.me/llms.txt

Use this file to discover all available pages before exploring further.

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

​
Requirements

RequirementMinimum Version
React Native0.76+ (New Architecture / TurboModules)
Node.js20+
TypeScript5+

​
Platform Requirements

PlatformMinimum VersionNotes
iOS13.0+NFC passport reading requires iOS 15.0+
AndroidAPI 23+ (6.0)Kotlin 1.9+, Java 17+

​
Installation

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:
PermissionInfo.plist KeyDescriptionRequired
CameraNSCameraUsageDescriptionDocument scanning and face verificationYes
NFCNFCReaderUsageDescriptionRead NFC chips in passports/ID cardsIf using NFC
LocationNSLocationWhenInUseUsageDescriptionGeolocation for fraud preventionOptional

​
NFC Configuration

To enable NFC reading for passports and ID cards with chips:
  1. Add NFC Capability in Xcode:
    • Select your target > Signing & Capabilities > + Capability > Near Field Communication Tag Reading
  2. 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:
PermissionDescriptionRequired
INTERNETNetwork access for API communicationYes
ACCESS_NETWORK_STATEDetect network availabilityYes
CAMERADocument scanning and face verificationYes
NFCRead NFC chips in passports/ID cardsIf 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: 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

PropertyTypeDefaultDescription
languageCodestringDevice localeISO 639-1 language code (e.g. "en", "fr", "ar")
fontFamilystringSystem fontCustom font family name (must be registered natively)
loggingEnabledbooleanfalseEnable 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

CaseDescription
completedVerification flow completed (check session.status for result)
cancelledUser cancelled the verification flow
failedAn error occurred during verification

​
SessionData Properties

PropertyTypeDescription
sessionIdstringUnique session identifier
statusVerificationStatusApproved, Pending, or Declined

​
Error Types

ErrorDescription
sessionExpiredThe session has expired
networkErrorNetwork connectivity issue
cameraAccessDeniedCamera permission not granted
notInitializedSDK not initialized (Android only)
apiErrorAPI request failed
unknownOther 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>
  );
}