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
- Mínimo SDK: 26 (Android 8.0 – Oreo)
- Linguagem base: Kotlin (compatível com Java)
- Ambientes suportados:
HML
: HomologaçãoPRD
: Produção
⚙️ Instalação
settings.gradle
:
dependencyResolutionManagement {
maven { url "https://raw.githubusercontent.com/oititec/android-oiti-sdk-versions/master" }
}
build.gradle
:
dependencies {
implementation "br.com.oiti:manager:X.Y.Z"
}
🚀 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
)
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
Personalize a interface usando IProovTheme
:
Nota: Propriedades fora dos blocos configuram globalmente o iProov; dentro dos blocos são específicas de cada tela.
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
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()
}
})
📦 Estrutura das Classes Importantes
Core SDK
- OitiSDK: Inicialização e gerenciamento.
- OitiSDKConfig: Configuração com AppKey e ambiente.
- LivenessProvider: Enum de provedores.
- OitiResultCallback: Interface de callbacks.
- LivenessResponse: Resultado do liveness.
IProov (Provedor Específico)
- IProovManager: Gerencia o fluxo com IProov.
- IProovManagerOptions: Define opções do tema.
- IProovTheme: Personalização visual do fluxo.
🔍 Principais Classes e Métodos de Chamada
OitiSDK.initialize()
OitiSDK.createLivenessManager()
IProovTheme.build {}
IProovManager.start(...)
OitiResultCallback.onSuccess()
OitiResultCallback.onError()
📱 Fluxo de Telas
- Tela Inicial/Instruções: Explicação pré-liveness.

Nº | Propriedade | Descrição | Exemplo |
---|---|---|---|
1 | setBackButtonImg | Define a imagem do botão de voltar | R.drawable |
1 | setBackButtonColor | Define a cor do botão de voltar | #01012e ou R.color |
2 | setBackgroundColor | Define a cor de fundo da tela | #170ec4 |
2 | setContextImage | Define a imagem de contexto na tela | R.drawable |
3 | setTitleColor | Define a cor do título | #a83290 ou R.color |
3 | setTitleText | Define o título da tela de instruções | titulo exemplo customizado |
4 | setDocumentTypesInstructionIcon | Define o ícone para o tipo de documento | R.drawable |
4 | setDocumentTypesInstructionIconBorderColor | Define a cor da borda do ícone do tipo de documento | #ff0000 ou R.color |
4 | setDocumentTypesInstructionIconBackgroundColor | Define a cor de fundo do ícone de tipo de documento | #cc6f16 ou R.color |
5 | setDocumentTipsInstructionIcon | Define o ícone para as dicas de instrução do documento | R.drawable |
5 | setDocumentTipsInstructionIconBackgroundColor | Define a cor de fundo do ícone das dicas | #012e0a ou R.color |
5 | setDocumentTipsInstructionIconBorderColor | Define a cor da borda do ícone das dicas | #00ff00 ou R.color |
6 | setBottomSheetColor | Define a cor do fundo da barra inferior | #3e32a8 ou R.color |
6 | setBottomSheetCornerRadius | Define o raio de canto da barra inferior | 15.0f |
7 | setCaptionColor | Define a cor do subtítulo | #a86b32 ou R.color |
7 | setCaptionText | Define o subtítulo da tela de instruções | subtitulo exemplo customizado |
8 | setDocumentTypesInstructionTextColor | Define a cor do texto de instrução do tipo de documento | #a8927d ou R.color |
8 | setDocumentTypesInstructionText | Define o texto de instrução para o tipo de documento | descricao do primeiro campo |
9 | setDocumentTipsInstructionText | Define o texto de dica de instrução para o documento | descricao do segundo campo |
9 | setDocumentTipsInstructionTextColor | Define a cor do texto das dicas de instrução do documento | #16cc3a ou R.color |
10 | setContinueButtonText | Define o texto do botão de continuar | Continuar button |
10 | setContinueButtonColor | Define a cor de fundo do botão de continuar | #2e030a ou R.color |
10 | setContinueButtonTextColor | Define a cor do texto do botão de continuar | #0000ff ou R.color |
- Tela de Permissão de Câmera: Solicita permissão.

Nº | Propriedade | Descrição | Exemplo |
---|---|---|---|
1 | backButtonIcon | Ícone do botão de voltar | R.drawable.arraow_left_black |
2 | cameraIcon | Ícone central (ilustração da câmera) | R.drawable.camera_permission |
3 | title | Título da tela | Permissões da câmera desativadas. |
3 | titleColor | Cor do título | #000000 |
4 | subTitle | Subtítulo explicativo | Habilite as configurações do seu aparelho. |
4 | subTitleColor | Cor do subtítulo | #666666 |
5 | permissionButtonText | Texto do botão de permitir | Permitir |
5 | permissionButtonColor | Cor de fundo do botão de permitir | #00FF00 |
5 | permissionButtonTextColor | Cor do texto do botão | #000000 |
6 | checkPermissionButtonText | Texto alternativo para botão de checagem | Permitir Acesso |
6 | checkPermissionButtonStyle | Cor (string) para estilo de botão alternativo | #00FF00 |
7 | backgroundColor | Cor de fundo da tela inteira | #FFFFFF |
- Tela de Processamento: Feedback visual durante verificação.

