Face Liveness (DESCONTINUADO)

O FaceLiveness para iOS traz tecnologia de ponta de verificação facial ao vivo e autenticação por impressão digital para seus aplicativos iOS. Ao aproveitar o SDK iOS do iProov Biometrics e FingerprintPro S

Versão atual

Nome	Versão
FaceLiveness	7.4.0

Requisitos

Informações de implantação	Versão
Alvo do iOS	15.0+
Xcode	16.2+
Swift	5.5+

• Um válido Token móvel da Caf.
• CocoaPods instalados

Dependências do SDK

O FaceLiveness utiliza dois SDKs externos principais, gerenciados por meio do CocoaPods para uma integração simples:

SDK	Versão
iProov	13.1.0
FingerprintPro	2.7.0

• iProov Biometrics iOS: Facilita a integração da tecnologia de verificação facial ao vivo.
• FingerprintPro iOS: Adiciona recursos de autenticação por impressão digital, aprimorando os recursos de segurança do seu app.

Permissões em tempo de execução

No info.plist arquivo, adicione as permissões abaixo:

Permissão	Motivo	Obrigatório
Privacidade - Descrição de Uso da Câmera	Captura da selfie em políticas de verificação facial ao vivo	Sim

Instalação

CocoaPods

No seu Podfile, especifique a referência ao nosso framework. Substituindo <version> pela atual versão:

target 'your-project' do
  use_frameworks!

  pod 'FaceLiveness', '<version>'

Para versões anteriores a FaceLiveness 4.0.0, você também deve incluir estas fontes adicionais no Podfile:

source 'https://github.com/combateafraude/iOS.git'
source 'https://cdn.cocoapods.org/'

SPM

1. Abra seu projeto no Xcode.
2. Navegue até Arquivo > Adicionar Pacotes.
3. Na barra de pesquisa, cole a URL deste repositório:

https://github.com/combateafraude/FaceLiveness.git

Instanciando o SDK

Primeiro, instancie um objeto do tipo FaceLivenessSDK. Este objeto é para você configurar todas as suas regras de negócio:

class FaceLivenessViewController: UIViewController {
    var faceLiveness: FaceLivenessSDK?

    func setupFaceLiveness() {
        faceLiveness = FaceLivenessSDK.Build()
        // a tabela abaixo mostra todas as opções de configuração do SDK
        .build()
        faceLiveness?.delegate = self
    }

    func startFaceLiveness() {
        faceLiveness?.startSDK(viewController: self, mobileToken:"yourMobileToken", personId: "personId")
    }
}

Opções do FaceLiveness

Parâmetro	Obrigatório	Valor Padrão
.startSDK(viewController: UIViewController, mobileToken: String, personId: String) token: Token de uso associado à sua conta CAF personId: Identificador do usuário que realizará a verificação de vivacidade facial. Recomenda-se usar o documento de identificação do usuário neste campo, como o CPF (documento de identificação brasileiro), mas pode ser qualquer outro valor.
.setStage(stage: CAFStage) Usado para redirecionar o SDK para o ambiente desejado na API da caf. Ele possui as seguintes opções: .beta ou .prod.	Não	.prod
.setFilter(filter: Filter) Define o filtro da câmera aplicado à prévia da câmera. Ele possui as seguintes opções: .natural ou .lineDrawing	Não	.lineDrawing
.setLoadingScreen(withLoading: Bool) Este parâmetro booleano determina se a tela de carregamento será implementada por meio de um delegate ou se você usará a tela padrão. Se definido como 'true', a tela de carregamento será uma tela padrão do SDK. No caso de 'false', você deve usar a sessão 'LoadingScreen' e implementar os delegates.	Não	false
.setImageUrlExpirationTime(time: Time) Use para alterar o tempo padrão de expiração da URL da imagem para recuperar a captura da varredura. Ele possui as seguintes opções: .threeHours, .thirtyDays ou .thirtyMin.	Não	30 min
.setAuthenticationBaseUrl(authBaseUrl: String) Permite o uso de um proxy reverso para executar as autenticações do SDK. Define a URL base para autenticação; o protocolo deve ser HTTPS. Adiciona uma barra no final, se estiver ausente.	Não	URL padrão da Caf
.setFaceLivenessBaseUrl(livenessBaseUrl: String) Permite o uso de um proxy reverso para executar verificações de liveness facial. Define a URL base; o protocolo deve ser WSS. Adiciona uma barra no final, se estiver ausente. Requer certificados definidos por .setCertificates por segurança.	Não	URL padrão da iProov
.setCertificates(certificates: [String]) Define os protocolos codificados em Base64 do SHA256 para comunicação segura em implementações de proxy reverso. Obrigatório ao usar URLs personalizadas para autenticação ou verificações de liveness facial.	Não	Lista vazia
.setCustomLocalization(named: String?) Este método permite que você especifique um nome de recurso de localização personalizado para o módulo iProov. Quando um nome é fornecido, o SDK carregará o arquivo de localização correspondente em vez do pacote de recursos padrão. Para mais detalhes sobre o formato dos arquivos de localização e a integração, consulte a documentação de localização da iProov.	Não	nil

