Integrasi Aplikasi Web

Markdown

Halaman ini menjelaskan cara kerja journey Unico dan model integrasi yang tersedia untuk menyematkannya ke dalam aplikasi.

Sebuah journey adalah serangkaian langkah yang dilalui pengguna untuk menyelesaikan verifikasi identitas. Misalnya: mengambil foto dokumen dan melakukan penangkapan wajah (liveness).

Unico mengelola seluruh pengalaman. Upaya integrasi minimal: journey dibuat melalui CreateProcess, pengguna diarahkan ke sana, dan hasilnya diterima di akhir. Semua yang ada di antaranya — layar, instruksi, validasi — sudah dibangun dan dipelihara oleh Unico.

Dua model integrasi

Setiap klien memiliki kebutuhan yang berbeda. Unico menawarkan dua model untuk mengarahkan pengguna ke journey.

Model	Terbaik untuk
Akses langsung	Aplikasi mobile yang sudah menggunakan WebView, atau alur web di mana journey dapat terjadi di luar halaman utama
Journeys SDK	Aplikasi web yang membutuhkan pengalaman terintegrasi dan mulus, menjaga pengguna dalam lingkungan yang sama

Akses langsung

Pengguna diarahkan ke tautan yang di-host oleh Unico, di mana journey berlangsung. Setelah selesai, mereka dikembalikan ke URL yang ditentukan saat pembuatan proses (parameter callbackUri).

Ini adalah pendekatan paling sederhana untuk diadopsi: tidak memerlukan instalasi library dan berfungsi dengan baik ketika journey tidak perlu terjadi di dalam halaman aplikasi itu sendiri. Di sisi lain, membawa pengguna keluar dari lingkungan klien cenderung menimbulkan lebih banyak gesekan dan, akibatnya, tingkat drop-off yang lebih tinggi.

Setelah membuat proses, respons API menyertakan URL journey yang di-host oleh Unico. Ada dua cara umum untuk mengarahkan pengguna:

• Redirect standar. Pengguna diarahkan langsung ke URL journey. Setelah selesai, Unico mengarahkan mereka kembali ke callbackUri yang ditentukan saat pembuatan proses.
• Tab baru dengan window.open(). Journey dibuka di tab browser baru, menjaga pengguna dalam konteks terpisah. Dalam kasus ini, disarankan untuk memantau perubahan URL ke callbackUri dan menutup tab setelah proses selesai. Lihat dokumentasi MDN untuk detail tentang API.

Di aplikasi mobile, umum menggunakan WebView untuk membuka journey secara langsung, tanpa redirect tambahan yang diperlukan. Dalam kasus ini, callbackUri juga menerima deeplink, memungkinkan penyelesaian journey memicu pembukaan layar tertentu di aplikasi native. Cukup konfigurasikan deeplink sebagai tujuan kembali dan sistem operasi menangani pengarahan pengguna ke tempat yang tepat.

Journeys SDK

Journey berlangsung di dalam aplikasi itu sendiri, tanpa membawa pengguna keluar dari konteks mereka. Journeys SDK diinstal di aplikasi dan digunakan untuk membuka journey saat diperlukan.

Ini adalah jalur yang direkomendasikan untuk pengalaman yang lebih terintegrasi dan mulus, menjaga pengguna di lingkungan yang sama sepanjang waktu, yang cenderung mengurangi gesekan dan drop-off di seluruh alur.

Unico menyediakan library JavaScript yang kompatibel dengan browser modern, memungkinkan journey diintegrasikan ke dalam hampir semua aplikasi hanya dengan beberapa baris kode.

Kompatibilitas

Library ini dirancang untuk cocok dengan proyek apa pun tanpa hambatan, terlepas dari stack yang digunakan:

