Skip to main content

certiface_sdk 2.0.0 copy "certiface_sdk: ^2.0.0" to clipboard
certiface_sdk: ^2.0.0 copied to clipboard

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 SaaS (FaceTec/Fortface), incluindo fluxo de permissões de câmera e customização visual opcional via ThemeBuilder.


Índice #


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 15.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
  1. 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 journeyToken, {
  required LivenessEnvironment environment,
  required LivenessProvider provider,
  Map<String, dynamic>? theme,
});
Parâmetro Tipo Descrição
journeyToken String Obrigatório. Credencial da jornada: para 'SAAS', o token da jornada SaaS; para 'IPROOV', a App Key fornecida pela Certiface. Sem ela o fluxo não deve ser iniciado.
environment LivenessEnvironment Obrigatório. LivenessEnvironment.hml (homologação) ou LivenessEnvironment.prd (produção).
provider LivenessProvider Obrigatório. LivenessProvider.iproov ou LivenessProvider.saas (o provedor SaaS resolve, por sessão, entre FaceTec e Fortface).
theme Map<String, dynamic>? Normalmente o retorno de ThemeBuilder() encadeado com .toJson(). Quando informado, a customização é aplicada na UI nativa; quando null, é usado o tema padrão do SDK.

Chamada típica:

final res = await certifaceSdk.startLiveness(
  journeyToken,
  environment: LivenessEnvironment.hml, // ou LivenessEnvironment.prd
  provider: LivenessProvider.saas, // ou LivenessProvider.iproov
  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(
    journeyToken,
    environment: environment,
    provider: provider,
    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 #

Para customizar a UI, construa o tema com ThemeBuilder (API fluente) e passe theme: builder.toJson(). As propriedades disponíveis espelham as interfaces nativas do CertifaceSDK (iOS 4.0.1 / Android 2.0.5); a lista completa por tela, com o equivalente nativo de cada uma, está em gaps/.

Telas #

Setter Tela Provedores
setInstructionsTheme Instruções (inclui setShowInstructionsScreen) iProov, FaceTec, Fortface
setPermissionTheme Permissão de câmera iProov, FaceTec, Fortface
setLoadingTheme Loading (spinner durante o processamento) iProov, FaceTec, Fortface
setResultTheme Resultado Oiti (sucesso / erro / retry) iProov, Fortface
setFortfaceTheme Captura Fortface Fortface (SaaS)
setFacetecTheme Telas da FaceTec (ready, oval, feedback, retry, resultado) FaceTec (SaaS)
setFacetecLowLightTheme FaceTec em pouca luz (somente iOS) FaceTec (SaaS)
setIproovTheme Captura iProov iProov

Convenções #

  • Nomes: quando o nome difere entre as plataformas, o setter usa o nome do iOS (ex.: setTitleBackgroundColor, que no Android é setHeaderBackgroundColor).
  • Tipos: cores são Color do Flutter (enviadas como #AARRGGBB); imagens e fontes são o nome do recurso nativo (String); dimensões são números; opções fechadas são enums (FortfaceScreenMode, IProovFilterStyle, …).
  • Plataforma: setters (e valores de enum) disponíveis em apenas uma plataforma são anotados com @androidOnly ou @iosOnly e ignorados na outra.
  • Valores não informados mantêm o padrão do SDK nativo.
import 'package:certiface_sdk/common/theme_builder.dart';
import 'package:flutter/painting.dart';

ThemeBuilder buildTheme({required bool showInstructionsScreen}) {
  return ThemeBuilder()
      .setInstructionsTheme((b) => b
        ..setShowInstructionsScreen(showInstructionsScreen)
        ..setTitle('Instruções')
        ..setTitleColor(const Color(0xFFFFFFFF))
        ..setContextImage('shell')
        ..setContinueButtonText('Iniciar')
        ..setContinueButtonBackgroundColor(const Color(0xFF00FF88))
        ..setStatusBarColor(const Color(0xFF1A1A1A))) // @androidOnly
      .setLoadingTheme((b) => b
        ..setSpinnerColor(const Color(0xFF00FF88))
        ..setSpinnerScaleFactor(2) // @iosOnly
        ..setSpinnerSize(96)) // @androidOnly
      .setFacetecTheme((b) => b
        ..setOvalStrokeColor(const Color(0xFF00FF88))
        ..setText(FacetecTextKey.readyButton, 'Começar'))
      .setIproovTheme((b) => b
        ..setTitle('Verificação facial')
        ..setTitleBackgroundColor(const Color(0xFF1A1A1A))
        ..setFilterStyle(IProovFilterStyle.naturalClear));
}

// Uso:
await certifaceSdk.startLiveness(
  journeyToken,
  environment: LivenessEnvironment.hml,
  provider: LivenessProvider.saas,
  theme: buildTheme(showInstructionsScreen: true).toJson(),
);

O app de exemplo (example/lib/theme/custom_theme.dart) usa praticamente todas as propriedades.

Imagens e fontes referenciadas nos setters (ex.: setContextImage('shell'), setTitleFont('sixty')) precisam existir no projeto nativo com o mesmo nome: no iOS, no Asset Catalog / fontes registradas em UIAppFonts; no Android, em res/drawable e res/font. Nomes inexistentes fazem startLiveness retornar erro com invalidParam.


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 journeyToken,
    required LivenessEnvironment environment,
    required LivenessProvider provider,
    Map<String, dynamic>? theme,
  }) async {
    if (journeyToken.trim().isEmpty) {
      throw StateError('Journey token is required');
    }
    try {
      return await _sdk.startLiveness(
        journeyToken.trim(),
        environment: environment,
        provider: provider,
        theme: theme,
      );
    } on PlatformException catch (e) {
      rethrow; // ou mapear para seu modelo de erro
    }
  }
}

Documentação oficial #


Licença e suporte #

MIT License — veja o arquivo LICENSE.

0
likes
150
points
195
downloads

Documentation

API reference

Publisher

verified publisheroititec.com.br

Weekly Downloads

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

Repository (GitHub)
View/report issues

Topics

#biometric #liveness #camera #authentication

License

MIT (license)

Dependencies

flutter, plugin_platform_interface

More

Packages that depend on certiface_sdk

Packages that implement certiface_sdk