SDK de Flutter: Afegeix Verificació d'Identitat a la teva App (CA)

Una integració de l'SDK de Flutter per a la verificació d'identitat hauria de mantenir les credencials permanents i l'autorització final al vostre backend, mentre que l'aplicació mòbil llança un flux de captura natiu amb un testimoni de sessió de curta durada. L'SDK de Didit Flutter exposa una API de Dart sobre els SDK de verificació natius d'iOS i Android, retornant resultats tipificats de finalització, cancel·lació o fallada a l'aplicació. La decisió completa encara pertany al webhook del backend o al flux de recuperació.

Aquesta guia utilitza només mètodes i tipus de resultats de Dart verificats amb la font i les proves de l'SDK local actual. Els detalls de les dependències natives canvien entre versions, de manera que la configuració de la plataforma es descriu per responsabilitat i s'enllaça a la guia canònica de l'SDK en lloc de copiar un Podfile o un bloc de Gradle sensible a la versió.

Punts clau

• Creeu sessions de producció al backend. Mantingueu la clau API fora del dispositiu i envieu només el testimoni de sessió necessari per l'SDK.
• Utilitzeu el resultat tipificat de Dart per a l'experiència de l'usuari, no per a l'autorització. VerificationCompleted significa que el flux de l'SDK ha finalitzat; inspeccioneu l'estat per a la visualització i espereu la decisió autoritzada del backend.
• Gestioneu la cancel·lació, els errors tipificats i els errors inesperats de la plataforma per separat. Necessiten una recuperació i anàlisis diferents.
• Tracteu la configuració nativa com a infraestructura de llançament. Les claus de privadesa d'iOS, els drets de comunicació de camp proper (NFC), els objectius de desplegament, les dependències d'Android, l'embalatge i els permisos s'han de provar en dispositius reals.
• Dissenyar tot el cicle de vida. La creació de sessions, el traspàs d'aplicacions, la captura, la verificació de webhooks, els canvis d'estat idempotents, la revisió, els reintents i l'observabilitat formen una única integració.

Què fa l'SDK de Didit Flutter

El paquet didit_sdk encapsula els SDK natius d'iOS i Android darrere d'una interfície de Dart compartida. Llança la interfície d'usuari de verificació com un flux natiu a pantalla completa i torna quan l'usuari completa, cancel·la o troba un error.

L'SDK pot llançar fluxos de treball amb verificació d'identitat, detecció de vida i altres comprovacions configurades. El flux de treball determina quins passos apareixen; la crida de Flutter no els codifica.

La superfície pública de Dart rellevant per al cicle de vida és:

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

Per a la producció, preferiu startVerification amb un testimoni creat al backend. El mètode d'ID de flux de treball és més senzill, però dóna al backend menys control sobre paràmetres avançats.

Arquitectura: backend, aplicació Flutter, SDK i webhook

El flux de producció té quatre límits de confiança:

Component	Propietats	No ha de posseir
El vostre backend	Clau API, elecció del flux de treball, referència del client, creació de sessions, estat final del client	Interfície de càmera
Aplicació Flutter	Sol·licitud de traspàs, interfície d'usuari de càrrega i recuperació, llançament de l'SDK, anàlisis locals	Clau API permanent o autorització final
SDK de Didit Flutter	Captura nativa i flux de verificació configurat	Decisió d'elegibilitat del vostre producte
Webhook/treballador de recuperació	Ingesta de resultats autenticats, deduplicació, conciliació	Suposicions de client no verificades

La seqüència és:

1. L'aplicació Flutter autenticada demana al vostre backend que iniciï la verificació.
2. El vostre backend crea una sessió de verificació amb el flux de treball previst i una referència de client interna estable.
3. El backend retorna el session_token delimitat a l'aplicació.
4. L'aplicació passa aquest testimoni a DiditSdk.startVerification.
5. L'SDK presenta el flux natiu i retorna un resultat tipificat per a una experiència d'usuari immediata.
6. El vostre backend rep i verifica l'esdeveniment de resultat, concilia l'estat canònic i actualitza el client segons la vostra política.
7. L'aplicació llegeix l'estat del client del vostre backend abans de concedir l'accés o reclamar l'aprovació final.

Aquesta arquitectura no confia en una pantalla d'èxit al dispositiu.

Per al contracte del servidor i el límit d'esdeveniments, consulteu la guia d'avaluació de la integració de l'API de verificació d'identitat.