• Aplikasi web apa pun. Didistribusikan dalam format UMD, berfungsi saat diimpor melalui bundler modern (seperti webpack atau Vite). Kompatibel dengan framework apa pun (React, Angular, Vue) atau JavaScript murni.
• Browser modern. Library sudah menyertakan polyfill yang diperlukan untuk fitur seperti Promises dan async/await, memperluas kompatibilitas ke versi browser lama juga.
• API web standar. Journey berjalan pada kemampuan native browser, tanpa ketergantungan pada plugin atau library eksternal di proyek.

Cara kerja internal SDK

Ketika journey dibuka, SDK menyisipkan iFrame ke dalam halaman dan mengambil kendali atas seluruh pengalaman visual dari titik itu dan seterusnya. Layar, skrip, dan aset untuk setiap langkah berjalan di dalam iFrame ini, dari saat pengguna memulai hingga penyelesaian proses.

Keputusan arsitektur ini disengaja: isolasi iFrame memastikan journey Unico tidak mengganggu style atau perilaku aplikasi. Tidak ada skrip yang bocor ke konteks eksternal, tidak ada aturan CSS yang bertabrakan dengan style aplikasi. Hasilnya adalah pengalaman yang konsisten bagi pengguna akhir dan dampak minimal pada produk klien.

Karena Unico bertanggung jawab untuk membuat dan mengelola iFrame, peningkatan journey — baik dalam kinerja, pengalaman, atau validasi — dikirimkan secara otomatis ke semua pengguna, tanpa perubahan yang diperlukan di aplikasi yang terintegrasi. Integrasi akan selalu berjalan dengan optimasi terbaik yang tersedia, tanpa perlu melacak atau merespons setiap pembaruan platform.

Memulai

Langkah 1 — Instalasi

Paket idpay-b2b-sdk dibagikan antara journey pembayaran IDPay dan journey verifikasi identitas. Untuk kasus penggunaan identitas, impor kelas ByUnicoSDK seperti yang ditunjukkan pada langkah-langkah di bawah.

  npm install idpay-b2b-sdk

Cara yang direkomendasikan untuk menginstal Journeys SDK adalah melalui pengelola paket seperti npm atau yarn, dari paket yang tersedia di npm registry. Selain menyederhanakan instalasi dan manajemen dependensi, pendekatan ini memberikan kontrol yang jelas atas versi yang digunakan dan memudahkan pembaruan ketika versi baru diterbitkan.

SDK mengikuti Semantic Versioning (SemVer), yang berarti pembaruan patch dan minor tidak memperkenalkan perubahan yang merusak. Aman untuk mengkonfigurasi proyek untuk menerima pembaruan ini secara otomatis. Perubahan yang mungkin memerlukan pembaruan integrasi dicadangkan untuk versi mayor dan selalu disertai panduan migrasi.

Menjaga SDK tetap terbaru

Tetap pada versi terbaru sangat penting karena dua alasan. Yang pertama adalah keamanan: patch keamanan diterbitkan setiap kali kerentanan teridentifikasi atau peluang untuk memperkuat protokol komunikasi muncul. Menjalankan versi lama berarti melewatkan perbaikan ini dan mengekspos alur ke risiko yang tidak perlu. Yang kedua adalah stabilitas: perbaikan bug didistribusikan dengan cara yang sama, dan versi lama mungkin menunjukkan perilaku yang sudah diselesaikan di rilis yang lebih baru.

Sebelum memulai, daftarkan domain Anda ke tim dukungan Unico. Semua domain harus menggunakan HTTPS.

Langkah 2 — Konfigurasi CSP dan Permissions-Policy

Jika halaman Anda sudah mengirim header Content-Security-Policy atau Permissions-Policy, tambahkan direktif berikut agar iFrame, skrip, dan akses kamera SDK berfungsi dengan benar.

Content-Security-Policy:

frame-src https://*.unico.io https://*.unico.app;
script-src https://idpay.unico.io;
style-src https://idpay.unico.io;
connect-src https://api.cadastro.unico.app;

