SDK Flutter: Adicionar Verificação de Identidade à Sua Aplicação (PT-PT)

Uma integração do SDK Flutter para verificação de identidade deve manter credenciais permanentes e autorização final no seu backend, enquanto a aplicação móvel lança 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 iOS e Android, devolvendo à aplicação resultados tipificados de conclusão, cancelamento ou falha. A decisão completa ainda pertence ao webhook do backend ou ao fluxo de recuperação.

Este guia utiliza apenas métodos Dart e tipos de resultados verificados contra a fonte e testes do SDK local atual. Os detalhes das dependências nativas mudam entre as versões, por isso a configuração da plataforma é descrita por responsabilidade e ligada 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 para o SDK.
• Utilize o resultado Dart tipificado para a experiência do utilizador, não para autorização. VerificationCompleted significa que o fluxo do SDK terminou; inspecione o estado para exibição e aguarde a decisão autorizada do backend.
• Lide com cancelamento, falhas tipificadas e erros de plataforma inesperados separadamente. Eles precisam de diferentes recuperações e análises.
• Trate a configuração nativa como infraestrutura de lançamento. Chaves de privacidade iOS, autorizações de comunicação de campo próximo (NFC), alvos de implementação, dependências Android, empacotamento e permissões devem ser testados em dispositivos reais.
• Desenhe todo o ciclo de vida. Criação de sessão, entrega da aplicação, 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 SDKs nativos iOS e Android por trás de uma interface Dart partilhada. Ele lança a interface de utilizador de verificação como um fluxo nativo de ecrã inteiro e retorna quando o utilizador completa, cancela ou encontra um erro.

O SDK pode lançar fluxos de trabalho com Verificação de ID, Deteção de Vivacidade e outras verificações configuradas. O fluxo de trabalho determina quais passos aparecem; a chamada Flutter não os 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 do fluxo de trabalho é mais simples, mas dá ao backend menos controlo sobre parâmetros avançados.

Arquitetura: backend, aplicação Flutter, SDK e webhook

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

Componente	Possui	Não deve possuir
O 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âmara
Aplicação Flutter	Pedido de entrega, UI de carregamento e recuperação, lançamento do SDK, análises locais	Chave da API permanente ou autorização final
SDK Flutter da Didit	Captura nativa e fluxo de verificação configurado	A sua decisão de autorização do produto
Worker de Webhook/Recuperação	Ingestão de resultados autenticados, deduplicação, reconciliação	Suposições de cliente não verificadas

A sequência é:

1. A aplicação Flutter autenticada pede ao seu backend para iniciar a verificação.
2. 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.
3. O backend devolve o session_token delimitado à aplicação.
4. A aplicação passa esse token para DiditSdk.startVerification.
5. O SDK apresenta o fluxo nativo e devolve um resultado tipificado para experiência imediata do utilizador.
6. O seu backend recebe e verifica o evento de resultado, reconcilia o estado canónico e atualiza o cliente de acordo com a sua política.
7. A aplicação lê o estado do cliente do seu backend antes de conceder acesso ou reivindicar aprovação final.

Esta arquitetura não confia num ecrã de sucesso no dispositivo.

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

Instalar o pacote

Utilize o comando do pacote em vez de copiar uma versão que pode ficar 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 declarados da plataforma em relação à sua aplicação e imagens CI.

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

Configurar iOS e Android

Responsabilidades iOS

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

• um alvo de implementação apropriado;
• descrições de uso da câmara e microfone;
• descrição de uso da biblioteca de fotos se uploads forem permitidos;
• descrição de uso e direitos NFC quando a leitura de chip estiver ativada;
• configuração CocoaPods compatível;
• capacidades de assinatura e provisionamento que correspondam ao uso de NFC;
• fontes personalizadas registadas se uma fonte específica da aplicação estiver configurada.

A falta de strings de propósito de privacidade pode encerrar uma aplicação iOS. Teste o fluxo de trabalho exato num dispositivo físico.

