Getting started: Shared logic

Others: SDK Product: Validators

This guide contains the shared logic used across all Truora Validations SDK integrations (Android, iOS, Flutter, React Native).

Prerequisites & Authentication

API Keys

Truora uses a Generator Key system.

  • Generator Key: A master API key with grants to only generate other SDK API keys. Your backend uses this key to generate temporary SDK keys on demand.
curl --location 'https://api.account.truora.com/v1/api-keys' \
--header 'Truora-API-Key: API KEY' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'key_name=sdk-generator' \
--data-urlencode 'key_type=generator' \
--data-urlencode 'grant=generator' \
--data-urlencode 'api_key_version=1'
  • Temporary Keys (sdk keys): Short-lived keys generated using the Generator Key. Each SDK key is scoped to your application id and a single validation session. It also expires automatically.
curl --location 'https://api.account.truora.com/v1/api-keys' \
  --header 'Truora-API-Key: GENERATOR_API_KEY' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'key_type=sdk' \
  --data-urlencode 'key_name=sdk-key' \
  --data-urlencode 'api_key_version=1' \
  --data-urlencode 'application_id=APPLICATION_ID' \
  --data-urlencode 'account_id=ACCOUNT_ID'

How to provide the API Key to the SDK

There are two options for supplying the SDK key to your mobile application:

  1. Retrieve from a backend (Recommended): Your backend generates SDK keys on demand using the Generator Key, and sends them to the mobile app. This is the most secure approach since the Generator Key never leaves your server.
  2. Encrypted storage: Store a pre-generated SDK key in the device’s encrypted storage (e.g., Keychain on iOS, EncryptedSharedPreferences on Android). The key must be retrieved and cached synchronously, or fetched asynchronously before SDK initialization is called.

Backend integration (Recommended)

When using the recommended backend approach, the communication flow is:

  1. The mobile app requests an SDK key from your backend
  2. Your backend calls the Truora API using the Generator Key
  3. Truora returns a temporary SDK key
  4. Your backend forwards the SDK key to the mobile app
  5. The mobile app initializes the Truora SDK with this temporary key

Backend integration flow sequence diagram

Note: Platform-specific examples for each option are available in each platform’s dedicated documentation.

UI Customization

Customize the validation UI to match your brand:

React Native (TypeScript) 

const uiConfig: UIConfig = {
  primaryColor: '#435AE0',
  onPrimaryColor: '#FFFFFF',
  secondaryColor: '#03DAC6',
  surfaceColor: '#FFFFFF',
  onSurfaceColor: '#000000',
  errorColor: '#FF5454',
  logoUrl: 'https://your-cdn.com/logo.png',
};

await TruoraSDK.initialize({
  getApiKeyFromSecureStorage: () => getApiKey(),
  userId: 'user-123',
  ui: uiConfig,
  validation: {
    type: 'face',
    useAutocapture: true,
    waitForResults: true,
    timeout: 120,
  },
});

const result = await TruoraSDK.start();

Flutter (Dart) 

final uiConfig = UIConfig(
  primaryColor: '#435AE0',
  onPrimaryColor: '#FFFFFF',
  secondaryColor: '#03DAC6',
  surfaceColor: '#FFFFFF',
  onSurfaceColor: '#000000',
  errorColor: '#FF5454',
  logoUrl: 'https://your-cdn.com/logo.png',
);

await TruoraValidationsSDK.initialize(InitializeConfig(
  getApiKeyFromSecureStorage: () => getApiKey(),
  userId: 'user-123',
  uiConfig: uiConfig,
  validation: FaceConfig(FaceValidationConfig(
    useAutocapture: true,
    waitForResults: true,
    timeout: 120,
  )),
));

final result = await TruoraValidationsSDK.start();

iOS (Swift) 

let validation = TruoraValidationsSDK.Builder(
    apiKeyGenerator: self,
    userId: "user-123"
)
.withConfig { config in
    config
        .setPrimaryColor("#435AE0")
        .setOnPrimaryColor("#FFFFFF")
        .setSecondaryColor("#03DAC6")
        .setSurfaceColor("#FFFFFF")
        .setOnSurfaceColor("#000000")
        .setErrorColor("#FF5454")
        .setLogo("https://your-cdn.com/logo.png")
}
.withValidation { (face: Face) in
    face.withAutocapture(true)
}
.build()

await validation.start(from: viewController) { result in
    // handle result
}

Android (Kotlin) 

TruoraSDK.Validations.Builder(this, "user-123")
    .withUIConfig { uiBuilder ->
        uiBuilder
            .withPrimaryColor("#435AE0")
            .withOnPrimaryColor("#FFFFFF")
            .withSecondaryColor("#03DAC6")
            .withSurfaceColor("#FFFFFF")
            .withOnSurfaceColor("#000000")
            .withErrorColor("#FF5454")
            .withLogoUrl("https://your-cdn.com/logo.png")
            .build()
    }
    .withValidation { faceBuilder ->
        faceBuilder
            .withAutocapture(true)
            .build()
    }
    .build(validationHandler)

validationHandler.start()

Android (Java) 

TruoraSDK.Validations.Builder(this, "user-123")
    .withUIConfig(uiBuilder ->
        uiBuilder
            .withPrimaryColor("#435AE0")
            .withOnPrimaryColor("#FFFFFF")
            .withSecondaryColor("#03DAC6")
            .withSurfaceColor("#FFFFFF")
            .withOnSurfaceColor("#000000")
            .withErrorColor("#FF5454")
            .withLogoUrl("https://your-cdn.com/logo.png")
            .build()
    )
    .withValidation(faceBuilder ->
        faceBuilder
            .withAutocapture(true)
            .build()
    )
    .build(validationHandler);

validationHandler.start();

UI Configuration Parameters:

Parameter Type Default Description
primaryColor String Truora blue Primary brand color
onPrimaryColor String White Text/icons color on primary elements
secondaryColor String Black Secondary accent color
onSecondaryColor String White Text/icons color on secondary elements
surfaceColor String White Background color
onSurfaceColor String Black Text/icons color on surface elements
surfaceVariantColor String Truora teal Secondary background color
onSurfaceVariantColor String White Text/icons color on surface variant elements
errorColor String Red Error state color
logoUrl String Truora logo URL to remote logo image

Default theme color showcase

Using the default Truora colors this is how some of our screens would look like:
Default theme example - Face validation screen
Default theme example - Document validation screen
Default theme example - Results screen

Custom theme color showcase

Following a custom theme with the “Google” logo and the colorset:

{
  "primaryColor": "#8B0000",
  "onPrimaryColor": "#FFFFFF",
  "secondaryColor": "#2F4F4F",
  "onSecondaryColor": "#E0E0E0",
  "surfaceColor": "#151419",
  "onSurfaceColor": "#D9CEC1",
  "surfaceVariantColor": "#252329",
  "onSurfaceVariantColor": "#A39B8F",
  "errorColor": "#CF6679"
}

We would get the following color customization:
Custom theme example - Face validation screen

Custom theme example - Document validation screen
Custom theme example - Results screen