Instalação

Este guia mostra como adicionar o LivenessFacetecSDK — o pacote que orquestra o motor FaceTec — ao seu projeto Android.

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 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 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.3.20
Android Gradle Plugin	9.1.1
ABIs suportadas	`armeabi-v7a`, `arm64-v8a`
Versão do `LivenessFacetecSDK`	`2.0.0`
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.

Obter os binários

Baixe na plataforma da Valid os dois arquivos: o .aar do LivenessFacetecSDK (liveness-facetec-sdk-2.0.0.aar, com os módulos internos do SDK e as bibliotecas nativas das duas ABIs suportadas) 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:

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 ──────────────────────────────
    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 ─────────────────────────────
    implementation("io.insert-koin:koin-core:4.2.1")
    implementation("io.insert-koin:koin-android:4.2.1")
    implementation("org.jetbrains.kotlinx:kotlinx-coroutines-android:1.10.2")
    implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.11.0")
    implementation("com.squareup.retrofit2:retrofit:3.0.0")
    implementation("com.squareup.okhttp3:okhttp:5.3.2")
    implementation("com.squareup.okhttp3:logging-interceptor:5.3.2")
    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 5.x	embutido no artefato
kotlinx-serialization 1.11.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. 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.

Primeiros Passos

Onboarding

Bureau

Liveness

Assinatura Digital

ID Check

Card Check

TrustPass

BPO

Extração Dados

Mensageria

Documentoscopia

Storage

Coleção Postman

Instalação

Pré-requisitos

Requisitos mínimos

Instalação

ProGuard / R8

Regras obrigatórias

Permissões

Próximos passos

Implementação

Solução de problemas

​Pré-requisitos

​Requisitos mínimos

​Instalação

​ProGuard / R8

​Regras obrigatórias

​Permissões

​Próximos passos

Implementação

Solução de problemas

Pré-requisitos

Requisitos mínimos

Instalação

ProGuard / R8

Regras obrigatórias

Permissões

Próximos passos