HomeGuia de ProdutoCertiface APIReleases
Guia de Produto

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

Updated 4 months ago