Instal·leu el paquet

Utilitzeu l'ordre del paquet en lloc de copiar una versió que pugui quedar obsoleta:

flutter pub add didit_sdk

A continuació, importeu la biblioteca pública:

import 'package:didit_sdk/sdk_flutter.dart';

Abans d'actualitzar, llegiu el registre de canvis i la documentació oficial de l'SDK de Flutter. Comproveu els requisits de la plataforma declarats amb la vostra aplicació i les imatges de CI.

Seguiu les instruccions de llançament de Flutter per a les dependències natives; barrejar versions arbitràries pot crear incompatibilitats.

Configureu iOS i Android

Responsabilitats d'iOS

La captura d'identitat pot utilitzar maquinari i dades protegides. Depenent del flux de treball configurat i de la variant de l'SDK, la configuració d'iOS pot requerir:

• un objectiu de desplegament adequat;
• descripcions d'ús de la càmera i el micròfon;
• descripció d'ús de la biblioteca de fotos si es permeten les càrregues;
• descripció d'ús de NFC i drets quan la lectura de xips està habilitada;
• configuració compatible de CocoaPods;
• capacitats de signatura i aprovisionament que coincideixin amb l'ús de NFC;
• fonts personalitzades registrades si es configura una font específica de l'aplicació.

Les cadenes de propòsit de privadesa que falten poden tancar una aplicació iOS. Proveu el flux de treball exacte en un dispositiu físic.

El suport de NFC pot augmentar l'objectiu de desplegament mínim o afegir dependències natives. Trieu la variant de l'SDK que coincideixi amb el vostre flux de treball i seguiu la documentació actual per a la seva configuració de Podfile.

Responsabilitats d'Android

A Android, comproveu:

• requisits mínims de SDK i Java;
• repositoris i dependències afegides pel connector;
• entrades de manifest de càmera, xarxa i NFC;
• comportament del permís de càmera en temps d'execució;
• compatibilitat amb Gradle i Kotlin;
• regles d'embalatge per a dependències natives o criptogràfiques;
• la variant de l'SDK all, core, autodetection o nfc;
• minificació de la compilació de llançament i comportament dels recursos.

El vostre producte encara necessita context de permisos, recuperació de denegació, accessibilitat i instruccions de suport. Proveu la denegació, la interrupció, la posada en segon pla, la rotació i la recreació de processos.

Creeu sessions al backend

El vostre backend hauria de cridar l'API de sessions utilitzant una clau API del servidor. Associeu cada sessió amb:

• el vostre identificador de client estable;
• el flux de treball seleccionat;
• entorn;
• comportament de la trucada de retorn o de retorn on escaigui;
• localització o dades de contacte requerides;
• detalls del client esperats on la política els utilitza;
• correlació interna i metadades de la política.

No incrusteu mai la clau API de Didit a Dart, actius de l'aplicació, configuració remota llegible o una sol·licitud mòbil.

Retorneu només el testimoni de sessió i l'estat de llançament mínim. Mantingueu-lo fora d'anàlisis, informes d'errors, registres, ús del porta-retalls i emmagatzematge a llarg termini.

Feu que les sol·licituds d'inici siguin idempotents

Un client pot tocar dues vegades, perdre la connectivitat després que el vostre backend creï una sessió o reobrir la pantalla mentre hi ha un intent actiu. Utilitzeu un identificador de sol·licitud estable i una lògica de backend que retorni l'intent adequat existent en lloc de crear duplicats desconnectats.

El botó de càrrega de la vostra aplicació hauria de bloquejar els tocs repetits obvis, però la idempotència del servidor segueix sent necessària perquè els clients reintenten i els processos es reinicien.

Inicia la verificació des de Dart

Aquest exemple complet de Dart utilitza només la importació de l'SDK, el mètode, les classes de resultats, els camps de sessió, l'enumeració d'estat i els camps d'error verificats a la font del paquet:

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 mostra l'estructura de tipus. Una aplicació real hauria d'actualitzar l'estat de la pantalla i actualitzar l'estat del backend, mai desbloquejar un compte només des d'aquesta funció.

Per què VerificationCompleted no sempre és aprovació

VerificationCompleted conté SessionData, el status del qual és un dels següents:

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

El flux de l'SDK pot finalitzar mentre la verificació roman pendent o rebutjada. Una revisió humana o una comprovació asíncrona també pot canviar l'estat del backend després que la crida de l'aplicació retorni. Anomeneu el vostre estat d'UI local "flux completat" en lloc de "identitat aprovada" fins que el vostre backend confirmi el resultat de la política.

