@smile_identity/react-native-expo

Smile ID Expo SDK

Smile ID provides premier solutions for Real Time Digital KYC, Identity Verification, User Onboarding, and User Authentication across Africa.

If you haven’t already, sign up for a free Smile ID account, which comes with Sandbox access.

Please see CHANGELOG.md or Releases for the most recent version and release notes.

Getting Started

Full documentation is available at Smile ID Documentation

1. Requirements

• Node.js >=18.0
• Expo SDK 53
• React Native >=0.79
• A smile_config.json file from Smile ID Portal
• See: Android Requirements for Android specific requirements.
• See: iOS Requirements for iOS specific requirements.

2. Dependency

For Expo Managed Projects

Install the Smile ID Expo SDK:

# Using npm
npm install @smile_identity/react-native-expo

# Using yarn
yarn add @smile_identity/react-native-expo

Avoid "Cannot find native module 'SmileIDExpo'" in Expo projects

Expo Go does not bundle third‑party native modules. If you attempt to render any SmileID* native view inside Expo Go you'll see an error like:

 Cannot find native module 'SmileIDExpo', js engine: hermes

To fix this you must run a Development Build (a custom client) or a full release build that actually contains the native code.

In short: stop using Expo Go for any screen that renders Smile ID components; create a development build with expo run:ios or expo run:android; start (or let the run command start) the bundler using expo start --dev-client; and rebuild whenever you add, remove, or upgrade native dependencies (including @smile_identity/react-native-expo).

Step‑by‑step:

• iOS Dev Build

  npx expo run:ios
  

  This prebuilds ios/, installs Pods, compiles a custom client and launches it.

• Android Dev Build

  npx expo run:android
  

Version alignment: This SDK expects React Native and Metro versions that match (e.g. Expo SDK 53 ships RN 0.79.x + aligned Metro). If you override versions in package.json, ensure React Native and Metro remain compatible or you may see native view render failures.

Quick verification: After launching the dev build, navigate to a screen that uses a Smile ID component. If it renders without the native module error, the dev build is set up correctly.

Android target / compile SDK version requirement

If npx expo run:android fails with an error similar to:

Execution failed for task ':app:processDebugResources'.
Android resource linking failed
... AndroidManifest.xml: AAPT: error: attribute android:pageSizeCompat not found.

Your app is still building with the default Expo compileSdkVersion/targetSdkVersion (35), while the Smile ID Expo SDK requires 36. Update your Android build properties using the Expo Build Properties plugin:

• Install the plugin (adds the compatible native Android versions):

  npx expo install expo-build-properties
  

• Add (or update) the plugin entry in app.json / app.config.js:

  {
     "expo": {
        "plugins": [
           [
              "expo-build-properties",
              {
                 "android": {
                    "compileSdkVersion": 36,
                    "targetSdkVersion": 36,
                    "buildToolsVersion": "36.0.0"
                 }
              }
           ]
        ]
     }
  }
  

• Regenerate native Android project with a clean prebuild (ensures Gradle + manifest are recreated):

  npx expo prebuild -p android --clean
  

• Run the Android dev build again:

  npx expo run:android
  

Whenever you adjust these Android version settings, repeat the clean prebuild + run sequence. This aligns the Expo managed workflow with the SDK's required Android API level and resolves the missing android:pageSizeCompat attribute error.

For Bare React Native Projects

• Install Expo Modules Support (if not already set up):

  npx install-expo-modules@latest
  

  This will configure your bare React Native project with the required Gradle and Pod settings to support Expo modules.

• Install the Smile ID Expo SDK:

   # Using npm
  npm install @smile_identity/react-native-expo
  
   # Using yarn
  yarn add @smile_identity/react-native-expo
  

• Rebuild Your Project:

  cd sample-react-native/ios
  pod-install
  cd ..
   # For Android
  npx react-native run-android
  # or for iOS
  npx react-native run-ios
  

⚠️ Important Note:

Ensure that your React Native and Metro versions match the versions used by smile_identity/react-native-expo. You can override them to use different versions, but make sure both React Native and Metro are on the same version. Mismatches can cause native views from smile_identity/react-native-expo to fail to render and throw runtime errors.

