Face Liveness (DESCONTINUADO)

Permite integrar tecnologia de verificação facial ao vivo e autenticação por impressão digital em seus aplicativos Android, oferecendo uma forma simples e segura de autenticar usuários.

Versão atual

Nome	Versão
FaceLiveness	5.2.0

Requisitos

• Versão mínima da API do Android SDK: minSdk 26 (Android 8 Oreo)
• Versão da API do Android SDK para compilação: compileSdk 34

Para publicar seu app na Google Play Store, você precisa preencher um formulário de segurança de dados. Como integramos com o SDK FingerPrintJS, você precisará fornecer as seguintes informações:

Pergunta no formulário de segurança de dados do Google Play Console	Resposta
Seu app coleta ou compartilha algum dos tipos de dados do usuário exigidos?	Sim.
Que tipo de dado é coletado?	Identificadores do dispositivo ou outros identificadores.
Esse dado é coletado, compartilhado ou ambos?	Coletado.
Esse dado é processado de forma efêmera?	Sim.
Por que esses dados do usuário são coletados?	Prevenção a fraudes, segurança e conformidade.

nome da versão e código da versão são obrigatórios para que o SDK funcione corretamente.

Dependências do SDK

O FaceLiveness utiliza os seguintes SDKs externos:

SDK	Versão
iProov Biometrics Android	11.1.0
Fingerprint Pro Android	2.7.0

• iProov Biometrics Android: Permite a integração da tecnologia de verificação facial ao vivo.
• Fingerprint Pro Android: Fornece recursos de autenticação por impressão digital para aprimorar os recursos de segurança do seu app.

Essas dependências são facilmente gerenciadas pelo Gradle e vêm incluídas no SDK para facilitar a instalação.

Permissões em tempo de execução

Permissão	Motivo	Obrigatório
CÂMERA	Captura da selfie em políticas de verificação facial ao vivo	Sim

Instalação

Se a sua versão do Gradle for anterior à 7, adicione estas linhas ao seu build.gradle.

allprojects {
  repositories {
  ...
  maven { url 'https://repo.combateafraude.com/android/release' }
  maven { url 'https://raw.githubusercontent.com/iProov/android/master/maven/' }
  maven { url 'https://maven.fpregistry.io/releases' }
  maven { url 'https://jitpack.io' }

}}

Se a sua versão do Gradle for 7 ou mais recente, adicione estas linhas ao seu settings.gradle.

dependencyResolutionManagement {
    repositories {
        ...
        maven { url 'https://repo.combateafraude.com/android/release' }
        maven { url 'https://raw.githubusercontent.com/iProov/android/master/maven/' }
        maven { url 'https://maven.fpregistry.io/releases' }
        maven { url 'https://jitpack.io' }
    }
}

Adicione suporte ao Java 8 ao seu build.gradle arquivo. Pule esta etapa se o Java 8 estiver ativado.

android {
    ...
    compileOptions {
        sourceCompatibility JavaVersion.VERSION_1_8
        targetCompatibility JavaVersion.VERSION_1_8
    }
}

Adicione a versão do SDK à seção de dependências no seu build.gradle arquivo

dependencies {
    implementation 'io.caf.sdk:new-face-liveness:{version}'
}

Instanciando o SDK

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

FaceLiveness faceLiveness = new FaceLiveness.Builder(String mobileToken)
    //veja a tabela abaixo
    .build();

Método builder

