SDK Android Liveness
V4.0.1
A partir da release 3.0.3 (16/05/2025), o único método de autenticação aceito é utilizando o token recuperado da autenticação com a Plataforma Datatrust. 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 otoken
do retorno.transactionId
: Crie uma transação seguindo as instruções da API DataTrust e obtenha oid
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, até a versão 3.0.3:
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'
...
}
A partir da release 4.0.0 (04/07/2025), o SDK passa a utilizar um único pacote, unificando os ambientes de homologação e produção. A terminação -hml foi removida, sendo utilizado apenas o pacote sale.clear.studio:sdk-csliveness:VERSION para ambos os ambientes.
Configuração
Instruções para configuração do framework no projeto:
- 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:
O parâmetro **environment **permite selecionar o ambiente entre PRD (Produção) e HML (homologação), através do enum CSLivenessEnvironments.HML e CSLivenessEnvironments.PRD.
[RECOMENDADO] Construtor que recebe o ambiente desejado (à partir da versão 4.0.0):
Parâmetros | Descrição |
---|---|
transactionId | String 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. |
token | String que serve para autenticação. Este parâmetro é obtido realizando uma autenticação na Plataforma Data Trust. Para mais informações, acesse esse link. |
environment: CSLivenessEnvironments | Enum CSLivenessEnvironments.HML ou CSLivenessEnvironments.PRD |
config: CSLivenessConfig | Data 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 3.0.3 ou inferior:
Parâmetros | Descrição |
---|---|
transactionId | String 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 . |
token | String 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: CSLivenessConfig | Data 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âmetro | Descrição |
---|---|
vocalGuidance: boolean | Habilita o conjunto de áudios auxiliares para usuários com baixa visão, reproduzindo falas humanas do que precisa ser feito em cada etapa. |
colors: CSLivenessConfigColors | Data 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âmetro | Descrição |
---|---|
primaryColor: int | Cor definida para atuar como PrimaryColor |
secondaryColor: int | Cor definida para atuar como SecondaryColor |
titleColor: int | Cor definida para atuar como TitleColor |
paragraphColor: int | Cor 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étodo | Descrição |
---|---|
getResponseMessage() :String | Permite 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() :String | Identifica a captura do Liveness dentro da ClearSale e poderá ser usado para a consulta da imagem. Em caso de erro ele retornará null. |
getImage() :String | Retorna 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, CSLivenessEnvironments.PRD, config);
mCSLiveness = new CSLiveness(transactionId, token, 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, CSLivenessEnvironments.PRD, 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 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);
}
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;
Updated 7 days ago