Best Practices
This page consolidates the most important guidelines for integrating and maintaining Unico's SDKs. Following these practices reduces integration errors, prevents security incidents, and ensures a smooth production rollout.
Getting started
Unico offers a reference app for each SDK in the reference-apps repository. Each app implements the full user journey.
SDKs evolve continuously to deliver greater security and new features. Applying updates promptly — especially critical ones — is essential. See Update Policy for timelines and obligations.
Check the current version for each platform through the respective release notes:
Update strategy
Your application likely loads multiple libraries alongside the Unico SDK. Upgrading several dependencies at once makes it difficult to identify the root cause of failures. Update the SDK in isolation and validate it in a staging environment before combining it with other changes.
When opening a support ticket for update issues, include:
- SDK language and implementation type (native or hybrid)
- Framework used
- Current version and target version
- API Key
- Description of the changes and steps to reproduce
- Results, errors, logs, screenshots, or videos
JWT security
The JWT returned after a successful capture is encrypted. Do not open, parse, or serialize it. Its internal structure may change without notice. Use it exclusively when submitting images to Unico's APIs.
For image previews, use the Base64 attribute provided alongside the JWT — never decode the JWT itself.
For security reasons, the JWT must be sent to Unico's backend within 10 minutes of capture. Packages submitted after this window are invalidated.
The JWT must be submitted only once. If an error occurs during submission, a new biometric capture must be performed — do not reuse the same JWT.
Testing guidelines
Running the SDK in virtual machines or emulators triggers security error codes (73006, 73600, 73400). Always test on physical devices to avoid misidentifying errors and unnecessary rework.
The Web SDK detects open DevTools as a potential fraud signal and invalidates the submission. Close DevTools before running end-to-end capture tests.
Perform tests in Unico's staging environment
Before going to production, run thorough tests in Unico's staging environment with realistic scenarios. Use staging-specific API Keys and configurations — never use production credentials in tests.
IDCloud's staging (UAT) environment applies the same security criteria as production. The guidelines below explain why, and how to test without interruptions.
Before — detected, but did not refuse Conditions outside the pattern of real-world usage were identified, but did not block the capture.
Now — detects and refuses The same conditions now result in a liveness rejection, with the same strictness as production.
Fidelity — similarity with production What passes in staging must behave the same way in production — preventing an integration approved in testing from failing unexpectedly after go-live.
By testing under conditions close to real-world usage, the security layers do not impact your development.
Development tooling that is not standard in the market triggers security validations, and the transaction may be blocked.
| Scenario | Status |
|---|---|
| Run the complete integration flow — capture, submission, API response, and return | ✅ Allowed |
| Test functional scenarios: UI/UX, performance, business errors | ✅ Allowed |
| Use a device in the standard configuration of an end user | ✅ Allowed |
| Integrate with backend, APIs, and data processing | ✅ Allowed |
| Use a device with root/jailbreak | ❌ Not allowed |
| Keep debug mode / USB debugging active | ❌ Not allowed |
| Use emulators or virtualization | ❌ Not allowed |
| Use virtual cameras or capture automation tools | ❌ Not allowed |
| Use tools that alter the connection | ❌ Not allowed |
| Have corporate MDM or active monitoring on the device | ❌ Not allowed |
| Use a sandbox in a container or virtual machine | ❌ Not allowed |
Any of these conditions may result in a liveness rejection.
Talk to the support team for guidance on configuring your environment. There is no exception, one-off waiver, or temporary flexibilization — Unico keeps staging equalized with production for as long as it deems necessary.
Platform-specific guidelines
Do not attempt to bridge the native Android or iOS SDKs inside a Flutter application. Native bridges frequently produce unmapped errors. Always use Unico's dedicated Flutter plugin.
When upgrading the Web SDK, delete the old resource files from your public folder before inserting the new ones. Files with identical names will not be overwritten automatically and can cause version conflicts.
Build artifacts from previous SDK versions can cause dependency errors after an update. Before building a new version:
- Flutter: delete
pubspec.lockand runflutter pub get - iOS: run
pod cache clean --allandpod install - Android: run
./gradlew clean
Exclude Unico SDK code from your obfuscation configuration. Obfuscating the SDK commonly causes failures in release builds that do not appear in debug builds. Refer to the platform-specific documentation for the required keep rules.
UX and performance
Structure the SDK flow into two distinct stages:
- Prepare — initialize the SDK while the page is loading (before user interaction).
- Open — launch the camera only when the user explicitly triggers the action.
Preparing the SDK in advance reduces perceived latency and improves the user experience significantly.
Production rollout
Before deploying to production, verify:
- Production API Keys and environment configurations are correct
- Rollback plan is defined and tested
- Log collection protocol is in place
- Support ticket procedures are documented for handling failures
- All validations passed in the staging environment