Blog · 28 juillet 2026

Intégration Flutter pour la vérification d'identité (FR)

Un guide pour les développeurs sur l'ajout de la vérification d'identité à une application Flutter avec le SDK Didit : configuration native, sessions créées par le backend, gestion des résultats Dart, erreurs typées, webhooks.

Par Didit28 juillet 2026Mis à jour le 28 juil. 2026

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

L'intégration d'un SDK Flutter pour la vérification d'identité doit conserver les informations d'identification permanentes et l'autorisation finale sur votre backend, tandis que l'application mobile lance un flux de capture natif avec un jeton de session de courte durée. Le SDK Flutter Didit expose une API Dart unique sur les SDK de vérification natifs iOS et Android, renvoyant à l'application des résultats typés de complétion, d'annulation ou d'échec. La décision finale appartient toujours au webhook ou au flux de récupération du backend.

Ce guide utilise uniquement des méthodes et des types de résultats Dart vérifiés par rapport à la source et aux tests du SDK local actuel. Les détails des dépendances natives changent d'une version à l'autre, la configuration de la plateforme est donc décrite par responsabilité et liée au guide canonique du SDK au lieu de copier un Podfile ou un bloc Gradle sensible à la version.

Points clés à retenir

Créez des sessions de production sur le backend. Gardez la clé API hors de l'appareil et n'envoyez que le jeton de session dont le SDK a besoin.
Utilisez le résultat typé Dart pour l'expérience utilisateur, pas pour l'autorisation. VerificationCompleted signifie que le flux du SDK est terminé ; inspectez le statut pour l'affichage et attendez la décision faisant autorité du backend.
Gérez séparément l'annulation, les échecs typés et les erreurs de plateforme inattendues. Ils nécessitent une récupération et une analyse différentes.
Traitez la configuration native comme une infrastructure de version. Les clés de confidentialité iOS, les autorisations de communication en champ proche (NFC), les cibles de déploiement, les dépendances Android, le packaging et les autorisations doivent être testés sur de vrais appareils.
Concevez le cycle de vie complet. La création de session, le transfert d'application, la capture, la vérification du webhook, les changements d'état idempotents, la révision, les tentatives et l'observabilité forment une seule intégration.

Ce que fait le SDK Flutter de Didit

Le package didit_sdk enveloppe les SDK natifs iOS et Android derrière une interface Dart partagée. Il lance l'interface utilisateur de vérification comme un flux natif plein écran et retourne un résultat lorsque l'utilisateur termine, annule ou rencontre une erreur.

Le SDK peut lancer des flux de travail avec la vérification d'identité, la détection du vivant et d'autres vérifications configurées. Le flux de travail détermine les étapes qui apparaissent ; l'appel Flutter ne les code pas en dur.

La surface Dart publique pertinente pour le cycle de vie est :

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

Pour la production, préférez startVerification avec un jeton créé par le backend. La méthode d'ID de flux de travail est plus simple mais donne moins de contrôle au backend sur les paramètres avancés.

Architecture : backend, application Flutter, SDK et webhook

Le flux de production comporte quatre limites de confiance :

Composant	Possède	Ne doit pas posséder
Votre backend	Clé API, choix du flux de travail, référence client, création de session, état client final	Interface de la caméra
Application Flutter	Demande de transfert, UI de chargement et de récupération, lancement du SDK, analyse locale	Clé API permanente ou autorisation finale
SDK Flutter Didit	Capture native et flux de vérification configuré	Décision d'autorisation de votre produit
Webhook/travailleur de récupération	Ingestion de résultats authentifiés, déduplication, réconciliation	Hypothèses client non vérifiées

La séquence est la suivante :

L'application Flutter connectée demande à votre backend de commencer la vérification.
Votre backend crée une session de vérification avec le flux de travail prévu et la référence client interne stable.
Le backend renvoie le session_token scopé à l'application.
L'application transmet ce jeton à DiditSdk.startVerification.
Le SDK présente le flux natif et renvoie un résultat typé pour une expérience utilisateur immédiate.
Votre backend reçoit et vérifie l'événement de résultat, réconcilie l'état canonique et met à jour le client selon votre politique.
L'application lit l'état client de votre backend avant d'accorder l'accès ou de revendiquer l'approbation finale.

Cette architecture ne fait pas confiance à un écran de succès sur l'appareil.

