SDK実装のベストプラクティス
このページでは、UnicoのSDKを統合・保守するための最も重要なガイドラインをまとめています。これらのプラクティスに従うことで、統合エラーを減らし、セキュリティインシデントを防止し、スムーズな本番環境へのロールアウトを実現できます。
はじめに
Unicoは、サポートされているすべての言語にわたる実動コード例を含むPoC（概念実証）を提供しています。これらのPoC は、期待されるメソッドシーケンスと統合パターンを示しています。利用可能なPoCには、クライアントポータルのサポートチケットシステムを通じてアクセスできます。
SDKはより高いセキュリティと新機能を提供するために継続的に進化しています。特に重要なアップデートは迅速に適用することが不可欠です。タイムラインと義務についてはアップデートポリシーを参照してください。
各プラットフォームの現在のバージョンは、それぞれのリリースノートで確認できます：
アップデート戦略
アプリケーションはUnico SDKと並行して複数のライブラリを読み込んでいる可能性があります。複数の依存関係を同時にアップグレードすると、障害の根本原因を特定することが困難になります。SDKを単独でアップデートし、他の変更と組み合わせる前にステージング環境で検証してください。
アップデートの問題についてサポートチケットを開く場合は、以下の情報を含めてください：
- SDKの言語と実装タイプ（ネイティブまたはハイブリッド）
- 使用フレームワーク
- 現在のバージョンとターゲットバージョン
- APIキー
- 変更内容の説明と再現手順
- 結果、エラー、ログ、スクリーンショット、または動画
JWTセキュリティ
キャプチャ成功後に返されるJWTは暗号化されています。開いたり、解析したり、シリアライズしたりしないでください。内部構造は予告なく変更される場合があります。UnicoのAPIに画像を送信する際にのみ使用してください。
画像プレビューには、JWTと一緒に提供されるBase64属性を使用してください — JWTそのものをデコードしないでください。
セキュリティ上の理由から、JWTはキャプチャから10分以内にUnicoのバックエンドに送信する必要があります。この時間を超えて送信されたパッケージは無効化されます。
JWTは一度だけ送信する必要があります。送信中にエラーが発生した場合は、新たな生体認証キャプチャを実施する必要があります — 同じJWTを再利用しないでください。
テストガイドライン
仮想マシンやエミュレーターでSDKを実行すると、セキュリティエラーコード（73006、73600、73400）が発生します。エラーを誤認識したり不要な手戻りを避けるために、常に物理デバイスでテストしてください。
Web SDKは、開いているDevToolsを潜在的な不正シグナルとして検出し、送信を 無効化します。エンドツーエンドのキャプチャテストを実行する前にDevToolsを閉じてください。
Unicoのステージング環境でテストを実施する
本番環境に移行する前に、Unicoのステージング環境でリアルなシナリオを用いた十分なテストを実施してください。ステージング専用のAPIキーと設定を使用してください — テストで本番環境の認証情報を使用しないでください。
プラットフォーム別ガイドライン
FlutterアプリケーションでネイティブのAndroidまたはiOS SDKをブリッジしようとしないでください。ネイティブブリッジはマッピングされていないエラーを頻繁に生成します。常にUnicoの専用Flutterプラグインを使用してください。
Web SDKをアップグレードする際は、新しいファイルを挿入する前にpublicフォルダから古いリソースファイルを削除してください。同一名のファイルは自動的に上書きされないため、バージョンの競合が発生する可能性があります。
以前のSDKバージョンのビルドアーティファクトがアップデート後に依存関係エラーを引き起こす可能性があります。新バージョンをビルドする前に：
- Flutter：
pubspec.lockを削除してflutter pub getを実行する - iOS：
pod cache clean --allとpod installを実行する - Android：
./gradlew cleanを実行する
難読化設定からUnico SDKコードを除外してください。SDKを難読化すると、デバッグビルドでは現れないリリースビルドでの障害が発生することがよくあります。必要なkeepルールについては、プラットフォーム固有のドキュメントを参照してください。
UXとパフォーマンス
SDKフローを2つの明確なステージに構成してください：
- 準備 — ページの読み込み中 （ユーザー操作の前）にSDKを初期化する。
- 起動 — ユーザーが明示的にアクションをトリガーしたときにのみカメラを起動する。
SDKを事前に準備しておくことで、体感的なレイテンシが低下し、ユーザーエクスペリエンスが大幅に向上します。
本番環境へのロールアウト
本番環境へのデプロイ前に確認：
- 本番環境のAPIキーと環境設定が正しい
- ロールバック計画が定義されテスト済み
- ログ収集プロトコルが整備されている
- 障害対応のためのサポートチケット手順が文書化されている
- ステージング環境でのすべての検証が完了した