Android

Abra o fluxo de verificação num app Android com a WebView SDK e receba os eventos da sessão.

Ao final deste guia o fluxo de verificação abre dentro do seu app Android, com câmera e microfone liberados e os eventos da sessão chegando ao seu código.

A SDK não cria a verificação. Ela renderiza uma que já existe, a partir do embed URL que o seu backend recebe em entry.url ao chamar criar verificação.

Pré-requisitos

• Android Studio recente, com AGP 9 e Gradle 9 ou superior.
• minSdk 24 e Java 11.
• Um embed URL emitido pelo seu backend, como em emitir a credencial.
• Acesso ao artefato. O pacote com.legitimuz:sdk é privado: peça ao suporte a URL do repositório Maven e as credenciais de leitura, ou o .aar da versão que você vai usar.

A chave de API (lz_...) nunca vai para o app. Ela fica no seu servidor. O app recebe apenas o embed URL, que vale para uma verificação e expira.

Confira o exemplo

Os arquivos desta integração, com o destino de cada um.

Configure o projeto

1. Declare o repositório e a dependência

   Maven

   // settings.gradle, no bloco dependencyResolutionManagement
   repositories {
       google()
       mavenCentral()
       maven {
           url = '<URL_DO_REPOSITORIO>'
           credentials {
               username = '<USUARIO>'
               password = '<TOKEN>'
           }
       }
   }
   
   // build.gradle do seu módulo
   dependencies {
       implementation 'com.legitimuz:sdk:1.1.0'
   }
   

   Pelo Maven, androidx.webkit, androidx.browser e androidx.appcompat vêm por transitividade. Pelo .aar, declare as três: sem elas o app compila e quebra em runtime com NoClassDefFoundError.

   Guarde as credenciais do repositório fora do controle de versão, em ~/.gradle/gradle.properties ou numa variável de ambiente do seu CI.

2. Prepare a Activity que hospeda a verificação

   A SDK já declara INTERNET, CAMERA, RECORD_AUDIO, ACCESS_FINE_LOCATION e ACCESS_COARSE_LOCATION no próprio manifest. O merge traz as cinco para o seu app e você não precisa repeti-las.

   O que o seu app precisa garantir são duas coisas:

   AndroidManifest.xml

   <activity
       android:name=".VerificationActivity"
       android:configChanges="orientation|screenSize|screenLayout|smallestScreenSize|keyboardHidden|uiMode"
       android:exported="true"
       android:screenOrientation="portrait" />
   

   A Activity hospedeira tem que ser uma ComponentActivity — uma AppCompatActivity já é. A SDK pede as permissões pelo ActivityResultRegistry dela; sem isso os diálogos do sistema não abrem e a câmera nunca liga.

   Sem configChanges, uma rotação recria a Activity e derruba a verificação em andamento. A SDK é uma View e não trava a orientação do host por conta própria.

3. Valide o embed URL

   Legitimuz.parseEmbedUrl exige https:// e um domínio de verificação da Legitimuz — a WebView só libera câmera e microfone em origem segura.

   VerificationActivity.java

   LegitimuzResult<String, LegitimuzEmbedUrlError> parsed =
           Legitimuz.parseEmbedUrl(embedUrl);
   
   if (!parsed.isSuccess()) {
       // getMessage() já vem em pt-BR, pronto para exibir
       showError(parsed.getError().getMessage());
       return;
   }
   

   Este passo é opcional: createSession valida de novo internamente. Ele existe para dar o retorno ao titular mais cedo.

4. Crie a sessão e anexe a view

   VerificationActivity.java

   LegitimuzResult<LegitimuzSessionHandle, LegitimuzEmbedUrlError> result =
           Legitimuz.createSession(this, embedUrl, true);
   
   if (!result.isSuccess()) {
       showError(result.getError().getMessage());
       return;
   }
   
   handle = result.getValue();
   
   LegitimuzVerificationView verificationView = new LegitimuzVerificationView(this);
   setContentView(verificationView);
   handle.attach(verificationView);
   

   O terceiro parâmetro é requestsDeviceAccessAutomatically. Com true, a SDK pede câmera, microfone e localização assim que a tela é anexada, antes de a página carregar. Passe false se o seu app já pede essas permissões numa tela anterior; mesmo assim a SDK pede o que faltar no momento em que o widget precisar.

   LegitimuzVerificationView é uma FrameLayout comum, sem toolbar nem navegação própria. Você decide como apresentá-la.

5. Observe os eventos e o desfecho

   VerificationActivity.java

   handle.setCallback(new LegitimuzCallback() {
       @Override
       public void onEvent(@NonNull LegitimuzEvent event) {
           Log.d(TAG, "event=" + event.getType());
       }
   
       @Override
       public void onOutcome(@NonNull LegitimuzVerificationOutcome outcome) {
           switch (outcome.getKind()) {
               case COMPLETED:
                   LegitimuzCompleteResult completeResult = outcome.getCompleteResult();
                   // isSuccessfulSubmission() é envio, não aprovação
                   break;
               case CANCELLED:
                   break;
               case FAILED:
                   showError(outcome.getError().getDisplayMessage());
                   break;
               case LOAD_FAILED:
                   // a própria view já mostra a tela de "Tentar novamente"
                   return;
           }
           releaseSession();
       }
   });
   

   Os dois métodos são sempre chamados na thread principal. Se você registrar o callback depois de a verificação já ter terminado, onOutcome dispara na hora.

