SDK Android Liveness

v2.0.14

⚠️

A versão 2.0.0 trouxe uma mudança na estrutura da classe CSLiveness que afetará implementações antigas. Atente-se à nova forma de implementação na documentação abaixo.

🚧

A partir do dia 16 de abril de 2024, na versão 2.0.0, foi alterado o layout padrão do SDK e implementada a feature de customização de cores. Para entender como customiza-la em sua aplicação, leia mais aqui.

Introdução

O objetivo deste manual é fornecer todas as informações necessárias para instalação e uso da ferramenta nos aplicativos desenvolvidos para plataforma Android.

Este SDK realiza a captura de faces para processamento de Liveness pela ClearSale. Todas as informações coletadas são dados relacionados apenas ao dispositivo, sem relação ao aplicativo integrado.

As informações de captura de imagem dependem da permissão concedida pelo usuário no momento de captura. Neste caso é necessário que o aplicativo solicite o acesso à câmera ao usuário para dar prosseguimento à coleta de prova de vida.

O SDK respeita a política de privacidade da Google para a captura dos dados do dispositivo e o nível de permissão atribuído pelo usuário (usuário do dispositivo).

Android

Requisitos mínimos

  • Espaço de armazenamento: ~26mb
  • Versão do sistema operacional Android: v5.0 (API v21)
  • compileSdk versão: 31
  • targetSdk versão: 31
  • com.google.android.material:material: 1.5.0

Instalação do Package

  • Gradle

Certifique-se que o seu gradle a nível de projeto settings.gradle possua os seguintes repositórios:

buildscript {
    ...    
    dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
        maven {
            url  ARTIFACTS_FEED_URL // valor fornecido pela ClearSale
            name  ARTIFACTS_FEED_NAME // valor fornecido pela ClearSale
            credentials {
                username USERNAME // valor fornecido pela ClearSale
                password PAT // valor fornecido pela ClearSale
            }
            authentication {
                basic(BasicAuthentication)
            }
        }
    }
}
    ...
}

Obs: o PAT é o token para baixar o repositório do SDK de Liveness Android da ClearSale.

No arquivo build.gradle da sua aplicação, habilite a compatibilidade de origem Java 1.8.

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

Existem dois pacotes, um deve ser utilizado para testes e o outro no ambiente produtivo.

  • sale.clear.studio:sdk-csliveness:VERSION deve ser utilizado apenas no ambiente produtivo.
  • sale.clear.studio:sdk-csliveness:VERSION-hml deve ser utilizado apenas no ambiente de desenvolvimento.

Adicione no build.gradle do seu aplicativo a seguinte dependência:

dependencies {
    implementation 'sale.clear.studio:sdk-csliveness:VERSION'
    ...
}
dependencies {
    implementation 'sale.clear.studio:sdk-csliveness:VERSION-hml'
    ...
}

Configuração

Instruções para configuração do framework no projeto:

  1. Para o uso do sdk, é necessário requisitar algumas permissões no arquivo de manifesto, são elas:
<uses-permission android:name="android.permission.INTERNET"/>		
<uses-feature android:name="android.hardware.camera" />  
<uses-permission android:name="android.permission.CAMERA" />

Classe CSLiveness

Descrição
CSLiveness é a classe responsável pela inicialização do SDK.

Construtores
Esta classe possui um construtor público que deverá receber dois parâmetros necessários para a comunicação com os servidores da ClearSale.

ParâmetrosDescrição
clientIdString que identifica o cliente junto a ClearSale. Este valor é fornecido pela ClearSale.
clientSecretString que serve como token de autenticação do cliente.
identifierIDString de até 100 caracteres que identifica todo o fluxo do usuário de forma única e é gerada pela entidade. Serve para agilizar consultas e chamados feitos pela entidade (e pode ser utilizada como identificador interno entre produtos aqui da ClearSale).
cpfString de 11 caracteres (no formato CPF) do usuário que irá realizar o fluxo, devendo seguir as regras de validade estipuladas pelo Governo.
config: CSLivenessConfigData class responsável por receber os parâmetros de configuração do SDK.

