实现

startFaceRecon 函数会打开原生的活体检测流程，将采集到的图像发送至 QI Tech 的人脸识别 API，并返回已处理图像的密钥。

前置条件：获取 Client Session Key

startFaceRecon 函数需要一个 client_session_key。该密钥是临时的，必须在调用 SDK 函数之前，由您的后端通过服务器到服务器请求向我们的 API 生成。

Endpoint

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

请求

Method: POST

Headers:

{
  "Authorization": "YOUR_FACE_RECON_API_KEY"
}

Body（可选，但建议提供）：

{
  "user_id": "unique_user_identifier"
}

重要： 出于安全和反欺诈考虑，强烈建议提供 user_id 字段。如果您能获取客户的 CPF，请使用该值。

响应

成功的响应中包含需要传给 startFaceRecon 函数的 client_session_key。

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

重要提示！

人脸识别 API Key 绝不能嵌入到应用中。上述请求必须且只能由您的后端发起。

函数签名

const result = await startFaceRecon(
  environment,         // CAAS_ENVIRONMENT
  client_session_key,  // string
  options              // FaceReconOptions（可选）
);

自定义项是可选的，通过 options 对象传入，详见 FaceReconOptions 对象。

完整示例

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() {
  // 第 1 步：通过您的后端获取 client_session_key
  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;
  }, []);

  // 第 2 步：使用获取到的密钥启动 SDK
  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 是该图像在 QI Tech 的标识——请保存并在 Onboarding API 中发送
        console.log('Face Recon successfully ended. Image Key: ', response.image_key);
        // device_scan_session_id 标识内部的设备扫描调用
        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>
  );
}

示例应用

模块仓库的 examples 目录下包含两个可直接运行的应用：

• QITechReactNativeExample — 纯 React Native
• QITechExpoExample — Expo

在两者中，App.tsx 演示了使用 @qitech/react-native-caas 的完整用法（人脸识别 + OCR + 设备扫描）。请将示例中的 token 和 API Key 替换为您的凭证。如果您尚未收到凭证，请联系 suporte.caas@qitech.com.br。