No hi ha cap crida d'inicialització de Flutter

La superfície pública verificada de Flutter no exposa cap mètode d'inicialització separat. No copieu un patró d'inicialització natiu d'Android a Dart. Si Android informa de notInitialized a través del resultat de Flutter, tracteu-lo com un problema d'integració o de pont natiu i inspeccioneu la configuració del paquet.

Gestioneu els errors tipificats i la recuperació

Els tipus d'error verificats de l'SDK són:

Tipus d'error	Significat per a la política de l'aplicació	Recuperació segura
sessionExpired	El testimoni ja no pot iniciar la sessió prevista	Demaneu al backend una sessió vàlida nova
networkError	El flux natiu no ha pogut completar una operació de xarxa	Conserveu el context i oferiu un reintent limitat
cameraAccessDenied	L'accés a la càmera requerit no està disponible	Expliqueu per què és necessari i guieu la configuració o la ruta alternativa
notInitialized	La integració nativa d'Android o el pont no estan preparats	Registreu el context de la versió i investigueu la configuració
apiError	L'SDK o el servei han retornat un error a nivell d'API	Reintenteu només quan sigui segur; concilieu l'estat del backend
retryBlocked	El flux impedeix un altre intent automàtic	Atureu el bucle i seguiu la política del backend o del suport
unknown	L'error natiu no s'ha assignat a un tipus de Dart conegut	Conserveu una alternativa segura i dades de correlació

Les plataformes natives poden exposar detalls diferents. Mantingueu un camí unknown.

Separeu els errors dels resultats del client

Un error de xarxa no és una denegació; la denegació de la càmera no és frau; la cancel·lació no és una identitat fallida. Mantingueu les categories separades a:

• missatges d'usuari;
• regles de reintent;
• accés al producte;
• eines de suport;
• anàlisi;
• informes de frau i conversió.

Reintents limitats

Deixeu que el backend decideixi si una sessió existent pot continuar o si se'n requereix una de nova. Eviteu un bucle il·limitat que cridi repetidament l'SDK amb un testimoni caducat o bloquejat. Feu un seguiment del recompte d'intents i la causa sense registrar el testimoni o les proves d'identitat.

Utilitzeu els esdeveniments del backend com a font de veritat

L'SDK retorna un resultat de client compacte. Les proves completes i l'estat final arriben a través de la integració del servidor. El vostre gestor de webhooks hauria de:

1. rebre la sol·licitud en brut en la forma requerida per l'esquema de signatura documentat;
2. autenticar l'esdeveniment i validar la seva frescor;
3. deduplicar el seu identificador d'esdeveniment;
4. assignar-lo a la sessió i al client esperats;
5. evitar que els esdeveniments antics sobreescriguin l'estat terminal posterior;
6. recuperar l'estat canònic de la sessió quan es requereixi la conciliació;
7. aplicar la vostra política i persistir la raó;
8. tornar dins del pressupost de resposta del proveïdor;
9. processar el treball lent del servei de forma asíncrona.

Suposeu un lliurament almenys una vegada. Els esdeveniments duplicats i desordenats són un comportament ordinari del sistema distribuït. Emmagatzemeu l'esdeveniment del proveïdor i la transició interna per separat perquè una auditoria pugui reconstruir ambdós.

L'aplicació només hauria de consultar el vostre backend per al seu propi estat de producte o utilitzar el vostre canal normal en temps real. No hauria d'exposar una clau API del proveïdor per recuperar el registre final directament.

Construïu un cicle de vida de pantalla de Flutter resilient

Modeleu estats locals explícits

Una pantalla de verificació pot utilitzar:

• inactiu;
• sol·licitant sessió;
• llançant l'SDK;
• flux de l'SDK obert;
• conciliant la decisió del backend;
• esperant revisió;
• aprovat;
• rebutjat;
• error recuperable;
• cancel·lat.

Persistiu només allò que sigui segur. Després de la mort del procés, pregunteu al backend si ja existeix una sessió activa o finalitzada. No confieu en un booleà en memòria per decidir si s'ha de crear un altre intent.

Respecteu el cicle de vida del widget

Després de la trucada esperada, comproveu mounted abans de setState, els diàlegs o la navegació. Mantingueu l'estat del negoci fora de la UI transitòria.

