certiface_sdk 1.2.0

SDK Flutter da Certiface para detecção de vida (liveness) e outras funcionalidades biométricas.

[CertiFace]

Oiti Certiface SDK – Flutter

Plugin Flutter oficial da Oiti (Certiface) para detecção de vida (liveness) com os provedores iProov e FaceTec, incluindo fluxo de permissões de câmera e customização visual opcional via ThemeBuilder.

---

Índice

• Instalação
• Requisitos
• Configuração do projeto
• Uso em alto nível
• API do CertifaceSdk
• Parâmetros de startLiveness
• Tratamento do retorno
• Customização com ThemeBuilder
• Integração sugerida
• Documentação oficial
• Licença e suporte

---

Instalação

Via pub.dev (quando publicado)

dependencies:
  certiface_sdk: ^1.0.0

Via GitHub (desenvolvimento)

dependencies:
  certiface_sdk:
    git:
      url: https://github.com/oititec/certiface-sdk-flutter.git
      ref: main # ou a branch / tag desejada

Depois execute flutter pub get.

---

Requisitos mínimos

Plataforma	Versão
Android	Gradle 8.0+
iOS	13.0+

O app host precisa declarar uso de câmera (por exemplo NSCameraUsageDescription no iOS e permissão de câmera no Android). Siga os guias oficiais de instalação para Maven/CocoaPods e chaves nativas.

---

Configuração do projeto (host)

1. Adicione a dependência certiface_sdk no pubspec.yaml do seu app.
2. Garanta que a App Key (e demais credenciais) sejam obtidas pelo fluxo acordado com a Certiface / Oiti (painel, API de credenciais ou integração do seu produto).
3. Importe o SDK:

import 'package:certiface_sdk/certiface_sdk.dart';
import 'package:certiface_sdk/common/theme_builder.dart'; // apenas se usar tema customizado

4. Mantenha uma instância de CertifaceSdk (por exemplo no State de um widget ou em um serviço injetável):

final _certifaceSdk = CertifaceSdk();

---

Uso em alto nível

Fluxo típico recomendado:

1. Verificar se a câmera já está autorizada com checkPermission().
2. Se necessário, solicitar a permissão com askPermission() (o sistema exibe o diálogo nativo).
3. Com uma App Key válida, chamar startLiveness informando ambiente, provedor e, se quiser, tema customizado.
4. Interpretar o Map<String, dynamic> retornado (status / result ou message) e tratar PlatformException para falhas do canal.

Em widgets, após await, verifique se o widget ainda está montado (por exemplo mounted em StatefulWidget) antes de chamar setState.

---

API do CertifaceSdk

Future<String?> getPlatformVersion()

Consulta opcional à plataforma nativa. Útil para diagnóstico; pode retornar null se o método não estiver implementado no lado nativo.

Future<bool> checkPermission()

Retorna se o app já tem permissão de câmera (true / false). Não exibe UI.

Future<bool> askPermission()

Solicita permissão de câmera ao usuário. O retorno indica se foi concedida após o fluxo nativo.

Envolva em try/catch para PlatformException se quiser exibir mensagens de erro do canal:

try {
  final granted = await _certifaceSdk.checkPermission();
} on PlatformException catch (e) {
  // e.code, e.message
}

Future<Map<String, dynamic>> startLiveness(...)

Inicia a jornada de liveness em tela cheia nativa. Veja a tabela abaixo para parâmetros e a seção Tratamento do retorno para o formato do mapa.

---

Parâmetros de startLiveness

Assinatura (valores padrão como no código):

Future<Map<String, dynamic>> startLiveness(
  String appKey, {
  String environment = 'HML',
  String provider = 'IPROOV',
  bool isCustomEnabled = false,
  Map<String, dynamic>? theme,
});

Parâmetro	Tipo	Descrição
appKey	String	Obrigatório. Chave da aplicação fornecida pela Certiface. Sem ela o fluxo não deve ser iniciado.
environment	String	'HML' (homologação) ou 'PRD' (produção).
provider	String	'IPROOV' ou 'FACETEC'.
isCustomEnabled	bool	Se true, o mapa theme é aplicado na UI nativa; se false, use tema padrão do SDK (theme pode ser null).
theme	Map<String, dynamic>?	Normalmente o retorno de ThemeBuilder() encadeado com .toJson() quando isCustomEnabled é true.

Chamada típica:

