Blog · 28 de julho de 2026

Integração Flutter: Verificação de Identidade no Seu Aplicativo (PT-BR)

Um guia para desenvolvedores sobre como adicionar verificação de identidade a um aplicativo Flutter com o SDK da Didit: configuração nativa, sessões criadas no backend, tratamento de resultados Dart, erros tipados, webhooks.

Por Didit28 de julho de 2026Atualizado 28 de jul. de 2026

flutter-sdk-identity-verification-integration-guide.png

A integração de um SDK Flutter para verificação de identidade deve manter credenciais permanentes e autorização final no seu backend, enquanto o aplicativo móvel inicia um fluxo de captura nativo com um token de sessão de curta duração. O SDK Flutter da Didit expõe uma API Dart sobre os SDKs de verificação nativos do iOS e Android, retornando resultados tipados de conclusão, cancelamento ou falha para o aplicativo. A decisão completa ainda pertence ao webhook do backend ou ao fluxo de recuperação.

Este guia usa apenas métodos Dart e tipos de resultado verificados em relação à fonte e aos testes do SDK local atual. Os detalhes de dependência nativa mudam entre os lançamentos, então a configuração da plataforma é descrita por responsabilidade e vinculada ao guia canônico do SDK, em vez de copiar um Podfile ou bloco Gradle sensível à versão.

Principais conclusões

Crie sessões de produção no backend. Mantenha a chave da API fora do dispositivo e envie apenas o token de sessão necessário pelo SDK.
Use o resultado Dart tipado para a experiência do usuário, não para autorização. VerificationCompleted significa que o fluxo do SDK terminou; inspecione o status para exibição e aguarde a decisão autoritária do backend.
Lide com cancelamento, falhas tipadas e erros inesperados da plataforma separadamente. Eles precisam de recuperação e análise diferentes.
Trate a configuração nativa como infraestrutura de lançamento. Chaves de privacidade do iOS, entitlements de comunicação de campo próximo (NFC), metas de implantação, dependências do Android, empacotamento e permissões devem ser testados em dispositivos reais.
Projete todo o ciclo de vida. Criação de sessão, entrega do aplicativo, captura, verificação de webhook, mudanças de estado idempotentes, revisão, novas tentativas e observabilidade formam uma única integração.

O que o SDK Flutter da Didit faz

O pacote didit_sdk envolve os SDKs nativos do iOS e Android por trás de uma interface Dart compartilhada. Ele inicia a interface de usuário de verificação como um fluxo nativo em tela cheia e retorna quando o usuário completa, cancela ou encontra um erro.

O SDK pode iniciar fluxos de trabalho com Verificação de Identidade, Detecção de Vivacidade e outras verificações configuradas. O fluxo de trabalho determina quais etapas aparecem; a chamada Flutter não as codifica.

A superfície pública Dart relevante para o ciclo de vida é:

DiditSdk.startVerification(token, config: ...)
DiditSdk.startVerificationWithWorkflow(workflowId, vendorData: ..., config: ...)

Para produção, prefira startVerification com um token criado no backend. O método de ID de fluxo de trabalho é mais simples, mas dá ao backend menos controle sobre parâmetros avançados.

Arquitetura: backend, aplicativo Flutter, SDK e webhook

O fluxo de produção tem quatro limites de confiança:

Componente	Possui	Não deve possuir
Seu backend	Chave da API, escolha do fluxo de trabalho, referência do cliente, criação de sessão, estado final do cliente	Interface da câmera
Aplicativo Flutter	Solicitação de entrega, UI de carregamento e recuperação, inicialização do SDK, análise local	Chave de API permanente ou autorização final
SDK Flutter da Didit	Captura nativa e fluxo de verificação configurado	Decisão de entitlement do seu produto
Trabalhador de webhook/recuperação	Ingestão de resultados autenticados, deduplicação, reconciliação	Suposições não verificadas do cliente

A sequência é:

O aplicativo Flutter conectado pede ao seu backend para iniciar a verificação.
Seu backend cria uma sessão de verificação com o fluxo de trabalho pretendido e uma referência interna estável do cliente.
O backend retorna o session_token com escopo para o aplicativo.
O aplicativo passa esse token para DiditSdk.startVerification.
O SDK apresenta o fluxo nativo e retorna um resultado tipado para uma experiência imediata do usuário.
Seu backend recebe e verifica o evento de resultado, reconcilia o estado canônico e atualiza o cliente de acordo com sua política.
O aplicativo lê o estado do cliente do seu backend antes de conceder acesso ou reivindicar aprovação final.

