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 realizadas, entre outras, as seguintes etapas:

• 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 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 é:

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

Uma vez iniciado o SDK e criada uma nova operação, o componente pode ser lançado utilizando qualquer um de seus controladores.

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 lançar o componente, é necessário criar um objeto SelphiConfigurationData, que define o comportamento do widget.

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 da execução é retornado como um objeto SdkResult, que pode indicar um resultado correto ou um erro.

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

Recebimento de erros

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

Lista de erros:

• SPI_ACTIVITY_RESULT_ERROR: O resultado da activity está incorreto.

• SPI_ACTIVITY_RESULT_MSG_ERROR: O resultado da activity recebido no 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 da 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 curso.

• SPI_RESOURCES_NOT_FOUND: Não foi encontrado o zip de recursos.

• 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.

Recepção 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:

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 possui o tamanho original extraído da câmera. Válida para o processo de liveness.

• bestImageCropped Imagem recortada centralizada no rosto 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:

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 meio de SelphiConfigurationData.

Parâmetros disponíveis

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

• 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 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 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 correspondente “TemplateRaw”.

  • SelphiFaceLivenessMode.MOVE: Indica que o teste de liveness é ativo, exibindo instruções durante a captura e retornando o resultado correspondente do processo.

• stabilizationMode Força o usuário a manter a cabeça estável antes de capturar, olhando para frente e sem mover a cabeça.

• cameraFlashEnabled Ativa o flash da câmera.

• fullscreen Prioriza a exibição em tela cheia.

• templateRawOptimized O templateRaw gerado.

• qrMode Ativa a leitura de QR antes do processo de autenticação.

• videoFilename Caminho absoluto para gravar o vídeo do processo. O aplicativo é responsável por solicitar ao telefone as permissões necessárias, caso sejam necessárias.

• viewsContent Configuração avançada de visualizações por meio de XML. Esta 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 Repetições permitidas em capturas corretas (padrão 1).

• moveFailedAttempts Repetições 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), este componente permite sua própria personalização.

Textos

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

Nome	Valor
selphi_component_timeout_title	Tempo esgotado
selphi_component_timeout_desc	Não conseguimos identificá-lo. 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 seu 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	Começar 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 seu rosto dentro do círculo, o move 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	Aponte o código QR dentro da caixa
selphi_component_qr_tip_anim_alt	Aponte o código QR dentro da caixa
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 escuros 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