Praktik Terbaik

Markdown

Halaman ini merangkum panduan terpenting untuk mengintegrasikan dan memelihara SDK Unico. Mengikuti praktik ini mengurangi kesalahan integrasi, mencegah insiden keamanan, dan memastikan peluncuran produksi yang lancar.

Memulai

Mulai dari aplikasi referensi

Unico menyediakan aplikasi referensi untuk setiap SDK di repository reference-apps. Setiap aplikasi mengimplementasikan user journey secara lengkap.

Selalu perbarui SDK Anda

SDK terus berkembang untuk menghadirkan keamanan yang lebih baik dan fitur baru. Menerapkan pembaruan dengan segera — terutama yang bersifat kritis — sangat penting. Lihat Kebijakan Pembaruan untuk jadwal dan kewajiban yang berlaku.

Identifikasi versi terbaru yang tersedia

Periksa versi terkini untuk setiap platform melalui catatan rilis masing-masing:

• Catatan rilis Android
• Catatan rilis iOS
• Catatan rilis Flutter
• Web — Catatan rilis SDK Journeys

Strategi pembaruan

Hindari memperbarui SDK dan komponen lain secara bersamaan

Aplikasi Anda kemungkinan memuat beberapa pustaka bersamaan dengan SDK Unico. Meningkatkan beberapa dependensi sekaligus menyulitkan identifikasi akar penyebab kegagalan. Perbarui SDK secara terpisah dan validasi di lingkungan staging sebelum menggabungkannya dengan perubahan lain.

Mendapatkan bantuan untuk pembaruan SDK

Saat membuka tiket dukungan terkait masalah pembaruan, sertakan:

• Bahasa SDK dan jenis implementasi (native atau hybrid)
• Framework yang digunakan
• Versi saat ini dan versi target
• API Key
• Deskripsi perubahan dan langkah-langkah untuk mereproduksi masalah
• Hasil, kesalahan, log, tangkapan layar, atau video

Keamanan JWT

Jangan memanipulasi objek JWT

Jangan membuka atau memodifikasi JWT yang terenkripsi

JWT yang dikembalikan setelah pengambilan gambar yang berhasil bersifat terenkripsi. Jangan membuka, mengurai, atau melakukan serialisasi padanya. Struktur internalnya dapat berubah tanpa pemberitahuan. Gunakan hanya saat mengirimkan gambar ke API Unico.

Untuk pratinjau gambar, gunakan atribut Base64 yang disediakan bersama JWT — jangan pernah mendekode JWT itu sendiri.

Kirim JWT dalam waktu 10 menit

peringatan

Demi alasan keamanan, JWT harus dikirim ke backend Unico dalam 10 menit setelah pengambilan gambar. Paket yang dikirimkan setelah jendela waktu ini akan dibatalkan.

Kirim JWT hanya sekali

peringatan

JWT harus dikirimkan hanya sekali. Jika terjadi kesalahan saat pengiriman, pengambilan gambar biometrik baru harus dilakukan — jangan gunakan kembali JWT yang sama.

Panduan pengujian

Jangan gunakan virtualisasi atau emulator

Menjalankan SDK di mesin virtual atau emulator memicu kode kesalahan keamanan (73006, 73600, 73400). Selalu uji pada perangkat fisik untuk menghindari kesalahan identifikasi dan pengerjaan ulang yang tidak perlu.

Jangan biarkan DevTools terbuka selama pengambilan gambar web

Web SDK mendeteksi DevTools yang terbuka sebagai sinyal potensi penipuan dan membatalkan pengiriman. Tutup DevTools sebelum menjalankan pengujian pengambilan gambar end-to-end.

Lakukan pengujian di lingkungan staging Unico

Sebelum beralih ke produksi, lakukan pengujian menyeluruh di lingkungan staging Unico dengan skenario yang realistis. Gunakan API Key dan konfigurasi khusus staging — jangan pernah menggunakan kredensial produksi dalam pengujian.

Lingkungan staging (UAT) IDCloud menerapkan kriteria keamanan yang sama dengan produksi. Panduan di bawah menjelaskan alasannya dan cara menguji tanpa gangguan.

Apa yang berubah di staging

Sebelumnya — mendeteksi, tetapi tidak menolak Kondisi di luar pola penggunaan nyata teridentifikasi, tetapi tidak menghalangi pengambilan.