Permissions-Policy:

camera=(self "https://human-token.unico.io" "https://cadastro.unico.app" "https://id.unico.io" "https://retry.unico.io" "https://ultimatum.unico.io");
geolocation=(self "https://human-token.unico.io" "https://cadastro.unico.app" "https://id.unico.io" "https://retry.unico.io" "https://ultimatum.unico.io");

informasi

Jika halaman Anda tidak mengirim header CSP atau Permissions-Policy, Anda dapat melewati langkah ini — browser tidak menerapkan batasan apa pun secara default.

Langkah 3 — Panggil init(options)

Menginisialisasi SDK dan memuat skrip yang diperlukan terlebih dahulu agar journey berfungsi dengan benar, menciptakan pengalaman yang lebih mulus bagi pengguna akhir. Panggil ini sedini mungkin dalam alur.

Parameter	Wajib	Deskripsi
token	Ya	Token proses yang dikembalikan oleh API Create Process
env	Tidak	Atur ke 'uat' hanya untuk lingkungan pengujian

import { ByUnicoSDK } from 'idpay-b2b-sdk';

ByUnicoSDK.init({
  token,
  // env: 'uat' // only for test environments
});

Langkah 4 — Panggil open(options)

Menampilkan iFrame dan memulai journey untuk pengguna. Dari titik ini dan seterusnya, semuanya terjadi secara otomatis di dalam iFrame, tanpa perlu mengelola langkah perantara apa pun.

Parameter	Wajib	Deskripsi
transactionId	Ya	ID proses yang dikembalikan oleh API Create Process
token	Ya	Token proses yang dikembalikan oleh API Create Process
onFinish	Ya	Callback yang dieksekusi ketika journey berakhir atau ditutup
onWidgetVisibilityChange	Tidak	Callback yang dieksekusi ketika status visibilitas widget berubah

Interaksi berikutnya dengan aplikasi terjadi ketika journey berakhir, baik pengguna menyelesaikannya atau menutupnya. Pada titik itu, SDK memanggil callback onFinish, yang diteruskan sebagai parameter di open. Dari sana, aplikasi dapat memanggil API getProcess untuk memeriksa hasilnya, atau menunggu notifikasi Webhook jika pendekatan asinkron lebih disukai.

Selain mengkueri hasil, disarankan menggunakan onFinish untuk menangani status front-end aplikasi:

• Hindari loop. Cegah pembuatan ulang proses yang segera dan tidak perlu jika pengguna memicu alur lagi tepat setelah journey berakhir.
• Manajemen alur. Pastikan pengguna diarahkan ke langkah berikutnya dari aplikasi, menghindari layar buntu setelah journey ditutup.

peringatan

Callback onFinish menandakan bahwa pengguna telah menyelesaikan journey, tetapi tidak menjamin persetujuan. Proses mungkin telah berakhir dengan kegagalan pada salah satu aturan validasi Unico. Mengkueri melalui getProcess atau menerima notifikasi Webhook tidak opsional: ini adalah satu-satunya sumber hasil aktual, dan perilaku aplikasi harus didasarkan padanya. onFinish tidak boleh digunakan secara terpisah untuk menentukan apakah pengguna telah disetujui.

Callback onFinish menerima objek yang menjelaskan bagaimana journey berakhir:

Field	Tipe	Deskripsi
type	string	Bagaimana journey berakhir: 'FINISH' (selesai) atau 'CLOSE' (pengguna menutup sebelum selesai)
transaction	object | undefined	Ada ketika type adalah 'FINISH'; undefined ketika type adalah 'CLOSE'
transaction.id	string	Identifier proses (sama dengan transactionId yang diteruskan)
transaction.redirectUrl	string	URL untuk mengarahkan pengguna setelah journey

