Integração nativa

Para importar nossas SDKs, é necessário realizar alteração no build.gradle de Projeto e de Aplicativo.

Adicionando ao Projeto

Adicione o endereço de nosso repositório maven no build.gradle do projeto (no Android Studio este arquivo aparece como: "Project: {nome_do_projeto}"), conforme exemplo abaixo.

buildscript {
    ...
}

allprojects {
    repositories {
        ...
        maven { url 'https://sdks.zaig.com.br/' }
    }
}

Adicionando ao Aplicativo

Após isso, adicione a biblioteca que você pretende importar em seu build.gradle do app (no Android Studio este arquivo aparece como: "Module: {nome_do_projeto}.app"), incluindo a dependência apresentada abaixo.

android {
    ...
}
...
dependencies {
    ...
    implementation 'com.zaig.android:facerecon:v5.2.1'
}

atenção

Desde abril de 2025, novas políticas da Google Play requerem Android API Level 35 para que aplicativos possam ser publicados ou atualizados na Google Play Store. Por isso recomendamos fortemente que utilize targetSdkVersion na versão 35 pelo menos.

info

A utilização de targetSdkVersion 35 implica na utilização do compileSdkVersion 35, o que desencadeia alguns requisitos mínimos para ferramentas do ecossistema do Android:

compileSdkVersion 35 --> AGP 8.6.0
AGP 8.6.0 --> Gradle 8.7
AGP 8.6.0 --> Java 17 (JDK 17)
AGP 8.6.0 --> Kotlin 2+

Iniciando a SDK

Aviso Importante!

A partir da versão 5.0.0, o sistema de autenticação foi atualizado para usar clientSessionKey em vez de mobileToken. Além disso, foram adicionadas novas opções de configuração para telas de feedback.

Obtendo o Client Session Key

Antes de configurar a SDK, você deve gerar um clientSessionkey temporário através de uma requisição server-to-server para a nossa API de face recognition.

Endpoint

Ambiente	URL
Sandbox	`https://api.sandbox.zaig.com.br/face_recognition/client_session`
Produção	`https://api.zaig.com.br/face_recognition/client_session`

Requisição

Method: POST

Headers:

{
  "Authorization": "YOUR_FACE_RECON_API_KEY"
}

Body (Opcional, mas recomendado):

{
  "user_id": "unique_user_identifier"
}

Importante: O campo user_id é altamente recomendado para medidas de segurança e antifraude. Use um identificador único do usuário da sua aplicação.

Resposta

A resposta bem-sucedida conterá o client_session_key que deve ser passado para a configuração da SDK.

