Guia Detalhado de Uso

Sumário

1. 📌 Visão geral
2. ✅ Requisitos de compatibilidade
3. ⚙️Instalação
4. 🚀 Inicialização do SDK
5. 📦CertifaceDocConfig
6. 🔍 Execução e callbacks
7. 🧾CertifaceDocResult e erros
8. 🎨 Customização — CertifaceDocTheme
   • 🎨Entrada do tema e formatos
   • 📝Instruções
   • 📋Instruções complementares
   • 📷Permissão de câmera
   • ⏳Diálogo de carregamento
   • 🔳QR Code
   • 📤Upload (PDF / CNH digital)
   • 🧾Resultado
   • 📸Captura (frente/verso)
   • ⚙️setCustomScreens
9. 🔤 Fontes (DocCoreFontsKey)
10. 🧪 Ambiente de testes
11. 🛠️ Boas práticas
12. 💻 Aplicativo de exemplo
13. 🔗 Links

📌Visão geral

O Certiface Doc SDK oferece documentoscopia (instruções, permissões, captura, QR, uploads, resultado) em Compose, com tema configurável. A dependência publicada é br.com.certiface:manager (versão alinhada ao release).

✅Requisitos de compatibilidade

⚙️Instalação

settings.gradle.kts

dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
        maven("https://raw.githubusercontent.com/oititec/certiface-doc-versions/main")
    }
}

build.gradle.kts (app)

dependencies {
    implementation("br.com.certiface.doc:manager:1.0.0")
}

🚀Inicialização do SDK

import br.com.certiface.doc.manager.main.CertifaceDocSDK

val documentManager = CertifaceDocSDK.initialize(context, config)

📦CertifaceDocConfig

Criada com createSDKConfig (br.com.certiface.doc.manager.exports).

val config = createSDKConfig(
    appKey = appKey,
    environment = Environment.PRD,
    theme = meuTemaOpcional,
    enableCnhDigital = true,
    enablePdfUpload = true
)

🔍Execução e callbacks

import br.com.certiface.doc.manager.exports.ResultCallback
import br.com.certiface.doc.domain.models.CertifaceDocResponse
import br.com.certiface.doc.domain.models.CertifaceDocResult

documentManager.start(
    config,
    object : ResultCallback<CertifaceDocResult> {
        override fun onSuccess(result: CertifaceDocResponse) {
            val payload = result.docResult
        }
        override fun onError(result: CertifaceDocResponse) {
            val erro = result.errorResponse
        }
    }
)

🧾CertifaceDocResult e erros

CertifaceDocResponse combina docResult e errorResponse; em falhas use CertifaceDocErrorType.

🎨Customização — CertifaceDocTheme

Esta secção cobre personalização visual do SDK. A ideia é simples: você monta um CertifaceDocTheme, escolhe apenas as etapas que quer ajustar e passa esse tema na configuração do SDK. No guia rápido o tema costuma ser null até você precisar aplicar a identidade visual do seu produto.

Em termos práticos, tudo começa com CertifaceDocTheme.build { }.

Há dois níveis de customização:

• Granular: você altera cores, textos, ícones e dimensões de etapas específicas.
• Completa: você substitui telas inteiras com setCustomScreens.

🎨Entrada do tema e formatos

import br.com.certiface.doc.domain.theme.CertifaceDocTheme
import br.com.certiface.doc.designsystem.ui.builders.DocCoreCustomInstructionsBuilder

val theme = CertifaceDocTheme.build {
    setInstructionsTheme(DocCoreCustomInstructionsBuilder.build { /* ... */ })
    // setPermissionTheme(PermissionCustomsBuilder.build { ... })
    // setCaptureTheme, setLoadingDialogTheme, setQrScreenTheme, ...
    // setFontsKey(mapOf(DocCoreFontsKey to R.font....))
}

val config = createSDKConfig(
    appKey = appKey,
    environment = environment,
    theme = theme,
    enableCnhDigital = true,
    enablePdfUpload = true
)

• Cores: Int (R.color) ou String hex, conforme o método.
• Medidas: bordas/raios em Float (ou Int onde aplicável).
• Elementos extra: permitidos se não quebrarem o comportamento obrigatório do SDK.

📝Instruções

Para customizar a tela inicial e as opções de documento, use setInstructionsTheme(...) dentro do CertifaceDocTheme.build { }. Esse bloco concentra os ajustes visuais dessa etapa.

Os números na figura correspondem à tabela.

📋Instruções complementares

Para customizar essa etapa, use setInstructionScreenTheme(...). Aqui você consegue ajustar título, legenda, ícones e textos das instruções numeradas, imagem de contexto, botão voltar, botão continuar, bottom sheet e status bar.

📷Permissão de câmera

Para customizar a tela de permissão de câmera, use setPermissionTheme(...).

⏳Diálogo de carregamento

Para customizar o loading, use setLoadingDialogTheme(...).

🔳QR Code

Para customizar a etapa de leitura por QR Code, use setQrScreenTheme(...).

📤Upload (PDF / CNH digital)

Para customizar as telas de upload, use os métodos abaixo no tema:

• setDocumentUploadTheme — PDF genérico
• setCnhUploadTheme — CNH digital

Os setters dessa etapa seguem o prefixo setUpload..., sempre agrupados por área da tela.

🧾Resultado

Para customizar a tela final de sucesso ou erro, use setResultScreenTheme(...).

📸Captura (frente/verso)

Para customizar a captura de frente e verso, use setCaptureTheme(...).

Os números na figura correspondem à tabela.

Observações:

• A tabela segue a numeração visível na figura.
• setCaptureStatusBarColor() e setCaptureStatusBarIsDarkIcons() são públicos, mas não aparecem numerados nessa ilustração.

⚙️setCustomScreens

Para substituir telas inteiras por Composables: setCustomScreens(CustomScreensBuilder.build { ... }), apenas nas etapas que quiser trocar. Para cores/textos por região, use os builders e tabelas acima.

🔤Fontes (DocCoreFontsKey)

Use setFontsKey(mapOf(DocCoreFontsKey to R.font....)) dentro de CertifaceDocTheme.build. As chaves disponíveis estão no enum DocCoreFontsKey (br.com.certiface.doc.designsystem.ui.doccore), por papel de texto em cada tela (instruções, permissão, captura, QR, upload CNH/PDF, resultado).

🧪Ambiente de testes

• HML + AppKey de homologação.
• Rede estável; permissão de câmera quando o fluxo exigir.

🛠️Boas práticas

• Uma inicialização coerente com o ciclo de vida do app.
• Tratar Cancelled e onError.
• Preferir builders granulares; setCustomScreens só para UI totalmente própria.

💻 Aplicativo de exemplo

Se você quiser ver uma integração pronta, use o repositório certiface-sdk-demo como referência de implementação do app cliente:

• GitHub - oititec/certiface-sdk-demo

O demo é útil para validar configuração, fluxo básico e estrutura de integração. Ainda assim, a referência de contrato continua sendo a API pública documentada neste guia.

Links

• Guia rápido de uso (configuração mínima)
• Doc Core Android (apenas referência de migração; ver callout no início deste guia)