Captura facial - Selphi

Este componente precisa de uma versão mínima do iOS9

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

  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.

  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.

//HTTPS
https://github.com/facephi-clienters/SDK-SdkPackage-SPM.git
//SSH
[email protected]:facephi-clienters/SDK-SdkPackage-SPM.git

Para instalar o componente Selphi, inclua-o nos módulos do projeto.

//HTTPS
https://github.com/facephi-clienters/SDK-Selphi_component-SPM.git
//SSH
[email protected]: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.

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:

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:

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:

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

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