Gestioneu la posada en segon pla i la cancel·lació

Proveu el canvi d'aplicació, el bloqueig de pantalla, la navegació i la terminació del procés. Definiu el comportament de represa, reinici i conciliació.

Disseny de recuperació de permisos

Expliqueu la necessitat de càmera o NFC. Després de la denegació permanent, mostreu una guia de configuració o una ruta alternativa accessible.

Configuració sense fuga de política

La superfície de DiditConfig de Flutter verificada fora de línia exposa languageCode, fontFamily, loggingEnabled, showCloseButton, showExitConfirmation, closeOnComplete, defaultDocumentCamera, defaultLivenessCamera, showDocumentCameraSwitchButton i showLivenessCameraSwitchButton. Els camps de la càmera utilitzen CameraLens.front o CameraLens.back; totes les opcions estan tipificades a Dart i assignades als SDK natius.

Mantingueu tres regles:

1. habiliteu el registre verbós només per al desenvolupament o una compilació de diagnòstic controlada;
2. no utilitzeu la configuració de la UI com a substitut de la política del backend;
3. proveu cada idioma admès, font personalitzada, comportament de tancament i política de càmera en ambdues plataformes, inclòs el comportament de reserva quan una lent o un recurs sol·licitats no estiguin disponibles.

La composició del flux de treball i la marca del producte pertanyen a la consola o al flux de treball gestionat pel backend en lloc d'un laberint de banderes de funcions mòbils. Això manté les vistes d'iOS, Android, web i de suport alineades.

Proveu la integració

Proves de Dart i widgets

Emboliqueu el llançament de l'SDK darrere d'un servei d'aplicacions perquè les proves de pantalla puguin retornar:

• completat i aprovat;
• completat i pendent;
• completat i rebutjat;
• cancel·lat;
• cada fallada tipificada;
• una excepció de plataforma inesperada llançada.

Assert neteja de l'estat de càrrega, comprovacions muntades, visibilitat de reintent, actualització del backend i categories d'anàlisi. No poseu testimonis de sessió reals als fitxers.

Proves d'integració nativa

Executeu compilacions de depuració i llançament en dispositius físics iOS i Android. Cobriu:

• permisos per primera vegada i prèviament decidits;
• càmeres compatibles i no compatibles;
• variants habilitades per NFC i no NFC on s'utilitzen;
• poca llum, desenfocament, enlluernament i orientació;
• connectivitat lenta, perduda i restaurada;
• posada en segon pla i recreació de processos;
• cancel·lació i llançament repetit;
• caducitat de la sessió i bloqueig de reintent;
• diferents localitzacions, escalat de fonts, lectors de pantalla i moviment reduït;
• signatura d'aplicacions, minificació i resolució de dependències de producció.

Un emulador és útil per a proves d'estat i errors, però no pot representar totes les condicions de càmera, NFC, biomètrics i integritat del dispositiu.

Proves de backend d'extrem a extrem

Utilitzeu casos de sandbox deterministes per a cada estat de client documentat. Reexecuteu esdeveniments de prova signats, envieu duplicats desordenats, retarde la revisió i concilieu després d'un webhook perdut simulat. Confirmeu que l'aplicació mai concedeix accés abans que canviï l'estat del vostre backend.

Per al disseny de proves biomètriques i els límits d'atac, consulteu la guia de proves de vida.

Llista de verificació de seguretat i privadesa

Abans del llançament, confirmeu que:

• les credencials permanents del proveïdor existeixen només al backend;
• l'aplicació rep un testimoni de sessió delimitat a través d'un canal autenticat;
• els testimonis i les proves estan absents dels registres, anàlisis, URL i informes d'errors;
• les sol·licituds de creació del backend són idempotents i estan vinculades a una referència de client estable;
• la finalització del client mai concedeix directament un dret;
• les proves de signatura, frescor, duplicat, ordenació i conciliació del webhook passen;
• les descripcions de privadesa d'iOS i els recorreguts de permisos d'Android utilitzen text de propòsit clar;
• les capacitats i variants de NFC coincideixen amb el flux de treball i la signatura de la versió;
• el registre de depuració està desactivat per a la producció;
• la retenció, el consentiment, l'avís de privadesa, la supressió i les rutes de suport coincideixen amb el vostre rol i la llei;
• l'SDK, la dependència nativa, el sistema operatiu i la compatibilitat del dispositiu es controlen després del llançament;
• les decisions de reversió i actualització forçada tenen propietaris.