{
  "client_session_key": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Para incorporar a SDK ao seu aplicativo você deve iniciar realizar a configuração do seu aplicativo de captura personalizado através de builder e submetê-lo como parâmetro via Intent Extra para a FaceReconActivity.

Exemplo de inicialização da SDK

  Intent intent = new Intent(getApplicationContext(), FaceReconActivity.class);

  VisualConfiguration visualConfiguration = new VisualConfiguration()
          .setOnboardingDrawable(R.drawable.introscreen,500);

  TextConfiguration textConfiguration = new TextConfiguration()
          .setCustomText(TextConfiguration.CustomLabel.onboardingTitle, "Para tirar uma boa foto:")
          .setCustomText(TextConfiguration.CustomLabel.onboardingFirstLabel, "- Vá para um local iluminado")
          .setCustomText(TextConfiguration.CustomLabel.onboardingSecondLabel, "- Retire adereços e mostre bem o rosto")
          .setCustomText(TextConfiguration.CustomLabel.onboardingThirdLabel, "- Insira seu rosto na moldura, aguardando que fique verde para realizar a captura");

  FaceRecognition mFaceRecognition = new FaceRecognition.Builder(clientSessionKey)
          .showIntroductionScreens(true)
          .setVisualConfiguration(visualConfiguration)
          .setTextConfiguration(textConfiguration)
          .setBackgroundColor("#000000")
          .setFontColor("#FFFFFF")
          .setFontFamily(FaceRecognition.FontFamily.futura)
          .setSessionId("SESSION_ID")
          .setLogLevel(FaceRecognition.LogLevel.debug)
          .setShowSuccessScreen(false)
          .build();
  intent.putExtra("settings", mFaceRecognition);
  startActivityForResult(intent, REQUEST_CODE);

FaceRecognition.Builder

Parâmetro	Função	Obrigatório
clientSessionKey	Chave do cliente que identifica que os dados coletados são provenientes do seu aplicativo. Obtida através de requisição à API da Face Recognition	Sim.
.setSandboxEnvironment()	Caso este parâmetro seja utilizado no construtor, a biblioteca será configurada para enviar os dados ao ambiente de sandbox. Caso ausente, as requisições são enviadas para o ambiente production.	Não.
.showIntroductionScreens(Boolean showIntroductionScreens)	Quando "false" desativa as telas de introdução à coleta da foto que aparecem para o usuário.	Não. O padrão é "true".
.setShowSuccessScreen(Boolean showSuccessScreen)	Quando "false" desativa a tela de sucesso após a coleta da foto.	Não. O padrão é "true".
.setShowInvalidTokenScreen(Boolean showSuccessScreen)	Quando "false" desativa a tela de falha de autenticação.	Não. O padrão é "true".
.setBackgroundColor(String backgroundColor)	Permite a configuração da cor de background das activities da SDK.	Não. O padrão é "#ffffff".
.setFontColor(String fontColor)	Permite a configuração da cor da fonte e dos ícones das activities da SDK.	Não. O padrão é "#000000".
.setFontFamily(FontFamily fontFamily)	Permite a configuração da fonte das activities da SDK.	Não. Caso não seja informada o padrão é FontFamily.open_sans. Fontes disponíveis: FontFamily.open_sans, FontFamily.futura, FontFamily.verdana, FontFamily.roboto, FontFamily.poppins e FontFamily.helvetica.
.activeFaceLiveness(Boolean activeFaceLiveness)	Indica se a SDK deve realizar um procedimento de captura de selfie do usuário ou de prova de vida ativa.	Não. O padrão é false.
.audioConfiguration(AudioConfiguration audioConfiguration)	Indica se a SDK deve ou não executar áudios de indicação para o usuário. As configurações aceitas são AudioConfiguration.enable que executa os áudios de indicação, AudioConfiguration.disable que não executa estes áudios e AudioConfiguration.accessibility que executa os áudios caso o dispositivo do usuário possua configurações de acessibilidade ativadas.	Não. O padrão é AudioConfiguration.disable.
.setVisualConfiguration(VisualConfiguration visualConfiguration)	Utilizado para customizar as imagens mostradas para o usuário ao longo da execução da SDK.	Não.
.setTextConfiguration(TextConfiguration textConfiguration)	Utilizado para customizar os textos da tela introdutória de onboarding mostradas para o usuário ao longo da execução da SDK.	Não.
.setSessionId(String sessionId)	Utilizado para definir a chave que identifica a sessão iniciada na SDK. É usada para rastrear todo fluxo percorrido pelo usuário na execução da FaceRecon através de logs. Este campo aceita até 255 caracteres.	Não.
.setLogLevel(FaceRecognition.LogLevel logLevel)	Utilizado para customizar o nível de verbosidade dos logs da SDK. Níveis disponíveis: LogLevel.debug, LogLevel.info, LogLevel.warn, LogLevel.error e LogLevel.trace. O padrão é LogLevel.debug.	Não.
.setDocumentNumber(String documentNumber)	Utilizado para definir o número do documento do usuário. Este campo aceita 14 caracteres.	Apenas para as chamadas que utilizem a validação 1:1 em algum momento.
.setValidation(Boolean validation)	Utilizado para definir se a SDK deve ou não realizar a validação 1:1 com a selfie do usuário. Na primeira sessão do usuário esta flag deve estar, obrigatoriamente, false. Esta função necessita do método setDocumentNumber preenchido.	Não. O padrão é false.

O Objeto VisualConfiguration

Parâmetro	Função	Obrigatório
.setOnboardingDrawable(int onboarding_drawable, int onboarding_width)	Utilizado para configurar a imagem mostrada para o usuário na tela de onboarding da SDK. O parâmetro onboarding_drawable deve referenciar o id da imagem a ser mostrada e onboarding_width é o tamanho desejado de exibição desta imagem.	Não.
.setButtonBorderSize(int border_size)	Utilizado para configurar a largura de borda dos botões da SDK.	Não. O padrão é 1.
.setButtonShadow(boolean button_shadow)	Quando setado para false remove o efeito de sombra, padrão no android, utilizado pelos botões da SDK.	Não. O padrão é true.

O Objeto TextConfiguration

Parâmetro	Função	Obrigatório
.setCustomText(CustomLabel label, String text)	Utilizado para configurar os textos mostrados para o usuário na tela de onboarding da SDK	Não.

Versões Anteriores

Iniciando a SDK

  Intent intent = new Intent(getApplicationContext(), FaceReconActivity.class);

  VisualConfiguration visualConfiguration = new VisualConfiguration()
          .setOnboardingDrawable(R.drawable.introscreen,500);

  TextConfiguration textConfiguration = new TextConfiguration()
          .setCustomText(TextConfiguration.CustomLabel.onboardingTitle, "Para tirar uma boa foto:")
          .setCustomText(TextConfiguration.CustomLabel.onboardingFirstLabel, "- Vá para um local iluminado")
          .setCustomText(TextConfiguration.CustomLabel.onboardingSecondLabel, "- Retire adereços e mostre bem o rosto")
          .setCustomText(TextConfiguration.CustomLabel.onboardingThirdLabel, "- Insira seu rosto na moldura, aguardando que fique verde para realizar a captura");

  FaceRecognition mFaceRecognition = new FaceRecognition.Builder("YOUR_MOBILE_TOKEN_SENT_BY_QITECH")
          .showIntroductionScreens(true)
          .setVisualConfiguration(visualConfiguration)
          .setTextConfiguration(textConfiguration)
          .setBackgroundColor("#000000")
          .setFontColor("#FFFFFF")
          .setFontFamily(FaceRecognition.FontFamily.futura)
          .setSessionId("SESSION_ID")
          .setLogLevel(FaceRecognition.LogLevel.debug)
          .setShowSuccessScreen(false)
          .build();
  intent.putExtra("settings", mFaceRecognition);
  startActivityForResult(intent, REQUEST_CODE);

Utilizamos um Mobile Token para permitir o acesso autenticado do seu aplicativo a nossa API. Ela provavelmente já foi enviada por e-mail para você. Caso ainda não tenha recebido o seu token, envie um e-mail para suporte.caas@qitech.com.br.

Nossa API espera receber o Mobile Token em todas as requisições ao nosso servidor vindas da SDK, portanto, este deve ser obrigatoriamente incluído como parâmetro de configuração através do método mencionado anteriormente.

Atenção

Você deve substituir <code>"YOUR_MOBILE_TOKEN_SENT_BY_QITECH"</code> com o Mobile Token recebido do suporte.

FaceRecognition.Builder

Parâmetro	Função	Obrigatório
mobileToken	Chave do cliente que identifica que os dados coletados são provenientes do seu aplicativo. Caso ainda não tenha recebido o seu mobile-token, entre em contato com o suporte.caas@qitech.com.br.	Sim.
.setSandboxEnvironment()	Caso este parâmetro seja utilizado no construtor, a biblioteca será configurada para enviar os dados ao ambiente de sandbox. Caso ausente, as requisições são enviadas para o ambiente production.	Não.
.showIntroductionScreens(Boolean showIntroductionScreens)	Quando "false" desativa as telas de introdução à coleta da foto que aparecem para o usuário.	Não. O padrão é "true".
.setShowSuccessScreen(Boolean showSuccessScreen)	Quando "false" desativa a tela de sucesso após a coleta da foto.	Não. O padrão é "true".
.setBackgroundColor(String backgroundColor)	Permite a configuração da cor de background das activities da SDK.	Não. O padrão é "#ffffff".
.setFontColor(String fontColor)	Permite a configuração da cor da fonte e dos ícones das activities da SDK.	Não. O padrão é "#000000".
.setFontFamily(FontFamily fontFamily)	Permite a configuração da fonte das activities da SDK.	Não. Caso não seja informada o padrão é FontFamily.open_sans. Fontes disponíveis: FontFamily.open_sans, FontFamily.futura, FontFamily.verdana, FontFamily.roboto, FontFamily.poppins e FontFamily.helvetica.
.activeFaceLiveness(Boolean activeFaceLiveness)	Indica se a SDK deve realizar um procedimento de captura de selfie do usuário ou de prova de vida ativa.	Não. O padrão é false.
.audioConfiguration(AudioConfiguration audioConfiguration)	Indica se a SDK deve ou não executar áudios de indicação para o usuário. As configurações aceitas são AudioConfiguration.enable que executa os áudios de indicação, AudioConfiguration.disable que não executa estes áudios e AudioConfiguration.accessibility que executa os áudios caso o dispositivo do usuário possua configurações de acessibilidade ativadas.	Não. O padrão é AudioConfiguration.disable.
.setVisualConfiguration(VisualConfiguration visualConfiguration)	Utilizado para customizar as imagens mostradas para o usuário ao longo da execução da SDK.	Não.
.setTextConfiguration(TextConfiguration textConfiguration)	Utilizado para customizar os textos da tela introdutória de onboarding mostradas para o usuário ao longo da execução da SDK.	Não.
.setSessionId(String sessionId)	Utilizado para definir a chave que identifica a sessão iniciada na SDK. É usada para rastrear todo fluxo percorrido pelo usuário na execução da FaceRecon através de logs. Este campo aceita até 255 caracteres.	Não.
.setLogLevel(FaceRecognition.LogLevel logLevel)	Utilizado para customizar o nível de verbosidade dos logs da SDK. Níveis disponíveis: LogLevel.debug, LogLevel.info, LogLevel.warn, LogLevel.error e LogLevel.trace. O padrão é LogLevel.debug.	Não.
.setDocumentNumber(String documentNumber)	Utilizado para definir o número do documento do usuário. Este campo aceita 14 caracteres.	Apenas para as chamadas que utilizem a validação 1:1 em algum momento.
.setValidation(Boolean validation)	Utilizado para definir se a SDK deve ou não realizar a validação 1:1 com a selfie do usuário. Na primeira sessão do usuário esta flag deve estar, obrigatoriamente, false. Esta função necessita do método setDocumentNumber preenchido.	Não. O padrão é false.

Integração nativa

Adicionando ao Projeto​

Adicionando ao Aplicativo​

Iniciando a SDK​

Obtendo o Client Session Key​

Endpoint​

Requisição​

Resposta​

Exemplo de inicialização da SDK​

FaceRecognition.Builder​

O Objeto VisualConfiguration​

O Objeto TextConfiguration​

Versões Anteriores​

Iniciando a SDK​

FaceRecognition.Builder​

Adicionando ao Projeto

Adicionando ao Aplicativo

Iniciando a SDK

Obtendo o Client Session Key

Endpoint

Requisição

Resposta

Exemplo de inicialização da SDK

FaceRecognition.Builder

O Objeto VisualConfiguration

O Objeto TextConfiguration

Versões Anteriores

Iniciando a SDK

FaceRecognition.Builder