> ## Documentation Index
> Fetch the complete documentation index at: https://docs-platform.services-valid.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Instalação

> Adicione o LivenessFacetecSDK v10 a um projeto Android via AAR fundido

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.

<Warning>
  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.
</Warning>

## 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`                  |

<Warning>
  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.
</Warning>

<Info>
  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.
</Info>

<Info>
  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.
</Info>

## Instalação

<Steps>
  <Step title="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.
  </Step>

  <Step title="Adicionar o AAR ao app">
    Copie o AAR para a pasta `libs` do módulo `app`:

    ```text theme={"theme":"catppuccin-latte"}
    seu-projeto/
      app/
        libs/
          liveness-facetec-sdk.aar
        build.gradle.kts
    ```
  </Step>

  <Step title="Configurar repositórios">
    No `settings.gradle.kts` do projeto, declare os repositórios necessários para resolver as dependências externas do SDK:

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

    <Warning>
      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.
    </Warning>
  </Step>

  <Step title="Configurar app/build.gradle.kts">
    Declare o AAR junto com as dependências externas obrigatórias:

    ```kotlin theme={"theme":"catppuccin-latte"}
    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")
    }
    ```

    <Info>
      `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.
    </Info>

    <Warning>
      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](#proguard-r8) — sem elas o app compila, mas quebra em runtime com `NoClassDefFoundError`.
    </Warning>
  </Step>

  <Step title="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`.
  </Step>
</Steps>

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

## 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`:

```proguard theme={"theme":"catppuccin-latte"}
# ── 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.

<Info>
  `-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.
</Info>

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

  ```proguard theme={"theme":"catppuccin-latte"}
  -keepattributes RuntimeVisibleAnnotations, RuntimeVisibleParameterAnnotations
  ```
</Info>

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.**

<Info>
  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.
</Info>

<Warning>
  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`.
</Warning>

## Próximos passos

<CardGroup cols={2}>
  <Card title="Implementação" icon="code" iconType="regular" href="/plataforma/liveness/facetec/v10/sdk/android/implementacao">
    Inicialize o SDK e colete o resultado da verificação
  </Card>

  <Card title="Solução de problemas" icon="wrench" iconType="regular" href="/plataforma/liveness/facetec/v10/sdk/android/troubleshooting">
    Erros comuns ao adicionar o AAR e configurar o Gradle
  </Card>
</CardGroup>