Errors comuns d'integració de l'SDK de Flutter

Enviament de la clau API a Dart

Les aplicacions mòbils no poden protegir una credencial de servidor permanent. Creeu sessions al vostre backend i passeu un testimoni delimitat.

Confiar en la trucada de retorn completada

El resultat del client és l'estat de la interfície d'usuari. Confirmeu l'estat autoritzat i apliqueu la política al backend.

Inventar mètodes d'una altra plataforma

Flutter no exposa tots els mètodes de l'SDK natiu amb el mateix nom. Compileu amb el paquet i comproveu la seva font pública de Dart abans d'escriure codi d'integració.

Copiar configuració nativa obsoleta

Les variants de l'SDK, els objectius de desplegament i la configuració del gestor de paquets canvien. Seguiu la documentació de la versió instal·lada i registreu-la a la vostra llista de verificació de la versió mòbil.

Tractar cada error com a rebuig

Els errors de permís, xarxa, caducitat, API, cancel·lació i decisió del client requereixen una recuperació i anàlisis diferents.

Provar només en un emulador

La càmera, NFC, permisos, signatura i dependències natives requereixen cobertura en dispositius físics i versions de llançament.

Ús de Didit en un flux de treball d'identitat de Flutter

L'SDK de Didit Flutter es mostra com a gratuït. Pot llançar fluxos de treball que continguin verificació d'identitat, detecció de vida i altres comprovacions configurades, mentre que els equips gestionen els camins condicionals a través de l'Orquestrador de Fluxos de Treball.

Les tarifes dels mòduls publicades estan disponibles a la pàgina de preus. L'SDK gestiona l'experiència de captura nativa; el vostre backend segueix sent responsable de la creació de sessions, la gestió de resultats autenticats, l'estat del client i les decisions del producte.

Preguntes freqüents

Quin mètode inicia la verificació?

Per a una sessió de producció creada al backend, truqueu a DiditSdk.startVerification(sessionToken). L'SDK també exposa DiditSdk.startVerificationWithWorkflow(...) per al mode d'integració d'ID de flux de treball més senzill.

L'aplicació Flutter ha de contenir la clau API de Didit?

No. Mantingueu la clau API al backend. L'aplicació només hauria de rebre el testimoni de sessió delimitat necessari per al seu intent de verificació.

VerificationCompleted significa aprovat?

No necessàriament. El seu estat de sessió pot ser aprovat, pendent o rebutjat. Utilitzeu el resultat per a l'estat immediat de la interfície i confirmeu la decisió autoritzada a través del vostre backend.

Com s'ha de gestionar la cancel·lació?

Tracteu-la com un resultat d'usuari diferent. Conserveu l'estat de la sessió del backend, oferiu una ruta clara de represa o reinici segons la política i no etiqueteu la cancel·lació com a frau o rebuig.

L'SDK de Flutter té un mètode d'inicialització?

L'API pública verificada de Dart no exposa cap mètode d'inicialització separat. Seguiu les instruccions de configuració nativa del paquet i utilitzeu els mètodes d'inici documentats.

Flutter pot utilitzar NFC per a documents d'identitat?

L'SDK natiu pot suportar NFC quan la variant de paquet seleccionada, el dispositiu, la configuració d'iOS o Android, les capacitats de signatura i el flux de treball ho permeten. Seguiu la documentació de la versió actual i proveu-lo en dispositius físics.

Què ha de fer l'aplicació mentre un cas està en revisió?

Mostreu un estat pendent verídic, permeteu que el client surti amb seguretat i llegiu l'estat final del producte del vostre backend quan arribi el resultat autenticat.

Referències principals

• Documentació de l'SDK de Didit Flutter
• Repositori de codi font de l'SDK de Didit Flutter
• Documentació de l'API de sessions de Didit
• Documentació de webhooks de Didit
• Documentació de Flutter: integració de plataformes
• OWASP Mobile Application Security Verification Standard

Una sòlida integració de l'SDK de Flutter manté cada límit explícit: el backend crea l'intent, l'aplicació llança un flux natiu delimitat, els resultats tipificats impulsen la recuperació, els esdeveniments de servidor autenticats impulsen l'estat del client i les proves en dispositius reals demostren que els permisos, el cicle de vida, les dependències natives i els camins d'error funcionen fora de la demostració del "camí feliç".