Guia Rápido 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 (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ção
    • PRD: 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

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

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

ClasseResponsabilidade
OitiSDKPonto de entrada, gerenciamento e inicialização.
OitiSDKConfigConfiguração base com AppKey e ambiente.
LivenessProviderEnum com os provedores disponíveis.
OitiResultCallback<T>Interface para retorno de sucesso ou erro.
LivenessResponseResultado do processo de verificação facial.

📦 IProov (Provedor Específico)

ClasseResponsabilidade
IProovManagerGerencia o fluxo de verificação facial usando o provedor IProov.
IProovManagerOptionsDefine o tema da jornada e outras opções vinculadas.
IProovThemeCustomizaçã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 / ClasseDescriçã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ãoDataDescrição
1.0.001/01/2025Lançamento inicial do SDK
1.1.015/02/2025Inclusão de novo provedor de liveness
1.2.030/03/2025Atualização do fluxo IProov

🔗 Links Externos

⚠️

Sempre consulte a documentação atualizada para obter os detalhes mais recentes.