final res = await certifaceSdk.startLiveness(
  appKey,
  environment: 'HML', // ou 'PRD'
  provider: 'FACETEC', // ou 'IPROOV'
  isCustomEnabled: useCustomTheme,
  theme: useCustomTheme ? myThemeBuilder.toJson() : null,
);

---

Tratamento do retorno

O plugin devolve um mapa com a seguinte leitura usual:

• Se res['status'] == 'success': sucesso; detalhes costumam vir em res['result'] (mapa com campos como validação, identificadores e blob de resultado, conforme contrato do backend/SDK nativo).
• Caso contrário: erro de negócio / fluxo, com mensagem em res['message'].

Trecho de referência:

Map<String, dynamic> res = {};
try {
  res = await _certifaceSdk.startLiveness(
    appKey,
    environment: environment,
    provider: provider,
    isCustomEnabled: isCustom,
    theme: isCustom ? themeMap : null,
  );
} on PlatformException catch (e) {
  // Falha no method channel (ex.: argumento inválido, activity indisponível no Android)
  return;
}

if (res['status'] == 'success') {
  final inner = res['result']; // Map com dados do liveness
  // usar inner conforme guia de retornos da Certiface
} else {
  final message = res['message'];
  // exibir erro
}

Para o significado exato de cada campo em result, use o Guia de Tratamento de Retorno na documentação oficial.

---

Customização com ThemeBuilder

Quando isCustomEnabled: true, construa o tema com ThemeBuilder (API fluente) e passe theme: builder.toJson().

Estrutura recomendada:

• Ajustes globais: setTitle, cores, setFontResource, setTimeoutSecs, setFilter, setOrientation, setCamera, setOvalColors, etc.
• Telas específicas via callbacks:
  • setInstructionsTheme — textos, cores, fontes, assets, setShowInstructionScreen (exibir ou pular a tela de instruções).
  • setPermissionTheme — tela de permissões.
  • setProcessingTheme — loading / processamento.
  • setResultTheme — sucesso / erro / retry.
  • setIproovTheme — elementos adicionais do fluxo iProov.

Trecho ilustrativo (simplificado):

import 'package:certiface_sdk/common/theme_builder.dart';

ThemeBuilder buildTheme({required bool showInstructionScreen}) {
  return ThemeBuilder()
      .setTitle('Verificação facial')
      .setHeaderBackgroundColor('#1A1A1A')
      .setOvalColors(
        ready: 0xFF00FF88,
        notReady: 0xFFFF4444,
        stroke: 0xFFFFFFFF,
        completed: 0xFF00FF88,
      )
      .setInstructionsTheme((b) => b
          .setTitleText('Instruções')
          .setShowInstructionScreen(showInstructionScreen)
          .setContinueButtonText('Iniciar'))
      .setPermissionTheme((b) => b.setTitle('Permissões necessárias'));
}

// Uso:
await certifaceSdk.startLiveness(
  appKey,
  isCustomEnabled: true,
  theme: buildTheme(showInstructionScreen: true).toJson(),
);

Assets referenciados nos setters (ex.: setBackButtonIconAsset('shell')) precisam existir no projeto nativo conforme o guia de customização (nomes de recurso Android / iOS).

---

Integração sugerida

import 'package:flutter/services.dart';
import 'package:certiface_sdk/certiface_sdk.dart';

class LivenessService {
  LivenessService() : _sdk = CertifaceSdk();

  final CertifaceSdk _sdk;

  Future<bool> ensureCameraPermission() async {
    if (await _sdk.checkPermission()) return true;
    return _sdk.askPermission();
  }

  Future<Map<String, dynamic>> run({
    required String appKey,
    String environment = 'HML',
    String provider = 'FACETEC',
    bool customUi = false,
    Map<String, dynamic>? theme,
  }) async {
    if (appKey.trim().isEmpty) {
      throw StateError('App Key is required');
    }
    try {
      return await _sdk.startLiveness(
        appKey.trim(),
        environment: environment,
        provider: provider,
        isCustomEnabled: customUi,
        theme: customUi ? theme : null,
      );
    } on PlatformException catch (e) {
      rethrow; // ou mapear para seu modelo de erro
    }
  }
}

---

Documentação oficial

• Guia de Instalação Flutter
• Guia de Uso e Integração
• Guia de Tratamento de Retornos
• Customização Flutter

---

Licença e suporte

MIT License — veja o arquivo LICENSE.

• Portal de Atendimento Oiti
• Compatibilidade dos serviços