Proxy reverso

Para configurar as definições de proxy reverso, siga estas instruções:

Proxy reverso do FaceLiveness

• Configure seu proxy para se comunicar com a URL correspondente ao CAFStage que você está usando:

  • CAFStage.PROD -> https://api.public.caf.io/v1/sdks/faces/
  • CAFStage.BETA -> https://api.public.beta.caf.io/v1/sdks/faces/
  • CAFStage.DEV -> https://api.public.dev.caf.io/v1/sdks/faces/
• Use o método .setFaceLivenessBaseUrl para definir a URL na qual o FaceLiveness deve ser executado.

  • O protocolo da URL deve ser WSS.
• Use o .setCertificates método para definir os certificados, que devem ser o hash SHA-256 do Subject Public Key Info do certificado codificado em base64.

  • Os certificados são necessários para que o proxy reverso do FaceLiveness funcione corretamente.

    faceLiveness = FaceLivenessSDK.Build()
    .setFaceLivenessBaseUrl("wss://my.proxy.io/ws/")
    .setCertificates(certificates: [
        "4d69f16113bed7d62ca56feb68d32a0fcb7293d3960=",
        "50f71c5dda30741ee4be1ac378e12539b0d1d511f99=",
        "9f85e26c1ae41f7ac97adc4099be7f2a40759510ab9="
    ])
    .build()

Proxy reverso de autenticação