Parâmetro	Obrigatório
String mobileToken Token de uso associado à sua conta Identity (veja como obtê-lo aqui).	Sim
.setStage(CAFStage stage) Usado para redirecionar o SDK para o estágio desejado na API da caf. O método recebe como parâmetro um enum CafStage para selecionar o ambiente: CAFStage.PROD definir ambiente de produção. CAFStage.BETA definir ambiente beta.	Não. O padrão é CAFStage.PROD
.setFilter(Filter filter) Usado para alterar o filtro do SDK, que tem as seguintes opções: Filter.NATURAL Filter.LINE_DRAWING	Não, o padrão é LINE_DRAWING
.setEnableScreenshots(boolean bool) Usado para habilitar capturas de tela durante a varredura do SDK. Desativado por padrão por motivos de segurança.	Não, o padrão é false
.setLoadingScreen(boolean bool) Usado para ativar uma barra de progresso de carregamento padrão durante os eventos de carregamento. Você pode definir sua própria tela de carregamento personalizada em vez disso, usando o onLoading método abaixo.	Não, o padrão é false
.setImageUrlExpirationTime(Time time) Usado para personalizar o tempo de expiração da URL da imagem, que tem as seguintes opções: Time.THREE_HOURS Time.THIRTY_DAYS	Não, o padrão é null
.setFaceLivenessBaseUrl(String baseURL) Usado para habilitar o uso de proxy reverso para executar a verificação de liveness facial. Se usado, os certificados devem ser definidos com o método setCertificates.	Não, o padrão é a URL original da IProov
.setCertificates(String[] certificates) Usado para definir certificados fixados para a implementação de proxy reverso.	Não, o padrão é uma lista vazia
.setAuthenticationBaseUrl(String baseURL) Usado para habilitar o uso de proxy reverso para executar as autenticações do SDK.	Não, o padrão é a URL original da Caf

Proxy reverso

Para implementar as configurações de proxy reverso, você deve seguir estas instruções:

Proxy reverso do FaceLiveness

