Guia Detalhado de Uso
Aprofunde seu entendimento e personalize com precisão, com explicações completas que orientam cada etapa do processo.
📑 Sumário
- 📌 Visão Geral
- ✅ Requisitos de Compatibilidade
- ⚙️ Instalação
- 🚀 Inicialização do SDK
- 🔌 Gerenciamento de Provedores de Liveness
5.1 🧩 Provedor: IProov - 📦 Estrutura das Classes Importantes
- 🔍 Principais Classes e Métodos de Chamada
- 📱 Fluxo de Telas
8.1 📝 Tela Inicial/Instruções
8.2 📷 Tela de Permissão de Câmera
8.3 🔄 Tela de Processamento
8.4 ✅ Tela de Resultado - 🧪 Ambiente de Testes
- 🛠️ Boas Práticas
- 📜 Changelogs e Versões
- 🔗 Links Externos
📌 Visão Geral
O Oiti SDK é um SDK modular e extensível, responsável por oferecer verificação facial remota (Liveness Detection) via múltiplos provedores de biometria.
Sua arquitetura foi desenvolvida com foco em segurança, personalização e abstração de provedores, permitindo que novos fornecedores sejam incorporados no futuro com impacto mínimo na integração.
Atualmente temos suporte ao provedor IProov, mas em breve outros serão incorporados ao SDK.
✅ Requisitos de Compatibilidade
-
AndroidX: obrigatório
-
Jetpack Compose: obrigatório (para renderização da interface dos provedores)
-
Mínimo SDK: 26 (Android 8.0 – Oreo)
-
Linguagem base: Kotlin (interoperável com Java)
-
Ambientes suportados:
HML
: HomologaçãoPRD
: Produção
⚙️ Instalação
Aponte o repositório no seu settings.gradle
:
dependencyResolutionManagement {
maven { url "https://raw.githubusercontent.com/oititec/android-oiti-sdk-versions/master" }
}
Adicione a dependência ao seu build.gradle
:
dependencies {
implementation "br.com.oiti:manager:X.Y.Z"
}
Substitua
X.Y.Z
pela versão mais recente fornecida pela Oiti.
🚀 Inicialização do SDK
Chame o método initialize()
na inicialização da aplicação:
OitiSDK.initialize(
context = applicationContext,
config = OitiSDKConfig(
environment = Environment.HML, // ou Environment.PRD
appKey = "SUA_APP_KEY"
)
)
🔌 Gerenciamento de Provedores de Liveness
O OitiSDK
utiliza o padrão de fábrica para criar instâncias específicas de cada provedor de Liveness:
val livenessManager = OitiSDK.createLivenessManager(
provider = OitiSDK.LivenessProvider.IPROOV
)
✅ Provedores Disponíveis
Provedor | Identificador Enum | Suporte |
---|---|---|
IProov | OitiSDK.LivenessProvider.IPROOV | ✅ Suporte Atual |
[Novo Provedor] | em breve | 🔜 Planejado |
🧩 Provedor: IProov
Este é o provedor atualmente integrado ao SDK. Ele oferece uma jornada de verificação baseada em luz e detecção passiva.
🎨 Personalização Visual
Utilize a classe IProovTheme
para configurar a interface do fluxo:
Observação: as propriedades declaradas fora dos blocos correspondem às configurações globais do iProov, enquanto aquelas definidas dentro dos blocos referem-se às personalizações de cada tela específica.
val demoTheme = IProovTheme.build {
// Texto & Cores principais
setTitle("Verificação Facial") // título da tela
setTitleColor("#FFFFFF") // cor do texto do título
setHeaderBackgroundColor("#121212") // cor do header
setSurroundColor("#00FF00") // cor do contorno do oval
setPromptTextColor("#FFFFFF") // cor do texto do prompt
setPromptBackgroundColor("#1F1F1F") // cor de fundo do prompt
// Comportamento
setTimeoutSecs(60) // timeout em segundos
setIsEnabledScreenShots(true) // habilita captura de tela
setFilter(FilterTheme.NaturalFilter) // filtro de imagem do liveness
// Orientação & Câmera
setOrientation(
gpa = OrientationGPA.PORTRAIT,
la = OrientationLA.PORTRAIT
)
setCamera(CameraSelection.FRONT) // câmera a ser usada
// Oval de estado
setOvalColors(
ready = "#00FF00".toColorInt(), // pronto
notReady = "#FF0000".toColorInt(), // não pronto
stroke = "#FFFFFF".toColorInt(), // borda
completed = "#00FF00".toColorInt() // concluído
)
// Tela de Instruções (InstructionCustomsBuilder)
setInstructionsTheme {
setTitleText("Reconhecimento facial") // texto do título
setTitleColor("#FFFFFF") // cor do título
setCaptionText("Isso garante que você é você mesmo.") // legenda
setCaptionColor("#AAAAAA") // cor da legenda
setBackgroundColor("#1F1F1F") // fundo da modal
setBottomSheetColor("#333333") // fundo da bottom sheet
setDocumentTypesInstructionText("Escolha um ambiente bem iluminado") // Legenda da primeira instrução
setDocumentTipsInstructionText("Não use acessórios como bonés mascáras e afins.") // Legenda da segunda instrução
setBottomSheetCornerRadius(16f) // raio dos cantos
setContextImage(R.drawable.ic_example) // imagem de contexto
setBackButtonImg(R.drawable.ic_back) // ícone voltar
setContinueButtonText("Continuar") // texto do botão
setContinueButtonColor("#00FF00") // cor do botão
setContinueButtonTextColor("#000000") // cor do texto do botão
}
// Permissões (PermissionCustomsBuilder)
setPermissionTheme {
setTitle("Permissões Necessárias")
setTitleColor("#FFFFFF")
setSubTitle("Precisamos da câmera pra prosseguir")
setSubTitleColor("#CCCCCC")
setCheckPermissionButtonText("Permitir Acesso")
setCheckPermissionButtonStyle("#00FF00")
setCameraIcon(R.drawable.ic_camera_perm)
setBackgroundColor("#1F1F1F")
setBackButtonIcon(R.drawable.ic_back)
setPermissionButtonText("OK, liberar")
setPermissionButtonColor("#00FF00")
setPermissionButtonTextColor("#000000")
}
// Processamento (LivenessCustomsBuilder)
setProcessingTheme {
setBackgroundColor("#000000")
setLoadingDialogColor("#FFFFFF")
setLoadingIndicatorSize(100)
setLoadingIndicatorWidth(10)
}
// Resultado (ResultCustomsBuilder)
setResultTheme {
setSuccessBackgroundColor("#DFFFD6")
setSuccessIcon(R.drawable.success_icon)
setSuccessText("Verificação concluída com sucesso!")
setSuccessTextColor("#0F9D58")
setErrorBackgroundColor("#FFD6D6")
setErrorIcon(R.drawable.error_icon)
setErrorText("Algo deu errado na verificação.")
setErrorTextColor("#D93025")
setRetryButtonColor("#0F9D58")
setRetryButtonText("Tentar novamente")
setRetryButtonTextColor("#FFFFFF")
}
}
🚀 Execução da Jornada
Após criar o IProovManagerOptions
com o tema desejado, inicie a jornada com:
val options = IProovManagerOptions(theme = theme)
livenessManager.start(options, object : OitiResultCallback<LivenessResult> {
override fun onSuccess(livenessResponse: LivenessResponse) {
Toast.makeText(context, "Verificação concluída!", Toast.LENGTH_LONG).show()
}
override fun onError(livenessResponse: LivenessResponse) {
val message = livenessResponse.errorResponse?.errorMessage ?: "Erro desconhecido"
Toast.makeText(context, message, Toast.LENGTH_SHORT).show()
}
})
🖼️ Fluxo Visual – IProov
(Espaço reservado para imagens explicativas do fluxo IProov)
📦 Estrutura das Classes Importantes
🧱 Core SDK
Classe | Responsabilidade |
---|---|
OitiSDK | Ponto de entrada, gerenciamento e inicialização. |
OitiSDKConfig | Configuração base com AppKey e ambiente. |
LivenessProvider | Enum com os provedores disponíveis. |
OitiResultCallback<T> | Interface para retorno de sucesso ou erro. |
LivenessResponse | Resultado do processo de verificação facial. |
📦 IProov (Provedor Específico)
Classe | Responsabilidade |
---|---|
IProovManager | Gerencia o fluxo de verificação facial usando o provedor IProov. |
IProovManagerOptions | Define o tema da jornada e outras opções vinculadas. |
IProovTheme | Customização da interface visual para o fluxo IProov. |
As classes específicas só devem ser utilizadas se o provedor selecionado for o IProov.
🔍 Principais Classes e Métodos de Chamada
Método / Classe | Descrição |
---|---|
OitiSDK.initialize() | Inicializa o SDK globalmente. |
OitiSDK.createLivenessManager() | Cria um gerenciador do provedor escolhido. |
IProovTheme.build {} | Cria tema visual personalizado. |
IProovManager.start(...) | Inicia a jornada facial do provedor IProov. |
OitiResultCallback.onSuccess() | Retorno de sucesso. |
OitiResultCallback.onError() | Retorno de erro. |
📱 Fluxo de Telas
📝 Tela Inicial/Instruções (Pré-Liveness)
Tela que apresenta as instruções iniciais ao usuário antes do início do processo de verificação facial. Inclui:
- Explicação do processo de liveness
- Requisitos de iluminação e posicionamento
- Botão de início do processo
📷 Tela de Permissão de Câmera
Exibida quando o usuário ainda não concedeu permissão de acesso à câmera. Contém:
- Explicação da necessidade da permissão
- Botão para conceder acesso
- Link para configurações do dispositivo caso a permissão tenha sido negada anteriormente
🔄 Tela de Processamento
Exibida durante a coleta e análise do liveness. Mostra:
- Feedback visual em tempo real do enquadramento facial
- Instruções dinâmicas (ex: "Mantenha o rosto no quadro")
- Barra de progresso ou indicador de processamento
✅ Tela de Resultado
Apresenta o resultado final do processo de verificação. Pode exibir:
- Mensagem de sucesso/erro
- Código de referência da verificação
- Ações pós-verificação (ex: "Continuar" ou "Tentar novamente")
🧪 Ambiente de Testes
Durante o desenvolvimento, utilize o ambiente HML
com AppKeys fornecidas pela equipe Oiti.
Evite o uso do ambiente de produção para testes manuais.
🛠️ Boas Práticas
- Inicialize o SDK apenas uma vez no ciclo de vida da aplicação.
- Use o padrão de fábrica para desacoplar a implementação dos provedores.
- Customize visualmente a interface conforme a identidade do seu app.
- Trate todos os retornos com UX amigável.
- Guarde logs e tokens apenas em ambiente seguro.
📜 Changelogs e Versões
Versão | Data | Descrição |
---|---|---|
1.0.0 | 01/01/2025 | Lançamento inicial do SDK |
1.1.0 | 15/02/2025 | Inclusão de novo provedor de liveness |
1.2.0 | 30/03/2025 | Atualização do fluxo IProov |
🔗 Links Externos
Sempre consulte a documentação atualizada para obter os detalhes mais recentes.
Updated about 15 hours ago