react-native-meon-face-verification

v1.0.2

Published

3 months ago

Face Verification SDK for React Native with IPV support

Downloads

0High
0Medium
0Low

dhananjaymeon

react-native face-verification face-recognition ipv biometric meon

🔐 react-native-meon-face-verification

Face Verification SDK for React Native with automatic permission handling, real-time verification, and beautiful result display.

✨ Features

✅ Face Matching - Compare captured face with reference image
✅ Video Capture - Record verification video
✅ Location Tracking - GPS coordinates with verification
✅ Native Permission Handling - Browser handles permissions automatically
✅ Beautiful Result Modal - Display verification results with images
✅ Liveness Detection - Real-time face verification
✅ Custom Configuration - Full control over verification parameters
✅ iOS & Android - Complete cross-platform support
✅ Enhanced Logging - Detailed console logs for debugging
✅ WebView Console Integration - See WebView logs in React Native console
✅ Smart Error Handling - Better error messages and recovery

📦 Installation

npm install react-native-meon-face-verification react-native-webview

iOS Setup

cd ios && pod install

Add permissions to ios/YourApp/Info.plist:

<key>NSCameraUsageDescription</key>
<string>Camera permission is required for face verification</string>
<key>NSMicrophoneUsageDescription</key>
<string>Microphone permission is required for video verification</string>
<key>NSLocationWhenInUseUsageDescription</key>
<string>Location permission is required for verification</string>

Android Setup

Add permissions to android/app/src/main/AndroidManifest.xml:

<uses-permission android:name="android.permission.CAMERA" />
<uses-permission android:name="android.permission.RECORD_AUDIO" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.INTERNET" />

🚀 Usage

Basic Usage

import React from 'react';
import { View } from 'react-native';
import MeonFaceVerification from 'react-native-meon-face-verification';

const FaceVerificationScreen = () => {
  return (
    <View style={{ flex: 1 }}>
      <MeonFaceVerification
        clientId="YOUR_CLIENT_ID"
        clientSecret="YOUR_CLIENT_SECRET"
        onSuccess={(data) => {
          console.log('✅ Verification Success!');
          console.log('Face Matched:', data.faces_matched);
          console.log('Location:', data.location);
        }}
        onError={(error) => {
          console.error('❌ Error:', error);
        }}
        onClose={() => {
          console.log('Closed');
        }}
      />
    </View>
  );
};

export default FaceVerificationScreen;

Advanced Usage with Full Configuration

import React from 'react';
import { View, Alert } from 'react-native';
import MeonFaceVerification from 'react-native-meon-face-verification';

const AdvancedFaceVerificationScreen = ({ navigation }) => {
  const handleSuccess = (data) => {
    console.log('Verification completed!', data);
    
    if (data.faces_matched) {
      Alert.alert(
        'Success',
        `Face verified successfully at ${data.location}`,
        [{ text: 'OK', onPress: () => navigation.goBack() }]
      );
    } else {
      Alert.alert(
        'Failed',
        'Face verification failed. Please try again.',
        [{ text: 'Retry' }]
      );
    }
  };

  const handleError = (error) => {
    console.error('Verification error:', error);
    Alert.alert('Error', error);
  };

  return (
    <View style={{ flex: 1 }}>
      <MeonFaceVerification
        // Required
        clientId="YOUR_CLIENT_ID"
        clientSecret="YOUR_CLIENT_SECRET"
        
        // Callbacks
        onSuccess={handleSuccess}
        onError={handleError}
        onClose={() => navigation.goBack()}
        
        // Configuration
        showHeader={true}
        headerTitle="Face Verification"
        baseURL="https://facefinder-uat.meon.co.in"
        
        // Verification Settings
        verificationConfig={{
          check_location: true,           // Enable GPS tracking
          capture_video: true,            // Record verification video
          match_face: true,               // Enable face matching
          read_script: false,             // Require reading script
          text_script: "Please look at the camera and follow instructions",
          video_time: 15,                 // Video duration (seconds)
          image_to_be_match: "https://example.com/reference-photo.jpg" // Reference image
        }}
        
        // Custom Styling
        customStyles={{
          header: {
            backgroundColor: '#0047AB',
          },
          headerTitle: {
            color: '#ffffff',
            fontSize: 20,
          },
          modalContainer: {
            backgroundColor: '#f5f5f5',
          }
        }}
      />
    </View>
  );
};

export default AdvancedFaceVerificationScreen;

With Navigation (React Navigation)

// In your navigator
import { createStackNavigator } from '@react-navigation/stack';
import FaceVerificationScreen from './screens/FaceVerificationScreen';

