Android

Abra o fluxo de verificação num app Android e receba os eventos da sessão em Kotlin.

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

Pré-requisitos

• Android 7.0 (API 24) ou superior.
• Uma access_credential emitida pelo seu backend, como em criar verificação. O app nunca gera uma credencial sozinho e nunca guarda a chave de API.
• O App Bundle do seu app registrado e verificado em Integrações → Segurança. Sem ele, a sessão recusa abrir.

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

Configure o projeto

1. Declare as permissões

   A verificação captura documento e prova de vida, então precisa da câmera. A localização só entra se o seu fluxo tiver etapa de geolocalização.

   AndroidManifest.xml

   <uses-permission android:name="android.permission.INTERNET" />
   <uses-permission android:name="android.permission.CAMERA" />
   <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
   <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
   
2. Adicione o componente à tela

   activity_verificacao.xml

   <com.legitimuz.LegitimuzVerification
       android:id="@+id/verificacao"
       android:layout_width="match_parent"
       android:layout_height="match_parent" />
   
3. Peça a permissão de câmera antes de abrir

   Peça a câmera antes de iniciar a sessão. Se o titular chega na etapa de captura e a permissão ainda não foi concedida, o fluxo trava numa tela sem saída.

   VerificacaoActivity.kt

   private val pedirCamera = registerForActivityResult(
       ActivityResultContracts.RequestPermission()
   ) { concedida ->
       if (concedida) iniciarVerificacao() else mostrarExplicacaoDeCamera()
   }
   
   override fun onCreate(savedInstanceState: Bundle?) {
       super.onCreate(savedInstanceState)
       setContentView(binding.root)
   
       if (ContextCompat.checkSelfPermission(this, Manifest.permission.CAMERA)
           == PackageManager.PERMISSION_GRANTED
       ) {
           iniciarVerificacao()
       } else {
           pedirCamera.launch(Manifest.permission.CAMERA)
       }
   }
   
4. Busque a credencial no seu backend

   O seu app pede ao seu servidor, que chama a Legitimuz e devolve só a credencial.

   VerificacaoRepository.kt

   suspend fun obterCredencial(refId: String): String = withContext(Dispatchers.IO) {
       val resposta = api.criarVerificacao(CriarVerificacaoRequest(refId = refId))
       resposta.accessCredential
   }
   

   No seu backend, a origem precisa ser a do app, o entry volta como { "kind": "native", "access_credential": "..." }.

5. Abra a sessão

   VerificacaoActivity.kt

   private fun iniciarVerificacao() = lifecycleScope.launch {
       val credencial = repository.obterCredencial(refId = "pedido-4471")
   
       binding.verificacao.start(
           accessCredential = credencial,
           listener = object : LegitimuzListener {
               override fun onEvent(nome: String, dados: Map<String, Any?>) {
                   Log.i("Legitimuz", "evento: $nome")
               }
   
               override fun onComplete(status: String) {
                   // O desfecho confiável chega pelo webhook, no seu backend.
                   finish()
               }
   
               override fun onError(codigo: String, mensagem: String) {
                   Log.e("Legitimuz", "erro $codigo: $mensagem")
               }
           }
       )
   }
   

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.

Os eventos

Os eventos são os mesmos da web. O catálogo completo, com os payloads, está em eventos.

Evento	Quando dispara
session.started	o fluxo abriu a primeira etapa
session.stepTransitioned	o servidor trocou a etapa
document.capture.completed	a captura do documento foi enviada
liveness.completed	a prova de vida foi concluída
session.completed	o fluxo terminou
session.error	um erro ocorreu na sessão

Não decida nada a partir de session.completed. Ele diz que o titular terminou de interagir, não que a verificação foi aprovada. O desfecho confiável chega ao seu backend por verification.decided, onde o titular não pode interferir.

Casos de borda

O titular negou a câmera

Uma negativa simples pode ser pedida de novo. Depois de “não perguntar mais”, só as configurações do sistema resolvem, mande o titular para lá com um Intent:

startActivity(
    Intent(
        Settings.ACTION_APPLICATION_DETAILS_SETTINGS,
        Uri.fromParts("package", packageName, null)
    )
)

Explique por que a câmera é necessária antes de pedir de novo. Um pedido repetido sem contexto é negado de novo.

O app foi para segundo plano no meio da jornada

A sessão é retomável. Ao voltar, o componente busca o estado atual e reabre na etapa onde o titular parou, desde que a credencial não tenha expirado.

Não recrie a Activity a cada rotação: declare android:configChanges ou guarde o estado no ViewModel.

A credencial expirou

session.error chega com um código de credencial inválida. Peça uma credencial nova ao seu backend e comece outra sessão. Não tente reaproveitar a antiga.

A sessão recusa abrir

Quase sempre é origem. Confirme que o App Bundle do seu applicationId está registrado e verificado em Integrações → Segurança, e que a verificação foi criada com o integration_origin_public_id dessa origem.

Próximo passo

iOS

O mesmo fluxo em Swift.

Receber a decisão

Onde o desfecho realmente chega.