Esta arquitetura não confia em uma tela de sucesso no dispositivo.

Para o contrato do lado do servidor e o limite de eventos, consulte o guia de avaliação de integração da API de verificação de identidade.

Instalar o pacote

Use o comando do pacote em vez de copiar uma versão que pode se tornar obsoleta:

flutter pub add didit_sdk

Em seguida, importe a biblioteca pública:

import 'package:didit_sdk/sdk_flutter.dart';

Antes de atualizar, leia o changelog e a documentação oficial do SDK Flutter. Verifique os requisitos de plataforma declarados em relação ao seu aplicativo e às imagens de CI.

Siga as instruções de lançamento do Flutter para dependências nativas; a mistura de versões arbitrárias pode criar incompatibilidade.

Configurar iOS e Android

Responsabilidades do iOS

A captura de identidade pode usar hardware e dados protegidos. Dependendo do fluxo de trabalho configurado e da variante do SDK, a configuração do iOS pode exigir:

uma meta de implantação apropriada;
descrições de uso da câmera e do microfone;
descrição de uso da biblioteca de fotos se uploads forem permitidos;
descrição de uso e entitlements de NFC quando a leitura de chip estiver ativada;
configuração compatível do CocoaPods;
capacidades de assinatura e provisionamento que correspondam ao uso do NFC;
fontes personalizadas registradas se uma fonte específica do aplicativo for configurada.

A falta de strings de propósito de privacidade pode encerrar um aplicativo iOS. Teste o fluxo de trabalho exato em um dispositivo físico.

O suporte a NFC pode aumentar a meta de implantação mínima ou adicionar dependências nativas. Escolha a variante do SDK que corresponde ao seu fluxo de trabalho e siga a documentação atual para sua configuração de Podfile.

Responsabilidades do Android

No Android, verifique:

requisitos mínimos de SDK e Java;
repositórios e dependências adicionadas pelo plugin;
entradas de manifesto de câmera, rede e NFC;
comportamento de permissão de câmera em tempo de execução;
compatibilidade com Gradle e Kotlin;
regras de empacotamento para dependências nativas ou criptográficas;
a variante do SDK all, core, autodetection ou nfc;
minificação de build de lançamento e comportamento de recursos.

Seu produto ainda precisa de contexto de permissão, recuperação de negação, acessibilidade e instruções de suporte. Teste negação, interrupção, segundo plano, rotação e recriação de processo.

Crie sessões no backend

Seu backend deve chamar a API de sessão usando uma chave de API do lado do servidor. Associe cada sessão com:

seu identificador de cliente estável;
o fluxo de trabalho selecionado;
ambiente;
callback ou comportamento de retorno, quando aplicável;
localidade ou detalhes de contato exigidos;
detalhes esperados do cliente onde a política os utiliza;
correlação interna e metadados de política.

Nunca incorpore a chave da API Didit em Dart, ativos do aplicativo, configuração remota legível ou uma solicitação móvel.

Retorne apenas o token de sessão e o estado de lançamento mínimo. Mantenha-o fora de análises, relatórios de falhas, logs, uso da área de transferência e armazenamento de longo prazo.

Torne as solicitações de início idempotentes

Um cliente pode tocar duas vezes, perder a conectividade depois que seu backend cria uma sessão ou reabrir a tela enquanto uma tentativa está ativa. Use um identificador de solicitação estável e lógica de backend que retorne a tentativa apropriada existente, em vez de criar duplicatas desconectadas.

O botão de carregamento do seu aplicativo deve bloquear toques repetidos óbvios, mas a idempotência do lado do servidor permanece necessária porque os clientes repetem e os processos reiniciam.

Inicie a verificação a partir do Dart

Este exemplo completo de Dart usa apenas a importação do SDK, método, classes de resultado, campos de sessão, enum de status e campos de erro verificados na fonte do pacote:

import 'package:didit_sdk/sdk_flutter.dart';

