Guia de integração

Introdução

O Certiface SDK é uma solução modular para verificação de biometria facial e validação de documentos, criada para facilitar o processo de autenticação de usuários. Ele é construído em torno do núcleo oiticore, que gerencia automaticamente dependências e fluxos de execução, garantindo uma integração simplificada e flexível.

Sua arquitetura permite que configure diferentes fluxos, com a possibilidade de customizar e capturar respostas específicas de cada solução através de interceptores.

Pré-requisitos de Compatibilidade

Para uma integração tranquila do Certiface SDK no seu projeto, basta configurar alguns detalhes essenciais de compatibilidade. Essas configurações minimizam conflitos e garantem que o SDK funcione como esperado.

Configuração Básica para Compatibilidade

O Certiface SDK foi projetado com Jetpack Compose e requer algumas configurações mínimas. Adicione ou verifique as configurações abaixo no build.gradle para garantir que tudo esteja alinhado com o ambiente do SDK:

android { ... compileSdk = 35 // Alinhamento com o SDK defaultConfig { minSdk = 26 // Compatibilidade mínima para as dependências } buildFeatures { compose = true // Habilitar o Jetpack Compose } composeOptions { kotlinCompilerExtensionVersion = "1.5.14" // Versão utilizada pelo SDK } }

Dependências Essenciais

Para evitar atrito com outras versões, recomendamos o mínimo necessário de dependências abaixo:

dependencies { implementation "androidx.core:core-ktx:1.7.0" // Core AndroidX implementation "androidx.appcompat:appcompat:1.4.0" // AppCompat implementation "androidx.lifecycle:lifecycle-runtime-ktx:2.4.0" // Lifecycle implementation "com.google.dagger:hilt-android:2.38.1" // Injeção de dependência com Hilt ksp "com.google.dagger:hilt-android-compiler:2.38.1" // Compilador Hilt implementation "androidx.activity:activity-compose:1.4.0" // Suporte para Compose implementation "androidx.compose.ui:ui:1.5.14" // Jetpack Compose }

Permissões Necessárias

Inclua as seguintes permissões no arquivo AndroidManifest.xml do seu aplicativo para garantir que o SDK funcione corretamente:

<!-- Permissão para acessar o estado da rede --> <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" /> <!-- Permissões para utilizar a câmera --> <uses-feature android:name="android.hardware.camera.any" /> <uses-permission android:name="android.permission.CAMERA" /> <!-- Permissão para acesso à internet, necessária para chamadas de rede --> <uses-permission android:name="android.permission.INTERNET" /> <!-- Permissão para detectar o estado do Wi-Fi, necessária para o monitoramento de rede --> <uses-permission android:name="android.permission.ACCESS_WIFI_STATE" /> <!-- Permissão para vibração, usada como feedback durante a verificação biométrica --> <uses-permission android:name="android.permission.VIBRATE" /> <!-- Permissão para leitura do estado do telefone para monitoramento de rede --> <uses-permission android:name="android.permission.READ_PHONE_STATE" /> <!-- Permissão de acesso aproximado à localização, necessária para conectividade em alguns dispositivos --> <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" /> <!-- Permissão para gravação em armazenamento externo, necessário para armazenamento temporário --> <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />

💡 Nota: Certifique-se de solicitar dinamicamente as permissões de Câmera e Armazenamento Externo em tempo de execução, especialmente em dispositivos com Android 6.0 (API 23) ou superior, pois são consideradas permissões sensíveis.

Resumo das Permissões

  • Câmera: Necessária para captura de imagem no processo de liveness e biometria.
  • Internet e Estado da Rede: Para comunicação com os servidores remotos e monitoramento de conectividade.
  • Vibração: Usada para fornecer feedback tátil aos usuários, durante os desafios.
  • Armazenamento Externo: Necessário para armazenamento temporário de dados.
  • Localização Aproximada e Estado do Telefone: Utilizadas apenas para monitoramento de conectividade em determinados dispositivos.

Com essas configurações, você garante uma integração suave, maximizando a compatibilidade do Certiface SDK no seu projeto.

Diagrama de Funcionamento

Abaixo está o diagrama de comunicação do Certiface SDK. Ele descreve o fluxo de dados entre o Aplicativo e o SDK, o HubManager e os provedores de liveness e documento:

Configuração do Gradle

Para utilizar o oiticore, é necessário adicionar a dependência no build.gradle do módulo de implementação. Utilize a seguinte configuração para importar o SDK:

Importando o Oiti Core

No build.gradle:

implementation "br.com.oiti.certiface:core:1.0.0"

No build.gradle.kts:

implementation("br.com.oiti.certiface:core:1.0.0")

Apontamento do Maven

Para garantir que o SDK seja carregado corretamente, é essencial apontar o repositório da oiti no Maven. Esse apontamento deve ser feito no settings.gradle:

No build.gradle:

dependencyResolutionManagement { repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS) repositories { google() mavenCentral() maven { url "https://raw.githubusercontent.com/oititec/android-oiti-versions/master" } } }

No build.gradle.kts:

dependencyResolutionManagement { repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS) repositories { google() mavenCentral() maven("https://raw.githubusercontent.com/oititec/android-oiti-versions/master") } }

Dependências Necessárias

Além do oiticore, apenas o hilt precisa ser configurado. O SDK gerencia as demais dependências e se adapta ao ambiente da aplicação, garantindo compatibilidade com Jetpack Compose e outras bibliotecas do projeto. Toda a arquitetura é baseada em um adaptador que redireciona as chamadas para os módulos do oiticore.

