Instalação

Este guia mostra como adicionar o LivenessFacetecSDK — o pacote que embute 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 ao arquivo .aar do LivenessFacetecSDK distribuído 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
ABIs suportadas	`armeabi-v7a`, `arm64-v8a`
Versão do `LivenessFacetecSDK`	`2.0.0`
FaceTec SDK embutido	`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.

O AAR fundido já inclui o FaceTec SDK 10.1.18 e todas as chaves internas do SDK — nenhuma chave precisa ser fornecida pelo app consumidor. Bibliotecas de terceiros (Koin, Retrofit, OkHttp, Shield, etc.) precisam ser declaradas explicitamente pelo app cliente; a lista completa está abaixo.

Obter o binário

Solicite à equipe da Valid o .aar do LivenessFacetecSDK. Ele já contém o FaceTec SDK, todos os módulos internos do SDK e as bibliotecas nativas das duas ABIs suportadas.

Adicionar o AAR ao app

Copie o AAR para a pasta libs do módulo app:

seu-projeto/
  app/
    libs/
      liveness-facetec-sdk.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 o AAR 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 (AAR fundido; FaceTec já incluído) ──────────
    implementation(files("libs/liveness-facetec-sdk.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.

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

O AAR fundido já contém um proguard.txt combinado (SDK + FaceTec), aplicado automaticamente pelo AGP ao app cliente. Ele cobre 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` fundido no SDK

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 o proguard.txt do AAR foi efetivamente mesclado abrindo o mapping.txt gerado pelo R8.

Permissões

O AAR fundido 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