Future<void> runIdentityVerification(String sessionToken) async {
  try {
    final result = await DiditSdk.startVerification(
      sessionToken,
      config: const DiditConfig(
        loggingEnabled: false,
      ),
    );

    switch (result) {
      case VerificationCompleted(:final session):
        switch (session.status) {
          case VerificationStatus.approved:
            print('Flow completed with approved client status.');
          case VerificationStatus.pending:
            print('Flow completed and still needs a backend decision.');
          case VerificationStatus.declined:
            print('Flow completed with declined client status.');
        }
        print('Session ID: ${session.sessionId}');
        return;
      case VerificationCancelled():
        print('The user cancelled the verification flow.');
        return;
      case VerificationFailed(:final error):
        print('SDK error: ${error.type.name}: ${error.message}');
        return;
    }
  } catch (error, stackTrace) {
    print('Unexpected platform error: $error');
    print(stackTrace);
  }
}

O exemplo mostra a estrutura do tipo. Um aplicativo real deve atualizar o estado da tela e atualizar o status do backend, nunca desbloquear uma conta apenas a partir desta função.

Por que `VerificationCompleted` nem sempre é aprovação

VerificationCompleted contém SessionData, cujo status é um de:

VerificationStatus.approved;
VerificationStatus.pending;
VerificationStatus.declined.

O fluxo do SDK pode terminar enquanto a verificação permanece pendente ou recusada. Uma revisão humana ou uma verificação assíncrona também pode alterar o estado do backend depois que a chamada do aplicativo retorna. Nomeie seu estado de UI local como “fluxo concluído” em vez de “identidade aprovada” até que seu backend confirme o resultado da política.

Não há chamada de inicialização do Flutter

A superfície pública verificada do Flutter não expõe nenhum método de inicialização separado. Não copie um padrão de inicialização nativo do Android para o Dart. Se o Android relatar notInitialized através do resultado do Flutter, trate-o como um problema de integração ou ponte nativa e inspecione a configuração do pacote.

Lide com erros tipados e recuperação

Os tipos de erro verificados do SDK são:

Tipo de erro	Significado para a política do aplicativo	Recuperação segura
`sessionExpired`	O token não pode mais iniciar a sessão pretendida	Peça ao backend uma nova sessão válida
`networkError`	O fluxo nativo não conseguiu concluir uma operação de rede	Preserve o contexto e ofereça uma nova tentativa limitada
`cameraAccessDenied`	O acesso à câmera necessário está indisponível	Explique por que é necessário e guie as configurações ou rota alternativa
`notInitialized`	A integração nativa ou a ponte do Android não está pronta	Registre o contexto de lançamento e investigue a configuração
`apiError`	O SDK ou serviço retornou uma falha no nível da API	Tente novamente apenas quando seguro; reconcilie o estado do backend
`retryBlocked`	O fluxo impede outra tentativa automática	Pare o loop e siga a política de backend ou suporte
`unknown`	O erro nativo não mapeou para um tipo Dart conhecido	Preserve um fallback seguro e dados de correlação

As plataformas nativas podem expor detalhes diferentes. Mantenha um caminho unknown.

Separe erros de resultados do cliente

Uma falha de rede não é uma recusa; a negação da câmera não é fraude; o cancelamento não é uma identidade falha. Mantenha as categorias separadas em:

mensagens do usuário;
regras de nova tentativa;
acesso ao produto;
ferramentas de suporte;
análises;
relatórios de fraude e conversão.

Tentativas limitadas

Deixe o backend decidir se uma sessão existente pode continuar ou se uma nova é necessária. Evite um loop ilimitado que chama repetidamente o SDK com um token expirado ou bloqueado. Rastreie a contagem de tentativas e a causa sem registrar o token ou a evidência de identidade.

Use eventos de backend como fonte da verdade

O SDK retorna um resultado de cliente compacto. Evidências completas e estado final chegam através da integração do lado do servidor. Seu manipulador de webhook deve:

receber a solicitação bruta na forma exigida pelo esquema de assinatura documentado;
autenticar o evento e validar a atualidade;
deduplicar seu identificador de evento;
mapeá-lo para a sessão e o cliente esperados;
impedir que eventos mais antigos sobrescrevam o estado terminal posterior;
recuperar o estado canônico da sessão quando a reconciliação for necessária;
aplicar sua política e persistir o motivo;
retornar dentro do orçamento de resposta do provedor;
processar trabalho lento a jusante assincronamente.

Assuma a entrega pelo menos uma vez. Eventos duplicados e fora de ordem são um comportamento comum de sistema distribuído. Armazene o evento do provedor e a transição interna separadamente para que uma auditoria possa reconstruir ambos.

