Implementation

The startFaceRecon function opens the native liveness flow, sends the captured image to QI Tech's Face Recognition API and returns the key of the processed image.

Prerequisite: obtaining the Client Session Key

The startFaceRecon function requires a client_session_key. This key is temporary and must be generated on your backend through a server-to-server request to our API, before calling the SDK function.

Endpoint

Environment	URL
Sandbox	https://api.sandbox.caas.qitech.app/face_recognition/client_session
Production	https://api.caas.qitech.app/face_recognition/client_session

Request

Method: POST

Headers:

{
  "Authorization": "YOUR_FACE_RECON_API_KEY"
}

Body (optional, but recommended):

{
  "user_id": "unique_user_identifier"
}

Important: The user_id field is highly recommended for security and anti-fraud measures. Use the customer's CPF if you have access to this information.

Response

The successful response contains the client_session_key that must be passed to the startFaceRecon function.

{
  "client_session_key": "8f14e45f-ceea-467a-9a2e-4b1d0c6ba1f7",
  "expiration_date": "2026-09-22T18:40:57Z"
}

The expiration_date states how long the key is valid. Each client_session_key serves a single capture session: generate a new one per flow, never reuse it across users.

Important Note!

The Face Recognition API key must never be embedded in the application. The request above must come exclusively from your backend.

Function signature

const result = await startFaceRecon(
  environment,         // CAAS_ENVIRONMENT
  client_session_key,  // string
  options              // FaceReconOptions (optional)
);

Customizations are optional and passed through the options object, described in The FaceReconOptions object.

Complete example

import * as React from 'react';
import { useCallback } from 'react';
import { View, Button } from 'react-native';
import {
  CAAS_ENVIRONMENT,
  CAAS_FONT_FAMILY,
  CAAS_LOG_LEVEL,
  FACE_RECON_AUDIO_CONFIGURATION,
  FACE_RECON_ERROR,
  startFaceRecon,
} from '@qitech/react-native-caas';

const FACE_RECON_API_URL = 'https://api.sandbox.caas.qitech.app/face_recognition/client_session';
const FACE_RECON_API_KEY = '<FACE_RECON_API_KEY>';

const config = {
  environment: CAAS_ENVIRONMENT.SANDBOX,
  sessionId: '<SESSION_ID>',
  documentNumber: '111.111.111-11',
  fontColor: '#5dcfe3',
  backgroundColor: '#f5f3f0',
  fontFamily: CAAS_FONT_FAMILY.VERDANA,
  showIntroductionScreens: true,
  showSuccessScreen: true,
  showInvalidTokenScreen: true,
  logLevel: CAAS_LOG_LEVEL.DEBUG,
};

export default function App() {
  // Step 1: obtain the client_session_key through your backend
  const fetchClientSessionKey = useCallback(async () => {
    const response = await fetch(FACE_RECON_API_URL, {
      method: 'POST',
      headers: {
        'Authorization': FACE_RECON_API_KEY,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({ user_id: '<USER_IDENTIFICATION>' }),
    });

    if (!response.ok) {
      throw new Error(`HTTP ${response.status}`);
    }

    const data = await response.json();

    if (!data.client_session_key) {
      throw new Error("No 'client_session_key' found.");
    }

    return data.client_session_key;
  }, []);

  // Step 2: start the SDK with the obtained key
  const startFr = async () => {
    const clientSessionKey = await fetchClientSessionKey();

    startFaceRecon(config.environment, clientSessionKey, {
      session_id: config.sessionId,
      document_number: config.documentNumber,
      font_color: config.fontColor,
      background_color: config.backgroundColor,
      font_family: config.fontFamily,
      show_introduction_screens: config.showIntroductionScreens,
      show_success_screen: config.showSuccessScreen,
      show_invalid_token_screen: config.showInvalidTokenScreen,
      audio_configuration: FACE_RECON_AUDIO_CONFIGURATION.ENABLE,
      onboarding_text_configuration: {
        onboarding_title: 'Important tips',
        onboarding_first_label: 'Make sure your face is visible',
        onboarding_second_label: 'Fit your face in the oval',
        onboarding_third_label: 'Remove accessories that cover your face',
      },
      log_level: config.logLevel,
    })
      .then((response) => {
        // image_key identifies the image at QI Tech — store it and send it to the Onboarding API
        console.log('Face Recon successfully ended. Image Key: ', response.image_key);
        // device_scan_session_id identifies the internal Device Scan call
        console.log('Device Scan Session Id: ', response.device_scan_session_id);
      })
      .catch((error) => {
        const reconError = error as FACE_RECON_ERROR;

        console.error('Error executing FaceRecon:');
        console.error('Status:', reconError.status_code);
        console.error('Reason:', reconError.reason);
        console.error('Description:', reconError.description);
      });
  };

  return (
    <View>
      <Button title="Start FaceRecon" onPress={startFr} />
    </View>
  );
}

Sample apps

The module repository contains two ready-to-run apps, in the examples folder:

• QITechReactNativeExample — pure React Native
• QITechExpoExample — Expo

In both, App.tsx demonstrates the full usage (Face Recognition + OCR + Device Scan) with @qitech/react-native-caas. Replace the sample tokens and API keys with your credentials. If you have not received them yet, contact suporte.caas@qitech.com.br.