Bonnes pratiques
Cette page regroupe les recommandations les plus importantes pour intégrer et maintenir les SDK d'Unico. Suivre ces pratiques réduit les erreurs d'intégration, prévient les incidents de sécurité et garantit un déploiement en production sans accroc.
Prise en main
Unico propose une application de référence pour chaque SDK dans le dépôt reference-apps. Chaque application met en œuvre le parcours utilisateur complet.
Les SDK évoluent en permanence pour offrir une sécurité accrue et de nouvelles fonctionnalités. Appliquer les mises à jour rapidement — en particulier les critiques — est essentiel. Consultez la Politique de mise à jour pour les délais et les obligations.
Vérifiez la version actuelle pour chaque plateforme dans les notes de version correspondantes :
- Notes de version Android
- Notes de version iOS
- Notes de version Flutter
- Web — Notes de version du SDK de Parcours
Stratégie de mise à jour
Votre application charge probablement plusieurs bibliothèques en parallèle du SDK Unico. Mettre à niveau plusieurs dépendances à la fois rend difficile l'identification de la cause des échecs. Mettez à jour le SDK de manière isolée et validez-le dans un environnement de préproduction avant de le combiner avec d'autres changements.
Lors de l'ouverture d'un ticket de support pour des problèmes de mise à jour, incluez :
- Langage du SDK et type d'implémentation (natif ou hybride)
- Framework utilisé
- Version actuelle et version cible
- Clé API
- Description des modifications et étapes pour reproduire le problème
- Résultats, erreurs, journaux, captures d'écran ou vidéos
Sécurité JWT
Le JWT retourné après une capture réussie est chiffré. Ne l'ouvrez pas, ne l'analysez pas et ne le sérialisez pas. Sa structure interne peut changer sans préavis. Utilisez-le exclusivement lors de la soumission d'images aux API d'Unico.
Pour les aperçus d'images, utilisez l'attribut Base64 fourni avec le JWT — ne décodez jamais le JWT lui-même.
Pour des raisons de sécurité, le JWT doit être envoyé au backend d'Unico dans les 10 minutes suivant la capture. Les paquets soumis après ce délai sont invalidés.
Le JWT ne doit être soumis qu'une seule fois. En cas d'erreur lors de la soumission, une nouvelle capture biométrique doit être effectuée — ne réutilisez pas le même JWT.
Directives de test
L'exécution du SDK dans des machines virtuelles ou des émulateurs déclenche des codes d'erreur de sécurité (73006, 73600, 73400). Testez toujours sur des appareils physiques pour éviter d'identifier incorrectement les erreurs et les retouches inutiles.
Le SDK Web détecte les DevTools ouverts comme un signal potentiel de fraude et invalide la soumission. Fermez les DevTools avant d'exécuter des tests de capture de bout en bout.
Effectuez des tests dans l'environnement de préproduction d'Unico
Avant de passer en production, effectuez des tests approfondis dans l'environnement de préproduction d'Unico avec des scénarios réalistes. Utilisez des clés API et des configurations spécifiques à la préproduction — n'utilisez jamais des identifiants de production lors des tests.
L'environnement de préproduction (UAT) d'IDCloud applique les mêmes critères de sécurité que la production. Les directives ci-dessous expliquent pourquoi et comment tester sans interruptions.
Avant — détectait, mais ne refusait pas Les conditions en dehors du schéma d'un usage réel étaient identifiées, mais n'empêchaient pas la capture.
Maintenant — détecte et refuse Les mêmes conditions entraînent désormais un refus de la preuve de vie, avec la même rigueur qu'en production.
Fidélité — similarité avec la production Ce qui passe en préproduction doit fonctionner de la même manière en production — évitant qu'une intégration validée en tests échoue de façon inattendue après la mise en production.
En testant dans des conditions proches de l'usage réel, les couches de sécurité n'impactent pas votre développement.
Les outils de développement qui ne sont pas les standards du marché déclenchent des validations de sécurité, et la transaction peut être bloquée.
| Scénario | Statut |
|---|---|
| Exécuter le flux complet de l'intégration — capture, envoi, réponse de l'API et retour | ✅ Autorisé |
| Tester des scénarios fonctionnels : UI/UX, performance, erreurs métier | ✅ Autorisé |
| Utiliser un appareil dans la configuration standard d'un utilisateur final | ✅ Autorisé |
| Intégrer le backend, les APIs et le traitement des données | ✅ Autorisé |
| Utiliser un appareil rooté/jailbreaké | ❌ Non autorisé |
| Laisser le mode debug / le débogage USB actif | ❌ Non autorisé |
| Utiliser des émulateurs ou de la virtualisation | ❌ Non autorisé |
| Utiliser des caméras virtuelles ou des outils d'automatisation de la capture | ❌ Non autorisé |
| Utiliser des outils qui modifient la connexion | ❌ Non autorisé |
| Avoir un MDM d'entreprise ou une surveillance active sur l'appareil | ❌ Non autorisé |
| Utiliser un sandbox dans un conteneur ou une machine virtuelle | ❌ Non autorisé |
Chacune de ces conditions peut entraîner un refus de la preuve de vie.
Contactez l'équipe de support pour obtenir des conseils sur la configuration de votre environnement. Il n'y a aucune exception, autorisation ponctuelle ou assouplissement temporaire — Unico maintient la préproduction alignée sur la production aussi longtemps qu'elle le juge nécessaire.
Recommandations spécifiques par plateforme
N'essayez pas de faire le pont avec les SDK natifs Android ou iOS dans une application Flutter. Les ponts natifs produisent fréquemment des erreurs non mappées. Utilisez toujours le plugin Flutter dédié d'Unico.
Lors de la mise à niveau du SDK Web, supprimez les anciens fichiers de ressources de votre dossier public avant d'insérer les nouveaux. Les fichiers portant des noms identiques ne seront pas écrasés automatiquement et peuvent entraîner des conflits de version.
Les artefacts de compilation des versions précédentes du SDK peuvent provoquer des erreurs de dépendances après une mise à jour. Avant de compiler une nouvelle version :
- Flutter : supprimez
pubspec.locket exécutezflutter pub get - iOS : exécutez
pod cache clean --alletpod install - Android : exécutez
./gradlew clean
Excluez le code du SDK Unico de votre configuration d'obfuscation. L'obfuscation du SDK provoque fréquemment des échecs dans les builds de release qui n'apparaissent pas dans les builds de debug. Consultez la documentation spécifique à la plateforme pour les règles keep requises.
UX et performance
Structurez le flux du SDK en deux étapes distinctes :
- Préparer — initialisez le SDK pendant le chargement de la page (avant l'interaction de l'utilisateur).
- Ouvrir — lancez la caméra uniquement lorsque l'utilisateur déclenche explicitement l'action.
Préparer le SDK à l'avance réduit la latence perçue et améliore significativement l'expérience utilisateur.
Déploiement en production
Avant de déployer en production, vérifiez :
- Les clés API de production et les configurations d'environnement sont correctes
- Le plan de retour arrière est défini et testé
- Le protocole de collecte des journaux est en place
- Les procédures de tickets de support sont documentées pour gérer les échecs
- Toutes les validations ont été réalisées avec succès dans l'environnement de préproduction