> 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 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 realizados, entre outros, os seguintes passos: * Gerenciamento interno de câmeras e permissões. * Assistência guiada durante a captura facial. * Geração de templates biométricos e imagens do usuário. Na seção [Lançamento simplificado](/docs.facephi-pt-br/sdks/sdk-mobile/android-sdk/inicializacion/lanzamiento-simplificado.md) são descritos os passos básicos para a integração do SDK. Nesta página, são detalhadas as informações específicas necessárias para iniciar e configurar este componente. *** ## Dependência 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 orientado a uma funcionalidade concreta. | 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 utilizando uma captura facial | *** ## 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. ```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 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 O resultado do lançamento é retornado como um objeto `SdkResult`, que pode indicar um resultado correto ou um erro. ```kotlin when (response) { is SdkResult.Error -> Napier.d("ERROR - ${response.error}") is SdkResult.Success -> response.data } ``` ### Recepção de erros Os erros serão retornados como um objeto 'SelphiError'. Lista de erros: * SPI\_ACTIVITY\_RESULT\_ERROR: O resultado da atividade está incorreto. * SPI\_ACTIVITY\_RESULT\_MSG\_ERROR: O resultado da atividade recebido na msg está incorreto. * 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\_CANCEL\_LAUNCH: Foi feito um cancelamento geral do SDK. * SPI\_COMPONENT\_LICENSE\_ERROR: A Licença do componente não está correta. * SPI\_CONTROL\_NOT\_INITIALIZATED\_ERROR: Widget: Erro de inicialização. * SPI\_EMPTY\_LICENSE: A String de Licença está vazia. * SPI\_EXTRACTION\_LICENSE\_ERROR: Widget: Erro de Licença. * SPI\_FETCH\_DATA\_ERROR: Erro na coleta do resultado. * SPI\_FLOW\_ERROR: Erro no processo de flow. * SPI\_HARDWARE\_ERROR: Widget: Erro de hardware. * SPI\_INITIALIZATION\_ERROR: Erro de inicialização. * SPI\_MANAGER\_NOT\_INITIALIZED: Os managers são nulos. * SPI\_NO\_DATA\_ERROR: Os dados de entrada são nulos. * SPI\_OPERATION\_NOT\_CREATED: Não há nenhuma operação em andamento. * SPI\_RESOURCES\_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. * 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 do resultado correto - *data* Quando o resultado é correto (`SdkResult.Success`), obtém-se 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 para Base64: ```kotlin Base64.encodeToString(this.toByteArray(), Base64.NO_WRAP) ``` #### Campos retornados * `templateRaw`\ Template bruto gerado após a extração. Válido para processos de Matching. * `template`\ Template 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 obtido da câmera. Válida para o processo de Liveness. * `bestImageCropped`\ Imagem recortada centralizada na face do usuário. É obtida a partir da *bestImage*. * `logImages`\ Lista com as 5 melhores imagens (requer `logImages = true`). * `bestImageTokenized`\ Melhor imagem criptografada do processo. Válida para o processo de Liveness. *** ## Informações avançadas ### Controladores Adicionais **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“.
* `cropPercent`\ Percentual de recorte do rosto. Quanto maior for o número, maior será o recorte do retângulo em relação ao rosto. * `cropImageDebug`\ Mostra informações de depuração do recorte. * `showResultAfterCapture`\ Exibe uma tela de confirmação após a captura. O usuário tem a possibilidade de 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. * `livenessMode`\ Modo de detecção de vida (`NONE`, `PASSIVE`, `MOVE`). * SelphiFaceLivenessMode.NONE: Indica que não deve ser ativado o modo de detecção de foto 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 algumas instruções durante a captura e retornando o resultado correspondente do processo. * `stabilizationMode`\ Exige que o usuário mantenha a cabeça estável antes de capturar, 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 Código QR antes do processo de autenticação. * `videoFilename`\ Caminho absoluto para gravar vídeo do processo. O aplicativo é 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. Essa propriedade não altera o conteúdo do arquivo de recursos. * `showDiagnostic`\ Exibe telas de diagnóstico. * `logImages`\ Retorna as 5 melhores imagens capturadas. * `showPreviousTip`\ Exibe uma tela informativa antes da captura. * `extractionDuration`\ Duração do processo de extração. * `cameraPreferred`\ Câmera preferida (`FRONT`, `BACK`). * `vibrationEnabled`\ Feedback de vibração ao finalizar. * `moveSuccessfulAttempts`\ Tentativas permitidas em capturas corretas (padrão 1). * `moveFailedAttempts`\ Tentativas permitidas em capturas incorretas (padrão 2). *** ## Personalização do componente Além das alterações que podem ser feitas no nível do SDK (explicadas em [Personalização do SDK](/docs.facephi-pt-br/sdks/sdk-mobile/android-sdk/personalizacion.md)), este componente permite sua própria Personalização. ### Textos Os textos podem ser personalizados sobrescrevendo os valores em um arquivo XML de strings. | **Name** | **Value** | | ----------------------------------------------- | -------------------------------------------------------------------------------------------------------- | | selphi\_component\_timeout\_title | Tempo esgotado | | selphi\_component\_timeout\_desc | Não conseguimos identificar você. Tente novamente | | selphi\_component\_internal\_error\_title | Houve 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. | | selphi\_component\_tip\_title | Reconhecimento Facial | | selphi\_component\_tip\_button | COMEÇAR | | selphi\_component\_tip\_button\_alt | Iniciar captura de 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 levemente para um lado e o aplicativo tira uma foto. | | 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 | Posicione o Código QR dentro do quadro | | selphi\_component\_qr\_tip\_anim\_alt | Posicione o Código QR dentro do quadro | | 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 | Remova qualquer elemento que cubra seu rosto. | | selphi\_component\_tutorial\_message\_3 | Procure um ambiente bem iluminado, sem sombras sobre seu rosto. | | 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 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 ```