> For the complete documentation index, see [llms.txt](https://docs.facephi.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.facephi.com/docs.facephi-pt-br/sdks/sdk-mobile/android-sdk/componentes-modulos/captura-facial.md).

# Captura Facial - Selphi

## Introdução <a href="#id-1-introduccion" id="id-1-introduccion"></a>

A captura facial é realizada por meio do **Selphi Component**.

Este componente é responsável por capturar uma selfie do usuário e extrair suas características faciais mais relevantes. Durante o processo, são realizadas, entre outras, as seguintes etapas:

* Gerenciamento interno de câmeras e permissões.
* Orientação durante a captura facial.
* Geração de modelos biométricos e imagens do usuário.

Na seção [Lançamento simplificado](https://docs.facephi.com/docs.facephi-pt-br/sdks/sdk-mobile/android-sdk/inicializacion/lanzamiento-simplificado.md) são descritas as etapas básicas para a integração do SDK. Esta página detalha as informações específicas necessárias para iniciar e configurar este componente.

***

## Dependência <a href="#id-2-dependencia" id="id-2-dependencia"></a>

A dependência específica do componente é:

```kotlin
implementation "com.facephi.androidsdk:selphi_component:$version"
```

***

## Controladores disponíveis

Este componente inclui vários controladores, cada um voltado para uma funcionalidade específica.

| Controlador                 | Descrição                                           |
| --------------------------- | --------------------------------------------------- |
| `SelphiController`          | Controlador principal de Reconhecimento Facial      |
| `RawTemplateController`     | Geração de um `RawTemplate` a partir de uma imagem  |
| `SignatureSelphiController` | Assinatura de um processo usando uma captura facial |

***

## Lançamento simplificado <a href="#id-4-lanzamiento-simplificado" id="id-4-lanzamiento-simplificado"></a>

Depois de iniciar o SDK e criar uma nova operação, o componente pode ser iniciado usando qualquer um de seus controladores.

```kotlin
val response = SDKController.launch(
    SelphiController(SelphiConfigurationData(...))
)
when (response) {
    is SdkResult.Error -> Napier.d("Selphi: ERROR - ${response.error.name}")
    is SdkResult.Success -> response.data
}
```

***

## Configuração básica <a href="#id-5-configuracion-basica" id="id-5-configuracion-basica"></a>

Para iniciar o componente, é necessário criar um objeto `SelphiConfigurationData`, que define o comportamento do widget.

```kotlin
SelphiConfigurationData(
  resourcesPath = "resources_file.zip",
  livenessMode = SelphiFaceLivenessMode.NONE
)
```

O componente permite os seguintes modos de detecção de vida:

* `SelphiFaceLivenessMode.NONE`
* `SelphiFaceLivenessMode.PASSIVE`
* `SelphiFaceLivenessMode.MOVE`

***

## Recebimento do resultado <a href="#id-6-recepcion-del-resultado" id="id-6-recepcion-del-resultado"></a>

O resultado do início é retornado como um objeto `SdkResult`, que pode indicar sucesso ou erro.

```kotlin
when (response) {
    is SdkResult.Error -> Napier.d("ERROR - ${response.error}")
    is SdkResult.Success -> response.data
}
```

### Recebimento de erros <a href="#id-61-recepcion-de-errores" id="id-61-recepcion-de-errores"></a>

Os erros serão retornados como um objeto `SelphiError`.

Lista de erros:

* `MOVE_FAIL` (`SPI_205`): Widget: O teste de vida ativo (`MOVE`) não foi aprovado. Inclui `livenessDiagnostic`.
* `ACTIVITY_RESULT_ERROR` (`SPI_212`): O resultado da atividade está incorreto.
* `ACTIVITY_RESULT_MSG_ERROR` (`SPI_213`): O resultado da atividade recebido na mensagem está incorreto.
* `APPLICATION_CONTEXT_ERROR` (`SPI_214`): O contexto de aplicação necessário é nulo.
* `BAD_CONFIGURATION_ERROR` (`SPI_210`): Widget: Configuração incorreta.
* `BAD_EXTRACTOR_CONFIGURATION_ERROR` (`SPI_200`): Widget: Configuração do extrator incorreta.
* `CAMERA_PERMISSION_DENIED` (`SPI_201`): O usuário recusou as permissões.
* `CANCEL_BY_USER` (`SPI_000`): O usuário cancelou o processo. Inclui `livenessDiagnostic`.
* `CANCEL_LAUNCH` (`SPI_007`): O SDK foi cancelado em geral.
* `COMPONENT_LICENSE_ERROR` (`SPI_002`): A licença do componente não está correta.
* `CONTROL_NOT_INITIALIZED_ERROR` (`SPI_202`): Widget: erro de inicialização.
* `EMPTY_LICENSE` (`SPI_003`): A string da licença está vazia.
* `EXTRACTION_LICENSE_ERROR` (`SPI_203`): Widget: erro de licença.
* `FETCH_DATA_ERROR` (`SPI_216`): Erro ao coletar o resultado.
* `FLOW_ERROR` (`SPI_250`): Erro no processo de flow.
* `FLOW_TRACKING_ERROR` (`SPI_241`): Erro no tracking do flow.
* `FLOW_VIDEO_RECORDING_ERROR` (`SPI_239`): Erro na gravação de vídeo do flow.
* `HARDWARE_ERROR` (`SPI_204`): Widget: erro de hardware.
* `INITIALIZATION_ERROR` (`SPI_004`): Erro de inicialização.
* `INTERNAL_ERROR` (`SPI_235`): Erro interno.
* `MANAGER_NOT_INITIALIZED` (`SPI_217`): Os managers são nulos.
* `NO_DATA_ERROR` (`SPI_005`): Os dados de entrada são nulos.
* `OPERATION_NOT_CREATED` (`SPI_006`): Não há nenhuma operação em andamento.
* `RESOURCES_FILE_NOT_FOUND` (`SPI_206`): O arquivo ZIP de recursos não foi encontrado.
* `SETTINGS_PERMISSION_ERROR` (`SPI_207`): Widget: erro de permissões.
* `TEMPLATE_ERROR` (`SPI_208`): Erro na geração do modelo.
* `SELPHI_TIMEOUT` (`SPI_001`): Timeout no processo. Inclui `livenessDiagnostic`.
* `TRACKING_STEP_ERROR` (`SPI_240`): Erro na etapa de Tracking.
* `UNEXPECTED_CAPTURE_ERROR` (`SPI_209`): Widget: erro na captura.
* `UNKNOWN_ERROR` (`SPI_215`): Erro desconhecido.
* `WIDGET_RESULT_DATA_ERROR` (`SPI_211`): Erro nos dados de saída do Widget.

### Recebimento do resultado correto - *data* <a href="#id-62-recepcion-del-resultado-correcto-data" id="id-62-recepcion-del-resultado-correcto-data"></a>

Quando o resultado é bem-sucedido (`SdkResult.Success`), é obtido um objeto `SelphiResult`.

As imagens são retornadas no formato `SdkImage`. É possível acessar o bitmap por meio de `image.bitmap`.\
Para converter uma imagem em Base64:

```kotlin
Base64.encodeToString(this.toByteArray(), Base64.NO_WRAP)
```

#### Campos retornados

* `templateRaw`\
  Modelo bruto gerado após a extração. Válido para processos de Matching.
* `template`\
  Modelo processado após a extração. Válido para processos de Matching.
* `bestImage`\
  Melhor imagem capturada na resolução original. Esta imagem tem o tamanho original extraído da câmera. Válida para o processo de Liveness.
* `bestImageCropped`\
  Imagem recortada e centralizada no rosto do usuário. É obtida a partir de *bestImage*.
* `logImages`\
  Lista com as 5 melhores imagens (requer `logImages = true`).
* `bestImageTokenized`\
  Melhor imagem criptografada do processo. Válida para o processo de Liveness.
* `livenessDiagnostic`\
  Diagnóstico do teste de vida (`LivenessDiagnostic`).
* `qrData`\
  Conteúdo do Código QR lido (requer `qrMode = true`).
* `statistics`\
  Estatísticas do processo de captura geradas pelo widget.

***

## Informações avançadas <a href="#id-7-informacion-avanzada" id="id-7-informacion-avanzada"></a>

### Controladores adicionais <a href="#id-71-controladores-adicionales" id="id-71-controladores-adicionales"></a>

**SignatureSelphiController**

Funciona de forma equivalente a `SelphiController`, com a diferença de que gera um arquivo de assinatura na plataforma.

**RawTemplateController**

Permite gerar um `RawTemplate` a partir de uma imagem (`Bitmap`).

Exemplo de uso:

```kotlin
val result = SDKController.launch(
    RawTemplateController(SdkImage(image))
)
when (result) {
    is SdkResult.Error -> Napier.d("GenerateRaw: KO - ${result.error}")
    is SdkResult.Success -> result.data
}
```

### Configuração avançada

O comportamento do componente é definido por `SelphiConfigurationData`.

#### Parâmetros disponíveis

* `resourcesPath`\
  Nome do arquivo ZIP de recursos (localizado em `assets`). Exemplo: “resources-selphi-2-0.zip“.

<div align="center"><figure><img src="https://427654043-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUo71Qbj6jZQDavjc0U5X%2Fuploads%2Fgit-blob-15ce71837bf3d4cff1f1509e00d49ef3c005ef31%2Fassets.png?alt=media" alt=""><figcaption></figcaption></figure></div>

* `cropPercent`\
  Porcentagem de recorte do rosto. Quanto maior o número, maior será o recorte do retângulo em relação ao rosto.
* `cropImageDebug`\
  Exibe informações de depuração do recorte.
* `showResultAfterCapture`\
  Exibe uma tela de confirmação após a captura. O usuário pode repetir o processo de captura se a imagem obtida não estiver correta.
* `showTutorial`\
  Ativa a tela de tutorial. Explica de forma intuitiva como a captura é realizada (por padrão, `true`).
* `livenessMode`\
  Modo de detecção de vida (`NONE`, `PASSIVE`, `MOVE`).
  * SelphiFaceLivenessMode.NONE: Indica que o modo de detecção de foto não deve ser ativado nos processos de autenticação.
  * SelphiFaceLivenessMode.PASSIVE: Indica que o teste de vida passivo é realizado no servidor, enviando para esse fim a “BestImage” ou o “TemplateRaw” correspondente.
  * SelphiFaceLivenessMode.MOVE: Indica que o teste de Liveness é ativo, exibindo instruções durante a captura e retornando o resultado correspondente do processo.
* `stabilizationMode`\
  Obriga o usuário a manter a cabeça estável antes da captura, olhando para a frente e sem mover a cabeça.
* `cameraFlashEnabled`\
  Ativa o flash da câmera.
* `fullscreen`\
  Prioriza a exibição em tela cheia.
* `templateRawOptimized`\
  Otimiza o `templateRaw` gerado.
* `qrMode`\
  Ativa a leitura de QR Code antes do processo de autenticação.
* `cameraId`\
  Identificador da câmera a ser usada (`Int`).
* `videoFilename`\
  Caminho absoluto para gravar o vídeo do processo. A aplicação é responsável por solicitar ao telefone as permissões necessárias, caso sejam exigidas.
* `viewsContent`\
  Configuração avançada de visualizações por meio de XML. Esta propriedade não altera o conteúdo do arquivo de recursos.
* `translationsContent`\
  Configuração avançada de traduções.
* `showDiagnostic`\
  Exibe telas de diagnóstico (por padrão, `true`).
* `logImages`\
  Retorna as 5 melhores imagens capturadas.
* `showPreviousTip`\
  Exibe uma tela informativa antes da captura (por padrão, `true`).
* `extractionDuration`\
  Duração do processo de extração (`SHORT`, `MEDIUM`, `LONG`).
* `cameraPreferred`\
  Câmera preferencial (`FRONT`, `BACK`). Por padrão, `FRONT`.
* `vibrationEnabled`\
  Feedback de vibração ao finalizar (por padrão, `false`).
* `moveSuccessfulAttempts`\
  Número de tentativas permitidas para capturas bem-sucedidas (por padrão, 1).
* `moveFailedAttempts`\
  Número de tentativas permitidas para capturas malsucedidas (por padrão, 2).
* `params`\
  Mapa (`HashMap<String, String>`) de parâmetros adicionais que são passados diretamente ao widget.

***

## Personalização do componente <a href="#id-8-personalizacion-del-componente" id="id-8-personalizacion-del-componente"></a>

Além das alterações que podem ser feitas no nível do SDK (explicadas em [Personalização do SDK](https://docs.facephi.com/docs.facephi-pt-br/sdks/sdk-mobile/android-sdk/personalizacion.md)), este componente permite sua própria personalização.

### Textos <a href="#id-81-textos" id="id-81-textos"></a>

Os textos podem ser personalizados substituindo os valores em um arquivo XML de strings.

| **Nome**                                                      | **Valor**                                                                                                         |
| ------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| selphi\_component\_timeout\_title                             | Tempo esgotado                                                                                                    |
| selphi\_component\_timeout\_desc                              | Não foi possível identificar você. Tente novamente                                                                |
| selphi\_component\_internal\_error\_title                     | Ocorreu um problema técnico                                                                                       |
| selphi\_component\_internal\_error\_desc                      | Pedimos desculpas. Não foi possível fazer a captura                                                               |
| selphi\_component\_tip\_message                               | Coloque seu rosto no centro do círculo                                                                            |
| selphi\_component\_tip\_message\_alt                          | Coloque seu rosto no centro do círculo                                                                            |
| selphi\_component\_tip\_anim\_alt                             | Uma pessoa mostra o rosto dentro do círculo, e o aplicativo tira uma foto dela.                                   |
| selphi\_component\_tip\_title                                 | Reconhecimento Facial                                                                                             |
| selphi\_component\_tip\_button                                | COMEÇAR                                                                                                           |
| selphi\_component\_tip\_button\_alt                           | Iniciar captura do rosto                                                                                          |
| selphi\_component\_tip\_move\_message                         | Coloque seu rosto no centro do círculo e siga as instruções                                                       |
| selphi\_component\_tip\_move\_message\_alt                    | Coloque seu rosto no centro do círculo e siga as instruções                                                       |
| selphi\_component\_tip\_move\_anim\_alt                       | Uma pessoa mostra o rosto dentro do círculo, move-o ligeiramente para um lado, e o aplicativo tira uma foto dela. |
| selphi\_component\_tip\_move\_title                           | Reconhecimento Facial                                                                                             |
| selphi\_component\_tip\_move\_button                          | COMEÇAR                                                                                                           |
| selphi\_component\_qr\_tip\_title                             | Escaneie o código QR                                                                                              |
| selphi\_component\_qr\_tip\_message                           | Enquadre o código QR dentro do retângulo                                                                          |
| selphi\_component\_qr\_tip\_anim\_alt                         | Enquadre o código QR dentro do retângulo                                                                          |
| selphi\_component\_qr\_tip\_button                            | Começar                                                                                                           |
| selphi\_component\_tip\_close\_button\_alt                    | Voltar                                                                                                            |
| selphi\_component\_tip\_info\_button\_alt                     | Ver dicas                                                                                                         |
| selphi\_component\_tutorial\_message\_1                       | Coloque seu rosto no centro e olhe diretamente para a câmera.                                                     |
| selphi\_component\_tutorial\_message\_2                       | Retire qualquer elemento que cubra seu rosto.                                                                     |
| Procure um ambiente bem iluminado, sem sombras sobre o rosto. | selphi\_component\_tutorial\_message\_3                                                                           |
| selphi\_component\_tutorial\_1\_anim\_alt                     | A foto é tirada quando a pessoa está no centro.                                                                   |
| selphi\_component\_tutorial\_2\_anim\_alt                     | Uma pessoa tira os óculos de sol e afasta o cabelo dos olhos.                                                     |
| selphi\_component\_tutorial\_3\_anim\_alt                     | A imagem aparece escura e uma pessoa acende a luz.                                                                |
| selphi\_component\_tutorial\_close\_button\_alt               | Voltar ao tutorial anterior                                                                                       |

### Animações <a href="#id-82-animaciones" id="id-82-animaciones"></a>

As animações Lottie podem ser substituídas adicionando os arquivos com o mesmo nome em `res/raw/`.

```
selphi_anim_prev_tip.json
selphi_anim_prev_tip_move.json
selphi_anim_tuto_m_1.json
selphi_anim_tuto_m_2.json
selphi_anim_tuto_m_3.json
```
