React Native Face Guard SDK

React Native wrapper for the FaceGuard Liveness Checker SDK.

Installation

npm install react-native-face-guard-sdk
# or
yarn add react-native-face-guard-sdk

Setup

Android

1. Add the Bureau repository to your root build.gradle:

allprojects {
    repositories {
        maven { url "https://packages.bureau.id/api/packages/Bureau/maven" }
    }
}

2. Add the native SDK dependency to your app's build.gradle:

dependencies {
    implementation 'id.bureau:livenesscheck:2.0.6'
}

3. Register the package in MainApplication.java:

import com.bureau.faceguard.LivenessCheckerPackage;

@Override
protected List<ReactPackage> getPackages() {
    return Arrays.<ReactPackage>asList(
        new MainReactPackage(),
        new LivenessCheckerPackage()
    );
}

Usage

Basic Example

import FaceguardSDK from 'react-native-face-guard-sdk';

// Initialize
await FaceguardSDK.initialize({
  basicAuthKey: 'YOUR_BASIC_AUTH_KEY',
  cypherKey: 'YOUR_CYPHER_KEY',
  credentialId: 'YOUR_CREDENTIAL_ID',
  userId: 'user123',
  environment: 'PRODUCTION', // or 'SANDBOX'
});

// Add listeners
const removeResultListener = FaceguardSDK.addResultListener((result) => {
  console.log('Liveness check completed:', result);
  console.log('Selfie path:', result.selfiePath);
  console.log('Session ID:', result.response.diInsights?.sessionId);
  // Remove listener when done
  removeResultListener();
});

const removeErrorListener = FaceguardSDK.addErrorListener((error) => {
  console.error('Error:', error.error.errorCode, error.error.message);
  removeErrorListener();
});

// Start liveness check
await FaceguardSDK.start();

Advanced Configuration

await FaceguardSDK.initialize({
  basicAuthKey: 'YOUR_BASIC_AUTH_KEY',
  cypherKey: 'YOUR_CYPHER_KEY',
  credentialId: 'YOUR_CREDENTIAL_ID',
  userId: 'user123',
  environment: 'PRODUCTION',
  
  // Threshold configuration (optional)
  thresholdConfig: {
    hijab: 0.8,        // Default: 0.8
    mask: 0.8,         // Default: 0.8
    headgear: 0.8,     // Default: 0.8
    clothing: 0.8,     // Default: 0.8
    glasses: 0.8,      // Default: 0.8
    skinOrChest: 0.9,  // Default: 0.9
  },
  
  // Theme configuration (optional)
  // Resource values can be passed as:
  // - String resource names (recommended): Automatically resolved to Android resource IDs
  // - Numeric resource IDs: Direct Android resource ID values
  theme: {
    primaryTextColor: 'primary_text',           // String: resolves to R.color.primary_text
    // primaryTextColor: 0xFF000000,           // Or numeric: Android color int
    primaryBackgroundColor: 'background',      // String: resolves to R.color.background
    // primaryBackgroundColor: 0xFFFFFFFF,     // Or numeric: Android color int
    secondaryTextColor: 'secondary_text',      // String: resolves to R.color.secondary_text
    // secondaryTextColor: 0xFF666666,        // Or numeric: Android color int
    fontStyleRes: 'custom_font',               // String: resolves to R.font.custom_font
    // fontStyleRes: 2131230720,               // Or numeric: Android font resource ID
    logo: 'logo',                               // String: resolves to R.drawable.logo
    // logo: 2131230720,                       // Or numeric: Android drawable resource ID
  },
  
  // Services configuration (optional)
  services: {
    isRetryEnabled: true,                    // Default: false
    statusScreenRequired: false,             // Default: false
    enableFaceMatch: false,                   // Default: false
    enableFaceAnalyser: false,               // Default: false
    enableFaceDedupe: false,                // Default: false
    enableFaceEntityEnrollment: false,       // Default: false
    imageURL: 'https://example.com/image.jpg', // Optional image URL for face match
    consentType: 'EXPLICIT',                // Default: 'EXPLICIT'
  },
});

Theme Configuration

The theme configuration allows you to customize the UI appearance of the liveness checker. You can pass resource values in two ways:

Using String Resource Names (Recommended)

Pass the resource name as a string, and the SDK will automatically resolve it to the Android resource ID:

theme: {
  primaryTextColor: 'aislePrimaryTextColor',    // Resolves to R.color.aislePrimaryTextColor
  primaryBackgroundColor: 'background',          // Resolves to R.color.background
  secondaryTextColor: 'secondary_text',         // Resolves to R.color.secondary_text
  fontStyleRes: 'custom_font',                  // Resolves to R.font.custom_font
  logo: 'logo',                                  // Resolves to R.drawable.logo
}

Resource Type Mapping:

• Color resources: 'color_name' → R.color.color_name
• Font resources: 'font_name' → R.font.font_name
• Drawable resources: 'drawable_name' → R.drawable.drawable_name

Using Numeric Resource IDs

You can also pass numeric resource IDs directly (for advanced use cases):

theme: {
  primaryTextColor: 0xFF000000,        // Direct Android color int
  primaryBackgroundColor: 0xFFFFFFFF, // Direct Android color int
  logo: 2131230720,                    // Direct Android drawable resource ID
}

