跳到主要内容

实现

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

前置条件：获取 Client Session Key​

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

Endpoint​

环境URL
Sandboxhttps://api.sandbox.caas.qitech.app/face_recognition/client_session
Produçãohttps://api.caas.qitech.app/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": "8f14e45f-ceea-467a-9a2e-4b1d0c6ba1f7",
  "expiration_date": "2026-09-22T18:40:57Z"
}

expiration_date 表示密钥的有效期。每个 client_session_key 仅服务于一次采集会话：每个流程请生成新的密钥，切勿在不同用户之间重复使用。

重要提示！

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

方法签名​

Future<FaceReconReturnValues> startFaceRecon(
  CaaSEnvironment environment,
  String clientSessionKey, {
  FaceReconOptions? options,
})

前两个参数是位置参数且为必填。自定义项是可选的，通过命名参数 options 传入，详见 FaceReconOptions 对象。

完整示例​

import 'dart:convert';
import 'dart:io';
import 'package:http/http.dart' as http;
import 'package:flutter_kyc_qitech/flutter_kyc_qitech.dart';

final _qitechFlutterKycPlugin = FlutterKycQitech();

// 第 1 步：通过您的后端获取 clientSessionKey
Future<String?> fetchClientSessionKey() async {
  final response = await http.post(
    Uri.parse('<FACE_RECON_API_URL>'),
    headers: {
      HttpHeaders.authorizationHeader: '<API_KEY>',
      HttpHeaders.contentTypeHeader: 'application/json',
    },
    body: jsonEncode({'user_id': '<USER_IDENTIFICATION>'}),
  );

  if (response.statusCode == 200) {
    final data = jsonDecode(response.body);
    return data['client_session_key'] as String?;
  }
  return null;
}

// 第 2 步：使用获取到的密钥启动 SDK
Future<void> startFaceRecon() async {
  final clientSessionKey = await fetchClientSessionKey();

  if (clientSessionKey == null) {
    print('Failed to fetch clientSessionKey');
    return;
  }

  try {
    final result = await _qitechFlutterKycPlugin.startFaceRecon(
      CaaSEnvironment.sandbox,
      clientSessionKey,
      options: FaceReconOptions(
        sessionId: '<SESSION_ID>',
        documentNumber: '111.111.111-11',
        fontColor: '#FFFFFF',
        backgroundColor: '#000000',
        fontFamily: CaaSFontFamily.futura,
        showIntroductionScreens: true,
        showSuccessScreen: true,
        showInvalidTokenScreen: true,
        audioConfiguration: FaceReconAudioConfiguration.enable,
        onboardingTextConfiguration: OnboardingTextConfiguration(
          onboardingTitle: 'Conselhos relevantes',
          onboardingFirstLabel: 'Esteja com o rosto visível',
          onboardingSecondLabel: 'Encaixe seu rosto no oval',
          onboardingThirdLabel: 'Retire acessórios que cubram o rosto',
        ),
        logLevel: CaaSLogLevel.debug,
      ),
    );

    print('Image key: ${result.imageKey}');
    print('Device Scan Session Id: ${result.deviceScanSessionId}');
  } on FaceReconException catch (e) {
    print('Error executing FaceRecon:');
    print('Status: ${e.statusCode}');
    print('Reason: ${e.reason}');
    print('Description: ${e.description}');
  }
}
注意

请在您的应用中启用 Portrait 和 Landscape Right 方向支持，以保证 iOS 原生 SDK 正常工作。

示例应用​

插件仓库在 flutter_kyc_qitech/example 下包含一个可直接运行的示例应用，演示了三个 SDK 的使用。运行前，请在 example 目录下创建 .env 文件并填入以下凭证，然后连接真机执行 flutter pub get 和 flutter run：

FACERECON_API_URL_SANDBOX=''
FACERECON_API_KEY_SANDBOX=''
OCR_MOBILE_TOKEN_SANDBOX=''
DEVICE_SCAN_API_URL_SANDBOX=''
DEVICE_SCAN_API_KEY_SANDBOX=''

如果您尚未收到凭证，请联系 suporte.caas@qitech.com.br。