Guia Detalhado de Uso

Aprofunde seu entendimento e personalize com precisão, com explicações completas que orientam cada etapa do processo.

📑 Sumário

  1. 📌 Visão Geral
  2. ✅ Requisitos de Compatibilidade
  3. ⚙️ Instalação
  4. 🚀 Inicialização do SDK
  5. 🔌 Gerenciamento de Provedores de Liveness
    5.1 🧩 Provedor: IProov
  6. 📦 Estrutura das Classes Importantes
  7. 🔍 Principais Classes e Métodos de Chamada
  8. 📱 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
  9. 🧪 Ambiente de Testes
  10. 🛠️ Boas Práticas
  11. 📜 Changelogs e Versões
  12. 🔗 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ção
    • PRD: 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
)
ProvedorIdentificador EnumSuporte
IProovOitiSDK.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.

PropriedadeDescriçãoExemplo
1setBackButtonImgDefine a imagem do botão de voltarR.drawable
1setBackButtonColorDefine a cor do botão de voltar#01012e ou R.color
2setBackgroundColorDefine a cor de fundo da tela#170ec4
2setContextImageDefine a imagem de contexto na telaR.drawable
3setTitleColorDefine a cor do título#a83290 ou R.color
3setTitleTextDefine o título da tela de instruçõestitulo exemplo customizado
4setDocumentTypesInstructionIconDefine o ícone para o tipo de documentoR.drawable
4setDocumentTypesInstructionIconBorderColorDefine a cor da borda do ícone do tipo de documento#ff0000 ou R.color
4setDocumentTypesInstructionIconBackgroundColorDefine a cor de fundo do ícone de tipo de documento#cc6f16 ou R.color
5setDocumentTipsInstructionIconDefine o ícone para as dicas de instrução do documentoR.drawable
5setDocumentTipsInstructionIconBackgroundColorDefine a cor de fundo do ícone das dicas#012e0a ou R.color
5setDocumentTipsInstructionIconBorderColorDefine a cor da borda do ícone das dicas#00ff00 ou R.color
6setBottomSheetColorDefine a cor do fundo da barra inferior#3e32a8 ou R.color
6setBottomSheetCornerRadiusDefine o raio de canto da barra inferior15.0f
7setCaptionColorDefine a cor do subtítulo#a86b32 ou R.color
7setCaptionTextDefine o subtítulo da tela de instruçõessubtitulo exemplo customizado
8setDocumentTypesInstructionTextColorDefine a cor do texto de instrução do tipo de documento#a8927d ou R.color
8setDocumentTypesInstructionTextDefine o texto de instrução para o tipo de documentodescricao do primeiro campo
9setDocumentTipsInstructionTextDefine o texto de dica de instrução para o documentodescricao do segundo campo
9setDocumentTipsInstructionTextColorDefine a cor do texto das dicas de instrução do documento#16cc3a ou R.color
10setContinueButtonTextDefine o texto do botão de continuarContinuar button
10setContinueButtonColorDefine a cor de fundo do botão de continuar#2e030a ou R.color
10setContinueButtonTextColorDefine a cor do texto do botão de continuar#0000ff ou R.color
  • Tela de Permissão de Câmera: Solicita permissão.
PropriedadeDescriçãoExemplo
1backButtonIconÍcone do botão de voltarR.drawable.arraow_left_black
2cameraIconÍcone central (ilustração da câmera)R.drawable.camera_permission
3titleTítulo da telaPermissões da câmera desativadas.
3titleColorCor do título#000000
4subTitleSubtítulo explicativoHabilite as configurações do seu aparelho.
4subTitleColorCor do subtítulo#666666
5permissionButtonTextTexto do botão de permitirPermitir
5permissionButtonColorCor de fundo do botão de permitir#00FF00
5permissionButtonTextColorCor do texto do botão#000000
6checkPermissionButtonTextTexto alternativo para botão de checagemPermitir Acesso
6checkPermissionButtonStyleCor (string) para estilo de botão alternativo#00FF00
7backgroundColorCor de fundo da tela inteira#FFFFFF
  • Tela de Processamento: Feedback visual durante verificação.

PropriedadeDescriçãoExemplo
1backgroundColorCor de fundo da tela de loading#000000
2circularProgressIndicatorColorCor do circulo de carregamento#FFFFFF
3circularProgressIndicatorSizeTamanho do circulo (diâmetro em px)100
4circularProgressIndicatorWidthEspessura da linha do circulo10
  • Tela do IProov: Executa a verificação de liveness.

    PropriedadeDescriçãoExemplo
    1closeButtonThemeÍcone de fechar a tela do ovalR.drawable.ic_close
    2headerBackgroundColorThemeCor do cabeçalho/topo da tela#121212
    3promptTextColorThemeCor do texto com instruções do oval#FFFFFF
    3promptBackgroundColorThemeCor de fundo da área de instruções#1F1F1F
    3promptRoundedCornersThemeDefine se a área de prompt tem bordas arredondadastrue
    4ovalStrokeColorCor da borda do oval#FFFFFF
    4readyOvalColorCor do oval quando o rosto está enquadrado corretamente#00FF00
    4notReadyOvalColorCor do oval quando ainda não está pronto#FF0000
    4completedOvalStrokeColorCor do oval quando a verificação foi concluída#00FF00
    5filterThemeEstilo visual aplicado ao oval (filtro)FilterTheme.Natural( FilterTheme.NaturalStyle.CLEAR)
    6disableExteriorEffectsThemeRemove efeitos visuais do ovalfalse
    7timeoutSecsThemeTempo máximo de captura antes do timeout60
    8enableScreenshotsThemePermite ou bloqueia screenshotstrue ou false
    9orientationGPA / orientationLAOrientação permitida para dispositivos específicosPORTRAIT
    10cameraThemeSeleciona a câmera frontal ou traseiraFRONT
    11titleThemeTexto do cabeçalho no topo"Verificação Facial"
    11titleTextColorThemeCor do título#FFFFFF
    11logoThemeÍcone ou logo no topoR.drawable.ic_logo
    12fontsKeyMapa de fontes do fluxomapOf(...)
  • Tela de Resultado: Exibe resultado final.

    PropriedadeDescriçãoExemplo
    1successIconÍcone exibido em caso de sucessoR.drawable.success_icon
    1errorIconÍcone exibido em caso de erroR.drawable.error_icon
    2successTextMensagem exibida em caso de sucessoVerificação concluída com sucesso!
    2errorTextMensagem exibida em caso de erroAlgo deu errado na verificação.
    2successTextColorCor do texto de sucesso#0F9D58
    2errorTextColorCor do texto de erro#D93025
    3retryButtonTextTexto do botão de nova tentativaTentar novamente
    3retryButtonColorCor de fundo do botão de nova tentativa#0F9D58
    3retryButtonTextColorCor do texto do botão de nova tentativa#FFFFFF
    4successBackgroundColorCor de fundo da tela de sucesso#DFFFD6
    4errorBackgroundColorCor de fundo da tela de erro#FFD6D6

    Como customizar as fontes das telas no fluxo do iProov

    Você 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
    )
    

💡

As fontes relacionadas à tela do iProov em si não são configuradas aqui — elas são passadas diretamente pelo builder do IProovTheme.


🧪 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ãoDataDescrição
1.0.001/01/2025Lançamento inicial.
1.1.015/02/2025Novo provedor liveness.
1.2.030/03/2025Atualização IProov.

🔗 Links Externos

⚠️

Sempre consulte a documentação atualizada.