Sekarang — mendeteksi dan menolak Kondisi yang sama kini menghasilkan penolakan bukti kehidupan, dengan ketatnya yang sama seperti produksi.

Mengapa pembatasan ini ada

Kesetiaan — kemiripan dengan produksi Apa yang lolos di staging harus berfungsi sama di produksi — mencegah integrasi yang disetujui saat pengujian gagal secara tak terduga setelah go-live.

Apa yang boleh dan tidak boleh Anda lakukan

Dengan menguji pada kondisi yang mendekati penggunaan nyata, lapisan keamanan tidak memengaruhi pengembangan Anda.

Perkakas pengembangan yang bukan standar pasar memicu validasi keamanan, dan transaksi dapat diblokir.

Skenario	Status
Alur integrasi lengkap — pengambilan, pengiriman, respons API, dan hasil kembalian	✅ Boleh
Skenario fungsional: UI/UX, performa, error bisnis	✅ Boleh
Perangkat dalam konfigurasi standar pengguna akhir	✅ Boleh
Integrasi dengan backend, API, dan pemrosesan data	✅ Boleh
Perangkat dengan root/jailbreak	❌ Tidak boleh
Mode debug / USB debugging aktif	❌ Tidak boleh
Emulator atau virtualisasi	❌ Tidak boleh
Kamera virtual atau alat otomatisasi pengambilan	❌ Tidak boleh
Alat yang mengubah koneksi	❌ Tidak boleh
MDM korporat atau pemantauan aktif pada perangkat	❌ Tidak boleh
Sandbox dalam container atau mesin virtual	❌ Tidak boleh

Kondisi apa pun di atas dapat menghasilkan penolakan bukti kehidupan.

Apakah siklus QA Anda bergantung pada salah satu kondisi ini?

Hubungi tim dukungan untuk panduan tentang konfigurasi lingkungan Anda. Tidak ada pengecualian, pembebasan sesaat, atau pelonggaran sementara — Unico menjaga staging tetap setara dengan produksi selama dianggap perlu.

Panduan khusus platform

Flutter: gunakan plugin Flutter dari Unico

Jangan mencoba menjembatani SDK Android atau iOS native di dalam aplikasi Flutter. Bridge native sering menghasilkan kesalahan yang tidak terpetakan. Selalu gunakan plugin Flutter khusus dari Unico.

Web: hapus file resource lama saat memperbarui versi

Saat meningkatkan versi Web SDK, hapus file resource lama dari folder public Anda sebelum memasukkan yang baru. File dengan nama yang sama tidak akan ditimpa secara otomatis dan dapat menyebabkan konflik versi.

Mobile: bersihkan cache sebelum membangun versi baru

Artefak build dari versi SDK sebelumnya dapat menyebabkan kesalahan dependensi setelah pembaruan. Sebelum membangun versi baru:

• Flutter: hapus pubspec.lock dan jalankan flutter pub get
• iOS: jalankan pod cache clean --all dan pod install
• Android: jalankan ./gradlew clean

Pengaturan obfuskasi

Kecualikan kode SDK Unico dari konfigurasi obfuskasi Anda. Mengobfuskasi SDK umumnya menyebabkan kegagalan pada build rilis yang tidak muncul pada build debug. Lihat dokumentasi khusus platform untuk aturan keep yang diperlukan.

UX dan performa

Pisahkan alur persiapan dan pembukaan kamera menjadi dua langkah

Strukturkan alur SDK menjadi dua tahap yang berbeda:

1. Persiapan — inisialisasi SDK saat halaman sedang dimuat (sebelum interaksi pengguna).
2. Buka — luncurkan kamera hanya ketika pengguna secara eksplisit memicu tindakan tersebut.

Mempersiapkan SDK lebih awal mengurangi latensi yang dirasakan dan meningkatkan pengalaman pengguna secara signifikan.

Peluncuran produksi

Buat daftar periksa yang aman untuk peluncuran produksi

Sebelum melakukan deploy ke produksi, verifikasi:

• API Key produksi dan konfigurasi lingkungan sudah benar
• Rencana rollback telah didefinisikan dan diuji
• Protokol pengumpulan log telah tersedia
• Prosedur tiket dukungan telah didokumentasikan untuk menangani kegagalan
• Semua validasi telah lulus di lingkungan staging