Integrasi Verifikasi Identitas di Aplikasi Flutter (ID)

Integrasi Flutter SDK untuk verifikasi identitas harus menyimpan kredensial permanen dan otorisasi akhir di backend Anda, sementara aplikasi seluler meluncurkan alur pengambilan native dengan token sesi berjangka pendek. Didit Flutter SDK mengekspos satu Dart API di atas SDK verifikasi native iOS dan Android, mengembalikan hasil penyelesaian, pembatalan, atau kegagalan bertipe ke aplikasi. Keputusan lengkap masih menjadi milik webhook backend atau alur pengambilan.

Panduan ini hanya menggunakan metode Dart dan tipe hasil yang diverifikasi terhadap sumber dan pengujian SDK lokal saat ini. Detail dependensi native berubah di setiap rilis, jadi konfigurasi platform dijelaskan berdasarkan tanggung jawab dan ditautkan ke panduan SDK kanonik, alih-alih menyalin Podfile atau blok Gradle yang sensitif versi.

Poin-poin penting

• Buat sesi produksi di backend. Jauhkan kunci API dari perangkat dan hanya kirim token sesi yang dibutuhkan oleh SDK.
• Gunakan hasil Dart bertipe untuk pengalaman pengguna, bukan otorisasi. VerificationCompleted berarti alur SDK telah berakhir; periksa status untuk tampilan dan tunggu keputusan backend yang berwenang.
• Tangani pembatalan, kegagalan bertipe, dan kesalahan platform yang tidak terduga secara terpisah. Mereka membutuhkan pemulihan dan analitik yang berbeda.
• Perlakukan penyiapan native sebagai infrastruktur rilis. Kunci privasi iOS, hak NFC (near-field communication), target deployment, dependensi Android, pengemasan, dan izin harus diuji pada perangkat nyata.
• Rancang seluruh siklus hidup. Pembuatan sesi, serah terima aplikasi, pengambilan, verifikasi webhook, perubahan status idempotent, peninjauan, percobaan ulang, dan observabilitas membentuk satu integrasi.

Fungsi Didit Flutter SDK

Paket didit_sdk membungkus SDK native iOS dan Android di balik antarmuka Dart bersama. Ini meluncurkan antarmuka pengguna verifikasi sebagai alur layar penuh native dan kembali ketika pengguna menyelesaikan, membatalkan, atau mengalami kesalahan.

SDK dapat meluncurkan alur kerja dengan Verifikasi ID, Deteksi Kehidupan, dan pemeriksaan terkonfigurasi lainnya. Alur kerja menentukan langkah-langkah yang muncul; panggilan Flutter tidak mengkodekannya secara langsung.

Permukaan Dart publik yang relevan dengan siklus hidup adalah:

DiditSdk.startVerification(token, config: ...)
DiditSdk.startVerificationWithWorkflow(workflowId, vendorData: ..., config: ...)

Untuk produksi, pilih startVerification dengan token yang dibuat backend. Metode ID alur kerja lebih sederhana tetapi memberi backend kontrol yang lebih sedikit atas parameter tingkat lanjut.

Arsitektur: backend, aplikasi Flutter, SDK, dan webhook

Alur produksi memiliki empat batas kepercayaan:

Komponen	Memiliki	Tidak boleh memiliki
Backend Anda	Kunci API, pilihan alur kerja, referensi pelanggan, pembuatan sesi, status pelanggan akhir	Antarmuka kamera
Aplikasi Flutter	Permintaan serah terima, UI pemuatan dan pemulihan, peluncuran SDK, analitik lokal	Kunci API permanen atau otorisasi akhir
Didit Flutter SDK	Pengambilan native dan alur verifikasi yang dikonfigurasi	Keputusan hak produk Anda
Worker Webhook/pengambilan	Asupan hasil terautentikasi, deduplikasi, rekonsiliasi	Asumsi klien yang tidak terverifikasi

Urutannya adalah:

