Instalação (Compat AGP 8)

Este guia mostra como adicionar o LivenessFacetecSDK — o pacote que orquestra o motor FaceTec — a um projeto Android que ainda está em Android Gradle Plugin (AGP) 8.x.

Essa é uma build alternativa do LivenessFacetecSDK, com o mesmo contrato público da 2.0.0 padrão, recompilada com um toolchain mais antigo (AGP, Kotlin, Gradle, Koin, OkHttp, kotlinx-serialization) para quem ainda não migrou para AGP 9.x. Se o seu projeto já está em AGP 9.x, use a build padrão em Instalação — o comportamento é idêntico.

Pré-requisitos

Antes de começar, garanta que você tem:

Uma chave de API válida emitida pela Plataforma ID, usada pelo seu backend na criação da sessão — o app nunca a recebe.
Acesso aos arquivos .aar do LivenessFacetecSDK (build compat) e do motor FaceTec distribuídos pela Valid.
O Package Name (applicationId) do seu app enviado à equipe da Valid para liberação na licença FaceTec.
Um projeto Android em AGP 8.x, atendendo aos Requisitos mínimos abaixo.

Sem a liberação do applicationId na licença FaceTec, a inicialização do SDK falha em runtime. Envie o Package Name à equipe da Valid antes de testar em dispositivo físico.

Requisitos mínimos

Item	Valor
`minSdk`	23 (Android 6.0)
`compileSdk`	36
Java toolchain	11
Kotlin	2.1.20
Android Gradle Plugin	8.11.0
ABIs suportadas	`armeabi-v7a`, `arm64-v8a`
Versão do `LivenessFacetecSDK`	`2.0.0` (build compat AGP 8)
FaceTec SDK (`.aar` separado)	`10.1.18`

O SDK só distribui bibliotecas nativas para armeabi-v7a e arm64-v8a — o fluxo de liveness não roda em emulador x86/x86_64. Valide em dispositivo físico ou em emulador com imagem ARM.

O compileSdk = 36 e o desugaring de bibliotecas do core são exigidos pelo aar-metadata do SDK (minCompileSdk=36). Configurar valores abaixo disso faz a build falhar na resolução da dependência.

Seu projeto pode estar em AGP 8.x com uma versão de Kotlin diferente de 2.1.20 — isso é normal e seguro. O Kotlin usado para compilar o SDK não precisa ser idêntico ao do seu projeto para interoperar; o que importa é o AGP estar na faixa 8.x.

Instalação

Obter os binários

Baixe na plataforma da Valid a build compat AGP 8 do LivenessFacetecSDK (liveness-facetec-sdk-2.0.0.aar) e o .aar do motor FaceTec (facetec-sdk-10.1.18.aar), entregue separadamente.

Adicionar os AARs ao app

Copie os dois arquivos para a pasta libs do módulo app:

seu-projeto/
  app/
    libs/
      liveness-facetec-sdk-2.0.0.aar
      facetec-sdk-10.1.18.aar
    build.gradle.kts

Configurar repositórios

No settings.gradle.kts do projeto, declare os repositórios necessários para resolver as dependências externas do SDK:

dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
        maven(url = "https://cashshield-sdk.s3.amazonaws.com/release/") // obrigatório — Shield
    }
}

O repositório do Shield é obrigatório. Sem ele, as classes com.shield.android.* — usadas pelo SDK em getSessionData() — não resolvem e a build falha.

Configurar app/build.gradle.kts

Declare os AARs junto com as dependências externas obrigatórias — atenção às versões abaixo, diferentes das da build padrão (Koin, OkHttp e kotlinx-serialization):

plugins {
    alias(libs.plugins.android.application)
    alias(libs.plugins.kotlin.android)
}