• Configure seu proxy para se comunicar com `wss://us.rp.secure.iproov.me/ws´.
• Use o método .setAuthenticationBaseUrl para definir a URL na qual as solicitações de autorização devem ser executadas.

  • O protocolo da URL deve ser HTTPS.

    faceLiveness = FaceLivenessSDK.Build()
        .setAuthenticationBaseUrl("https://my.proxy.io/v1/faces/")
        .build();

Obtendo os Resultados

Você deve implementar a FaceLivenessDelegate classe para obter os resultados do SDK. Para isso, você deve fornecer um UIViewController à sua instância do SDK:

faceLiveness?.delegate = self

Implementação do Delegate

O delegate abaixo deve ser implementado para tratar os resultados do SDK. Ao implementar a extensão do delegate, você terá acesso a um objeto dependendo do tipo de retorno. Em cada caso, o objeto carrega informações diferentes.

extension FaceLivenessViewController: FaceLivenessDelegate {
    func didFinishLiveness(with livenessResult: FaceLiveness.LivenessResult) {
        //tratar o resultado de sucesso
    }
    
    func didFinishWithError(with sdkError: FaceLiveness.SDKError) {
        //tratar o resultado de erro
    }

    func didFinishWithFailure(with sdkFailure: FaceLiveness.SDKFailure) {
        //tratar resultado de falha
    }
    
    func didFinishWithCancelled() {
        //tratar quando o usuário fecha o SDK
    }
    
    func onConnectionChanged(_ state: FaceLiveness.LivenessState) {
        //handle loading screen display
    }
}

Tela de Carregamento

Para criar uma tela de carregamento durante os processos de validação do SDK, você precisa implementar uma view com a tela de carregamento e exibir essa tela no onConnectionChanged(_ state: FaceLiveness.LivenessState) delegate function.

estado	descrição	tela de carregamento
fechado	O SDK foi fechado	fechar
conectando	O SDK está se conectando ao servidor de liveness	exibir
conectado	O SDK foi conectado ao servidor de liveness	fechar

Na implementação do SDK, é necessário adicionar a view à pilha de views usando o código a seguir. Isso torna a view visível.

  view.addSubview(loadingHUD)

Esta view deve ser adicionada antes do Builder de cada SDK.

Resultados do SDK

Casos de sucesso

Ao final de uma execução bem-sucedida, você receberá um objeto do tipo LivenessResult. Esse objeto contém uma signedResponse propriedade contendo um token JWT com o resultado da execução. Esse token deve ser descriptografado para obter os detalhes dos resultados da execução.

  livenessResult.signedResponse

LivenessResult (Struct)

Propriedade	Descrição
signedResponse: String?	Resposta assinada do servidor da CAF confirmando que a selfie capturada tem um rosto real. Este parâmetro é usado para obter uma camada extra de segurança, verificando se a assinatura da resposta não está quebrada ou se foi causada por interceptação da solicitação. Se estiver quebrada, há uma forte indicação de interceptação da solicitação.

Parâmetros SignedResponse

Dentro de signedResponse, o parâmetro isAlive define a execução do liveness, em que true é aprovado e false é rejeitado (Caso de falha será retornado).

Evento	Descrição
requestId	Identificador da solicitação.
isAlive	Validação de uma pessoa viva, identifica se o usuário passou com sucesso ou não.
token	Token da solicitação.
userId	Identificador do usuário fornecido para a solicitação.
imageUrl	Link temporário para a imagem, gerado pela nossa API.
personId	Identificador do usuário fornecido para o SDK.
sdkVersion	Versão do Sdk em uso.
iat	Expiração do token.

O isAlive parâmetro é MUITO IMPORTANTE, pois determina se o processo de validação prossegue ou é interrompido. Quando isAlive: true, o usuário recebe permissão para continuar sua jornada; por outro lado, se isAlive: false, o usuário é considerado inválido e o acesso a etapas posteriores da jornada deve ser negado. Esse parâmetro desempenha um papel fundamental na orientação do fluxo das operações.

Casos de erro

Em caso de erros de execução, você receberá um objeto do tipo SDKError. Esse objeto engloba um enum contendo o errorType, e um descrição.

SDKError (Struct)

Propriedade	Descrição
errorType ErrorType?	Retorna o tipo do erro.
description String?	Descrição do erro.

ErrorType (Enum)

ErrorType	Descrição
dispositivoSemSuporte	Indica que o hardware ou software do dispositivo não atende aos requisitos mínimos para reconhecimento facial.
permissãoDaCâmera	Indica que o dispositivo não tem permissão para acessar a câmera, seja por negação do usuário ou por permissões ausentes no app.
exceçãoDeRede	Indica um erro relacionado à rede, como ausência de conexão com a internet, timeouts do servidor ou congestionamento de rede.
exceçãoDeToken	Indica um problema com o token de autenticação fornecido, como ser inválido, expirado ou não ter as permissões necessárias.
exceçãoDoServidor	Indica um erro do lado do servidor, que pode incluir configurações incorretas do servidor, falhas de processamento ou interrupções no serviço.
exceçãoDeCertificado	Indica que não há certificados válidos para a URL do proxy, impedindo a comunicação segura.
exceçãoDeCapturaJáAtiva	Indica que uma captura de reconhecimento facial já está em andamento. Uma nova captura não pode ser iniciada até que a atual seja concluída.
exceçãoDeErroInesperado	Indica que ocorreu um erro irrecuperável durante a transação de reconhecimento facial.
exceçãoDeTempoEsgotadoDoUsuário	Indica um erro do lado do servidor, que pode incluir configurações incorretas do servidor, falhas de processamento ou interrupções no serviço.
exceçãoDeImagemNãoEncontrada	Indica que um usuário demorou demais para concluir a solicitação.
exceçãoDeMuitasSolicitações	Indica que o servidor recebeu mais solicitações do que está preparado para processar.

Casos de falha

Em caso de falhas de execução, você receberá um objeto do tipo SDKFailure. Esse objeto engloba um enum contendo o failureType, descrição e um signedResponse.

SDKFailure (Class)

Propriedade	Descrição
signedResponse String?	Resposta assinada do servidor da CAF confirmando que a selfie capturada tem um rosto real. Este parâmetro é usado para obter uma camada extra de segurança, verificando se a assinatura da resposta não está quebrada ou se foi causada por interceptação da solicitação. Se estiver quebrada, há uma forte indicação de interceptação da solicitação.
failureType String?	Em caso de uma falha específica, retorne o tipo do erro.
failureMessage String?	Em caso de uma falha específica, retorne as instruções para evitar o erro.

Tipos de falha

Todos os motivos de falha são retornados exclusivamente nos fluxos de validação de liveness GPA. Nos fluxos de LA (Liveness Assurance), qualquer falha sempre retornará o erro genérico UNKNOWN, independentemente do problema específico encontrado.

FailureType	Descrição	LA	GPA
unknown	Tente novamente.	✅	✅
movimentoExcessivo	Fique parado.	❌	✅
muitoBrilhante	Vá para um lugar mais escuro.	❌	✅
muitoEscuro	Vá para um lugar mais claro.	❌	✅
rostoDesalinhado	Mantenha o rosto dentro do oval.	❌	✅
olhosFechados	Mantenha os olhos abertos.	❌	✅
rostoMuitoLonge	Aproxime o rosto da tela.	❌	✅
rostoMuitoPerto	Afaste o rosto da tela.	❌	✅
sunglasses	Remova os óculos de sol.	❌	✅
rostoObstruído	Remova qualquer cobertura facial.	❌	✅
múltiplosRostos	Certifique-se de que apenas uma pessoa esteja visível.	❌	✅

⚠️ Configuração do Sandbox para iOS

Se você encontrar o erro relacionado a Sandbox: rsync.samba deny file-write-create ao usar este SDK em um projeto iOS, siga as etapas abaixo:

1. No Xcode, vá para seu projeto na aba Build Settings.
2. No campo de busca, procure por sandbox.
3. Localize a opção User Script Sandboxing.
4. Altere o valor para No.