1. Aplikasi Flutter yang masuk meminta backend Anda untuk memulai verifikasi.
2. Backend Anda membuat sesi verifikasi dengan alur kerja yang dimaksud dan referensi pelanggan internal yang stabil.
3. Backend mengembalikan session_token yang dicakup ke aplikasi.
4. Aplikasi meneruskan token tersebut ke DiditSdk.startVerification.
5. SDK menyajikan alur native dan mengembalikan hasil bertipe untuk pengalaman pengguna langsung.
6. Backend Anda menerima dan memverifikasi peristiwa hasil, merekonsiliasi status kanonik, dan memperbarui pelanggan sesuai kebijakan Anda.
7. Aplikasi membaca status pelanggan backend Anda sebelum memberikan akses atau mengklaim persetujuan akhir.

Arsitektur ini tidak mempercayai layar keberhasilan di perangkat.

Untuk kontrak sisi server dan batas peristiwa, lihat panduan evaluasi integrasi API verifikasi ID.

Instal paket

Gunakan perintah paket daripada menyalin versi yang bisa menjadi usang:

flutter pub add didit_sdk

Kemudian impor perpustakaan publik:

import 'package:didit_sdk/sdk_flutter.dart';

Sebelum meningkatkan, baca changelog dan dokumentasi resmi Flutter SDK. Periksa persyaratan platform yang dideklarasikan terhadap aplikasi dan citra CI Anda.

Ikuti petunjuk rilis Flutter untuk dependensi native; mencampur versi arbitrer dapat menimbulkan ketidakcocokan.

Konfigurasi iOS dan Android

Tanggung Jawab iOS

Pengambilan identitas dapat menggunakan perangkat keras dan data yang dilindungi. Tergantung pada alur kerja yang dikonfigurasi dan varian SDK, penyiapan iOS mungkin memerlukan:

• target deployment yang sesuai;
• deskripsi penggunaan kamera dan mikrofon;
• deskripsi penggunaan perpustakaan foto jika unggahan diizinkan;
• deskripsi penggunaan dan hak NFC saat pembacaan chip diaktifkan;
• konfigurasi CocoaPods yang kompatibel;
• kemampuan penandatanganan dan penyediaan yang sesuai dengan penggunaan NFC;
• font kustom terdaftar jika font spesifik aplikasi dikonfigurasi.

String tujuan privasi yang hilang dapat menghentikan aplikasi iOS. Uji alur kerja yang tepat pada perangkat fisik.

Dukungan NFC dapat meningkatkan target deployment minimum atau menambahkan dependensi native. Pilih varian SDK yang sesuai dengan alur kerja Anda dan ikuti dokumen saat ini untuk konfigurasi Podfile-nya.

Tanggung Jawab Android

Di Android, periksa:

• persyaratan SDK dan Java minimum;
• repositori dan dependensi yang ditambahkan oleh plugin;
• entri manifes kamera, jaringan, dan NFC;
• perilaku izin kamera saat runtime;
• kompatibilitas Gradle dan Kotlin;
• aturan pengemasan untuk dependensi native atau kriptografi;
• varian SDK all, core, autodetection, atau nfc;
• minifikasi build rilis dan perilaku sumber daya.

Produk Anda masih membutuhkan konteks izin, pemulihan penolakan, aksesibilitas, dan instruksi dukungan. Uji penolakan, interupsi, latar belakang, rotasi, dan pembuatan ulang proses.

Buat sesi di backend

Backend Anda harus memanggil API sesi menggunakan kunci API sisi server. Kaitkan setiap sesi dengan:

• pengidentifikasi pelanggan stabil Anda;
• alur kerja yang dipilih;
• lingkungan;
• perilaku panggilan balik atau pengembalian jika berlaku;
• lokal atau detail kontak yang diperlukan;
• detail pelanggan yang diharapkan di mana kebijakan menggunakannya;
• korelasi internal dan metadata kebijakan.

Jangan pernah menyematkan kunci API Didit di Dart, aset aplikasi, konfigurasi jarak jauh yang dapat dibaca, atau permintaan seluler.

Kembalikan hanya token sesi dan status peluncuran minimum. Jauhkan dari analitik, laporan crash, log, penggunaan papan klip, dan penyimpanan jangka panjang.

Buat permintaan mulai menjadi idempotent