android {
    namespace = "com.example.myapp"
    compileSdk = 36

    defaultConfig {
        applicationId = "com.example.myapp"
        minSdk = 23
        targetSdk = 36
        multiDexEnabled = true
    }

    compileOptions {
        isCoreLibraryDesugaringEnabled = true
        sourceCompatibility = JavaVersion.VERSION_11
        targetCompatibility = JavaVersion.VERSION_11
    }

    kotlin { jvmToolchain(11) }

    buildTypes {
        release {
            isMinifyEnabled = true
            proguardFiles(
                getDefaultProguardFile("proguard-android-optimize.txt"),
                "proguard-rules.pro"
            )
        }
    }
}

dependencies {
    coreLibraryDesugaring("com.android.tools:desugar_jdk_libs:2.1.4")

    // ── LivenessFacetecSDK — SDK da Valid (build compat AGP 8) ──────────
    implementation(files("libs/liveness-facetec-sdk-2.0.0.aar"))

    // ── FaceTec SDK — motor biométrico, entregue separadamente ─────────
    implementation(files("libs/facetec-sdk-10.1.18.aar"))

    // ── Dependências externas obrigatórias (versões desta build compat) ─
    implementation("io.insert-koin:koin-core:4.1.0")
    implementation("io.insert-koin:koin-android:4.1.0")
    implementation("org.jetbrains.kotlinx:kotlinx-coroutines-android:1.10.2")
    implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.8.1")
    implementation("com.squareup.retrofit2:retrofit:3.0.0")
    implementation("com.squareup.okhttp3:okhttp:4.12.0")
    implementation("com.squareup.okhttp3:logging-interceptor:4.12.0")
    implementation("com.jakewharton.retrofit:retrofit2-kotlinx-serialization-converter:1.0.0")
    implementation("io.sentry:sentry-android:8.38.0")
    implementation("com.shield.android:partner-fraud:2.6.0")

    // AndroidX
    implementation("androidx.core:core-ktx:1.18.0")
    implementation("androidx.appcompat:appcompat:1.7.1")
    implementation("androidx.activity:activity:1.13.0")
    implementation("com.google.android.material:material:1.13.0")
}

kotlinx-serialization-json é necessária porque o código compilado do SDK referencia essas classes em runtime. O plugin do compilador (kotlin.serialization) não é necessário no app consumidor — a serialização já vem compilada dentro do AAR do SDK.

O build type release acima liga isMinifyEnabled = true. Antes de gerar o APK/AAB, adicione ao proguard-rules.pro as regras obrigatórias descritas em ProGuard / R8 — sem elas o app compila, mas quebra em runtime com NoClassDefFoundError.

Sincronizar e validar

Sincronize o Gradle (File → Sync Project with Gradle Files no Android Studio). Após o sync, o classpath deve resolver com.vcc.vendor.facetec.sdk.LivenessFacetecSDK.

Faltar qualquer uma das dependências externas resultará em ClassNotFoundException em runtime. Verifique a lista completa antes de rodar o app.

ProGuard / R8

Os .aar do SDK e da FaceTec já trazem, cada um, seu próprio proguard.txt, aplicados automaticamente pelo AGP ao app cliente assim que os dois são declarados como dependência. Juntos, cobrem as classes públicas do SDK, as classes do FaceTec, a ponte JNI e os metadados do Kotlin — nenhuma regra manual para esses itens é necessária. As dependências abaixo empacotam suas próprias regras consumer e não requerem regras manuais:

Dependência	Regras consumer embutidas desde
Retrofit 3.x	2.9.0+
OkHttp 4.12.x	embutido no artefato
kotlinx-serialization 1.8.x	1.5.0+
kotlinx-coroutines 1.10.x	1.7.0+
Sentry Android 8.x	embutido no artefato
Shield (`partner-fraud`) 2.6.x	embutido no artefato
FaceTec 10.1.18	`proguard.txt` no próprio `.aar` da FaceTec

Regras obrigatórias

Como o build type release liga isMinifyEnabled = true, adicione ao proguard-rules.pro do módulo app:

# ── Koin 4.x — não empacota consumer ProGuard rules ──────────────────────────
-keep class org.koin.** { *; }
-dontwarn org.koin.**