Pour le contrat côté serveur et la limite d'événements, consultez le guide d'évaluation de l'intégration de l'API de vérification d'identité.

Installer le package

Utilisez la commande du package plutôt que de copier une version qui pourrait devenir obsolète :

flutter pub add didit_sdk

Importez ensuite la bibliothèque publique :

import 'package:didit_sdk/sdk_flutter.dart';

Avant de mettre à niveau, lisez le journal des modifications et la documentation officielle du SDK Flutter. Vérifiez les exigences de plateforme déclarées par rapport à votre application et à vos images CI.

Suivez les instructions de publication de Flutter pour les dépendances natives ; le mélange de versions arbitraires peut créer une incompatibilité.

Configurer iOS et Android

Responsabilités iOS

La capture d'identité peut utiliser du matériel et des données protégés. Selon le flux de travail configuré et la variante du SDK, la configuration iOS peut nécessiter :

une cible de déploiement appropriée ;
des descriptions d'utilisation de la caméra et du microphone ;
une description d'utilisation de la photothèque si les téléchargements sont autorisés ;
une description d'utilisation NFC et des autorisations lorsque la lecture de puce est activée ;
une configuration CocoaPods compatible ;
des capacités de signature et un provisionnement correspondant à l'utilisation NFC ;
des polices personnalisées enregistrées si une police spécifique à l'application est configurée.

Des chaînes de confidentialité manquantes peuvent entraîner la fermeture d'une application iOS. Testez le flux de travail exact sur un appareil physique.

La prise en charge NFC peut augmenter la cible de déploiement minimale ou ajouter des dépendances natives. Choisissez la variante du SDK qui correspond à votre flux de travail et suivez la documentation actuelle pour sa configuration Podfile.

Responsabilités Android

Sur Android, vérifiez :

les exigences minimales du SDK et de Java ;
les dépôts et dépendances ajoutés par le plugin ;
les entrées du manifeste de la caméra, du réseau et du NFC ;
le comportement de l'autorisation de caméra d'exécution ;
la compatibilité Gradle et Kotlin ;
les règles de packaging pour les dépendances natives ou cryptographiques ;
la variante du SDK all, core, autodetection ou nfc ;
la minification de la version de publication et le comportement des ressources.

Votre produit a toujours besoin d'un contexte d'autorisation, d'une récupération en cas de refus, d'accessibilité et d'instructions de support. Testez le refus, l'interruption, la mise en arrière-plan, la rotation et la recréation de processus.

Créer des sessions sur le backend

Votre backend doit appeler l'API de session en utilisant une clé API côté serveur. Associez chaque session à :

votre identifiant client stable ;
le flux de travail sélectionné ;
l'environnement ;
le comportement de rappel ou de retour, le cas échéant ;
la langue ou les coordonnées requises ;
les détails client attendus lorsque la politique les utilise ;
les métadonnées de corrélation interne et de politique.

N'intégrez jamais la clé API Didit dans Dart, les ressources de l'application, la configuration distante lisible ou une requête mobile.

Ne renvoyez que le jeton de session et l'état de lancement minimum. Gardez-le hors des analyses, des rapports d'erreurs, des journaux, de l'utilisation du presse-papiers et du stockage à long terme.

Rendre les requêtes de démarrage idempotentes

Un client peut taper deux fois, perdre la connectivité après la création d'une session par votre backend, ou rouvrir l'écran pendant qu'une tentative est active. Utilisez un identifiant de requête stable et une logique backend qui renvoie la tentative appropriée existante plutôt que de créer des doublons déconnectés.

Le bouton de chargement de votre application doit bloquer les taps répétés évidents, mais l'idempotence côté serveur reste nécessaire car les clients relancent et les processus redémarrent.

Démarrer la vérification depuis Dart

Cet exemple Dart complet utilise uniquement l'importation du SDK, la méthode, les classes de résultats, les champs de session, l'énumération de statut et les champs d'erreur vérifiés dans la source du package :

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);
  }
}

L'exemple montre la structure du type. Une application réelle devrait mettre à jour l'état de l'écran et rafraîchir le statut du backend, et ne jamais déverrouiller un compte à partir de cette seule fonction.

Pourquoi `VerificationCompleted` n'est pas toujours une approbation

VerificationCompleted contient SessionData, dont le status est l'un des suivants :

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