Métodos

Nome do métodoDescrição
getClientId() :StringPermite recuperar o valor configurado no parâmetro clientId.
getClientSecret() :StringPermite recuperar o valor configurado no parâmetro clientSecret.
getIdentifierId :StringPermite recuperar o valor configurado no parâmetro identifierId.
getCpf() :StringPermite recuperar o valor configurado no parâmetro cpf.
getConfig() :CSLivenessConfigPermite recuperar o valor configurado no parâmetro config.

Classe CSLivenessConfig

Descrição
CSLivenessConfig é a classe responsável por receber os parâmetros de configuração do SDK.

ParâmetroDescrição
vocalGuidance: booleanHabilita o conjunto de áudios auxiliares para usuários com baixa visão, reproduzindo falas humanas do que precisa ser feito em cada etapa.
colors: CSLivenessConfigColorsData class responsável por receber os parâmetros de customização de cores do SDK. Para mais informações, visite a sessão de customização de UI.

Classe CSLivenessConfigColors

Descrição
CSLivenessConfigColors é a classe responsável por receber os parâmetros de customização de cores do SDK. Para mais informações, visite a sessão de customização de UI.

ParâmetroDescrição
primaryColor: intCor definida para atuar como PrimaryColor
secondaryColor: intCor definida para atuar como SecondaryColor
titleColor: intCor definida para atuar como TitleColor
paragraphColor: intCor definida para atuar como ParagraphColor

Classe CSLivenessActivity

Descrição
CSLivenessActivity é a Activity responsável pela inicialização da tela de captura da selfie.

Classe CSLivenessResult

Descrição
CSLivenessResult é a classe que informa o resultado da captura do Liveness.

Construtores
Esta classe não possui um construtor público e deve usada apenas para receber o resultado emitido pela CSLivenessActivity.

Métodos

Nome do métodoDescrição
getResponseMessage() :StringPermite recuperar o resultado da captura do Liveness. Caso seja um caso de sucesso ela irá conter como resposta a string Real, do contrário será uma string explicando o erro que aconteceu.
getSessionId() :StringIdentifica a captura do Liveness dentro da ClearSale e poderá ser usado para a consulta da imagem. Em caso de erro ele retornará null.
getImage() :StringRetorna um base64 da imagem autenticada pelo processo de Liveness. Em caso de erro no processo de Liveness ele retornará null.

Exemplos

Para inicializar o SDK, crie uma instância da classe CSLiveness na Activity que você deseja que seja iniciada a captura do Liveness, passando as credenciais de acesso que foram recebidas pela ClearSale, identifierId, cpf do usuário e config de cores (OPCIONAL):

 mCSLiveness = new CSLiveness(clientID, clientSecret, identifierId, cpf, config);

Como os campos identifierId, cpf e config são opcionais e aceitam valores nulos, conforme exemplo:

 mCSLiveness = new CSLiveness(clientID, clientSecret, null, null, null);

Crie uma Intent passando a atual Activity e a classe CSLivenessActivity como parâmetros:

Intent mIntent = new Intent(this, CSLivenessActivity.class);
mIntent.putExtra("PARAMETER_NAME", mCSLiveness);

Em seguida, passe a instância da classe CSLiveness para dentro da CSLivenessActivity, através do método putExtra(String name, Serializable value) conforme exemplo:

 mIntent.putExtra("PARAMETER_NAME", mCSLiveness);

Para inicializar a chamada da tela de captura do Liveness, use o seguinte método:

startActivityForResult(mIntent, REQUEST_CODE);

Após a finalização do processo de captura CSLivenessActivity vai emitir o resultado através de um objeto do tipo CSLivenessResult. Para recuperar o valor emitido utilize o método onActivityResult(int requestCode, int resultCode, Intent data) conforme exemplo:

@Override
protected void onActivityResult(int requestCode, int resultCode, @Nullable Intent data) {
    if (requestCode == REQUEST_CODE){
        if (resultCode == RESULT_OK && data != null) {
            CSLivenessResult mCSLivenessResult = (CSLivenessResult) data.getSerializableExtra("PARAMETER_NAME");
            Log.d(mCSLivenessResult.getResponseMessage());
        } else {
            Log.d("UserCancel");
        }
    }
    super.onActivityResult(requestCode, resultCode, data);
}

Juntando todas as etapas, o código ficará da seguinte forma:

 //chame o método startCSLiveness no momento que você deseja iniciar a tela de captura do processo de Liveness.
void startCSLiveness (){
    String clientID = "clientID recebido da ClearSale";
    String clientSecret = "clientSecret recebido da ClearSale";
    String cpf = "12345678901" //Cpf do cliente OPCIONAL;
    String identifierId = "rgmrieg98revefnbwbr0rgw" //Identifier ID é uma string de até 100 caracteres OPCIONAL que identifica todo o fluxo do usuário
    boolean vocalGuidance = true; //Coloque true para habilitar o Vocal Guidance ou false para desabilita-lo, esse parâmetro é OPCIONAL e o default é false
  	CSLivenessConfigColors colors = new CSLivenessConfigColors(); //Parâmetro OPCIONAL para customização das cores do SDK
		CSLivenessConfig config = new CSLivenessConfig(vocalGuidance, colors);//Parâmetro OPCIONAL para configurações do SDK
  
    mCSLiveness = new CSLiveness(clientID, clientSecret, identifierId, cpf, config);
    Intent mIntent = new Intent(this, CSLivenessActivity.class);
    mIntent.putExtra("PARAMETER_NAME", mCSLiveness);
    startActivityForResult(mIntent, REQUEST_CODE);
}

@Override
protected void onActivityResult(int requestCode, int resultCode, @Nullable Intent data) {
    if (requestCode == REQUEST_CODE){
        if (resultCode == RESULT_OK && data != null) {
            CSLivenessResult mCSLivenessResult = (CSLivenessResult) data.getSerializableExtra("PARAMETER_NAME");
            Log.d(TAG, mCSLivenessResult.getResponseMessage());
        } else {
            Log.d(TAG, "UserCancel");
        }
    }
    super.onActivityResult(requestCode, resultCode, data);
}

Caso opte por não colocar o identifierId, cpf e config, o código ficará da seguinte forma:

//chame o método startCSLiveness no momento que você deseja iniciar a tela de captura do processo de Liveness.
void startCSLiveness (){
    String clientID = "clientID recebido da ClearSale";
    String clientSecret = "clientSecret recebido da ClearSale";
    
    mCSLiveness = new CSLiveness(clientID, clientSecret, null, null, null);
    Intent mIntent = new Intent(this, CSLivenessActivity.class);
    mIntent.putExtra("PARAMETER_NAME", mCSLiveness);
    startActivityForResult(mIntent, REQUEST_CODE);
}

@Override
protected void onActivityResult(int requestCode, int resultCode, @Nullable Intent data) {
    if (requestCode == REQUEST_CODE){
        if (resultCode == RESULT_OK && data != null) {
            CSLivenessResult mCSLivenessResult = (CSLivenessResult) data.getSerializableExtra("PARAMETER_NAME");
            Log.d(TAG, mCSLivenessResult.getResponseMessage());
        } else {
            Log.d(TAG, "UserCancel");
        }
    }
    super.onActivityResult(requestCode, resultCode, data);
}

📘

Arquivo de Exemplo: clique aqui

Detalhes de privacidade

Uso de dados

Todas as informações coletadas pelo SDK da ClearSale são com exclusiva finalidade de prevenção à fraude e proteção ao próprio usuário, aderente à política de segurança e privacidade das plataformas Google e Apple e à LGPD. Por isso, estas informações devem constar na política de privacidade do aplicativo.

Tipo de dados coletados

O SDK da ClearSale coleta as seguintes informações do dispositivo :

  • Características físicas do dispositivo/ hardware (Como tela, modelo, nome do dispositivo);
  • Características de software (Como versão, idioma, build, controle parental);
  • Informações da câmera;