Skip to main content

Best Practices for SDK Implementation

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​

Use a PoC to facilitate your implementation

Unico offers Proofs of Concept (PoCs) with functional code examples across all supported languages. They demonstrate the expected method sequences and integration patterns. Access available PoCs through the client portal support ticket system.

Always keep your SDKs updated

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.

Identify the latest version available

Check the current version for each platform through the respective release notes:

Update strategy​

Avoid updating the SDK and other components simultaneously

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.

Getting help with an SDK update

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​

Do not manipulate the JWT object
Do not open or modify the encrypted JWT

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.

Send the JWT within 10 minutes
warning

For security reasons, the JWT must be sent to Unico's backend within 10 minutes of capture. Packages submitted after this window are invalidated.

Send the JWT only once
warning

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​

Do not use virtualization or emulators

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.

Do not keep DevTools open during web captures

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.

Platform-specific guidelines​

Flutter: use Unico's Flutter plugin

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.

Web: delete old resource files when updating versions

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.

Mobile: clear cache before building new versions

Build artifacts from previous SDK versions can cause dependency errors after an update. Before building a new version:

  • Flutter: delete pubspec.lock and run flutter pub get
  • iOS: run pod cache clean --all and pod install
  • Android: run ./gradlew clean
Obfuscation settings

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​

Separate the preparation and camera opening flow into two steps

Structure the SDK flow into two distinct stages:

  1. Prepare — initialize the SDK while the page is loading (before user interaction).
  2. 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​

Create a safe checklist for 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
Last updated on