Implementation

The startFaceRecon method 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 method requires a clientSessionKey. This key is temporary and must be generated on your backend through a server-to-server request to our API, before calling the SDK method.

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 method.

{
  "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.

Method signature

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

The first two parameters are positional and required. Customizations are optional and passed through the named options parameter, described in The FaceReconOptions object.

Complete example

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();

// Step 1: obtain the clientSessionKey through your backend
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;
}

// Step 2: start the SDK with the obtained key
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: 'Important tips',
          onboardingFirstLabel: 'Make sure your face is visible',
          onboardingSecondLabel: 'Fit your face in the oval',
          onboardingThirdLabel: 'Remove accessories that cover your face',
        ),
        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}');
  }
}

Warning

Enable support for the Portrait and Landscape Right orientations in your application for the native iOS SDK to work correctly.

Sample app

The plugin repository contains a ready-to-run sample app, under flutter_kyc_qitech/example, demonstrating the use of all three SDKs. To run it, create a .env file in the example folder with the credentials below, then run flutter pub get followed by flutter run with a physical device connected:

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

If you have not received your credentials yet, contact suporte.caas@qitech.com.br.