• Configure seu proxy para se comunicar com `wss://us.rp.secure.iproov.me/ws´.
• 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 método .setCertificates método para definir os certificados, que são o hash SHA-256 codificado em base64 da Subject Public Key Info do certificado.

  • Os certificados são necessários para fazer o proxy reverso do FaceLiveness funcionar.

FaceLiveness faceLiveness = new FaceLiveness.Builder(usersToken)
        .setFaceLivenessBaseUrl("wss://my.proxy.io/ws/")
        .setCertificates(new String[]{
                "4d69f16113bed7d62ca56feb68d32a0fcb7293d3960=",
                "50f71c5dda30741ee4be1ac378e12539b0d1d511f99=",
                "9f85e26c1ae41f7ac97adc4099be7f2a40759510ab9="
        })
        .build();

Proxy reverso de autenticação

• Defina seu proxy para se comunicar com a URL que corresponde 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 .setAuthenticationBaseUrl para definir a URL na qual as solicitações de autorização devem ser executadas.

  • O protocolo da URL deve ser HTTPS.

FaceLiveness faceLiveness = new FaceLiveness.Builder(usersToken)
        .setAuthenticationBaseUrl("https://my.proxy.io/v1/faces/")
        .build();

Consultando uma política

Para autenticar um usuário, use o .startSDK() método. Você deve inserir o personId, o Context da sua app e um VerifyLivenessListener objeto.

Parâmetros

Parâmetro	Obrigatório
String 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, mas pode ser qualquer outro valor.	Sim
Context context Context do seu app	Sim
VerifyLivenessListener listener Listener de resposta	Sim

Exemplo

faceLiveness.startSDK(Context context, String personId, new VerifyLivenessListener() {
    @Override
    public void onSuccess(FaceLivenessResult result) {

    }

    @Override
    public void onFailure(FaceLivenessFailureResult result) {

    }

    @Override
    public void onError(SDKError sdkerror) {

    }

    @Override
    public void onCancel() {

    }

    @Override
    public void onLoading() {

    }

    @Override
    public void onLoaded() {

    }
});

opções de VerifyLivenessListener

Método	Descrição
onSuccess	A execução terminou com sucesso, você deve usar o faceLivenessResult e verificar os resultados do SDK.
onFailure	A execução terminou com falha, você deve usar o faceLivenessFailureResult e verificar os resultados do SDK.
onError	A execução terminou com erro, você deve usar o sdkFailure e verificar os resultados de erro do SDK.
onCancel	A execução foi cancelada pelo usuário.
onLoading	O SDK está carregando; você pode usar este método para definir uma ação no seu app, por exemplo, um carregamento.
onLoaded	O SDK não está mais carregando; você pode usar este método para definir uma ação no seu app, por exemplo, você pode interromper seu carregamento anterior.

Resultados do SDK

Casos de sucesso

Ao final de uma execução bem-sucedida, você receberá um objeto do tipo FaceLivenessResult. 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.getSignedResponse()

FaceLivenessResult (Classe)

Propriedade	Descrição
String signedResponse	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 (Classe)

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

ErrorType (classe Enum)

Error	Descrição
CAMERA_PERMISSION	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.
NETWORK_EXCEPTION	Indica um erro relacionado à rede, como ausência de conexão com a internet, timeouts do servidor ou congestionamento de rede.
SERVER_EXCEPTION	Indica um erro do lado do servidor, que pode incluir configurações incorretas do servidor, falhas de processamento ou interrupções no serviço.
TOKEN_EXCEPTION	Indica um problema com o token de autenticação fornecido, como ser inválido, expirado ou não ter as permissões necessárias.
UNSUPPORTED_DEVICE	Indica que o hardware ou software do dispositivo não atende aos requisitos mínimos para reconhecimento facial.
MULTI_WINDOW_UNSUPPORTED_EXCEPTION	Indica que o usuário tentou usar o reconhecimento facial em modo de tela dividida ou multitelas, o que não é suportado.
CAPTURE_ALREADY_ACTIVE_EXCEPTION	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.
CAMERA_EXCEPTION	Indica que ocorreu um erro ao adquirir ou usar a câmera, normalmente ao usar suporte a câmera externa.
FACE_DETECTOR_EXCEPTION	Indica que ocorreu um erro com o detector de rosto durante o processo de reconhecimento facial.
UNEXPECTED_ERROR_EXCEPTION	Indica que ocorreu um erro irrecuperável durante a transação de reconhecimento facial.
INVALID_OPTIONS_EXCEPTION	Indica que ocorreu um erro ao aplicar as opções especificadas para o reconhecimento facial.
CERTIFICATE_EXCEPTION	Indica que não há certificados válidos para a URL do proxy, impedindo a comunicação segura.
IMAGE_NOT_FOUND_EXCEPTION	Indica que a imagem capturada não pôde ser encontrada para validação.
TOO_MANY_REQUESTS_EXCEPTION	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.

FaceLivenessFailureResult (Classe)

Propriedade	Descrição
String signedResponse	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.
String failureType	Em caso de uma falha específica, retorne o tipo do erro.
String failureMessage	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.

Valor de FailureReason	Descrição (Inglês)	LA	GPA
UNKNOWN	Tente novamente	✅	✅
TOO_MUCH_MOVEMENT	Fique parado	❌	✅
TOO_BRIGHT	Mova-se para um lugar mais escuro	❌	✅
TOO_DARK	Mova-se para um lugar mais claro	❌	✅
MISALIGNED_FACE	Mantenha o rosto dentro do oval	❌	✅
EYES_CLOSED	Mantenha os olhos abertos	❌	✅
FACE_TOO_FAR	Aproxime o rosto da tela	❌	✅
FACE_TOO_CLOSE	Afaste o rosto da tela	❌	✅
SUNGLASSES	Remova os óculos de sol	❌	✅
OBSCURED_FACE	Remova quaisquer coberturas faciais	❌	✅
MULTIPLE_FACES	Certifique-se de que apenas uma pessoa esteja visível	❌	✅
BACKGROUND_ISSUE	Fundo inadequado	❌	✅
DEVICE_ISSUE	Dispositivo incompatível	❌	✅
EYEWEAR	Óculos detectados	❌	✅
FACE_NOT_FOUND	Falha na detecção do rosto	❌	✅
FRAMES_BLURRY	Quadros borrados detectados	❌	✅
MOTION_ISSUE	Erro de movimento do dispositivo	❌	✅
LIGHTING_ISSUES	Condições de iluminação ruim	❌	✅
REJECTED	Transação rejeitada	❌	✅
SYSTEM_ERROR	Erro interno do sistema	❌	✅
TIMEOUT	Tempo da sessão esgotado	❌	✅
USER_NOT_FOUND	Falha na busca do usuário	❌	✅
DEVICE_RESTART	Erro de estado do dispositivo	❌	✅
PROCESSING_FAULT	Erro de processamento	❌	✅