> 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/ios-sdk/modulos/captura-facial.md).
# Captura facial - Selphi
## Introdução
A Captura Facial é realizada por meio do **Componente Selphi**.
Este componente é responsável por capturar uma selfie do usuário e extrair suas principais características faciais. Inclui os seguintes processos:
* Gerenciamento interno de câmeras e permissões.
* Assistência durante a captura do rosto.
* Geração de templates faciais e da imagem do usuário.
Na seção de [Lançamento simplificado](/docs.facephi-pt-br/sdks/sdk-mobile/ios-sdk/inicializacion/lanzamiento-simplificado.md) são descritos os passos necessários para a integração básica do SDK. Nesta página, é detalhada a informação específica para iniciar este componente.
***
## Dependências
Para evitar conflitos e problemas de compatibilidade, se o projeto contiver versões antigas de bibliotecas Facephi (Widgets), elas devem ser totalmente removidas antes de instalar os componentes de **SDKMobile**.
### CocoaPods
As bibliotecas da Facephi são distribuídas remotamente por meio de gerenciadores de dependências. No iOS, utiliza-se **CocoaPods**. As dependências **obrigatórias** que deverão ter sido instaladas previamente (adicionando-as no arquivo Podfile do projeto) são:
```swift
pod 'FPHISDKMainComponent', '~> $VERSION'
```
Para instalar o componente **Selphi**, adicione a dependência correspondente no `Podfile` do projeto, junto com as dependências obrigatórias do SDK.
```swift
pod 'FPHISDKSelphiComponent', '~> $VERSION'
```
### Swift Package Manager (SPM)
Se você usa **SPM**, certifique-se de que as dependências obrigatórias do SDK estejam instaladas previamente.
```sh
//HTTPS
https://github.com/facephi-clienters/SDK-SdkPackage-SPM.git
//SSH
git@github.com:facephi-clienters/SDK-SdkPackage-SPM.git
```
Para instalar o componente **Selphi**, inclua-o nos módulos do projeto.
```swift
//HTTPS
https://github.com/facephi-clienters/SDK-Selphi_component-SPM.git
//SSH
git@github.com:facephi-clienters/SDK-Selphi_component-SPM.git
```
***
## Permissões
Na aplicação cliente onde os componentes forem integrados, é necessário incorporar o seguinte elemento no arquivo **Info.plist**:
```
É necessário permitir o uso da câmera (Privacy - Camera Usage Description)
```
## Controladores disponíveis
| **Controlador** | **Descrição** |
| ------------------------- | ------------------------------------------------------------ |
| SelphiController | Controlador principal de Reconhecimento Facial |
| RawTemplateController | Controlador para gerar um RawTemplate a partir de uma imagem |
| SignatureSelphiController | Controlador para assinar um processo com uma Captura |
***
## Lançamento simplificado
Uma vez iniciado o SDK e criada uma nova operação, o componente pode ser iniciado utilizando qualquer um de seus controladores disponíveis, conforme a funcionalidade necessária.
```swift
let controller = SelphiController(data: selphiConfigurationData, output: { sdkResult in
// Do whatever with the result
...
}, viewController: viewController)
SDKController.shared.launch(controller: controller)
```
***
## Recebimento do resultado
A execução do componente retorna um resultado em formato `SdkResult`, que inclui:
* `selphiResult.finishStatus`
* `selphiResult.errorType`
* `selphiResult.data`
### Recebimento de erros
*finishStatus*: Indica se a operação foi concluída corretamente. Valores possíveis:
FinishStatus.STATUS_OK
FinishStatus.STATUS_ERROR
*errorType*: Erros próprios do widget.
No iOS, `errorType` é um `ErrorType` do SDK. Em um timeout, o enum Swift pode ser `.SDK_TIMEOUT`, `.SELPHI_TIMEOUT(LivenessDiagnostic?)` ou, se for interpolado diretamente, exibir nomes como `SDK_TIMEOUT` ou `SELPHI_TIMEOUT`. No iOS não existe um caso `TIMEOUT` sem prefixo.
Para serializar o erro deve ser usado:
```swift
sdkResult.errorType.toString(addComponentPrefix: "SPI_")
```
Isso retorna `SPI_TIMEOUT` tanto se o enum for `SDK_TIMEOUT` quanto `SELPHI_TIMEOUT`.
#### Comportamento em timeout
Em um timeout, o resultado tem:
* `finishStatus`: `STATUS_ERROR`
* `data`: `nil` (não é retornado um `SelphiResult`)
* `errorType`: `.SDK_TIMEOUT` ou `.SELPHI_TIMEOUT(LivenessDiagnostic?)`
O caso `SELPHI_TIMEOUT` mantém, quando disponível, o diagnóstico de Liveness do Widget. Essas informações **não** faz parte de `data`; só pode ser lida no iOS por meio de pattern matching sobre `errorType`:
```swift
if case .SELPHI_TIMEOUT(let diagnostic) = sdkResult.errorType {
// diagnostic: LivenessDiagnostic? (puede ser nil)
}
```
Se o timeout chegar como `SDK_TIMEOUT`, não inclui diagnóstico de Liveness. Se chegar como `SELPHI_TIMEOUT`, o diagnóstico associado pode ser `nil` quando o timeout ocorre pela via de erro do widget (`FWETimeout`) em vez do delegate `extractionTimeout()`.
Para integrações iOS nativas, o valor serializado deve ser tratado como `SPI_TIMEOUT` (inclui tanto `SDK_TIMEOUT` quanto `SELPHI_TIMEOUT` do enum).
Se `showDiagnostic` está ativo, o callback `output` não é invocado no instante do timeout: primeiro é exibida a tela de diagnóstico e o resultado é entregue ao clicar em fechar. Com `showDiagnostic` desativado, o callback é executado imediatamente.
A lista a seguir inclui erros do contrato multiplataforma; alguns não ocorrem no iOS.
* SPI\_APPLICATION\_CONTEXT\_ERROR: O contexto de aplicação necessário é nulo.
* SPI\_BAD\_EXTRACTOR\_CONFIGURATION\_ERROR: Widget: Configuração incorreta do extrator.
* SPI\_CAMERA\_PERMISSION\_DENIED: O usuário rejeitou as permissões.
* SPI\_CANCEL\_BY\_USER: O usuário cancelou o processo.
* SPI\_COMPONENT\_LICENSE\_ERROR: A Licença do componente não está correta.
* SPI\_EMPTY\_LICENSE: A String de Licença está vazia.
* SPI\_EXTRACTION\_LICENSE\_ERROR: Widget: Erro de Licença.
* SPI\_ACTIVE\_LIVENESS\_ERROR: Widget: Erro no processo de Liveness Ativo.
* SPI\_HARDWARE\_ERROR: Widget: Erro de hardware.
* SPI\_INITIALIZATION\_ERROR: Erro de Inicialização.
* SPI\_MANAGER\_NOT\_INITIALIZED: Os managers estão nulos.
* SPI\_NO\_DATA\_ERROR: Os dados de entrada estão nulos.
* SPI\_OPERATION\_NOT\_CREATED: Não há nenhuma operação em andamento.
* SPI\_RESOURCES\_FILE\_NOT\_FOUND: O zip de recursos não foi encontrado.
* SPI\_SETTINGS\_PERMISSION\_ERROR: Widget: Erro de permissões.
* SPI\_TEMPLATE\_ERROR:
* SPI\_TIMEOUT: Timeout no processo (`SDK_TIMEOUT` ou `SELPHI_TIMEOUT` do enum).
* SPI\_UNEXPECTED\_CAPTURE\_ERROR: Widget: Erro na captura.
* SPI\_UNKNOWN\_ERROR: Erro desconhecido.
* SPI\_WIDGET\_RESULT\_DATA\_ERROR: Erro nos dados de saída do Widget.
### Recebimento de execução bem-sucedida - data
O conteúdo do campo `data` depende do componente iniciado. Em **Selphi**, pode incluir:
* `template`\
Template facial gerado após a extração. Válido para **autenticação**.
* `templateRaw`\
Template facial bruto gerado após o processo de extração. Válido para **autenticação**.
* `bestImageData`\
Melhor imagem capturada, em formato de array de bytes e tamanho original. Válido para **liveness**.
* `bestImageCroppedData`\
Imagem recortada centralizada no rosto. Recomendado como avatar do usuário.
* `qrData`\
Informações obtidas da leitura de QR no formato `String`.
* `bestImageTokenized`\
Imagem criptografada resultante do processo. Válida para **liveness**.
***
## Informações avançadas
### Controladores adicionais
**SignatureSelphiController**\
Funciona da mesma forma que `SelphiController`, mas gera um arquivo de assinatura do processo.
**RawTemplateController**\
Permite gerar um `RawTemplate` a partir de uma imagem (`bitmap`).
Exemplo de uso:
```swift
let controller = RawTemplateController(
base64: bestImageData.base64EncodedString(),
output: { sdkResult in
guard let result = sdkResult.data else {return}
print(result.base64EncodedString())
})
SDKController.shared.launchMethod(controller: controller)
```
ou
```swift
let controller = RawTemplateController(
data: bestImageData,
output: { sdkResult in
guard let result = sdkResult.data else {return}
print(result.base64EncodedString())
})
SDKController.shared.launchMethod(controller: controller)
```
### Configuração avançada
Para lançar o componente, deve-se criar um objeto `SelphiConfigurationData`.\
Este objeto define o comportamento e a configuração do componente.
#### Parâmetros disponíveis
* `resourcesPath`\
Caminho relativo à pasta `Resources` onde se encontra o arquivo de recursos.
* `showTutorial`\
Exibe o tutorial antes da captura.
* `showDiagnostic`\
Exibe uma tela de diagnóstico em caso de erro ou permissões insuficientes.
* `showResultAfterCapture`\
Exibe a imagem capturada e permite repetir o processo.
* `depuração`\
Ativa o modo de depuração.
* `fullscreen`\
Prioriza a visualização em tela cheia.
* `cropPercent`\
Porcentagem de recorte do rosto.
* `livenessMode`\
Modo de detecção de vida:
* `NONE`
* `PASSIVE`
* `MOVE`
* `stabilizationMode`\
Obriga o usuário a manter a cabeça estável antes de iniciar o processo.
* `templateRawOptimized`\
Indica se o `templateRaw` deve ser otimizado.
* `qrMode`\
Ativa ou desativa a leitura de QR.
* `videoFilename`\
Caminho absoluto para gravar o vídeo do processo.
* `cameraFlashEnabled`\
Ativa o flash da câmera.
* `translationsContent`\
Configuração avançada de textos por meio de XML.
* `viewsContent`\
Configuração avançada de views por meio de XML.
* `vibrationEnabled`\
Ativa a vibração em erros e em resultados corretos.
* `animateDismiss`\
Indica se o fechamento do SDK ao finalizar o processo é animado. Disponível desde **2.8.1**.
### Personalização do componente
Além das mudanças que podem ser feitas no nível de SDK (explicadas em *Personalização do SDK*), este componente permite sua própria Personalização.
#### Textos
Os textos são personalizados sobrescrevendo chaves em `Localizable.strings`, dentro da pasta `Resources`.
As chaves com sufixo `_alt` são utilizados para acessibilidade (VoiceOver).
Exemplo de modificação do texto **COMEÇAR** para `es`:
É preciso ir para o arquivo **Localizable.strings** da pasta **es.lproj** (se esta pasta não existir, será necessário criá-la).
```
"selphi_component_tip_button_message" = "EMPEZAR";
```
Se uma chave não estiver definida, será usado o valor padrão.
| **Name** | **Value** |
| ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| selphi\_component\_tutorial\_message\_1 | Coloque seu rosto no centro e olhe diretamente para a câmera. |
| selphi\_component\_tutorial\_message\_2 | Remova qualquer objeto que cubra seu rosto. |
| selphi\_component\_tutorial\_message\_3 | Procure um ambiente bem iluminado, sem sombras sobre o seu rosto. |
| selphi\_component\_tip\_message | Coloque seu rosto no centro do círculo |
| selphi\_component\_tip\_title | Reconhecimento Facial |
| selphi\_component\_tip\_button | COMEÇAR |
| selphi\_component\_tip\_button\_alt | Iniciar captura do rosto |
| selphi\_component\_tip\_anim\_alt | Uma pessoa mostra o rosto dentro do círculo e o aplicativo tira uma foto dela. |
| selphi\_component\_tip\_move\_anim\_alt | Animação de uma tela de celular com a câmera frontal ativada. No centro da tela aparece um círculo. Uma pessoa mostra o rosto dentro do círculo, move-o levemente para um lado e o aplicativo tira uma foto dela. |
| 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\_tip\_move\_message | Coloque seu rosto no centro do círculo e siga as instruções. |
| selphi\_component\_timeout\_title | Tempo esgotado |
| selphi\_component\_timeout\_desc | Não conseguimos identificá-lo. Tente novamente |
#### Animações
As animações da dica prévia e dos tutoriais são **Lottie (.json)**.
Para substituí-las:
* Adicione o arquivo na pasta `Resources`.
* Mantenha exatamente o mesmo nome do arquivo.
Se não forem substituídas, as animações padrão serão exibidas.
| Nome | Função |
|---|
| selphi_anim_tip | Animação LivenessMode: None, Passive |
| selphi_anim_tip_move | Animação LivenessMode: Move |
| selphi_anim_tuto_1 | Primeira animação do tutorial |
| selphi_anim_tuto_2 | Segunda animação do tutorial |
| selphi_anim_tuto_3 | Terceira animação do tutorial |