O suporte a NFC pode aumentar o alvo de implementaçã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 a sua configuração Podfile.

Responsabilidades Android

No Android, verifique:

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

O 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

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

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

Nunca incorpore a chave da API Didit em Dart, ativos da aplicação, configuração remota legível ou um pedido móvel.

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

Torne os pedidos de início idempotentes

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

O botão de carregamento da sua aplicação deve bloquear toques repetidos óbvios, mas a idempotência do lado do servidor continua necessária porque os clientes tentam novamente e os processos reiniciam.

Iniciar verificação a partir de Dart

Este exemplo completo de Dart utiliza 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. Uma aplicação real deve atualizar o estado do ecrã e atualizar o estado 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 da aplicação retornar. Nomeie o seu estado de UI local como “fluxo concluído” em vez de “identidade aprovada” até que o seu backend confirme o resultado da política.

Não há chamada de inicialização 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 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.

Lidar com erros tipificados e recuperação

Os tipos de erro verificados do SDK são:

Tipo de erro	Significado para a política da aplicação	Recuperação segura
sessionExpired	O token não pode mais iniciar a sessão pretendida	Pedir ao backend uma nova sessão válida
networkError	O fluxo nativo não conseguiu completar uma operação de rede	Preservar o contexto e oferecer uma nova tentativa limitada
cameraAccessDenied	O acesso à câmara necessário não está disponível	Explicar por que é necessário e guiar as configurações ou rota alternativa
notInitialized	A integração nativa do Android ou a ponte não está pronta	Registar o contexto de lançamento e investigar a configuração
apiError	O SDK ou serviço retornou uma falha de nível de API	Tentar novamente apenas quando seguro; reconciliar o estado do backend
retryBlocked	O fluxo impede outra tentativa automática	Parar o ciclo e seguir a política do backend ou de suporte
unknown	O erro nativo não mapeou para um tipo Dart conhecido	Preservar um fallback seguro e dados de correlação

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

Separar erros de resultados do cliente

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

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

Novas tentativas limitadas

Deixe o backend decidir se uma sessão existente pode continuar ou se uma nova é necessária. Evite um ciclo ilimitado que chama repetidamente o SDK com um token expirado ou bloqueado. Acompanhe a contagem e a causa da tentativa sem registar o token ou a prova de identidade.

Use eventos de backend como fonte da verdade

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

1. receber o pedido bruto na forma exigida pelo esquema de assinatura documentado;
2. autenticar o evento e validar a sua frescura;
3. desduplicar o seu identificador de evento;
4. mapeá-lo para a sessão e cliente esperados;
5. impedir que eventos mais antigos sobreponham o estado terminal posterior;
6. recuperar o estado canónico da sessão quando a reconciliação é necessária;
7. aplicar a sua política e persistir a razão;
8. retornar dentro do orçamento de resposta do provedor;
9. processar trabalho lento a jusante assincronamente.

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

A aplicação deve consultar o seu backend apenas para o seu próprio estado de produto ou utilizar o seu canal em tempo real normal. Não deve expor uma chave da API do provedor para recuperar o registo final diretamente.

Construir um ciclo de vida de ecrã Flutter resiliente

Modelar estados locais explícitos

Um ecrã de verificação pode usar:

• ocioso;
• solicitando sessão;
• lançando o 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 concluída já existe. Não confie num booleano na memória para decidir se cria outra tentativa.

Respeitar o ciclo de vida do widget

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

Lidar com segundo plano e cancelamento

Teste a troca de aplicações, bloqueio de ecrã, navegação e término de processo. Defina o comportamento de retomar, reiniciar e reconciliar.

Projetar recuperação de permissões

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

Configuração sem fuga 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âmara usam CameraLens.front ou CameraLens.back; todas as opções são tipificadas em Dart e mapeadas para os SDKs nativos.

Mantenha três regras:

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

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

Teste a integração

Testes Dart e de widgets

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

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

