certiface_sdk 2.0.0
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
- 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 | 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) #
- Adicione a dependência
certiface_sdknopubspec.yamldo seu app. - 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).
- Importe o SDK:
import 'package:certiface_sdk/certiface_sdk.dart';
import 'package:certiface_sdk/common/theme_builder.dart'; // apenas se usar tema customizado
- Mantenha uma instância de
CertifaceSdk(por exemplo noStatede um widget ou em um serviço injetável):
final _certifaceSdk = CertifaceSdk();
Uso em alto nível #
Fluxo típico recomendado:
- Verificar se a câmera já está autorizada com
checkPermission(). - Se necessário, solicitar a permissão com
askPermission()(o sistema exibe o diálogo nativo). - Com uma App Key válida, chamar
startLivenessinformando ambiente, provedor e, se quiser, tema customizado. - Interpretar o
Map<String, dynamic>retornado (status/resultoumessage) e tratarPlatformExceptionpara 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 emres['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
Colordo 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
@androidOnlyou@iosOnlye 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 #
- 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.