3. SDK Initialization

The Smile ID Expo SDK offers three flexible initialization methods to suit different development needs.

import { initialize, SmileConfig } from 'react-native-expo';

Option 1: Configuration File (Recommended)

This method uses a smile_config.json file containing your configuration settings.

Setup Requirements:

• iOS: Add smile_config.json to your copy bundle phases in your iOS target
• Android: Place smile_config.json in your assets folder

// Initialize using configuration file
initialize(true);

Option 2: Programmatic Configuration

// Create configuration object with your Smile ID portal credentials
const config = new SmileConfig(
  'your_partner_id',              // Partner ID from Smile ID portal
  'your_auth_token',              // Authentication token
  'https://prod-lambda-url.com',  // Production lambda URL
  'https://test-lambda-url.com'   // Test lambda URL
);

// Initialize with configuration object
initialize(true, true, config);

Option 3: Configuration with API Key

// Use the same config object from Option 2
const config = new SmileConfig(
  'your_partner_id',
  'your_auth_token', 
  'https://prod-lambda-url.com',
  'https://test-lambda-url.com'
);

// Initialize with configuration and API key
initialize(true, true, config, 'YOUR_API_KEY');

4. Products

The SDK supports all Smile ID products with a simple, integrated component approach.This implementation works the same way for both Expo projects and bare React Native projects.

Configuration Setup

First, create a document verification params object:

import { DocumentVerificationParams } from 'react-native-expo';

const documentVerificationParams: DocumentVerificationParams = {
   userId: 'user123',
   jobId: 'job456',
   countryCode: 'NG',
   allowNewEnroll: false,
   documentType: 'PASSPORT',
   idAspectRatio: 1.414,
   bypassSelfieCaptureWithFile: 'your_selfie_image_path',
   enableAutoCapture: true,
   captureBothSides: false,
   allowAgentMode: true,
   showInstructions: true,
   showAttribution: true,
   allowGalleryUpload: true,
   skipApiSubmission: false,
   useStrictMode: false,
   extraPartnerParams: {
      'custom_param_1': 'value1',
      'custom_param_2': 'value2'
   }
};

Implementation

Integrate the document verification component into your React Native view:

import { SmileIDDocumentVerificationView } from 'react-native-expo';

// Component implementation
<SmileIDDocumentVerificationView 
  style={styles.nativeView}
  params={documentVerificationParams}
  onResult={handleDocumentVerificationResult}
  onError={handleDocumentVerificationError}
/>

Event Handlers

Implement the required callback functions to handle verification results:

// Handle successful verification
const handleSuccessResult = (result: DocumentVerificationResult) => {
  console.log('Document verification successful:', result);
  // Process the verification result
};

// Handle verification errors
const handleError = (error: DocumentVerificationError) => {
  console.error('Document verification failed:', error);
  // Handle error appropriately
};

Component Props:

• style: React Native StyleSheet for component styling
• params: Document verification parameters object
• onResult: Callback function for successful verification
• onError: Callback function for error handling

This implementation provides a complete document verification flow with comprehensive error handling and result processing capabilities. Other Smile ID products can be integrated in a similar way using the provided components and configuration objects.

Getting Help

For detailed documentation, please visit Smile ID Documentation

If you require further assistance, you can file a support ticket or contact us

Contributing

Bug reports and Pull Requests are welcomed. Please see CONTRIBUTING.md

License

MIT License

Changelog

11.2.0 - October 7, 2025

🚀 Major Updates

• Upgraded Expo SDK from 53 to 54 - Full compatibility with the latest Expo release
  • Updated React and React Native to latest compatible versions
  • Updated Kotlin to version 2.1.20 and removed dependencies pinned to Kotlin 2.0.21 for Expo SDK 54 compatibility
  • Upgraded Android Gradle Plugin (AGP) to version 8.13

Changed

• Android SDK: Bumped to v11.1.2
• sample-react-native: Updated Metro and package configuration to use local SDK source, fixed iOS entry point, and resolved TypeScript type and path issues

Added

• Added Dependabot for automatic dependency updates.