O aplicativo deve pesquisar seu backend apenas para o estado do seu próprio produto ou usar seu canal em tempo real normal. Ele não deve expor uma chave de API do provedor para recuperar o registro final diretamente.

Construa um ciclo de vida de tela Flutter resiliente

Modele estados locais explícitos

Uma tela de verificação pode usar:

ocioso;
solicitando sessão;
lançando SDK;
fluxo do SDK aberto;
reconciliando decisão do backend;
aguardando revisão;
aprovado;
recusado;
erro recuperável;
cancelado.

Persista apenas o que é seguro. Após a morte do processo, pergunte ao backend se uma sessão ativa ou finalizada já existe. Não confie em um booleano em memória para decidir se deve criar outra tentativa.

Respeite o ciclo de vida do widget

Após a chamada aguardada, verifique mounted antes de setState, diálogos ou navegação. Mantenha o estado do negócio fora da UI transitória.

Lide com segundo plano e cancelamento

Teste a troca de aplicativos, bloqueio de tela, navegação e término de processo. Defina o comportamento de retomada, reinício e reconciliação.

Projete a recuperação de permissão

Explique a necessidade de câmera ou NFC. Após negação permanente, mostre orientação de configurações ou uma rota alternativa acessível.

Configuração sem vazamento de política

A superfície DiditConfig do Flutter verificada offline expõe languageCode, fontFamily, loggingEnabled, showCloseButton, showExitConfirmation, closeOnComplete, defaultDocumentCamera, defaultLivenessCamera, showDocumentCameraSwitchButton e showLivenessCameraSwitchButton. Os campos da câmera usam CameraLens.front ou CameraLens.back; todas as opções são tipadas em Dart e mapeadas para os SDKs nativos.

Mantenha três regras:

ative o registro verboso apenas para desenvolvimento ou uma construção de diagnóstico controlada;
não use a configuração da UI como substituto da política de backend;
teste cada idioma suportado, fonte personalizada, comportamento de fechamento e política de câmera em ambas as plataformas, incluindo o comportamento de fallback quando uma lente ou ativo solicitado estiver indisponível.

A composição do fluxo de trabalho e a marca do produto pertencem ao console ou ao fluxo de trabalho gerenciado pelo backend, em vez de um labirinto de sinalizadores de recursos móveis. Isso mantém as visualizações de iOS, Android, web e suporte alinhadas.

Teste a integração

Testes Dart e de widget

Envolva o lançamento do SDK por trás de um serviço de aplicativo para que os testes de tela possam retornar:

concluído e aprovado;
concluído e pendente;
concluído e recusado;
cancelado;
cada falha tipada;
uma exceção de plataforma inesperada.

Afirme a limpeza do estado de carregamento, verificações montadas, visibilidade de nova tentativa, atualização do backend e categorias de análise. Não coloque tokens de sessão reais em fixtures.

Testes de integração nativa

Execute builds de depuração e lançamento em dispositivos físicos iOS e Android. Cubra:

permissões pela primeira vez e previamente decididas;
câmeras suportadas e não suportadas;
variantes habilitadas para NFC e não NFC, onde usadas;
pouca luz, desfoque, brilho e orientação;
conectividade lenta, perdida e restaurada;
segundo plano e recriação de processo;
cancelamento e lançamento repetido;
expiração de sessão e bloqueio de nova tentativa;
diferentes localidades, escala de fonte, leitores de tela e movimento reduzido;
assinatura do aplicativo, minificação e resolução de dependência de produção.

Um emulador é útil para testes de estado e erro, mas não pode representar todas as condições de câmera, NFC, biométricas e integridade do dispositivo.

Testes de backend de ponta a ponta

Use casos de sandbox determinísticos para cada estado de cliente documentado. Reproduza eventos de teste assinados, envie duplicatas fora de ordem, atrase a revisão e reconcilie após um webhook simulado perdido. Confirme que o aplicativo nunca concede acesso antes que o estado do seu backend mude.

Para design de teste biométrico e limites de ataque, consulte o guia de teste de vivacidade.

Lista de verificação de segurança e privacidade

Antes do lançamento, confirme que:

credenciais permanentes do provedor existem apenas no backend;
o aplicativo recebe um token de sessão com escopo por um canal autenticado;
tokens e evidências estão ausentes de logs, análises, URLs e relatórios de falhas;
as solicitações de criação de backend são idempotentes e vinculadas a uma referência de cliente estável;
a conclusão do cliente nunca concede diretamente um entitlement;
testes de assinatura de webhook, atualidade, duplicação, ordenação e reconciliação são aprovados;
descrições de privacidade do iOS e jornadas de permissão do Android usam texto de propósito claro;
capacidades e variantes de NFC correspondem ao fluxo de trabalho e à assinatura de lançamento;
o registro de depuração está desativado para produção;
retenção, consentimento, aviso de privacidade, exclusão e caminhos de suporte correspondem ao seu papel e à lei;
SDK, dependência nativa, OS e compatibilidade do dispositivo são monitorados após o lançamento;
as decisões de rollback e atualização forçada têm proprietários.

Erros comuns de integração do SDK Flutter

Enviando a chave da API em Dart

Aplicativos móveis não podem proteger uma credencial de servidor permanente. Crie sessões no seu backend e passe um token com escopo.

Confiando no callback de conclusão

O resultado do cliente é o estado da interface do usuário. Confirme o status autoritário e aplique a política no backend.

Inventando métodos de outra plataforma

O Flutter não expõe todos os métodos do SDK nativo com o mesmo nome. Compile contra o pacote e verifique sua fonte pública Dart antes de escrever o código de integração.

Copiando configuração nativa obsoleta

Variantes do SDK, metas de implantação e configuração do gerenciador de pacotes mudam. Siga a documentação para a versão instalada e registre-a na sua lista de verificação de lançamento móvel.

Tratando todo erro como recusa

Permissão, rede, expiração, falha da API, cancelamento e decisão do cliente exigem recuperação e análise diferentes.

Testando apenas em um emulador

Câmera, NFC, permissões, assinatura e dependências nativas exigem cobertura de dispositivo físico e build de lançamento.

Usando Didit em um fluxo de trabalho de identidade Flutter

O SDK Flutter da Didit é listado como gratuito. Ele pode iniciar fluxos de trabalho contendo Verificação de Identidade, Detecção de Vivacidade e outras verificações configuradas, enquanto as equipes gerenciam caminhos condicionais através do Workflow Orchestrator.

As taxas de módulo publicadas estão disponíveis na página de preços. O SDK gerencia a experiência de captura nativa; seu backend continua responsável pela criação da sessão, tratamento autenticado de resultados, estado do cliente e decisões do produto.

Perguntas frequentes

Qual método inicia a verificação?

Para uma sessão de produção criada no backend, chame DiditSdk.startVerification(sessionToken). O SDK também expõe DiditSdk.startVerificationWithWorkflow(...) para o modo de integração de ID de fluxo de trabalho mais simples.

O aplicativo Flutter deve conter a chave da API Didit?

Não. Mantenha a chave da API no backend. O aplicativo deve receber apenas o token de sessão com escopo necessário para sua tentativa de verificação.

`VerificationCompleted` significa aprovado?

Não necessariamente. Seu status de sessão pode ser aprovado, pendente ou recusado. Use o resultado para o estado imediato da interface e confirme a decisão autoritária através do seu backend.

Como o cancelamento deve ser tratado?

Trate-o como um resultado de usuário distinto. Preserve o estado da sessão do backend, ofereça um caminho claro de retomada ou reinício de acordo com a política e não rotule o cancelamento como fraude ou recusa.

O SDK Flutter tem um método de inicialização?

A API pública verificada do Dart não expõe nenhum método de inicialização separado. Siga as instruções de configuração nativa do pacote e use os métodos de início documentados.

O Flutter pode usar NFC para documentos de identidade?

O SDK nativo pode suportar NFC quando a variante de pacote selecionada, o dispositivo, a configuração iOS ou Android, as capacidades de assinatura e o fluxo de trabalho o permitem. Siga a documentação de lançamento atual e teste em dispositivos físicos.

O que o aplicativo deve fazer enquanto um caso está em revisão?

Mostre um estado pendente verdadeiro, permita que o cliente saia com segurança e leia o estado final do produto do seu backend quando o resultado autenticado chegar.

Referências primárias

Uma forte integração do SDK Flutter mantém cada limite explícito: o backend cria a tentativa, o aplicativo lança um fluxo nativo com escopo, resultados tipados impulsionam a recuperação, eventos de servidor autenticados impulsionam o estado do cliente e testes em dispositivos reais provam que permissões, ciclo de vida, dependências nativas e caminhos de falha funcionam fora da demonstração de caminho feliz.

Continue lendo