@truora/validations-sdk

React Native SDK for Truora Validations. This SDK provides a bridge to native iOS and Android validation flows, supporting both face and document verification.

Installation

npm install @truora/validations-sdk

If you encounter peer dependency conflicts (common in strict ESLint/Prettier setups), use:

npm install @truora/validations-sdk --legacy-peer-deps

Native Setup

Android

The Android SDK requires initialization in your MainActivity before the activity reaches the STARTED state. This is necessary to handle native activity results correctly.

In android/app/src/main/java/.../MainActivity.kt:

import android.os.Bundle
import com.truora.validationssdk.TruoraValidationsSdkModule

class MainActivity : ReactActivity() {
  override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    // Initialize the validation handler for result callbacks
    TruoraValidationsSdkModule.init(this)
  }
  // ... rest of activity
}

iOS

Ensure you have installed the pods:

cd ios && pod install

Usage

1. Initialize and Start

The SDK uses a two-step process: initialize to configure the session and start to launch the UI.

import TruoraSDK, { Country, DocumentType } from '@truora/validations-sdk';

async function performValidation() {
  try {
    await TruoraSDK.initialize({
      // Security: Fetch your API key from a secure provider/storage
      getApiKeyFromSecureStorage: async () => {
        return await MySecureStorage.get('truora_key');
      },
      userId: 'user_12345',
      language: 'es', // 'en' | 'es' | 'pt'
      validation: {
        type: 'document',
        // Optional, if not set then the user will be prompted to select
        // their country and document type
        country: Country.co,
        documentType: DocumentType.nationalId,
        useAutocapture: true,
      },
      ui: {
        primaryColor: '#435AE0',
      },
    });

    const result = await TruoraSDK.start();

    switch (result.type) {
      case 'completed':
        console.log('Validation ID:', result.validation.validationId);
        console.log('Status:', result.validation.status);
        break;
      case 'canceled':
        console.log('User closed the SDK');
        break;
      case 'error':
        console.error('SDK Error:', result.error.message);
        break;
    }
  } catch (error) {
    console.error('Initialization failed:', error);
  }
}

2. Chaining Validations (Document to Face)

A common flow is validating a document and then using the photo from that document to perform a face similarity check.

const docResult = await TruoraSDK.start();

if (docResult.type === 'completed') {
  // Extract the photo URL from the document result
  const faceReference = docResult.validation.getFaceReferenceImage();

  if (faceReference) {
    await TruoraSDK.initialize({
      getApiKeyFromSecureStorage: () => API_KEY,
      userId: docResult.validation.detail?.account_id,
      validation: {
        type: 'face',
        referenceFace: faceReference, // Use the doc photo as reference
        similarityThreshold: 0.8,
      },
    });

    const faceResult = await TruoraSDK.start();
  }
}

Configuration Options

UIConfig

Customizes the look and feel of the SDK. | Property | Type | Description | | :--- | :--- | :--- | | primaryColor | string | Main brand color (Hex) | | logoUrl | string | URL of the logo to display | | language | TruoraLanguage | SPANISH, ENGLISH, or PORTUGUESE |

DocumentValidationConfig

| Property | Type | Description | | :--- | :--- | :--- | | type | 'document' | Discriminator | | country | Country | e.g., Country.mx, Country.co | | documentType | DocumentType | e.g., nationalId, passport | | useAutocapture| boolean | Enable automatic shutter |

FaceValidationConfig

| Property | Type | Description | | :--- | :--- | :--- | | type | 'face' | Discriminator | | referenceFace | string | URL, Local Path, or Base64 | | similarityThreshold| number | Value between 0.0 and 1.0 |

App Size Impact

The npm package itself is lightweight (~115 KB unpacked), since it is a thin bridge layer with zero runtime JS dependencies. The actual size impact comes from the native SDKs pulled at build time.

Size Overview

| Layer | Impact | Notes | | :--- | :--- | :--- | | JS bundle | < 5 KB | Negligible. Only 3 source files, no runtime dependencies. | | Android APK (arm64) | ~5.7 MB | Measured delta between baseline and SDK-integrated app. | | iOS app binary (arm64) | ~8.8 MB | Measured delta with Release optimizations (LTO, -Osize). |

What Contributes to the Size

| Component | Android | iOS | | :--- | :--- | :--- | | TFLite model (general_int8.tflite) | 2.3 MB | 2.3 MB | | TensorFlow Lite runtime | ~577 KB (GMS client .so) | ~5.6 MB (vendored TensorFlowLiteC, after LTO) | | ML Kit / Vision face detection | ~3-5 MB (Play Services client libs) | 0 MB (uses built-in Apple Vision) | | UI assets (images, fonts, animations) | ~1.3 MB | ~1.0 MB | | Compiled SDK code | Included in DEX | Included in binary |

Best Practices to Minimize App Size

Android

1. Enable R8 (ProGuard) minification — this is essential for production builds, as it strips unused code and resources:

   android {
       buildTypes {
           release {
               minifyEnabled true
               proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro'
           }
       }
   }

2. Exclude unused TFLite GPU native libraries — the SDK uses CPU inference only. These GPU libraries can be pulled transitively and are unnecessary:

   android {
       packaging {
           jniLibs {
               excludes += [
                   "lib/**/libtensorflowlite_gpu_jni.so",
                   "lib/**/libtensorflowlite_gpu_delegate.so",
                   "lib/**/libLiteRtOpenClAccelerator.so"
               ]
           }
       }
   }

3. Use Android App Bundles (AAB) instead of APK for Play Store distribution. Google Play will deliver only the resources and native libraries needed for each device, avoiding unnecessary ABI and density splits.

4. Restrict ABI filters to arm64 if your app only targets 64-bit devices (covers 99%+ of active devices):

   android {
       defaultConfig {
           ndk {
               abiFilters 'arm64-v8a'
           }
       }
   }

iOS

1. Use size-optimized Release build settings — these are recommended for any production build and significantly reduce the TensorFlow Lite binary footprint:

   SWIFT_OPTIMIZATION_LEVEL = -Osize
   LLVM_LTO = YES_THIN
   DEAD_CODE_STRIPPING = YES
   STRIP_SWIFT_SYMBOLS = YES
   ASSETCATALOG_COMPILER_OPTIMIZATION = space
   GCC_OPTIMIZATION_LEVEL = s

2. App Thinning is automatic when distributing via the App Store — only the arm64 device slice of TensorFlowLiteC is delivered to users (the simulator slice is excluded).

3. Bitcode is not required — the SDK ships as a static library, so no bitcode overhead is added.

General

• The SDK adds zero JavaScript dependencies to your project. The JS bundle impact is negligible regardless of configuration.
• Both face and document validation modules are included in the native dependency chain. If you only use one validation type, the unused module's code is still present but its assets and ML models are shared across both flows.

License

MIT