@smile_identity/react-native-expo

v11.2.0

Published

2 months ago

Official Smile ID SDK for Expo

0High
0Medium
0Low

react-native expo react-native-expo SmileIDExpo

Smile ID Expo SDK

NPM Version

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