Nº | Propriedade | Descrição | Exemplo |
---|---|---|---|
1 | backgroundColor | Cor de fundo da tela de loading | #000000 |
2 | circularProgressIndicatorColor | Cor do circulo de carregamento | #FFFFFF |
3 | circularProgressIndicatorSize | Tamanho do circulo (diâmetro em px) | 100 |
4 | circularProgressIndicatorWidth | Espessura da linha do circulo | 10 |
-
Tela do IProov: Executa a verificação de liveness.
Nº Propriedade Descrição Exemplo 1 closeButtonTheme
Ícone de fechar a tela do oval R.drawable.ic_close
2 headerBackgroundColorTheme
Cor do cabeçalho/topo da tela #121212
3 promptTextColorTheme
Cor do texto com instruções do oval #FFFFFF
3 promptBackgroundColorTheme
Cor de fundo da área de instruções #1F1F1F
3 promptRoundedCornersTheme
Define se a área de prompt tem bordas arredondadas true
4 ovalStrokeColor
Cor da borda do oval #FFFFFF
4 readyOvalColor
Cor do oval quando o rosto está enquadrado corretamente #00FF00
4 notReadyOvalColor
Cor do oval quando ainda não está pronto #FF0000
4 completedOvalStrokeColor
Cor do oval quando a verificação foi concluída #00FF00
5 filterTheme
Estilo visual aplicado ao oval (filtro) FilterTheme.Natural( FilterTheme.NaturalStyle.CLEAR)
6 disableExteriorEffectsTheme
Remove efeitos visuais do oval false
7 timeoutSecsTheme
Tempo máximo de captura antes do timeout 60
8 enableScreenshotsTheme
Permite ou bloqueia screenshots true
oufalse
9 orientationGPA
/orientationLA
Orientação permitida para dispositivos específicos PORTRAIT
10 cameraTheme
Seleciona a câmera frontal ou traseira FRONT
11 titleTheme
Texto do cabeçalho no topo "Verificação Facial"
11 titleTextColorTheme
Cor do título #FFFFFF
11 logoTheme
Ícone ou logo no topo R.drawable.ic_logo
12 fontsKey
Mapa de fontes do fluxo mapOf(...)
-
Tela de Resultado: Exibe resultado final.
Nº Propriedade Descrição Exemplo 1 successIcon
Ícone exibido em caso de sucesso R.drawable.success_icon
1 errorIcon
Ícone exibido em caso de erro R.drawable.error_icon
2 successText
Mensagem exibida em caso de sucesso Verificação concluída com sucesso!
2 errorText
Mensagem exibida em caso de erro Algo deu errado na verificação.
2 successTextColor
Cor do texto de sucesso #0F9D58
2 errorTextColor
Cor do texto de erro #D93025
3 retryButtonText
Texto do botão de nova tentativa Tentar novamente
3 retryButtonColor
Cor de fundo do botão de nova tentativa #0F9D58
3 retryButtonTextColor
Cor do texto do botão de nova tentativa #FFFFFF
4 successBackgroundColor
Cor de fundo da tela de sucesso #DFFFD6
4 errorBackgroundColor
Cor de fundo da tela de erro #FFD6D6
Como customizar as fontes das telas no fluxo do iProovVocê pode alterar as fontes usadas nas telas de instrução, permissão e resultado passando um mapa para o parâmetro
fontsKey
.Esse mapa deve conter as chaves do enum
IProovFontsKey
associadas a:- Um caminho de asset (
"fonts/nome_da_fonte.ttf"
) - Ou uma referência de recurso (
R.font.nome_da_fonte
)
val iProovFonts = mapOf( // 📝 Tela de Instruções IProovFontsKey.INSTRUCTIONS_TITLE_FONT to "fonts/sixty.ttf", // via assets IProovFontsKey.INSTRUCTIONS_CAPTION_FONT to R.font.sixty, // via recurso IProovFontsKey.INSTRUCTIONS_DOCUMENT_TYPES_INSTRUCTIONS_FONT to R.font.sixty, IProovFontsKey.INSTRUCTIONS_DOCUMENT_TIPS_INSTRUCTIONS_FONT to R.font.sixty, IProovFontsKey.INSTRUCTIONS_BUTTON_FONT to R.font.sixty, // 📷 Tela de Permissão de Câmera IProovFontsKey.PERMISSION_TITLE_FONT to R.font.sixty, IProovFontsKey.PERMISSION_CAPTION_FONT to R.font.sixty, IProovFontsKey.PERMISSION_BUTTON_FONT to R.font.sixty, // ✅ Tela de Resultado IProovFontsKey.RESULT_MESSAGE_FONT to R.font.sixty, IProovFontsKey.RESULT_RETRY_BUTTON_FONT to R.font.sixty )
- Um caminho de asset (
As fontes relacionadas à tela do iProov em si não são configuradas aqui — elas são passadas diretamente pelo
builder
doIProovTheme
.
🧪 Ambiente de Testes
Utilize ambiente HML
com AppKeys de teste fornecidas.
Evite usar produção para testes.
🛠️ Boas Práticas
- Inicialize SDK uma vez.
- Use padrão fábrica.
- Personalize visualmente.
- UX amigável.
- Segurança em logs e tokens.
📜 Changelogs e Versões
Versão | Data | Descrição |
---|---|---|
1.0.0 | 01/01/2025 | Lançamento inicial. |
1.1.0 | 15/02/2025 | Novo provedor liveness. |
1.2.0 | 30/03/2025 | Atualização IProov. |
🔗 Links Externos
Sempre consulte a documentação atualizada.
Updated 11 days ago