Configuração na Activity

Para utilizar o SDK, é preciso inicializar o HubManagerLauncher com uma referência da Activity que realizará a navegação e o registro do Intent. Essa configuração deve ser feita dentro do onCreate da Activity, pois o Activity.registerForActivityResult não pode ser registrado em tempo de execução.

// Exemplo no onCreate da Activity override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) // Configura o hubManagerLauncher passando a Activity hubManagerLauncher = HubManagerLauncher(this) }

Após garantir que o hubManagerLauncher tem a referência correta da Activity, é possível configurar e iniciar o SDK.

Soluções Disponíveis no SDK

O Certiface SDK oferece várias soluções para verificação de identidade, cada uma delas projetada para responder a diferentes necessidades de segurança e autenticidade:

  • Facetec: Solução de liveness 3D que utiliza reconhecimento facial avançado para verificar a autenticidade do usuário. Ideal para aplicações que demandam alta segurança.
  • Liveness2D: Uma solução de liveness mais leve, baseada em verificação 2D, adequada para casos de uso que demandam menos processamento.
  • DocCore: Focada na validação de documentos, esta solução realiza a verificação de autenticidade de documentos de identidade, complementando as verificações de biometria facial.

Essas soluções são configuradas através de Providers, que permitem a personalização e o uso de interceptores para capturar os dados de cada verificação.

Guia de Uso dos Providers

⚠️

DocCore provider e o unico provider ao qual não é vinculado um interceptor, sendo assim seu retorno é através do hubCallback

Configuração Geral dos Providers

Os Providers são componentes do SDK que representam cada uma das soluções de liveness e de validação de documentos. Eles podem ser configurados com Interceptors para capturar resultados detalhados, além de permitir a personalização das interações do usuário, como temas visuais específicos para cada provider.

Exemplo de Configuração com Interceptor

A configuração com interceptores permite que o SDK capture informações detalhadas sobre o resultado de cada provider. Esse método é útil para desenvolver um controle granular sobre o fluxo, além de facilitar a coleta de dados para análises posteriores.

// Configurando Interceptors val facetecProviderInterceptor = FacetecProviderInterceptor( getFacetecThemeBuilder(this), // Factory que devolve um FacetecTheme() object : LivenessInterceptor { override fun onIntercept(result: LivenessResult) { // Response do interceptor } } ) val liveness2DProviderInterceptor = Liveness2DProviderInterceptor( getLiveness2DThemeBuilder(), // Factory que devolve um Liveness2dTheme() object : LivenessInterceptor { override fun onIntercept(result: LivenessResult) { // Response do interceptor } } )

Configuração do HubManagerUser

O HubManagerUser deve ser configurado com os parâmetros necessários para a execução. No exemplo, utilizamos um ticket, environment, org, branch e key.

val hubManagerUser = HubManagerUser.Builder( ticket = ticket, environment = HubCoreRequestParams.ENVIRONMENT.HML, org = ORG.toInt(), branch = BRANCH.toInt(), key = xKey ).build()

Configuração do HubManager

O HubManager é configurado com o hubManagerLauncher, hubManagerUser, HubCallback e os provedores (Facetec e Liveness2D) com os interceptors definidos. O HubCallback permite tratar os eventos de conexão, sucesso, erro e cancelamento.

hubManager = HubManager.Builder( hubManagerLauncher = hubManagerLauncher, hubManagerUser = hubManagerUser, hubCallback = object : HubCallback { override fun onConnect() { // Conexão inicializada } override fun onSuccess() { // Fluxo concluído com sucesso } override fun onError(code: String?, message: String?) { // Erro genérico } override fun onCancel() { // Fluxo cancelado pelo usuário } } ) .addProvider(facetecProviderInterceptor) .addProvider(liveness2DProviderInterceptor) .addGroup(group) // Parametro opcional caso possua .addSubOrg(subOrg) // Parametro opcional caso possua .addProvider(DocCoreOitiProvider()) .build() hubManager?.start(this)

Configuração sem Interceptor (Execução Orquestrada)

Caso prefira executar o SDK de forma orquestrada, sem capturar os detalhes de cada provider individualmente, você pode configurar os providers sem interceptores. Nesse caso, o HubManager cuida do fluxo completo e retorna uma resposta genérica ao final.

hubManager = HubManager.Builder( hubManagerLauncher = hubManagerLauncher, hubManagerUser = hubManagerUser, hubCallback = object : HubCallback { override fun onConnect() { // Conexão inicializada } override fun onSuccess() { // Fluxo concluído com sucesso } override fun onError(code: String?, message: String?) { // Erro genérico } override fun onCancel() { // Fluxo cancelado pelo usuário } } ) .addProvider(FacetecProvider()) // Sem interceptores para Facetec .addProvider(Liveness2DProvider()) // Sem interceptores para Liveness2D .addProvider(DocCoreOitiProvider()) .build() hubManager?.start(this)

Exemplo de Implementação do Certiface SDK

Para facilitar a integração e implementação do Certiface SDK em projetos Android, disponibilizamos um projeto de exemplo no GitHub. Este projeto contém:

  • Exemplo de configurações iniciais do SDK.
  • Demonstrações práticas de diferentes fluxos de execução, incluindo Flow Orquestrado e Interceptor.
  • Demonstrações customizando as soluções.

Acesse o Projeto de Exemplo

Você pode acessar o projeto clicando no link abaixo:

Certiface SDK Android - Exemplo de Implementação