Menangani callback onWidgetVisibilityChange bersifat opsional dan mungkin tidak relevan untuk kasus penggunaan Anda. Ini dipanggil setiap kali status visibilitas widget berubah, dan berguna hanya dalam skenario tertentu: beberapa journey menampilkan latar belakang transparan, menjaga halaman aplikasi terlihat di belakang pengalaman. Aplikasi yang menampilkan modal kustom selama alur verifikasi (misalnya, sebagai bagian dari orkestrasi lintas beberapa penyedia KYC) mungkin menampilkan modal tersebut di belakang widget Unico, menurunkan pengalaman visual. Dalam kasus itu, callback memungkinkan aplikasi menekan elemen visual tambahan apa pun sementara journey Unico aktif, dan memulihkannya setelah selesai. Jika aplikasi Anda tidak memiliki UI yang dapat tumpang tindih dengan widget, Anda dapat dengan aman menghilangkannya.

ByUnicoSDK.open({
  transactionId: '9bc22bac-1e64-49a5-94d6-9e4f8ec9a1bf',
  token: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...',
  onFinish: ({ transaction, type }) => {
    if (type === 'FINISH') {
      // Journey completed (transaction = { id, redirectUrl }) — continue your flow here.
    }
    // type === 'CLOSE' → user closed before finishing;
  },
  // Optional: only needed if your app shows UI that could overlap the widget.
  onWidgetVisibilityChange: (visible) => {
    // suppress or restore your modal based on widget visibility
  },
});

// To close the SDK explicitly at any point:
ByUnicoSDK.close();

Diagram urutan di bawah ini menunjukkan cara menggunakan SDK dan hasil API untuk mengkonfigurasi iFrame:

Aplikasi contoh

Bahasa / Framework	Deskripsi	Repositori
Angular	PoC di Angular yang mengimplementasikan Journeys SDK	GitHub — unico-cbu-poc-angular
JS Vanilla	PoC di JS Vanilla yang mengimplementasikan Journeys SDK	GitHub — unico-cbu-poc-js
React	PoC di React yang mengimplementasikan Journeys SDK	GitHub — unico-cbu-poc-react
Vue JS	PoC di Vue JS yang mengimplementasikan Journeys SDK	GitHub — unico-cbu-poc-vuejs

Keamanan

Keamanan dalam model ini dibangun berlapis, dimulai dari protokol komunikasi antara SDK dan aplikasi yang berjalan di dalam iFrame.

Ketika journey dimuat, kedua pihak melakukan handshake untuk membangun komunikasi. Dalam proses ini, aplikasi Unico memvalidasi asal pesan injeksi data yang diterima melalui postMessage terhadap daftar tertutup domain resmi, disegmentasi berdasarkan lingkungan (UAT dan PROD). Pesan dari asal yang tidak disetujui langsung dibuang, mencegah journey disematkan di halaman yang tidak sah dan menghilangkan permukaan serangan untuk kerentanan seperti clickjacking.

Selain validasi asal, alur hanya berlanjut dengan token transaksi yang valid: JWT sekali pakai, diterbitkan dan ditandatangani oleh backend Unico. Ini memastikan bahwa bahkan asal yang sah tidak dapat beroperasi dengan token yang kedaluwarsa, digunakan ulang, atau dipalsukan.

Setelah handshake, token diinjeksikan ke dalam iFrame dan tidak ada informasi sensitif yang mengalir di antara kedua pihak. Semua komunikasi yang tersisa hanya berfungsi untuk kontrol antarmuka — membuka, menutup, dan transisi layar — mencegah data proses dicegat atau bocor selama journey.

Isolasi iFrame juga melindungi integritas skrip Unico pada saat runtime. Karena kode berjalan dalam konteks terpisah dari halaman, tidak dapat diakses atau dimodifikasi oleh skrip eksternal, memastikan journey dieksekusi persis seperti yang dibangun, tanpa gangguan.

CSP dan Permissions-Policy

