Implementação

A função startFaceRecon abre o fluxo nativo de prova de vida, envia a imagem capturada para a API de Reconhecimento facial da QI Tech e devolve a chave da imagem processada.

Pré-requisito: obtendo o Client Session Key

A função startFaceRecon exige um client_session_key. Essa chave é temporária e deve ser gerada no seu backend por meio de uma requisição server-to-server para a nossa API, antes de chamar a função do SDK.

Endpoint

Ambiente	URL
Sandbox	https://api.sandbox.zaig.com.br/face_recognition/client_session
Produção	https://api.zaig.com.br/face_recognition/client_session

Requisição

Method: POST

Headers:

{
  "Authorization": "YOUR_FACE_RECON_API_KEY"
}

Body (Opcional, mas recomendado):

{
  "user_id": "unique_user_identifier"
}

Importante: O campo user_id é altamente recomendado para medidas de segurança e antifraude. Use o CPF do cliente caso tenha acesso a essa informação.

Resposta

A resposta bem-sucedida conterá o client_session_key que deve ser passado para a função startFaceRecon.

{
  "client_session_key": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Aviso Importante!

A API Key de Reconhecimento facial nunca deve ser embarcada no aplicativo. A requisição acima deve partir exclusivamente do seu backend.

Assinatura da função

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

As customizações são opcionais e passadas pelo objeto options, descrito em O objeto FaceReconOptions.

Exemplo completo

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() {
  // Etapa 1: obter o client_session_key por meio do seu 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;
  }, []);

  // Etapa 2: iniciar o SDK com a chave obtida
  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: 'Conselhos relevantes',
        onboarding_first_label: 'Esteja com o rosto visível',
        onboarding_second_label: 'Encaixe seu rosto no oval',
        onboarding_third_label: 'Retire acessórios que cubram o rosto',
      },
      log_level: config.logLevel,
    })
      .then((response) => {
        // image_key identifica a imagem na QI Tech — armazene e envie na API de Onboarding
        console.log('Face Recon successfully ended. Image Key: ', response.image_key);
        // device_scan_session_id identifica a chamada interna ao Device Scan
        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>
  );
}

Aplicativos de exemplo

O repositório do módulo contém dois aplicativos prontos para execução, na pasta examples:

• QITechReactNativeExample — React Native puro
• QITechExpoExample — Expo

Em ambos, o arquivo App.tsx demonstra o uso completo (Reconhecimento facial + OCR + Scan de dispositivo) com o @qitech/react-native-caas. Substitua os tokens e API Keys de exemplo pelas suas credenciais. Caso ainda não as tenha recebido, entre em contato com o suporte.caas@qitech.com.br.