CLEARSALE

SDK Android Liveness

v2.0.18

🚧

A partir da release 2.0.18 (08/10/2024), foi implementado um novo método opcional de autenticação via token resgatado da autenticação via Plataforma Data Trust. Recomenda-se que todos façam a alteração, pois, futuramente, será o único método. Para mais informações, confira a seção Exemplos.

Como obter o accessToken e transactionId?

  • accessToken: Faça a autenticação seguindo as instruções da API DataTrust e obtenha o token do retorno.
  • transactionId: Crie uma transação seguindo as instruções da API DataTrust e obtenha o id do retorno.

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

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" />

Classes

CSLiveness

Descrição

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

Construtores

Esta classe possui dois construtores públicos. São eles:

[RECOMENDADO] Construtor que utiliza o token da Plataforma Data Trust (08/10/2024)

ParâmetrosDescrição
transactionIdString que identifica a transação. Este parâmetro é obtido na geração da transaction na Plataforma Data Trust. Para mais informações, acesse esse link.
tokenString que serve para autenticação. Este parâmetro é obtido realizando uma autenticação na Plataforma Data Trust. Para mais informações, acesse esse link.
config: CSLivenessConfigData class responsável por receber os parâmetros de configuração do SDK. Há uma seção logo abaixo explicando todas as possíveis configurações aplicáveis.

[LEGADO] Construtor das versões 2.0.16 ou inferior

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. Há uma seção logo abaixo explicando todas as possíveis configurações aplicáveis.

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.

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

CSLivenessActivity

Descrição

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

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 os seguintes parâmetros:

mCSLiveness = new CSLiveness(transactionId, token, config);
mCSLiveness = new CSLiveness(clientId, clientSecret, identifierId, cpf, config);

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, a classe 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 transactionId = ""; //Obtido via https://datatrustapihml.clearsale.com.br/v1/transaction OU https://datatrustapi.clearsale.com.br/v1/transaction
    String token = ""; //Obtido via https://datatrustapihml.clearsale.com.br/v1/authentication OU https://datatrustapi.clearsale.com.br/v1/authentication
    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(transactionId, token, 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);
}
//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);
}

📘

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;