const Stack = createStackNavigator();

function AppNavigator() {
  return (
    <Stack.Navigator>
      <Stack.Screen 
        name="FaceVerification" 
        component={FaceVerificationScreen}
        options={{ headerShown: false }}
      />
    </Stack.Navigator>
  );
}

📚 API Reference

Props

| Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | clientId | string | ✅ Yes | - | Your Meon client ID | | clientSecret | string | ✅ Yes | - | Your Meon client secret | | onSuccess | function | No | undefined | Called when verification succeeds with result data | | onError | function | No | undefined | Called when an error occurs | | onClose | function | No | undefined | Called when user closes verification | | showHeader | boolean | No | true | Show/hide header | | headerTitle | string | No | 'Face Verification' | Custom header title | | baseURL | string | No | 'https://facefinder-uat.meon.co.in' | API base URL | | verificationConfig | object | No | See below | Verification configuration | | customStyles | object | No | {} | Custom style overrides |

Verification Config Object

{
  check_location: false,        // Enable GPS location tracking
  capture_video: false,         // Record verification video
  match_face: false,            // Enable face matching with reference image
  read_script: false,           // Require user to read a script
  text_script: "text",          // Text script for user to read
  video_time: 10,               // Video recording duration (seconds)
  image_to_be_match: ""         // Reference image URL or base64 string
}

Success Callback Data

onSuccess={(data) => {
  console.log(data);
  // {
  //   faces_matched: true,                    // Boolean - face match result
  //   image: "base64_or_url",                // Captured image
  //   image_to_be_matched: "base64_or_url", // Reference image
  //   location: "Address string",            // Full address
  //   latitude: "12.9716",                   // GPS latitude
  //   longitude: "77.5946",                  // GPS longitude
  //   timestamp: "2024-01-15T10:30:00Z",    // Verification timestamp
  //   video_url: "url",                      // Video URL (if captured)
  // }
}}

🎨 Custom Styling

You can customize the appearance using the customStyles prop:

<MeonFaceVerification
  customStyles={{
    // Container
    container: {
      backgroundColor: '#f0f0f0'
    },
    
    // Header
    header: {
      backgroundColor: '#0047AB',
      elevation: 4,
      shadowOpacity: 0.3
    },
    headerTitle: {
      color: '#ffffff',
      fontSize: 20,
      fontWeight: 'bold'
    },
    
    // Modal
    modalContainer: {
      backgroundColor: '#ffffff'
    }
  }}
/>

🔐 Security Best Practices

1. Store Credentials Securely

// ❌ Bad - Don't hardcode credentials
const clientId = "YOUR_CLIENT_ID";

// ✅ Good - Use environment variables
import Config from 'react-native-config';

const clientId = Config.MEON_CLIENT_ID;
const clientSecret = Config.MEON_CLIENT_SECRET;

2. Use .env File

Create .env:

MEON_CLIENT_ID=your_client_id_here
MEON_CLIENT_SECRET=your_client_secret_here

Add to .gitignore:

.env

3. Backend Proxy (Recommended for Production)

// Instead of passing credentials directly:
// Create a backend API endpoint that handles token generation

const MyVerificationScreen = () => {
  const [token, setToken] = useState(null);
  
  useEffect(() => {
    // Fetch token from your secure backend
    fetch('https://your-api.com/face-verification/token')
      .then(res => res.json())
      .then(data => setToken(data.token));
  }, []);
  
  return (
    <MeonFaceVerification
      // Use token from backend instead of credentials
      preGeneratedToken={token}
      onSuccess={handleSuccess}
    />
  );
};

🎯 Common Use Cases

1. KYC Verification

<MeonFaceVerification
  clientId={CLIENT_ID}
  clientSecret={CLIENT_SECRET}
  verificationConfig={{
    check_location: true,
    capture_video: true,
    match_face: true,
    video_time: 10,
    image_to_be_match: userProfilePhoto
  }}
  onSuccess={(data) => {
    if (data.faces_matched) {
      // Complete KYC process
      completeKYC(data);
    }
  }}
/>

2. Employee Attendance

<MeonFaceVerification
  clientId={CLIENT_ID}
  clientSecret={CLIENT_SECRET}
  verificationConfig={{
    check_location: true,
    capture_video: false,
    match_face: true,
    image_to_be_match: employeePhoto
  }}
  onSuccess={(data) => {
    if (data.faces_matched) {
      markAttendance(employeeId, data.location, data.timestamp);
    }
  }}
/>

3. Video Interview Verification

