> 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/web-javascript/getting-started/faceliveness-deprecated.md).

# Face Liveness (OBSOLETO)

## **Importando SDK** <a href="#ec6hruocgdfc" id="ec6hruocgdfc"></a>

Para usar o Sdk, você pode importar remotamente o `.js` arquivo ou baixá-lo localmente.

## **Remotamente** <a href="#vbdis2v796qu" id="vbdis2v796qu"></a>

Inclua o `.js` arquivo diretamente da CDN:

```html
<script src="https://repo.combateafraude.com/javascript/release/face-liveness/<VERSION>.js" type="text/javascript"></script>
```

Você pode obter a classe do SDK usando o seguinte código:

```javascript
const sdk = window['FacesSDK'];
```

### **Inicialização** <a href="#e8bl0o5hv2i4" id="e8bl0o5hv2i4"></a>

### `initializeSdk(token: string, sdkContainer: string, useFaceAuthenticator: boolean, personId: string, options: any)` <a href="#tdlbz5hosfd" id="tdlbz5hosfd"></a>

O SDK possui um método de inicialização isolado, para permitir maior controle sobre quando ele ocorre.

Durante esse processo, o SDK inicializará suas variáveis internas e baixará os recursos necessários para sua execução.

\[!]Você deve chamar este método antes de usar outros métodos do SDK.

## Parâmetros suportados <a href="#m3han9t9fipv" id="m3han9t9fipv"></a>

| Parâmetro                                                                                                                                                                                                                          | Obrigatório?                                                              |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
| <p><a href="https://github.com/combateafraude/public-docs/blob/docs-sdks/sdk_integration_documentation.md#2-generating-access-tokens"><strong><code>token</code></strong></a></p><p>Token de autenticação para consumir o SDK.</p> | Sim.                                                                      |
| <p><strong><code>sdkContainer</code></strong></p><p>Id do contêiner onde o SDK será inserido.</p>                                                                                                                                  | Sim.                                                                      |
| <p><strong><code>useFaceAuthenticator</code></strong></p><p>Flag indicando se o FaceAuthenticator será usado.</p>                                                                                                                  | Não. O padrão é **`false`**                                               |
| <p><strong><code>personId</code></strong></p><p>Número do documento usado como identificador único para cada usuário.</p>                                                                                                          | Sim.                                                                      |
| <p><strong><code>options.timeExpiresUrl</code></strong></p><p>Personalização do tempo de expiração da Url da imagem retornada pelo Sdk.</p>                                                                                        | Não. O padrão é 30 minutos, os valores aceitos são **`3H`** ou **`30D`**. |
| <p><strong><code>opções.</code></strong><a href="#_av30ro16qapb"><strong><code>filter</code></strong></a></p><p>Personalização do filtro de captura de imagem.</p>                                                                 | Não. O padrão é **`sombreado`**                                           |
| <p><strong><code>options.settings.</code></strong><a href="#_av30ro16xcbvd"><strong><code>language</code></strong></a></p><p>Personalização do idioma.</p>                                                                         | Não. O padrão é **`pt_BR`**                                               |
| <p><strong><code>options.startButton.label</code></strong></p><p>Personalize o texto do botão de início do SDK.</p>                                                                                                                | Não.                                                                      |
| <p><strong><code>options.startButton.color</code></strong></p><p>Personalize a cor do texto do botão de início do SDK.</p>                                                                                                         | Não.                                                                      |
| <p><strong><code>options.startButton.backgroundColor</code></strong></p><p>Personalize a cor de fundo do botão de início do SDK.</p>                                                                                               | Não.                                                                      |
| <p><strong><code>options.startButton.borderRadius</code></strong></p><p>Personalize o raio da borda do botão de início do SDK.</p>                                                                                                 | Não.                                                                      |
| <p><strong><code>options.startButton.border</code></strong></p><p>Personalize a borda do botão de início do SDK.</p>                                                                                                               | Não.                                                                      |
| <p><strong><code>options.reverseProxy</code></strong></p><p>Veja mais detalhes na <a href="#reverse-proxy-configuration">Configuração de proxy reverso</a> seção.</p>                                                              | Não.                                                                      |

#### **Exemplo** <a href="#j4h8eo4ng95u" id="j4h8eo4ng95u"></a>

```javascript
const options = {
  timeExpiresUrl: '30D',
  settings: {
    filter: 'classic',
    language: 'pt_BR'
  },
  startButton: {
    label: 'Escanear rosto',
    color: '#F9F9F9',
    backgroundColor: 'blue',
    borderRadius: '0.25rem',
    border: '1px solid #2D994B'
  }
}

const facesSdk = await sdk.initializeSdk(token, sdkContainer, useFaceAuthenticator, personId, options);
```

