> For the complete documentation index, see [llms.txt](https://docs.caf.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.caf.io/caf-sdk/caf-sdk-pt-br/android/standalone-modules/faceliveness.md).

# Face Liveness (OBSOLETO)

## Versão atual

| Nome           | Versão |
| -------------- | ------ |
| `FaceLiveness` | 5.2.0  |

## Requisitos

* Versão mínima da API do Android SDK: `minSdk 26` (Android 8 Oreo)
* Versão da API do Android SDK para compilação: `compileSdk 34`

Para publicar seu app na *Google Play Store*, você precisa preencher um formulário de segurança de dados. Como integramos com o *SDK FingerPrintJS*, você precisará fornecer as seguintes informações:

| Pergunta no formulário de segurança de dados do Google Play Console         | Resposta                                                  |
| --------------------------------------------------------------------------- | --------------------------------------------------------- |
| Seu app coleta ou compartilha algum dos tipos de dados do usuário exigidos? | Sim.                                                      |
| Que tipo de dado é coletado?                                                | Identificadores do dispositivo ou outros identificadores. |
| Esse dado é coletado, compartilhado ou ambos?                               | Coletado.                                                 |
| Esse dado é processado de forma efêmera?                                    | Sim.                                                      |
| Por que esses dados do usuário são coletados?                               | Prevenção a fraudes, segurança e conformidade.            |

{% hint style="warning" %}
`nome da versão` e `código da versão` são obrigatórios para que o SDK funcione corretamente.
{% endhint %}

## Dependências do SDK

O FaceLiveness utiliza os seguintes SDKs externos:

| SDK                         | Versão |
| --------------------------- | ------ |
| `iProov Biometrics Android` | 11.1.0 |
| `Fingerprint Pro Android`   | 2.7.0  |

* [iProov Biometrics Android](https://github.com/iProov/android): Permite a integração da tecnologia de verificação facial ao vivo.
* [Fingerprint Pro Android](https://github.com/fingerprintjs/fingerprintjs-pro-android-demo): Fornece recursos de autenticação por impressão digital para aprimorar os recursos de segurança do seu app.

Essas dependências são facilmente gerenciadas pelo Gradle e vêm incluídas no SDK para facilitar a instalação.

### Permissões em tempo de execução

| Permissão | Motivo                                                       | Obrigatório |
| --------- | ------------------------------------------------------------ | ----------- |
| `CÂMERA`  | Captura da selfie em políticas de verificação facial ao vivo | Sim         |

### Instalação

Se a sua versão do Gradle for anterior à 7, adicione estas linhas ao seu `build.gradle`.

```groovy
allprojects {
  repositories {
  ...
  maven { url 'https://repo.combateafraude.com/android/release' }
  maven { url 'https://raw.githubusercontent.com/iProov/android/master/maven/' }
  maven { url 'https://maven.fpregistry.io/releases' }
  maven { url 'https://jitpack.io' }

}}
```

Se a sua versão do Gradle for 7 ou mais recente, adicione estas linhas ao seu `settings.gradle`.

```groovy
dependencyResolutionManagement {
    repositories {
        ...
        maven { url 'https://repo.combateafraude.com/android/release' }
        maven { url 'https://raw.githubusercontent.com/iProov/android/master/maven/' }
        maven { url 'https://maven.fpregistry.io/releases' }
        maven { url 'https://jitpack.io' }
    }
}
```

Adicione suporte ao Java 8 ao seu `build.gradle` arquivo. Pule esta etapa se o Java 8 estiver ativado.

```groovy
android {
    ...
    compileOptions {
        sourceCompatibility JavaVersion.VERSION_1_8
        targetCompatibility JavaVersion.VERSION_1_8
    }
}
```

Adicione a versão do SDK à seção de dependências no seu `build.gradle` arquivo

```groovy
dependencies {
    implementation 'io.caf.sdk:new-face-liveness:{version}'
}
```

## Instanciando o SDK

Primeiro, crie um objeto do tipo `FaceLiveness`. Este objeto é para você configurar todas as suas regras de negócio:

```java
FaceLiveness faceLiveness = new FaceLiveness.Builder(String mobileToken)
    //veja a tabela abaixo
    .build();
```

### Método builder

| Parâmetro                                                                                                                                                                                                                                                                                                                                             | Obrigatório                              |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------- |
| <p><code>String mobileToken</code></p><p>Token de uso associado à sua conta Identity (veja como obtê-lo <a href="https://github.com/combateafraude/public-docs/blob/docs-sdks/android/standalone-modules/faceliveness/broken-reference/README.md">aqui</a>).</p>                                                                                      | Sim                                      |
| <p><code>.setStage(CAFStage stage)</code></p><p>Usado para redirecionar o SDK para o estágio desejado na API da caf. O método recebe como parâmetro um enum <code>CafStage</code> para selecionar o ambiente:</p><ul><li><code>CAFStage.PROD</code> definir ambiente de produção.</li><li><code>CAFStage.BETA</code> definir ambiente beta.</li></ul> | Não. O padrão é `CAFStage.PROD`          |
| <p><code>.setFilter(Filter filter)</code></p><p>Usado para alterar o filtro do SDK, que tem as seguintes opções:</p><ul><li><code>Filter.NATURAL</code></li><li><code>Filter.LINE\_DRAWING</code></li></ul>                                                                                                                                           | Não, o padrão é `LINE_DRAWING`           |
| <p><code>.setEnableScreenshots(boolean bool)</code></p><p>Usado para habilitar capturas de tela durante a varredura do SDK. Desativado por padrão por motivos de segurança.</p>                                                                                                                                                                       | Não, o padrão é `false`                  |
| <p><code>.setLoadingScreen(boolean bool)</code></p><p>Usado para ativar uma barra de progresso de carregamento padrão durante os eventos de carregamento. Você pode definir sua própria tela de carregamento personalizada em vez disso, usando o <code>onLoading</code> método abaixo.</p>                                                           | Não, o padrão é `false`                  |
| <p><code>.setImageUrlExpirationTime(Time time)</code></p><p>Usado para personalizar o tempo de expiração da URL da imagem, que tem as seguintes opções:</p><ul><li><code>Time.THREE\_HOURS</code></li><li><code>Time.THIRTY\_DAYS</code></li></ul>                                                                                                    | Não, o padrão é `null`                   |
| <p><code>.setFaceLivenessBaseUrl(String baseURL)</code></p><p>Usado para habilitar o uso de proxy reverso para executar a verificação de liveness facial. Se usado, os certificados devem ser definidos com o método setCertificates.</p>                                                                                                             | Não, o padrão é a URL original da IProov |
| <p><code>.setCertificates(String\[] certificates)</code></p><p>Usado para definir certificados fixados para a implementação de proxy reverso.</p>                                                                                                                                                                                                     | Não, o padrão é uma lista vazia          |
| <p><code>.setAuthenticationBaseUrl(String baseURL)</code></p><p>Usado para habilitar o uso de proxy reverso para executar as autenticações do SDK.</p>                                                                                                                                                                                                | Não, o padrão é a URL original da Caf    |

## Proxy reverso

Para implementar as configurações de proxy reverso, você deve seguir estas instruções:

### Proxy reverso do FaceLiveness

* Configure seu proxy para se comunicar com \`wss\://us.rp.secure.iproov.me/ws´.
* Use o método `.setFaceLivenessBaseUrl` para definir a URL na qual o FaceLiveness deve ser executado.
  * **O protocolo da URL deve ser WSS.**
* Use o método `.setCertificates` método para definir os certificados, que são o hash SHA-256 codificado em base64 da Subject Public Key Info do certificado.
  * **Os certificados são necessários para fazer o proxy reverso do FaceLiveness funcionar.**

```java
FaceLiveness faceLiveness = new FaceLiveness.Builder(usersToken)
        .setFaceLivenessBaseUrl("wss://my.proxy.io/ws/")
        .setCertificates(new String[]{
                "4d69f16113bed7d62ca56feb68d32a0fcb7293d3960=",
                "50f71c5dda30741ee4be1ac378e12539b0d1d511f99=",
                "9f85e26c1ae41f7ac97adc4099be7f2a40759510ab9="
        })
        .build();
```

### Proxy reverso de autenticação

* Defina seu proxy para se comunicar com a URL que corresponde ao CAFStage que você está usando:
  * CAFStage.PROD -> <https://api.public.caf.io/v1/sdks/faces/>
  * CAFStage.BETA -> <https://api.public.beta.caf.io/v1/sdks/faces/>
  * CAFStage.DEV -> <https://api.public.dev.caf.io/v1/sdks/faces/>
* Use o método `.setAuthenticationBaseUrl` para definir a URL na qual as solicitações de autorização devem ser executadas.
  * **O protocolo da URL deve ser HTTPS.**

```java
FaceLiveness faceLiveness = new FaceLiveness.Builder(usersToken)
        .setAuthenticationBaseUrl("https://my.proxy.io/v1/faces/")
        .build();
```

## Consultando uma política

Para autenticar um usuário, use o `.startSDK()` método. Você deve inserir o `personId`, o Context da sua app e um `VerifyLivenessListener` objeto.

### Parâmetros

| Parâmetro                                                                                                                                                                                                                                  | Obrigatório |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------- |
| <p><code>String personId</code></p><p>Identificador do usuário que realizará a verificação de vivacidade facial. Recomenda-se usar o documento de identificação do usuário neste campo, como o CPF, mas pode ser qualquer outro valor.</p> | Sim         |
| <p><code>Context context</code></p><p>Context do seu app</p>                                                                                                                                                                               | Sim         |
| <p><code>VerifyLivenessListener listener</code></p><p>Listener de resposta</p>                                                                                                                                                             | Sim         |

### Exemplo

```java
faceLiveness.startSDK(Context context, String personId, new VerifyLivenessListener() {
    @Override
    public void onSuccess(FaceLivenessResult result) {

    }

    @Override
    public void onFailure(FaceLivenessFailureResult result) {

    }

    @Override
    public void onError(SDKError sdkerror) {

    }

    @Override
    public void onCancel() {

    }

    @Override
    public void onLoading() {

    }

    @Override
    public void onLoaded() {

    }
});
```

### opções de VerifyLivenessListener

| Método      | Descrição                                                                                                                                                  |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `onSuccess` | A execução terminou com sucesso, você deve usar o `faceLivenessResult` e verificar os resultados do SDK.                                                   |
| `onFailure` | A execução terminou com falha, você deve usar o `faceLivenessFailureResult` e verificar os resultados do SDK.                                              |
| `onError`   | A execução terminou com erro, você deve usar o `sdkFailure` e verificar os resultados de erro do SDK.                                                      |
| `onCancel`  | A execução foi cancelada pelo usuário.                                                                                                                     |
| `onLoading` | O SDK está carregando; você pode usar este método para definir uma ação no seu app, por exemplo, um carregamento.                                          |
| `onLoaded`  | O SDK não está mais carregando; você pode usar este método para definir uma ação no seu app, por exemplo, você pode interromper seu carregamento anterior. |

## Resultados do SDK

### Casos de sucesso

Ao final de uma execução bem-sucedida, você receberá um objeto do tipo [FaceLivenessResult](#facelivenessresult). Esse objeto contém uma `signedResponse` propriedade contendo um token JWT com o resultado da execução. Esse token deve ser descriptografado para obter os detalhes dos resultados da execução.

```java
  livenessResult.getSignedResponse()
```

#### FaceLivenessResult (Classe)

| Propriedade             | Descrição                                                                                                                                                                                                                                                                                                                                              |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `String signedResponse` | Resposta assinada do servidor da CAF confirmando que a selfie capturada tem um rosto real. Este parâmetro é usado para obter uma camada extra de segurança, verificando se a assinatura da resposta não está quebrada ou se foi causada por interceptação da solicitação. Se estiver quebrada, há uma forte indicação de interceptação da solicitação. |

#### Parâmetros SignedResponse

Dentro de `signedResponse`, o parâmetro `isAlive` define a execução do liveness, em que `true` é aprovado e `false` é rejeitado ([Caso de falha](#failure-cases) será retornado).

| Evento       | Descrição                                                                        |
| ------------ | -------------------------------------------------------------------------------- |
| `requestId`  | Identificador da solicitação.                                                    |
| `isAlive`    | Validação de uma pessoa viva, identifica se o usuário passou com sucesso ou não. |
| `token`      | Token da solicitação.                                                            |
| `userId`     | Identificador do usuário fornecido para a solicitação.                           |
| `imageUrl`   | Link temporário para a imagem, gerado pela nossa API.                            |
| `personId`   | Identificador do usuário fornecido para o SDK.                                   |
| `sdkVersion` | Versão do Sdk em uso.                                                            |
| `iat`        | Expiração do token.                                                              |

{% hint style="warning" %}
O **isAlive** parâmetro é **MUITO IMPORTANTE**, pois determina se o processo de validação prossegue ou é interrompido. Quando `isAlive: true`, o usuário recebe permissão para continuar sua jornada; por outro lado, se `isAlive: false`, o usuário é considerado inválido e o acesso a etapas posteriores da jornada deve ser negado. Esse parâmetro desempenha um papel fundamental na orientação do fluxo das operações.
{% endhint %}

### Casos de erro

Em caso de erros de execução, você receberá um objeto do tipo `SDKError`. Esse objeto engloba um enum contendo o `errorType`, e um `descrição`.

#### SDKError (Classe)

| Propriedade           | Descrição               |
| --------------------- | ----------------------- |
| `String description`  | Descrição do erro.      |
| `ErrorType errorType` | Retorna o tipo do erro. |

#### ErrorType (classe Enum)

| Error                                | Descrição                                                                                                                                      |
| ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `CAMERA_PERMISSION`                  | Indica que o dispositivo não tem permissão para acessar a câmera, seja por negação do usuário ou por permissões ausentes no app.               |
| `NETWORK_EXCEPTION`                  | Indica um erro relacionado à rede, como ausência de conexão com a internet, timeouts do servidor ou congestionamento de rede.                  |
| `SERVER_EXCEPTION`                   | Indica um erro do lado do servidor, que pode incluir configurações incorretas do servidor, falhas de processamento ou interrupções no serviço. |
| `TOKEN_EXCEPTION`                    | Indica um problema com o token de autenticação fornecido, como ser inválido, expirado ou não ter as permissões necessárias.                    |
| `UNSUPPORTED_DEVICE`                 | Indica que o hardware ou software do dispositivo não atende aos requisitos mínimos para reconhecimento facial.                                 |
| `MULTI_WINDOW_UNSUPPORTED_EXCEPTION` | Indica que o usuário tentou usar o reconhecimento facial em modo de tela dividida ou multitelas, o que não é suportado.                        |
| `CAPTURE_ALREADY_ACTIVE_EXCEPTION`   | Indica que uma captura de reconhecimento facial já está em andamento. Uma nova captura não pode ser iniciada até que a atual seja concluída.   |
| `CAMERA_EXCEPTION`                   | Indica que ocorreu um erro ao adquirir ou usar a câmera, normalmente ao usar suporte a câmera externa.                                         |
| `FACE_DETECTOR_EXCEPTION`            | Indica que ocorreu um erro com o detector de rosto durante o processo de reconhecimento facial.                                                |
| `UNEXPECTED_ERROR_EXCEPTION`         | Indica que ocorreu um erro irrecuperável durante a transação de reconhecimento facial.                                                         |
| `INVALID_OPTIONS_EXCEPTION`          | Indica que ocorreu um erro ao aplicar as opções especificadas para o reconhecimento facial.                                                    |
| `CERTIFICATE_EXCEPTION`              | Indica que não há certificados válidos para a URL do proxy, impedindo a comunicação segura.                                                    |
| `IMAGE_NOT_FOUND_EXCEPTION`          | Indica que a imagem capturada não pôde ser encontrada para validação.                                                                          |
| `TOO_MANY_REQUESTS_EXCEPTION`        | Indica que o servidor recebeu mais solicitações do que está preparado para processar.                                                          |

### Casos de falha

Em caso de falhas de execução, você receberá um objeto do tipo `SDKFailure`. Esse objeto engloba um enum contendo o `failureType`, `descrição` e um `signedResponse`.

#### FaceLivenessFailureResult (Classe)

| Propriedade             | Descrição                                                                                                                                                                                                                                                                                                                                              |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `String signedResponse` | Resposta assinada do servidor da CAF confirmando que a selfie capturada tem um rosto real. Este parâmetro é usado para obter uma camada extra de segurança, verificando se a assinatura da resposta não está quebrada ou se foi causada por interceptação da solicitação. Se estiver quebrada, há uma forte indicação de interceptação da solicitação. |
| `String failureType`    | Em caso de uma falha específica, retorne o tipo do erro.                                                                                                                                                                                                                                                                                               |
| `String failureMessage` | Em caso de uma falha específica, retorne as instruções para evitar o erro.                                                                                                                                                                                                                                                                             |

#### Tipos de falha

Todos os motivos de falha são retornados exclusivamente nos fluxos de validação de liveness GPA. Nos fluxos de LA (Liveness Assurance), qualquer falha sempre retornará o erro genérico UNKNOWN, independentemente do problema específico encontrado.

| Valor de FailureReason | Descrição (Inglês)                                    | LA | GPA |
| ---------------------- | ----------------------------------------------------- | -- | --- |
| `UNKNOWN`              | Tente novamente                                       | ✅  | ✅   |
| `TOO_MUCH_MOVEMENT`    | Fique parado                                          | ❌  | ✅   |
| `TOO_BRIGHT`           | Mova-se para um lugar mais escuro                     | ❌  | ✅   |
| `TOO_DARK`             | Mova-se para um lugar mais claro                      | ❌  | ✅   |
| `MISALIGNED_FACE`      | Mantenha o rosto dentro do oval                       | ❌  | ✅   |
| `EYES_CLOSED`          | Mantenha os olhos abertos                             | ❌  | ✅   |
| `FACE_TOO_FAR`         | Aproxime o rosto da tela                              | ❌  | ✅   |
| `FACE_TOO_CLOSE`       | Afaste o rosto da tela                                | ❌  | ✅   |
| `SUNGLASSES`           | Remova os óculos de sol                               | ❌  | ✅   |
| `OBSCURED_FACE`        | Remova quaisquer coberturas faciais                   | ❌  | ✅   |
| `MULTIPLE_FACES`       | Certifique-se de que apenas uma pessoa esteja visível | ❌  | ✅   |
| `BACKGROUND_ISSUE`     | Fundo inadequado                                      | ❌  | ✅   |
| `DEVICE_ISSUE`         | Dispositivo incompatível                              | ❌  | ✅   |
| `EYEWEAR`              | Óculos detectados                                     | ❌  | ✅   |
| `FACE_NOT_FOUND`       | Falha na detecção do rosto                            | ❌  | ✅   |
| `FRAMES_BLURRY`        | Quadros borrados detectados                           | ❌  | ✅   |
| `MOTION_ISSUE`         | Erro de movimento do dispositivo                      | ❌  | ✅   |
| `LIGHTING_ISSUES`      | Condições de iluminação ruim                          | ❌  | ✅   |
| `REJECTED`             | Transação rejeitada                                   | ❌  | ✅   |
| `SYSTEM_ERROR`         | Erro interno do sistema                               | ❌  | ✅   |
| `TIMEOUT`              | Tempo da sessão esgotado                              | ❌  | ✅   |
| `USER_NOT_FOUND`       | Falha na busca do usuário                             | ❌  | ✅   |
| `DEVICE_RESTART`       | Erro de estado do dispositivo                         | ❌  | ✅   |
| `PROCESSING_FAULT`     | Erro de processamento                                 | ❌  | ✅   |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.caf.io/caf-sdk/caf-sdk-pt-br/android/standalone-modules/faceliveness.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.