Note: Make sure your Android resources are defined in your app's res directory:

• Colors: android/app/src/main/res/values/colors.xml
• Drawables: android/app/src/main/res/drawable/
• Fonts: android/app/src/main/res/font/

Event Listeners

Result Listener

Called when the liveness check completes successfully:

const removeListener = FaceguardSDK.addResultListener((result) => {
  // result.response contains:
  // - diInsights: Session info, user ID, fingerprint, IP location, network info
  // - faceDetectionResponse: Face detection results, liveness score, accessories, moderation
  // - faceMatchResponse: (if enableFaceMatch is true) Face matching results
  // - faceAnalyserResponse: (if enableFaceAnalyser is true) Age and gender analysis
  // - faceDedupeResponse: (if enableFaceDedupe is true) Duplicate detection results
  // - faceEntityEnrollmentResponse: (if enableFaceEntityEnrollment is true) Enrollment results
  
  // result.selfiePath: Local file path to the captured selfie image
  
  removeListener();
});

Error Listener

Called when an error occurs:

const removeListener = FaceguardSDK.addErrorListener((error) => {
  console.error('Error Code:', error.error.errorCode);
  console.error('Error Message:', error.error.message);
  console.error('Event ID:', error.eventId);
  removeListener();
});

Activity Listener

Called when user activity changes during the liveness check:

const removeListener = FaceguardSDK.addActivityListener((activity, eventId) => {
  console.log('User activity:', activity);
  console.log('Event ID:', eventId);
  removeListener();
});

Cleanup

Always remove listeners when your component unmounts:

useEffect(() => {
  return () => {
    FaceguardSDK.removeAllListeners();
  };
}, []);

API Reference

Methods

initialize(config: LivenessCheckerConfig): Promise<boolean>

Initializes the SDK with the provided configuration.

Parameters:

• config.basicAuthKey (required): Basic authentication key
• config.cypherKey (required): Cypher key for encryption
• config.credentialId (required): Credential ID
• config.userId (optional): User identifier
• config.environment (optional): 'PRODUCTION' or 'SANDBOX' (default: 'SANDBOX')
• config.thresholdConfig (optional): Threshold values for various checks
• config.theme (optional): UI theme customization
  • theme.primaryTextColor (optional): Primary text color - string resource name (e.g., 'primary_text') or numeric color int
  • theme.primaryBackgroundColor (optional): Primary background color - string resource name or numeric color int
  • theme.secondaryTextColor (optional): Secondary text color - string resource name or numeric color int
  • theme.fontStyleRes (optional): Font style resource - string resource name (e.g., 'custom_font') or numeric font resource ID
  • theme.logo (optional): Logo drawable - string resource name (e.g., 'logo') or numeric drawable resource ID
  • Note: String resource names are automatically resolved to Android resource IDs. For example, 'logo' resolves to R.drawable.logo, 'primary_text' resolves to R.color.primary_text.
• config.services (optional): Service configuration flags

start(): Promise<boolean>

Starts the liveness detection flow. Make sure to set up listeners before calling this method.

addResultListener(listener: (result: LivenessResult) => void): () => void

Adds a listener for successful liveness check results. Returns a function to remove the listener.

addErrorListener(listener: (error: LivenessError) => void): () => void

Adds a listener for errors. Returns a function to remove the listener.

addActivityListener(listener: (activity: string, eventId: string) => void): () => void

Adds a listener for user activity changes. Returns a function to remove the listener.

removeAllListeners(): void

Removes all registered listeners.

Response Structure

LivenessResult

{
  response: {
    diInsights?: {
      sessionId?: string;
      userId?: string;
      fingerprint?: string;
      IPLocation?: {
        city?: string;
        region?: string;
        country?: string;
      };
      networkInformation?: {
        isp?: string;
        ipType?: string;
      };
    };
    faceDetectionResponse?: {
      bureauConsentId?: string;
      consent?: boolean;
      custID?: string;
      merchantId?: string;
      message?: string;
      requestId?: string;
      sessionId?: string;
      statusCode?: number;
      timestamp?: number;
      result?: {
        faces?: {
          accessories?: {
            clothing?: number;
            glasses?: number;
            headgear?: number;
            hijab?: number;
            mask?: number;
          };
          eyesOpen?: boolean;
          multipleFacesDetected?: boolean;
        };
        liveness?: {
          live?: boolean;
          livenessScore?: number;
        };
        moderation?: {
          blackAndWhite?: boolean;
          gore?: boolean;
          nudity?: boolean;
          poorQuality?: boolean;
          skinOrChest?: number;
          whiteBackground?: boolean;
        };
      };
    };
    faceMatchResponse?: FaceMatchResponse;
    faceAnalyserResponse?: FaceAnalyserResponse;
    faceDedupeResponse?: FaceDedupeResponse;
    faceEntityEnrollmentResponse?: FaceEntityEnrollmentResponse;
  };
  selfiePath: string; // Local file path to the captured selfie
}

LivenessError

{
  error: {
    message: string;
    errorCode: string;
  };
  eventId: string;
}

Platform Support

Currently, this SDK only supports Android. iOS support may be added in the future.

License

MIT