Le flux du SDK peut se terminer alors que la vérification est toujours en attente ou refusée. Un examen humain ou une vérification asynchrone peut également modifier l'état du backend après le retour de l'appel de l'application. Nommez votre état d'interface utilisateur local « flux terminé » plutôt que « identité approuvée » jusqu'à ce que votre backend confirme le résultat de la politique.

Il n'y a pas d'appel d'initialisation Flutter

La surface publique Flutter vérifiée n'expose aucune méthode d'initialisation distincte. Ne copiez pas un modèle d'initialisation natif Android dans Dart. Si Android signale notInitialized via le résultat Flutter, traitez-le comme un problème d'intégration ou de pont natif et inspectez la configuration du package.

Gérer les erreurs typées et la récupération

Les types d'erreurs vérifiés du SDK sont :

Type d'erreur	Signification pour la politique de l'application	Récupération sûre
`sessionExpired`	Le jeton ne peut plus démarrer la session prévue	Demandez au backend une nouvelle session valide
`networkError`	Le flux natif n'a pas pu terminer une opération réseau	Préserver le contexte et offrir une nouvelle tentative limitée
`cameraAccessDenied`	L'accès à la caméra requis n'est pas disponible	Expliquez pourquoi il est nécessaire et guidez les paramètres ou le chemin alternatif
`notInitialized`	L'intégration native Android ou le pont n'est pas prêt	Enregistrez le contexte de la version et examinez la configuration
`apiError`	Le SDK ou le service a renvoyé un échec au niveau de l'API	Réessayez uniquement si cela est sûr ; réconciliez l'état du backend
`retryBlocked`	Le flux empêche une autre tentative automatique	Arrêtez la boucle et suivez la politique du backend ou du support
`unknown`	L'erreur native ne correspondait pas à un type Dart connu	Conservez un chemin de secours sûr et des données de corrélation

Les plateformes natives peuvent exposer des détails différents. Gardez un chemin unknown.

Séparer les erreurs des résultats client

Une panne de réseau n'est pas un refus ; le refus de la caméra n'est pas une fraude ; l'annulation n'est pas une identité échouée. Gardez les catégories séparées dans :

les messages utilisateur ;
les règles de nouvelle tentative ;
l'accès au produit ;
les outils de support ;
les analyses ;
les rapports de fraude et de conversion.

Tentatives limitées

Laissez le backend décider si une session existante peut continuer ou si une nouvelle est requise. Évitez une boucle illimitée qui appelle à plusieurs reprises le SDK avec un jeton expiré ou bloqué. Suivez le nombre et la cause des tentatives sans enregistrer le jeton ou les preuves d'identité.

Utiliser les événements backend comme source de vérité

Le SDK renvoie un résultat client compact. Les preuves complètes et l'état final arrivent via l'intégration côté serveur. Votre gestionnaire de webhook doit :

recevoir la requête brute sous la forme requise par le schéma de signature documenté ;
authentifier l'événement et valider la fraîcheur ;
dédupliquer son identifiant d'événement ;
le mapper à la session et au client attendus ;
empêcher les événements plus anciens d'écraser l'état terminal ultérieur ;
récupérer l'état canonique de la session lorsque la réconciliation est requise ;
appliquer votre politique et persister la raison ;
retourner dans le budget de réponse du fournisseur ;
traiter le travail aval lent de manière asynchrone.

Supposons une livraison au moins une fois. Les événements dupliqués et désordonnés sont un comportement ordinaire des systèmes distribués. Stockez l'événement du fournisseur et la transition interne séparément afin qu'un audit puisse reconstituer les deux.

L'application ne doit interroger votre backend que pour son propre état de produit ou utiliser votre canal en temps réel normal. Elle ne doit pas exposer une clé API de fournisseur pour récupérer directement l'enregistrement final.

Construire un cycle de vie d'écran Flutter résilient

Modéliser les états locaux explicites

Un écran de vérification peut utiliser :

inactif ;
demande de session ;
lancement du SDK ;
flux SDK ouvert ;
réconciliation de la décision du backend ;
en attente de révision ;
approuvé ;
refusé ;
erreur récupérable ;
annulé.

Ne persistez que ce qui est sûr. Après la mort du processus, demandez au backend si une session active ou terminée existe déjà. Ne vous fiez pas à un booléen en mémoire pour décider de créer une autre tentative.