Essa é a única regra manual necessária. O Koin é a única dependência da lista que não traz regras consumer próprias.

-dontoptimize não é necessário. Integrações antigas do SDK exigiam essa flag para contornar um VerifyError em classes internas do FaceTec sob R8 Full Mode; o problema foi corrigido no FaceTec 10.1.18. AGP 8.11 (usado nesta build) já usa R8 Full Mode por padrão desde a série 8.x — o mesmo cuidado de validar duas capturas consecutivas numa build release minificada se aplica aqui tanto quanto na build padrão. Se você carrega -dontoptimize de uma integração anterior, pode remover.

Se o seu app usar Retrofit diretamente com interfaces anotadas, pode ser necessário preservar anotações em runtime:

-keepattributes RuntimeVisibleAnnotations, RuntimeVisibleParameterAnnotations

Se observar NoClassDefFoundError em release com minificação ligada, valide se os proguard.txt dos AARs foram efetivamente aplicados abrindo o mapping.txt gerado pelo R8.

Permissões

A solução injeta no manifesto do seu app, via manifest merger, todas as permissões e Activities necessárias — INTERNET, CAMERA, ACCESS_NETWORK_STATE, a Activity de captura do FaceTec e a Activity-ponte do SDK. Nenhuma declaração manual é necessária.

A FaceTec trata a solicitação de permissão de câmera e a respectiva tela inteiramente por conta própria — o SDK não contém lógica de permissão de câmera, e seu app não precisa pedir CAMERA antes de iniciar a captura.

O merge de manifesto também aplica android:largeHeap="true", android:hardwareAccelerated="true" e android:supportsRtl="true" no <application>, por exigência do FaceTec. Esses atributos valem para o app inteiro, não apenas para a tela de captura — é a única parte da injeção com efeito fora do fluxo do SDK. Se o seu app já define algum deles com outro valor, resolva o conflito no seu próprio AndroidManifest.xml.

Checklist pós-integração

Antes de considerar a integração concluída:

Manifesto mesclado

Abra app/build/intermediates/merged_manifest/<variante>/AndroidManifest.xml e confirme a presença da permissão CAMERA, da Activity de captura do FaceTec e da Activity-ponte do SDK.

Bibliotecas nativas no APK

Confirme que o APK traz arm64-v8a e armeabi-v7a com as .so do SDK — via unzip -l app-debug.apk | grep '\.so' ou pelo APK Analyzer do Android Studio.

Build release minificado

Rode ./gradlew :app:assembleRelease com as regras de ProGuard / R8 e valide duas capturas consecutivas no mesmo launch do app. É a regressão mais barata contra problemas de minificação, que só aparecem a partir da segunda captura.

Dispositivo real ARM

O fluxo completo não roda em emulador x86/x86_64. Valide em hardware ARM.

AGP/Kotlin do seu projeto

Confirme que seu projeto está de fato em AGP 8.x. Se migrar para AGP 9.x depois de integrar esta build, troque para a build padrão (2.0.0) na próxima atualização — veja Instalação.

Primeiros Passos

Onboarding

Bureau

Liveness

Assinatura Digital

ID Check

Card Check

TrustPass

BPO

Extração Dados

Mensageria

Documentoscopia

Storage

Coleção Postman

Instalação (Compat AGP 8)

Pré-requisitos

Requisitos mínimos

Instalação

ProGuard / R8

Regras obrigatórias

Permissões

Checklist pós-integração

Próximos passos

Implementação

Solução de problemas

​Pré-requisitos

​Requisitos mínimos

​Instalação

​ProGuard / R8

​Regras obrigatórias

​Permissões

​Checklist pós-integração

​Próximos passos

Implementação

Solução de problemas

Pré-requisitos

Requisitos mínimos

Instalação

ProGuard / R8

Regras obrigatórias

Permissões

Checklist pós-integração

Próximos passos