6. Destrua o handle

   VerificationActivity.java

   @Override
   protected void onDestroy() {
       if (handle != null) {
           handle.destroy();
           handle = null;
       }
       super.onDestroy();
   }
   

   destroy() encerra o fluxo, apaga os cookies e o storage da verificação e destrói a WebView. Chame sempre.

Confira que funcionou

O fluxo abre na primeira etapa e o seu Logcat registra session.started. No dashboard, a verificação sai de not_opened e passa a started.

Eventos

event.getType() devolve a string crua. LegitimuzEventType.fromRawValue(...) converte para o enum quando você quer um switch.

event.getType()	LegitimuzEventType	Quando dispara
session.started	SESSION_STARTED	a sessão começou
session.stepTransitioned	SESSION_STEP_TRANSITIONED	o fluxo avançou de etapa
document.capture.started	DOCUMENT_CAPTURE_STARTED	a captura do documento começou
document.capture.completed	DOCUMENT_CAPTURE_COMPLETED	o documento foi capturado
document.capture.failed	DOCUMENT_CAPTURE_FAILED	a captura falhou, o titular pode repetir
selfie.capture.started	SELFIE_CAPTURE_STARTED	a captura da selfie começou
selfie.capture.completed	SELFIE_CAPTURE_COMPLETED	a selfie foi capturada
liveness.completed	LIVENESS_COMPLETED	a prova de vida foi concluída
liveness.failed	LIVENESS_FAILED	a prova de vida falhou
session.completed	SESSION_COMPLETED	o fluxo terminou
session.error	SESSION_ERROR	um erro foi reportado na sessão
session.abandoned	SESSION_ABANDONED	o titular abandonou o fluxo
decision.notified	DECISION_NOTIFIED	uma decisão foi notificada ao widget
terms.open	TERMS_OPEN	o titular abriu os termos de uso
redirect.open	REDIRECT_OPEN	foi pedido um redirecionamento externo

Não intercepte terms.open nem redirect.open: a LegitimuzVerificationView já abre essas URLs em Custom Tabs.

event.getPayload() é um LegitimuzJsonValue, um envelope JSON genérico para as etapas que emitem dados extras. Acesse com get(...) e os acessores tipados:

Ler o payload

LegitimuzJsonValue payload = event.getPayload();
if (payload != null && payload.get("step") != null) {
    String step = payload.get("step").getStringValue();
}

Não decida nada a partir de COMPLETED. isSuccessfulSubmission() confirma que o titular enviou os dados, não que a verificação foi aprovada. O desfecho chega ao seu backend por verification.decided, onde o titular não pode interferir.

Tratamento de erros

Os erros vêm de três lugares, em momentos diferentes.

Validação do embed URL, antes da sessão

LegitimuzEmbedUrlError, devolvido por parseEmbedUrl e por createSession. O getMessage() já vem em pt-BR, pronto para exibir.

Caso	Quando ocorre
EMPTY	string vazia ou só espaços
MALFORMED	não é uma URL válida
INSECURE_SCHEME	scheme diferente de https
MISSING_HOST	URL sem host
UNTRUSTED_HOST	host fora dos domínios da Legitimuz

Erros durante a verificação

LegitimuzPublicError chega em onOutcome com getKind() == FAILED.

Método	Tipo	O que é
getCode()	int	o código do erro, o mesmo catálogo da web
getName()	String?	nome curto
getErrorType()	String?	categoria
getMessage()	String?	mensagem técnica
getUserMessage()	String?	mensagem pensada para o titular
isRecoverable()	boolean	false encerrou a sessão
getContext()	LegitimuzJsonValue?	dados de diagnóstico
getDocUrl()	String?	link da documentação do erro
getUuid()	String?	identificador da ocorrência, para o suporte
getDisplayMessage()	String	o que exibir ao titular

Exiba sempre getDisplayMessage(): ele já resolve a prioridade entre getUserMessage(), getMessage() e o texto genérico.

Só erro com isRecoverable() == false encerra a sessão. Erro recuperável aparece em onEvent como session.error e o fluxo continua. O catálogo de códigos está em tratamento de erros.

Falha ao carregar a página

LOAD_FAILED é problema de rede, DNS ou TLS ao abrir o embed URL, não erro da verificação. A própria view já mostra a tela de “Não foi possível abrir a verificação” com botão de tentar de novo, então normalmente não trate. getLoadFailedMessage() traz o detalhe em pt-BR.

onOutcome pode disparar mais de uma vez por causa desse retry.

Casos de borda

A verificação some quando o aparelho gira

Falta o android:configChanges na sua Activity. Veja o segundo passo.

O titular negou a câmera

Depois de “não perguntar mais”, só as configurações do sistema resolvem. Mande o titular para lá, explicando antes por que a câmera é necessária:

Abrir as configurações do app

startActivity(
    new Intent(
        Settings.ACTION_APPLICATION_DETAILS_SETTINGS,
        Uri.fromParts("package", getPackageName(), null)
    )
);

O embed URL expirou

O embed URL vale até o expires_at da verificação. Expirado, peça um novo ao seu backend e crie outra sessão. Não reaproveite o antigo.

Próximo passo

iOS

O mesmo fluxo em Swift.

Receber a decisão

Onde o desfecho realmente chega.