### **Filtro** <a href="#av30ro16qapb" id="av30ro16qapb"></a>

Configuração do filtro para a pré-visualização da câmera. Pode ser `clássico`, `sombreado` (detalhe adicional, o padrão), `vibrante` (cores completas), `limpo` (sem filtro) e `desfocado` (começa desfocado).

### **Idioma** <a href="#av30ro16xcbvd" id="av30ro16xcbvd"></a>

Por meio do `language` parâmetro, o idioma do aplicativo pode ser alterado, o valor padrão é `pt_BR`, confira a disponibilidade abaixo:

| **Parâmetro** | **Idioma** |
| ------------- | ---------- |
| `cy_GB`       | Galês.     |
| `de`          | Alemão.    |
| `en`          | Inglês.    |
| `es`          | Espanhol.  |
| `fr`          | Francês.   |
| `it`          | Italiano.  |
| `nl`          | Holandês.  |
| `pt_BR`       | Português. |

### **Iframe** <a href="#id-1zo6vxxf782" id="id-1zo6vxxf782"></a>

Para realizar a integração por meio de um iframe, as permissões de câmera e tela cheia devem ser fornecidas.

```javascript
<iframe
  src="https://caf.example"
  allow="camera;fullscreen;accelerometer;gyroscope;magnetometer;"
></iframe>
```

### **Configuração de proxy reverso**

Se você escolher usar um proxy reverso, deverá configurá-lo para encaminhar corretamente as solicitações para os endpoints apropriados. Abaixo está o mapeamento para redirecionamento:

* `/v1/` → `https://api.public.caf.io/v1/sdks/faces/`
  * Considere usar `https://api.public.beta.caf.io/v1/sdks/faces/` para homologação.
* `/std/` → `https://us.rp.secure.iproov.me/`
* `/std/ws/` → `wss://us.rp.secure.iproov.me/ws/`
* `/assets/` → `https://cdn.iproov.app/`

#### **Exemplo de configuração do SDK**

Supondo que seu domínio seja `my.proxy.io`, sua configuração do SDK seria assim:

```javascript
reverseProxy: {
    authBaseUrl: "https://my.proxy.io/v1/",
    livenessBaseUrl: "https://my.proxy.io/std/",
    assetsBaseUrl: "https://my.proxy.io/assets/"
}
```

**Observação:** Os caminhos fornecidos neste exemplo são apenas para referência. Você pode configurar seu proxy e caminhos de acordo com seus padrões de melhores práticas.

## **Webview** <a href="#d6tsn0954bw8" id="d6tsn0954bw8"></a>

Para usar o SDK por meio de um Webview, a permissão de câmera deve ser concedida em seu aplicativo nativo.

Exemplo de implementação no Android.

`AndroidManifest.xml`

```java
  <uses-permission android:name="android.permission.CAMERA" />
  <uses-feature
      android:name="android.hardware.camera"
      android:required="true" />
```

`MainActivity`

```java
  @Override
  public void onPermissionRequest(final PermissionRequest request) {
      request.grant(request.getResources());
  }
```