<MeonFaceVerification
  clientId={CLIENT_ID}
  clientSecret={CLIENT_SECRET}
  verificationConfig={{
    check_location: false,
    capture_video: true,
    match_face: true,
    read_script: true,
    text_script: "I confirm that I am attending this interview honestly",
    video_time: 20,
    image_to_be_match: candidatePhoto
  }}
  onSuccess={(data) => {
    startInterview(data);
  }}
/>

🐛 Troubleshooting

Permissions Not Working

The SDK now uses native browser permission handling. Permissions are automatically requested by the WebView when needed.

iOS:

Verify all permissions are in Info.plist
Permissions will be requested by the browser when WebView loads
Test on real device (not simulator)

Android:

Verify permissions in AndroidManifest.xml
Permissions will be requested by the browser when WebView loads
For Android 6+, runtime permissions must be granted

Note: If you're getting permission errors from the backend, set capture_video: false and check_location: false in verificationConfig to let the browser handle permissions natively.

WebView Not Loading

// Check console for detailed logs
// The SDK now provides extensive logging:
// - [FaceVerification] ========== GENERATE TOKEN START ==========
// - [FaceVerification] ========== INITIATE REQUEST START ==========
// - [WebView] [LOG/ERROR/WARN/INFO] messages from WebView

// Verify credentials
console.log('Client ID:', clientId);
console.log('Base URL:', baseURL);

// Test API manually
fetch('https://facefinder-uat.meon.co.in/backend/generate_token_for_ipv_credentials', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ client_id: clientId, client_secret: clientSecret })
})
.then(res => res.json())
.then(console.log)
.catch(console.error);

Modal Not Showing

Ensure verification completes successfully
Check success URL patterns in WebView
Verify onSuccess callback is called
Check for JavaScript errors in console

Camera Not Working

Permissions are now handled natively by the browser when WebView loads
Test on real device (camera doesn't work on simulator/emulator)
Check React Native console for WebView logs (now integrated)
Verify mediaPlaybackRequiresUserAction={false} is set (already configured)
If backend is blocking due to permissions, set capture_video: false in config

🔍 Debugging & Logging

The SDK provides extensive logging to help you debug issues:

Console Logs

All logs are prefixed with [FaceVerification] for easy filtering:

// Filter logs in your console
// Look for:
// - [FaceVerification] ========== GENERATE TOKEN START ==========
// - [FaceVerification] ========== INITIATE REQUEST START ==========
// - [FaceVerification] ✅ Token generated successfully
// - [FaceVerification] ❌ Error messages
// - [WebView] [LOG/ERROR/WARN/INFO] messages from WebView

WebView Console Integration

WebView console logs are automatically forwarded to React Native console:

// WebView console.log() → React Native console.log('[WebView] [LOG] ...')
// WebView console.error() → React Native console.error('[WebView] [ERROR] ...')
// WebView console.warn() → React Native console.warn('[WebView] [WARN] ...')

Debugging Tips

Check Initialization Logs: Look for token generation and request initiation logs
Monitor WebView Logs: See what's happening inside the WebView
Error Messages: SDK provides detailed error messages with suggestions
Permission Errors: Check if backend is blocking due to permission config

📊 Performance Tips

Lazy Load Component

const MeonFaceVerification = React.lazy(() => 
  import('react-native-meon-face-verification')
);

Optimize Images

verificationConfig={{
  image_to_be_match: compressedImageUrl // Use compressed/optimized images
}}

Reduce Video Time

verificationConfig={{
  video_time: 5 // Shorter videos = faster processing
}}

📝 Changelog

v1.0.2 (Current)

✨ Enhanced Logging - Detailed console logs for better debugging
✨ WebView Console Integration - WebView logs now appear in React Native console
✨ Native Permission Handling - Browser handles permissions automatically (removed react-native-permissions dependency)
✨ Smart Error Handling - Better error messages with helpful suggestions
✨ Improved URL Handling - Better handling of backend responses even with permission warnings
🔧 Default Base URL - Updated to https://facefinder-uat.meon.co.in
🐛 Bug Fixes - Fixed permission request handling and error recovery

v1.0.1

Face verification with matching
Video capture support
Location tracking
Result modal with images
Custom styling support

v1.0.0

Initial release

🤝 Contributing

Contributions are welcome! Please open an issue or submit a PR.

📄 License

MIT License - see LICENSE file

🆘 Support

📧 Email: [email protected]
🐛 Issues: GitHub Issues
📚 Docs: Full Documentation

🔗 Related Packages

react-native-meon-kyc - Complete KYC solution

Made with ❤️ for React Native developers