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.zaig.com.br/face_recognition/client_session
Production	https://api.zaig.com.br/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": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

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.zaig.com.br/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.