Pelanggan dapat mengetuk dua kali, kehilangan konektivitas setelah backend Anda membuat sesi, atau membuka kembali layar saat upaya aktif. Gunakan pengidentifikasi permintaan yang stabil dan logika backend yang mengembalikan upaya yang sesuai yang ada daripada membuat duplikat yang terputus.

Tombol pemuatan aplikasi Anda harus memblokir ketukan berulang yang jelas, tetapi idempotensi sisi server tetap diperlukan karena klien mencoba lagi dan proses dimulai ulang.

Mulai verifikasi dari Dart

Contoh Dart lengkap ini hanya menggunakan impor SDK, metode, kelas hasil, bidang sesi, enum status, dan bidang kesalahan yang diverifikasi dalam sumber paket:

import 'package:didit_sdk/sdk_flutter.dart';

Future<void> runIdentityVerification(String sessionToken) async {
  try {
    final result = await DiditSdk.startVerification(
      sessionToken,
      config: const DiditConfig(
        loggingEnabled: false,
      ),
    );

    switch (result) {
      case VerificationCompleted(:final session):
        switch (session.status) {
          case VerificationStatus.approved:
            print('Flow completed with approved client status.');
          case VerificationStatus.pending:
            print('Flow completed and still needs a backend decision.');
          case VerificationStatus.declined:
            print('Flow completed with declined client status.');
        }
        print('Session ID: ${session.sessionId}');
        return;
      case VerificationCancelled():
        print('The user cancelled the verification flow.');
        return;
      case VerificationFailed(:final error):
        print('SDK error: ${error.type.name}: ${error.message}');
        return;
    }
  } catch (error, stackTrace) {
    print('Unexpected platform error: $error');
    print(stackTrace);
  }
}

Contoh ini menunjukkan struktur tipe. Aplikasi nyata harus memperbarui status layar dan menyegarkan status backend, tidak pernah membuka kunci akun dari fungsi ini saja.

Mengapa VerificationCompleted tidak selalu persetujuan

VerificationCompleted berisi SessionData, yang statusnya adalah salah satu dari:

• VerificationStatus.approved;
• VerificationStatus.pending;
• VerificationStatus.declined.

Alur SDK dapat selesai sementara verifikasi tetap tertunda atau ditolak. Peninjauan manusia atau pemeriksaan asinkron juga dapat mengubah status backend setelah panggilan aplikasi kembali. Beri nama status UI lokal Anda “alur selesai” daripada “identitas disetujui” sampai backend Anda mengonfirmasi hasil kebijakan.

Tidak ada panggilan inisialisasi Flutter

Permukaan Flutter publik yang diverifikasi tidak mengekspos metode inisialisasi terpisah. Jangan menyalin pola inisialisasi native Android ke dalam Dart. Jika Android melaporkan notInitialized melalui hasil Flutter, anggap itu sebagai masalah integrasi atau jembatan native dan periksa penyiapan paket.

Tangani kesalahan bertipe dan pemulihan

Tipe kesalahan SDK yang diverifikasi adalah:

Tipe kesalahan	Arti untuk kebijakan aplikasi	Pemulihan aman
sessionExpired	Token tidak dapat lagi memulai sesi yang dimaksud	Minta backend untuk sesi valid yang baru
networkError	Alur native tidak dapat menyelesaikan operasi jaringan	Pertahankan konteks dan tawarkan percobaan ulang terbatas
cameraAccessDenied	Akses kamera yang diperlukan tidak tersedia	Jelaskan mengapa diperlukan dan pandu pengaturan atau rute alternatif
notInitialized	Integrasi atau jembatan native Android belum siap	Catat konteks rilis dan selidiki penyiapan
apiError	SDK atau layanan mengembalikan kegagalan tingkat API	Coba lagi hanya jika aman; rekonsiliasi status backend
retryBlocked	Alur mencegah upaya otomatis lainnya	Hentikan loop dan ikuti kebijakan backend atau dukungan
unknown	Kesalahan native tidak dipetakan ke tipe Dart yang diketahui	Pertahankan fallback aman dan data korelasi

Platform native dapat mengekspos detail yang berbeda. Pertahankan jalur unknown.