Jika halaman Anda mengirim header Content-Security-Policy atau Permissions-Policy, pastikan direktif berikut ada agar iFrame, skrip, dan akses kamera SDK berfungsi dengan benar.

Content-Security-Policy:

frame-src https://*.unico.io https://*.unico.app;
script-src https://idpay.unico.io;
style-src https://idpay.unico.io;
connect-src https://api.cadastro.unico.app;

Permissions-Policy:

camera=(self "https://human-token.unico.io" "https://cadastro.unico.app" "https://id.unico.io" "https://retry.unico.io" "https://ultimatum.unico.io");
geolocation=(self "https://human-token.unico.io" "https://cadastro.unico.app" "https://id.unico.io" "https://retry.unico.io" "https://ultimatum.unico.io");

Jika halaman Anda tidak mengirim header ini, browser tidak menerapkan batasan apa pun secara default dan tidak diperlukan konfigurasi.

Pemecahan masalah khusus SDK

Bagian ini mencakup masalah paling umum yang ditemui selama integrasi dan cara yang direkomendasikan untuk menyelidikinya.

Perilaku tak terduga atau alur rusak

Periksa apakah ada skrip aplikasi yang langsung memanipulasi iFrame di DOM. SDK membuat dan mengelola iFrame di body halaman, dan modifikasi eksternal apa pun — baik pada scope, positioning, atau atribut — dapat mengganggu siklus hidup journey dan menyebabkan perilaku yang tidak dapat diprediksi.

Pengalaman visual berbeda dari yang diharapkan

Periksa apakah ada stylesheet global di aplikasi yang menimpa properti di dalam iFrame. SDK membuat iFrame dan semua elemen internalnya dengan ID dinamis dan kelas yang diawali unico, yang secara signifikan mengurangi risiko konflik melalui selektor ID atau kelas. Meski begitu, aturan CSS yang luas — seperti selektor tag — dapat menjangkau elemen di dalam iFrame dan mengubah pengalaman visual yang disampaikan kepada pengguna.

File library SDK dimodifikasi langsung

Periksa apakah ada file library yang dimodifikasi di luar pengelola paket. Library harus dikelola secara eksklusif melalui npm atau yarn, tanpa pengeditan langsung pada file yang terinstal. Modifikasi manual dapat menghasilkan perilaku anomali yang sulit direproduksi dan akan mencegah dukungan Unico untuk dapat membantu.

Jangan biarkan DevTools terbuka selama tes capture

Aplikasi Unico menggunakan Capture SDK (unico-webframe) untuk penangkapan wajah, yang mendeteksi DevTools terbuka sebagai sinyal potensi penipuan dan memblokir pengiriman. Tutup DevTools sebelum menjalankan tes capture end-to-end.

Integrasi yang tidak didukung

Model yang dijelaskan dalam dokumentasi ini — akses langsung dan Journeys SDK — adalah satu-satunya pendekatan integrasi yang secara resmi didukung oleh Unico. Integrasi yang menyimpang dari standar ini dapat menyebabkan perilaku tak terduga, kegagalan alur keamanan, dan gangguan journey, dan tidak akan dicakup oleh dukungan Unico.

Contoh pendekatan yang tidak didukung:

• Menyematkan SDK di dalam WebView di aplikasi mobile. Dalam kasus ini, pendekatan yang benar adalah menggunakan model akses langsung, membuka tautan journey langsung di WebView tanpa melibatkan Journeys SDK.
• Memuat iFrame langsung melalui tag HTML <iframe>, tanpa melalui Journeys SDK. iFrame adalah detail implementasi internal SDK dan tidak boleh diinstansiasi secara manual. Pendekatan yang benar adalah menggunakan Journeys SDK, yang mengelola siklus hidup iFrame secara aman dan sesuai standar yang diharapkan.

Jika ada keraguan apakah suatu pendekatan sesuai dengan standar yang didukung, konsultasikan dokumentasi atau hubungi dukungan sebelum melanjutkan implementasi.