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
)

🧩 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.

• Tela de Permissão de Câmera: Solicita permissão.

• Tela de Processamento: Feedback visual durante verificação.

• 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 ou false
  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 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)
  Kotlin

  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

🔗 Links Externos

• Aplicativo de exemplo
• Exemplos de customização

⚠️

Sempre consulte a documentação atualizada.