Afirme a limpeza do estado de carregamento, verificações de montagem, 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 compilações de depuração e lançamento em dispositivos físicos iOS e Android. Inclua:

• permissões pela primeira vez e previamente decididas;
• câmaras suportadas e não suportadas;
• variantes habilitadas para NFC e não NFC, quando usadas;
• baixa luminosidade, 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 localizações, dimensionamento de fonte, leitores de ecrã e movimento reduzido;
• assinatura da aplicação, minificação e resolução de dependências de produção.

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

Testes de backend de ponta a ponta

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

Para design de testes biométricos e limites de ataque, consulte o guia de testes de vivacidade.

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

Antes do lançamento, confirme que:

• credenciais de provedor permanentes existem apenas no backend;
• a aplicação recebe um token de sessão delimitado por um canal autenticado;
• tokens e evidências estão ausentes de registos, análises, URLs e relatórios de falhas;
• os pedidos de criação do backend são idempotentes e vinculados a uma referência de cliente estável;
• a conclusão do cliente nunca concede diretamente uma autorização;
• testes de assinatura, frescura, duplicação, ordenação e reconciliação de webhook são aprovados;
• descrições de privacidade iOS e jornadas de permissão Android usam texto de propósito claro;
• as capacidades e variantes NFC correspondem ao fluxo de trabalho e à assinatura de lançamento;
• o registo de depuração está desativado para produção;
• retenção, consentimento, aviso de privacidade, exclusão e caminhos de suporte correspondem à sua função e lei;
• compatibilidade de SDK, dependência nativa, SO e dispositivo são monitorizadas após o lançamento;
• decisões de reversão e atualização forçada têm proprietários.

Erros comuns de integração do SDK Flutter

Enviar a chave da API em Dart

As aplicações móveis não podem proteger uma credencial de servidor permanente. Crie sessões no seu backend e passe um token delimitado.

Confiar no callback concluído

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

Inventar 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 a sua fonte pública Dart antes de escrever código de integração.

Copiar configuração nativa obsoleta

As variantes do SDK, os alvos de implementação e a configuração do gestor de pacotes mudam. Siga a documentação da versão instalada e registe-a na sua lista de verificação de lançamento móvel.

Tratar cada erro como recusa

Permissão, rede, expiração, falha de API, cancelamento e decisão do cliente exigem diferentes recuperações e análises.

Testar apenas num emulador

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

Usar a Didit num fluxo de trabalho de identidade Flutter

O SDK Flutter da Didit está listado como gratuito. Pode lançar fluxos de trabalho contendo Verificação de ID, Deteção de Vivacidade e outras verificações configuradas, enquanto as equipas gerem caminhos condicionais através do Orquestrador de Fluxo de Trabalho.

As taxas de módulo publicadas estão disponíveis na página de preços. O SDK trata da experiência de captura nativa; o seu backend permanece responsável pela criação da sessão, tratamento de resultados autenticados, estado do cliente e decisões de 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.

A aplicação Flutter deve conter a chave da API Didit?

Não. Mantenha a chave da API no backend. A aplicação deve receber apenas o token de sessão delimitado necessário para a sua tentativa de verificação.

VerificationCompleted significa aprovado?

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

Como deve ser tratado o cancelamento?

Trate-o como um resultado distinto do utilizador. Preserve o estado da sessão do backend, ofereça um caminho claro para retomar ou reiniciar 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 Dart verificada 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, dispositivo, configuração iOS ou Android, capacidades de assinatura e fluxo de trabalho o permitem. Siga a documentação da versão atual e teste em dispositivos físicos.

O que a aplicação deve fazer enquanto um caso está em revisão?

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

Referências primárias

• Documentação do SDK Flutter da Didit
• Repositório de código do SDK Flutter da Didit
• Documentação da API de sessão da Didit
• Documentação de webhook da Didit
• Documentação Flutter: integração de plataforma
• OWASP Mobile Application Security Verification Standard

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