Guia Detalhado de Uso

Sumário

1. Visão geral
2. Requisitos de compatibilidade
3. Instalação
4. Configuração do AndroidManifest
5. Inicialização do SDK
6. CertifaceDocConfig
7. Execução e callbacks
8. CertifaceDocResult e erros
9. 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
10. Fontes (DocCoreFontsKey)
11. Ambiente de testes
12. Boas práticas
13. Aplicativo de exemplo
14. 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")
}

Configuração do AndroidManifest

O app integrador deve declarar no AndroidManifest.xml do módulo app as entradas abaixo, antes do bloco <application>:

<manifest xmlns:android="http://schemas.android.com/apk/res/android">

    <uses-feature
        android:name="android.hardware.camera"
        android:required="false" />
    <uses-permission android:name="android.permission.CAMERA" />
    <uses-permission android:name="android.permission.INTERNET" />

    <application
        ...>
        ...
    </application>
</manifest>

O SDK trata a solicitação de permissão de câmera em runtime na tela dedicada do fluxo. A permissão de internet não exige prompt ao usuário — basta a declaração no manifest.

Se o seu app já declara INTERNET ou CAMERA, não é necessário duplicar; o merge de manifests do Android unifica as entradas.

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)