Respecter le cycle de vie du widget

Après l'appel attendu, vérifiez mounted avant setState, les dialogues ou la navigation. Gardez l'état métier en dehors de l'interface utilisateur transitoire.

Gérer la mise en arrière-plan et l'annulation

Testez le changement d'application, le verrouillage de l'écran, la navigation et la terminaison du processus. Définissez le comportement de reprise, de redémarrage et de réconciliation.

Concevoir la récupération des autorisations

Expliquez le besoin de la caméra ou du NFC. Après un refus permanent, affichez des conseils de configuration ou un itinéraire alternatif accessible.

Configuration sans fuite de politique

La surface Flutter DiditConfig vérifiée hors ligne expose languageCode, fontFamily, loggingEnabled, showCloseButton, showExitConfirmation, closeOnComplete, defaultDocumentCamera, defaultLivenessCamera, showDocumentCameraSwitchButton et showLivenessCameraSwitchButton. Les champs de la caméra utilisent CameraLens.front ou CameraLens.back ; toutes les options sont typées dans Dart et mappées aux SDK natifs.

Gardez trois règles :

activez la journalisation détaillée uniquement pour le développement ou une version de diagnostic contrôlée ;
n'utilisez pas la configuration de l'interface utilisateur comme substitut à la politique du backend ;
testez chaque langue prise en charge, police personnalisée, comportement de fermeture et politique de caméra sur les deux plateformes, y compris le comportement de secours lorsqu'un objectif ou une ressource demandée n'est pas disponible.

La composition du flux de travail et l'image de marque du produit appartiennent à la console ou au flux de travail géré par le backend plutôt qu'à un labyrinthe de fonctionnalités mobiles. Cela permet d'aligner les vues iOS, Android, web et de support.

Tester l'intégration

Tests Dart et widgets

Enveloppez le lancement du SDK derrière un service d'application afin que les tests d'écran puissent renvoyer :

terminé et approuvé ;
terminé et en attente ;
terminé et refusé ;
annulé ;
chaque échec typé ;
une exception de plateforme inattendue lancée.

Affirmez le nettoyage de l'état de chargement, les vérifications montées, la visibilité de la nouvelle tentative, le rafraîchissement du backend et les catégories d'analyse. Ne mettez pas de vrais jetons de session dans les fixtures.

Tests d'intégration native

Exécutez les versions de débogage et de publication sur des appareils physiques iOS et Android. Couvrez :

les autorisations pour la première fois et celles déjà décidées ;
les caméras prises en charge et non prises en charge ;
les variantes NFC activées et non NFC, le cas échéant ;
faible luminosité, flou, éblouissement et orientation ;
connectivité lente, perdue et rétablie ;
mise en arrière-plan et recréation de processus ;
annulation et lancement répété ;
expiration de session et blocage des tentatives ;
différentes locales, mise à l'échelle des polices, lecteurs d'écran et mouvement réduit ;
signature de l'application, minification et résolution des dépendances de production.

Un émulateur est utile pour les tests d'état et d'erreur, mais ne peut pas représenter toutes les conditions de caméra, NFC, biométrie et intégrité de l'appareil.

Tests backend de bout en bout

Utilisez des cas de sandbox déterministes pour chaque état client documenté. Rejouez les événements de test signés, envoyez des doublons dans le désordre, retardez la révision et réconciliez après un webhook manqué simulé. Confirmez que l'application n'accorde jamais l'accès avant que l'état de votre backend ne change.

Pour la conception des tests biométriques et les limites d'attaque, consultez le guide de test du vivant.

Liste de contrôle de sécurité et de confidentialité

Avant la publication, confirmez que :

les informations d'identification permanentes du fournisseur existent uniquement sur le backend ;
l'application reçoit un jeton de session scopé via un canal authentifié ;
les jetons et les preuves sont absents des journaux, des analyses, des URL et des rapports d'erreurs ;
les requêtes de création backend sont idempotentes et liées à une référence client stable ;
l'achèvement client n'accorde jamais directement un droit ;
les tests de signature de webhook, de fraîcheur, de doublons, d'ordre et de réconciliation réussissent ;
les descriptions de confidentialité iOS et les parcours d'autorisation Android utilisent un texte de but clair ;
les capacités et variantes NFC correspondent au flux de travail et à la signature de la publication ;
la journalisation de débogage est désactivée pour la production ;
la rétention, le consentement, la politique de confidentialité, la suppression et les chemins de support correspondent à votre rôle et à la loi ;
le SDK, la dépendance native, l'OS et la compatibilité de l'appareil sont surveillés après le lancement ;
les décisions de rollback et de mise à niveau forcée ont des propriétaires.