Pisahkan kesalahan dari hasil pelanggan

Kegagalan jaringan bukanlah penolakan; penolakan kamera bukanlah penipuan; pembatalan bukanlah identitas yang gagal. Pisahkan kategori di:

• pesan pengguna;
• aturan percobaan ulang;
• akses produk;
• alat dukungan;
• analitik;
• pelaporan penipuan dan konversi.

Percobaan ulang terbatas

Biarkan backend memutuskan apakah sesi yang ada dapat dilanjutkan atau sesi baru diperlukan. Hindari loop tanpa batas yang berulang kali memanggil SDK dengan token yang kedaluwarsa atau diblokir. Lacak jumlah upaya dan penyebab tanpa mencatat token atau bukti identitas.

Gunakan peristiwa backend sebagai sumber kebenaran

SDK mengembalikan hasil klien yang ringkas. Bukti lengkap dan status akhir tiba melalui integrasi sisi server. Penangan webhook Anda harus:

1. menerima permintaan mentah dalam bentuk yang disyaratkan oleh skema tanda tangan yang didokumentasikan;
2. mengautentikasi peristiwa dan memvalidasi kebaruannya;
3. menduplikasikan pengidentifikasi peristiwanya;
4. memetakannya ke sesi dan pelanggan yang diharapkan;
5. mencegah peristiwa yang lebih lama menimpa status terminal yang lebih baru;
6. mengambil status sesi kanonik saat rekonsiliasi diperlukan;
7. menerapkan kebijakan Anda dan menyimpan alasannya;
8. kembali dalam anggaran respons penyedia;
9. memproses pekerjaan hilir yang lambat secara asinkron.

Asumsikan pengiriman setidaknya sekali. Peristiwa duplikat dan di luar urutan adalah perilaku sistem terdistribusi yang biasa. Simpan peristiwa penyedia dan transisi internal secara terpisah sehingga audit dapat merekonstruksi keduanya.

Aplikasi harus hanya melakukan polling backend Anda untuk status produknya sendiri atau menggunakan saluran real-time normal Anda. Seharusnya tidak mengekspos kunci API penyedia untuk mengambil catatan akhir secara langsung.

Bangun siklus hidup layar Flutter yang tangguh

Model status lokal eksplisit

Layar verifikasi dapat menggunakan:

• diam;
• meminta sesi;
• meluncurkan SDK;
• alur SDK terbuka;
• merekomendasikan keputusan backend;
• menunggu peninjauan;
• disetujui;
• ditolak;
• kesalahan yang dapat dipulihkan;
• dibatalkan.

Pertahankan hanya yang aman. Setelah proses mati, tanyakan kepada backend apakah sesi aktif atau selesai sudah ada. Jangan mengandalkan boolean dalam memori untuk memutuskan apakah akan membuat upaya lain.

Hormati siklus hidup widget

Setelah panggilan yang ditunggu, periksa mounted sebelum setState, dialog, atau navigasi. Jaga status bisnis di luar UI transien.

Tangani latar belakang dan pembatalan

Uji peralihan aplikasi, kunci layar, navigasi, dan penghentian proses. Definisikan perilaku resume, restart, dan rekonsiliasi.

Rancang pemulihan izin

Jelaskan kebutuhan kamera atau NFC. Setelah penolakan permanen, tunjukkan panduan pengaturan atau rute alternatif yang dapat diakses.

Konfigurasi tanpa kebocoran kebijakan

Permukaan DiditConfig Flutter yang diverifikasi secara offline mengekspos languageCode, fontFamily, loggingEnabled, showCloseButton, showExitConfirmation, closeOnComplete, defaultDocumentCamera, defaultLivenessCamera, showDocumentCameraSwitchButton, dan showLivenessCameraSwitchButton. Bidang kamera menggunakan CameraLens.front atau CameraLens.back; semua opsi bertipe di Dart dan dipetakan ke SDK native.

Patuhi tiga aturan:

1. aktifkan logging verbose hanya untuk pengembangan atau build diagnostik terkontrol;
2. jangan gunakan konfigurasi UI sebagai pengganti kebijakan backend;
3. uji setiap bahasa yang didukung, font kustom, perilaku penutupan, dan kebijakan kamera di kedua platform, termasuk perilaku fallback ketika lensa atau aset yang diminta tidak tersedia.

Komposisi alur kerja dan branding produk termasuk dalam konsol atau alur kerja yang dikelola backend daripada labirin flag fitur seluler. Itu membuat tampilan iOS, Android, web, dan dukungan selaras.

Uji integrasi

Pengujian Dart dan widget

Bungkus peluncuran SDK di balik layanan aplikasi sehingga pengujian layar dapat mengembalikan:

• selesai dan disetujui;
• selesai dan tertunda;
• selesai dan ditolak;
• dibatalkan;
• setiap kegagalan bertipe;
• pengecualian platform yang tidak terduga.

Pastikan pembersihan status pemuatan, pemeriksaan pemasangan, visibilitas percobaan ulang, penyegaran backend, dan kategori analitik. Jangan meletakkan token sesi nyata di fixture.

Pengujian integrasi native

Jalankan build debug dan rilis pada perangkat fisik iOS dan Android. Cakup:

• izin pertama kali dan yang telah diputuskan sebelumnya;
• kamera yang didukung dan tidak didukung;
• varian yang mendukung NFC dan non-NFC jika digunakan;
• cahaya rendah, buram, silau, dan orientasi;
• konektivitas lambat, hilang, dan dipulihkan;
• latar belakang dan pembuatan ulang proses;
• pembatalan dan peluncuran berulang;
• kedaluwarsa sesi dan pemblokiran percobaan ulang;
• lokal yang berbeda, penskalaan font, pembaca layar, dan gerakan yang dikurangi;
• penandatanganan aplikasi, minifikasi, dan resolusi dependensi produksi.

Emulator berguna untuk pengujian status dan kesalahan tetapi tidak dapat mewakili setiap kamera, NFC, biometrik, dan kondisi integritas perangkat.

Pengujian backend end-to-end

Gunakan kasus sandbox deterministik untuk setiap status pelanggan yang didokumentasikan. Putar ulang peristiwa pengujian yang ditandatangani, kirim duplikat di luar urutan, tunda peninjauan, dan rekonsiliasi setelah webhook yang terlewat disimulasikan. Konfirmasikan bahwa aplikasi tidak pernah memberikan akses sebelum status backend Anda berubah.

Untuk desain pengujian biometrik dan batas serangan, lihat panduan pengujian keaktifan.

Daftar periksa keamanan dan privasi

Sebelum rilis, konfirmasikan bahwa:

• kredensial penyedia permanen hanya ada di backend;
• aplikasi menerima token sesi yang dicakup melalui saluran terautentikasi;
• token dan bukti tidak ada dari log, analitik, URL, dan laporan crash;
• permintaan pembuatan backend bersifat idempotent dan terikat pada referensi pelanggan yang stabil;
• penyelesaian klien tidak pernah secara langsung memberikan hak;
• pengujian tanda tangan webhook, kebaruan, duplikat, pengurutan, dan rekonsiliasi berhasil;
• deskripsi privasi iOS dan perjalanan izin Android menggunakan teks tujuan yang jelas;
• kemampuan dan varian NFC cocok dengan alur kerja dan penandatanganan rilis;
• logging debug dinonaktifkan untuk produksi;
• retensi, persetujuan, pemberitahuan privasi, penghapusan, dan jalur dukungan sesuai dengan peran dan hukum Anda;
• SDK, dependensi native, OS, dan kompatibilitas perangkat dipantau setelah peluncuran;
• keputusan rollback dan upgrade paksa memiliki pemilik.

Kesalahan integrasi Flutter SDK yang umum

Mengirim kunci API di Dart

Aplikasi seluler tidak dapat melindungi kredensial server permanen. Buat sesi di backend Anda dan berikan token yang dicakup.

Mempercayai panggilan balik yang selesai

Hasil klien adalah status antarmuka pengguna. Konfirmasikan status yang berwenang dan terapkan kebijakan di backend.

Menciptakan metode dari platform lain