Exemplo [android](https://github.com/combateafraude/android-webview-example) projeto para implementação webview, além disso é necessário poder abrir o aplicativo em tela cheia, o exemplo mostra como configurá-lo corretamente.

No iOS, as permissões de câmera e movimento devem ser concedidas com `NSCameraUsageDescription` e `NSMotionUsageDescription` de acordo com o [exemplo](https://github.com/combateafraude/ios-webview-example) projeto.

## **Abertura e captura de selfies** <a href="#s3y7w2l7a01m" id="s3y7w2l7a01m"></a>

### `execute()` <a href="#id-1l7spulz52hu" id="id-1l7spulz52hu"></a>

O método usado para carregar o SDK na tela e realizar a captura de selfie.

Ele inicializará o *stream* (solicitando permissões, se necessário) e o carregará no contêiner.

### **Exemplo** <a href="#rb9d2o76lxbw" id="rb9d2o76lxbw"></a>

```javascript
await facesSdk.execute();
```

### **Retornar** <a href="#exv8broymq71" id="exv8broymq71"></a>

| **Campo**        | **Tipo** | **Descrição**                                                                                                                                                                                                                                                                                                                                          |
| ---------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `signedResponse` | `string` | 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. |

### **Exemplo** <a href="#li5quwhp57l9" id="li5quwhp57l9"></a>

```javascript
{
   "signedResponse": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyZXF1ZXN0SWQiOiIyY2QwMTkxZS1jNzc0LTRjZWEtYjliNC1hOGJhYjRiODEzNGQiLCJpc0FsaXZlIjp0cnVlLCJ0b2tlbiI6ImYyOWFhNmM0YjczMmYyYWNhZTJjOGMxZWYxZDUyN2FhMDY0ZTI1YTg1OWMyNWU2MzZhMzQ0MTAzMTgwMXZ1MDEiLCJ1c2VySWQiOiJlZmI1NTg5NS1lMmY0LTRkMjQtOGE4OS04NGI0Nzg3ZjViM2EiLCJpbWFnZVVybCI6ImltYWdlVXJsIiwicGVyc29uSWQiOiJwZXJzb25JZCIsInNka1ZlcnNpb24iOiIxLjAuNCIsImF0dGVtcHRJZCI6IjY1M2ZmYjg2ZmViZTZhMzJiZWMyOWM1ZSIsImlhdCI6MTY5ODY5MTk3NH0.BKCtQUbPRBMchHX30_fqf6vSWVN__K4nsOecKLoybGs"
}
```

### **Parâmetros da resposta assinada** <a href="#exv8broymq72" id="exv8broymq72"></a>

| **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**, com base nele, a validação deve ser realizada para continuar ou não com o fluxo, em caso de `isAlive: true`, seu usuário pode continuar com a jornada, em caso de `isAlive: false`, este usuário não é válido e deve ser impedido de continuar o restante da jornada. {% endhint %}

## **Eventos** <a href="#d6tsn2342fax" id="d6tsn2342fax"></a>

Atualmente o SDK emite três tipos de eventos:

| **Evento**         | **Descrição**                                                    |
| ------------------ | ---------------------------------------------------------------- |
| `started`          | Inicialização do fluxo de captura.                               |
| `sdk-button-ready` | Os componentes do SDK foram carregados e estão prontos para uso. |
| `passed`           | A captura da imagem foi bem-sucedida.                            |
| `failed`           | A captura da imagem falhou.                                      |
| `error`            | Ocorreu um erro durante o processo de captura.                   |
| `streaming`        | streaming iniciado, início em tela cheia.                        |
| `streamed`         | Fim do streaming, encerrando a tela cheia.                       |
| `canceled`         | Cancelamento do fluxo de captura.                                |
| `unsupported`      | O navegador não oferece suporte ao Sdk.                          |

## **Detalhes do evento de falha**

O evento failed é do tipo [customEvent](https://developer.mozilla.org/en-US/docs/Web/API/CustomEvent/detail) portanto, se você desejar obter detalhes sobre o motivo da falha, pode consumir o `event.detail` onde você encontrará as seguintes descrições.

| Feedback            | Motivo                                                               | LA | GPA |
| ------------------- | -------------------------------------------------------------------- | -- | --- |
| eyes\_closed        | Mantenha os olhos abertos                                            | ✅  | ✅   |
| face\_too\_far      | Aproxime o rosto da tela                                             | ❌  | ✅   |
| face\_too\_close    | Afaste o rosto da tela                                               | ❌  | ✅   |
| misaligned\_face    | Mantenha o rosto dentro do oval                                      | ❌  | ✅   |
| multiple\_faces     | Certifique-se de que apenas uma pessoa esteja visível                | ✅  | ✅   |
| obscured\_face      | Remova quaisquer coberturas faciais                                  | ✅  | ✅   |
| sunglasses          | Remova os óculos de sol                                              | ✅  | ✅   |
| too\_bright         | A luz ambiente está muito forte ou o brilho da tela está muito baixo | ✅  | ✅   |
| too\_dark           | Seu ambiente parece estar escuro demais                              | ✅  | ✅   |
| too\_much\_movement | Por favor, fique parado                                              | ❌  | ✅   |
| unknown             | Tente novamente                                                      | ✅  | ✅   |

### **Exemplo de listener do evento de falha**

```javascript
document.addEventListener(
  "failed",
  (event) => {
    console.log(event.detail.feedback);
    console.log(event.detail.reason);
  }
);
```

## **Detalhes do evento de erro**

O evento error é do tipo [customEvent](https://developer.mozilla.org/en-US/docs/Web/API/CustomEvent/detail) portanto, se você desejar obter detalhes sobre o motivo do erro, pode consumir event.detail, onde encontrará as seguintes descrições.

| Feedback                           | Motivo                                                                          |
| ---------------------------------- | ------------------------------------------------------------------------------- |
| unknown                            | Tente novamente                                                                 |
| client\_camera                     | Houve um erro ao obter o vídeo da câmera                                        |
| client\_error                      | Ocorreu um erro desconhecido                                                    |
| error\_asset\_fetch                | Não foi possível buscar os assets                                               |
| error\_camera                      | A câmera não pode ser iniciada por motivos desconhecidos                        |
| error\_camera\_in\_use             | A câmera já está em uso e não pode ser acessada                                 |
| error\_camera\_not\_supported      | A resolução da câmera é muito pequena                                           |
| error\_camera\_permission\_denied  | O usuário negou nossa solicitação de permissão de câmera                        |
| error\_device\_motion\_denied      | O usuário negou nossa solicitação de permissão de movimento do dispositivo      |
| error\_device\_motion\_unsupported | Seu dispositivo aparentemente não informa totalmente o movimento do dispositivo |
| error\_fullscreen\_change          | Saiu da tela cheia sem concluir o iProov                                        |
| error\_invalid\_token              | O token interno do sdk é inválido                                               |
| error\_network                     | Erro de rede                                                                    |
| error\_no\_face\_found             | Nenhum rosto pôde ser encontrado                                                |
| error\_not\_supported              | O dispositivo ou a integração não consegue executar o Web SDK                   |
| error\_server                      | Ocorreu um erro ao comunicar-se com os servidores do iProov                     |
| error\_token\_timeout              | O token foi solicitado muito tempo depois de ter sido criado                    |
| error\_too\_many\_requests         | O serviço está sob alta carga e o usuário deve tentar novamente                 |
| error\_user\_timeout               | O usuário iniciou a solicitação, mas não fez o streaming a tempo                |
| integration\_unloaded              | O SDK foi desmontado do DOM antes de terminar                                   |
| sdk\_unsupported                   | O SDK atingiu o fim da vida útil e não tem mais suporte                         |

### **Exemplo de listener do evento de erro**

```javascript
document.addEventListener(
  "error",
  (event) => {
    console.log(event.detail.feedback);
    console.log(event.detail.reason);
  }
);
```

## **Erros**

Todos os erros são instâncias do objeto [Error](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error) Para entender a causa de um erro, você pode acessar `error.name` e `error.message` propriedades, que fornecem os seguintes detalhes:

| Nome                        | Mensagem                                            | Método        |
| --------------------------- | --------------------------------------------------- | ------------- |
| CameraPermissionDeniedError | Erro: permissão da câmera negada pelo usuário.      | initializeSdk |
| CameraPermissionError       | Erro ao obter permissão da câmera.                  | initializeSdk |
| CameraUnsupportedError      | A câmera não é suportada por este navegador.        | initializeSdk |
| RequestTokenError           | Erro ao solicitar um token.                         | initializeSdk |
| RenderCaptureWindowError    | Erro ao renderizar a janela de captura.             | initializeSdk |
| CaptureError                | Erro ao capturar uma imagem.                        | execute       |
| FaceLivenessError           | Erro durante a detecção de vivacidade facial.       | execute       |
| FaceLivenessError           | Nenhum rosto pôde ser encontrado na selfie enviada. | execute       |
| FaceLivenessError           | Muitas solicitações em um curto período de tempo.   | execute       |

### **Exemplo de tratamento de um `initializeSdk` error**

```javascript
  try {
    const facesSdk = await sdk.initializeSdk(token, sdkContainer, useFaceAuthenticator, personId, options);
  } catch (error) {
    console.log("Nome do erro:", error.name); // RequestTokenError 
    console.log("Mensagem do erro:", error.message); // Error while requesting a token.
  }
```

### **Exemplo de tratamento `execute` error**

```javascript
  try {
    await facesSdk.execute();
  } catch (error) {
    console.log("Nome do erro:", error.name); // CaptureError 
    console.log("Mensagem do erro:", error.message); // Error while capturing an image.
  }
```

> **Observação:**\
> O **detalhes do evento de erro** capturar erros específicos que ocorrem durante o processo de detecção de vivacidade,\
> enquanto a **erros** seção se refere a funcionalidades mais gerais e fundamentais do SDK.\
> Dependendo da implementação, talvez seja necessário lidar com ambos os tipos de erro para garantir uma integração robusta.


---

# 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/web-javascript/getting-started/faceliveness-deprecated.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.