Erreurs courantes d'intégration du SDK Flutter

Expédition de la clé API dans Dart

Les applications mobiles ne peuvent pas protéger un identifiant de serveur permanent. Créez des sessions sur votre backend et transmettez un jeton scopé.

Faire confiance au rappel terminé

Le résultat client est l'état de l'interface utilisateur. Confirmez le statut faisant autorité et appliquez la politique sur le backend.

Inventer des méthodes à partir d'une autre plateforme

Flutter n'expose pas toutes les méthodes du SDK natif sous le même nom. Compilez contre le package et vérifiez sa source Dart publique avant d'écrire le code d'intégration.

Copier une configuration native obsolète

Les variantes du SDK, les cibles de déploiement et la configuration du gestionnaire de packages changent. Suivez la documentation de la version installée et enregistrez-la dans votre liste de contrôle de publication mobile.

Traiter chaque erreur comme un refus

Les autorisations, le réseau, l'expiration, les échecs d'API, l'annulation et les décisions client nécessitent des récupérations et des analyses différentes.

Tester uniquement sur un émulateur

La caméra, le NFC, les autorisations, la signature et les dépendances natives nécessitent une couverture sur un appareil physique et une version de publication.

Utilisation de Didit dans un flux de travail d'identité Flutter

Le SDK Flutter de Didit est gratuit. Il peut lancer des flux de travail contenant la vérification d'identité, la détection du vivant et d'autres vérifications configurées, tandis que les équipes gèrent les chemins conditionnels via l'Orchestrateur de flux de travail.

Les tarifs des modules publiés sont disponibles sur la page de tarification. Le SDK gère l'expérience de capture native ; votre backend reste responsable de la création de session, de la gestion authentifiée des résultats, de l'état client et des décisions produit.

Questions fréquemment posées

Quelle méthode démarre la vérification ?

Pour une session de production créée par le backend, appelez DiditSdk.startVerification(sessionToken). Le SDK expose également DiditSdk.startVerificationWithWorkflow(...) pour le mode d'intégration plus simple avec ID de flux de travail.

L'application Flutter doit-elle contenir la clé API Didit ?

Non. Gardez la clé API sur le backend. L'application ne doit recevoir que le jeton de session scopé requis pour sa tentative de vérification.

`VerificationCompleted` signifie-t-il approuvé ?

Pas nécessairement. Son statut de session peut être approuvé, en attente ou refusé. Utilisez le résultat pour l'état immédiat de l'interface et confirmez la décision faisant autorité via votre backend.

Comment gérer l'annulation ?

Traitez-la comme un résultat utilisateur distinct. Préservez l'état de la session backend, offrez un chemin de reprise ou de redémarrage clair selon la politique, et n'étiquetez pas l'annulation comme une fraude ou un refus.

Le SDK Flutter a-t-il une méthode d'initialisation ?

L'API Dart publique vérifiée n'expose aucune méthode d'initialisation distincte. Suivez les instructions de configuration native du package et utilisez les méthodes de démarrage documentées.

Flutter peut-il utiliser le NFC pour les documents d'identité ?

Le SDK natif peut prendre en charge le NFC lorsque la variante de package sélectionnée, l'appareil, la configuration iOS ou Android, les capacités de signature et le flux de travail l'activent tous. Suivez la documentation de la version actuelle et testez sur des appareils physiques.

Que doit faire l'application pendant qu'un cas est en cours d'examen ?

Affichez un état d'attente véridique, permettez au client de partir en toute sécurité et lisez l'état final du produit depuis votre backend lorsque le résultat authentifié arrive.

Références principales

Une intégration solide du SDK Flutter rend chaque limite explicite : le backend crée la tentative, l'application lance un flux natif scopé, les résultats typés guident la récupération, les événements de serveur authentifiés guident l'état du client, et les tests sur des appareils réels prouvent que les autorisations, le cycle de vie, les dépendances natives et les chemins d'échec fonctionnent en dehors de la démonstration du chemin heureux.

Continue ta lecture