Flutter tidak mengekspos setiap metode SDK native dengan nama yang sama. Kompilasi terhadap paket dan periksa sumber Dart publiknya sebelum menulis kode integrasi.

Menyalin konfigurasi native yang usang

Varian SDK, target deployment, dan penyiapan manajer paket berubah. Ikuti dokumentasi untuk rilis yang terinstal dan catat dalam daftar periksa rilis seluler Anda.

Memperlakukan setiap kesalahan sebagai penolakan

Izin, jaringan, kedaluwarsa, kegagalan API, pembatalan, dan keputusan pelanggan memerlukan pemulihan dan analitik yang berbeda.

Menguji hanya pada emulator

Kamera, NFC, izin, penandatanganan, dan dependensi native memerlukan cakupan perangkat fisik dan build rilis.

Menggunakan Didit dalam alur kerja identitas Flutter

Didit Flutter SDK terdaftar sebagai gratis. Ini dapat meluncurkan alur kerja yang berisi Verifikasi ID, Deteksi Kehidupan, dan pemeriksaan terkonfigurasi lainnya, sementara tim mengelola jalur bersyarat melalui Orkestrator Alur Kerja.

Tarif modul yang dipublikasikan tersedia di halaman harga. SDK menangani pengalaman pengambilan native; backend Anda tetap bertanggung jawab untuk pembuatan sesi, penanganan hasil terautentikasi, status pelanggan, dan keputusan produk.

Pertanyaan yang sering diajukan

Metode mana yang memulai verifikasi?

Untuk sesi produksi yang dibuat backend, panggil DiditSdk.startVerification(sessionToken). SDK juga mengekspos DiditSdk.startVerificationWithWorkflow(...) untuk mode integrasi ID alur kerja yang lebih sederhana.

Haruskah aplikasi Flutter berisi kunci API Didit?

Tidak. Simpan kunci API di backend. Aplikasi hanya boleh menerima token sesi yang dicakup yang diperlukan untuk upaya verifikasinya.

Apakah VerificationCompleted berarti disetujui?

Belum tentu. Status sesinya bisa disetujui, tertunda, atau ditolak. Gunakan hasil untuk status antarmuka langsung dan konfirmasikan keputusan yang berwenang melalui backend Anda.

Bagaimana seharusnya pembatalan ditangani?

Perlakukan itu sebagai hasil pengguna yang berbeda. Pertahankan status sesi backend, tawarkan jalur resume atau restart yang jelas sesuai kebijakan, dan jangan labeli pembatalan sebagai penipuan atau penolakan.

Apakah Flutter SDK memiliki metode inisialisasi?

API Dart publik yang diverifikasi tidak mengekspos metode inisialisasi terpisah. Ikuti instruksi penyiapan native paket dan gunakan metode mulai yang didokumentasikan.

Bisakah Flutter menggunakan NFC untuk dokumen identitas?

SDK native dapat mendukung NFC ketika varian paket yang dipilih, perangkat, konfigurasi iOS atau Android, kemampuan penandatanganan, dan alur kerja semuanya mengaktifkannya. Ikuti dokumentasi rilis saat ini dan uji pada perangkat fisik.

Apa yang harus dilakukan aplikasi saat kasus sedang ditinjau?

Tunjukkan status tertunda yang jujur, biarkan pelanggan pergi dengan aman, dan baca status produk akhir dari backend Anda ketika hasil terautentikasi tiba.

Referensi utama

• Dokumentasi Didit Flutter SDK
• Repositori sumber Didit Flutter SDK
• Dokumentasi Didit Session API
• Dokumentasi Didit Webhook
• Dokumentasi Flutter: integrasi platform
• Standar Verifikasi Keamanan Aplikasi Seluler OWASP

Integrasi Flutter SDK yang kuat menjaga setiap batas tetap eksplisit: backend membuat upaya, aplikasi meluncurkan alur native yang dicakup, hasil bertipe mendorong pemulihan, peristiwa server terautentikasi mendorong status pelanggan, dan pengujian perangkat nyata membuktikan bahwa izin, siklus hidup, dependensi native, dan jalur kegagalan berfungsi di luar demo jalur bahagia.