Integrasi Aplikasi Web

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

Sebuah journey adalah rangkaian langkah yang dilalui pengguna untuk menyelesaikan verifikasi identitas. Misalnya: mengambil foto dokumen dan melakukan pengambilan wajah (Deteksi Kehidupan).

Unico menangani seluruh pengalaman tersebut. Upaya integrasi sangat minimal: journey dibuat melalui CreateProcess, pengguna diarahkan ke sana, dan pada akhirnya hasilnya diterima. Semua yang terjadi di antaranya (layar, instruksi, validasi) sudah siap dan dikelola oleh Unico.

Memilih pendekatan integrasi Anda

• Web SDK (paket unico-webframe): gunakan ketika back-end Anda sudah mengontrol alur verifikasi identitas dan hanya memerlukan komponen pengambilan di sisi klien. Mengembalikan base64 + JWT terenkripsi langsung ke callback Anda; Anda yang mengelola panggilan API.
• Web App Integration (paket idpay-b2b-sdk): gunakan ketika Anda ingin Unico mengorkestrasi seluruh journey (alur multi-langkah, pengambilan dokumen + Deteksi Kehidupan). Paket idpay-b2b-sdk mendukung model SDK Journeys (iFrame) yang tersemat; model Akses langsung (redirect) tidak memerlukan pustaka.

Dua model integrasi

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

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

Akses langsung

Pengguna diarahkan ke tautan yang dihosting oleh Unico, tempat journey berlangsung. Setelah selesai, pengguna dikembalikan ke URL yang ditentukan saat pembuatan proses (parameter callbackUri).

Ini adalah pendekatan yang paling sederhana untuk diadopsi: tidak memerlukan pemasangan pustaka dan bekerja dengan baik ketika journey tidak perlu berlangsung di dalam halaman aplikasi itu sendiri. Di sisi lain, membawa pengguna keluar dari lingkungan klien cenderung menimbulkan lebih banyak friksi dan, sebagai akibatnya, tingkat pengabaian yang lebih tinggi.

Setelah membuat proses, respons API menyertakan URL journey yang dihosting oleh Unico. Ada dua cara umum untuk mengarahkan pengguna ke sana:

• Redirect standar. Pengguna diarahkan langsung ke URL journey. Setelah selesai, Unico mengarahkannya 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 hal ini, disarankan untuk memantau perubahan URL ke callbackUri dan menutup tab setelah proses selesai. Lihat dokumentasi MDN untuk detail tentang API tersebut.

Pada aplikasi mobile, umum digunakan WebView untuk membuka journey secara langsung, tanpa perlu redirect tambahan. Dalam hal ini, callbackUri juga menerima sebuah deeplink, yang memungkinkan penyelesaian journey memicu pembukaan layar tertentu di aplikasi native. Cukup konfigurasikan deeplink sebagai tujuan pengembalian dan sistem operasi akan menangani pengarahan pengguna ke tempat yang tepat.

SDK Journeys

Journey berlangsung di dalam aplikasi itu sendiri, tanpa mengeluarkan pengguna dari konteksnya. SDK Journeys dipasang di aplikasi dan digunakan untuk membuka journey saat diperlukan.

Ini adalah jalur yang direkomendasikan untuk pengalaman yang lebih terintegrasi dan mulus, menjaga pengguna tetap berada di lingkungan yang sama sepanjang proses, yang cenderung mengurangi friksi dan pengabaian di sepanjang alur.

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

Kompatibilitas

Pustaka ini dirancang agar dapat menyatu dengan proyek apa pun tanpa friksi, terlepas dari stack yang digunakan:

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

Cara kerja SDK secara internal

Saat sebuah journey dibuka, SDK menyisipkan sebuah iFrame ke dalam halaman dan mengambil kendali atas seluruh pengalaman visual sejak saat itu. Layar, skrip, dan aset setiap langkah berjalan di dalam iFrame ini, sejak saat pengguna mulai hingga proses selesai.

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

Karena Unico bertanggung jawab untuk membuat dan mengelola iFrame, peningkatan pada journey (baik dari sisi performa, pengalaman, maupun validasi) dikirimkan secara otomatis kepada semua pengguna, tanpa perlu perubahan apa pun pada aplikasi yang terintegrasi. Integrasi akan selalu berjalan dengan optimasi terbaik yang tersedia, tanpa perlu mengikuti atau bereaksi terhadap setiap pembaruan platform.

Memulai

Langkah 1: Pemasangan

Paket idpay-b2b-sdk digunakan bersama 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 memasang SDK Journeys adalah melalui pengelola dependensi seperti npm atau yarn, dari paket yang tersedia di npm registry. Selain menyederhanakan pemasangan dan pengelolaan dependensi, pendekatan ini memberikan kontrol yang jelas atas versi yang digunakan dan memudahkan pembaruan setiap kali versi baru dirilis.

SDK mengikuti Semantic Versioning (SemVer), yang berarti pembaruan patch dan minor tidak memperkenalkan perubahan yang merusak. Aman untuk mengonfigurasi proyek agar menerima pembaruan ini secara otomatis. Perubahan yang mungkin memerlukan penyesuaian pada integrasi disediakan untuk versi major dan selalu disertai panduan migrasi.

Selalu perbarui SDK

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

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

Langkah 2: Panggil init(options)

Menginisialisasi SDK dan memuat lebih awal skrip yang diperlukan 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	Setel ke 'uat' hanya untuk lingkungan pengujian

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

ByUnicoSDK.init({
  token,
  // env: 'uat' // hanya untuk lingkungan pengujian
});

Langkah 3: Panggil open(options)

Menampilkan iFrame dan memulai journey untuk pengguna. Sejak titik ini, 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 dijalankan saat journey berakhir atau ditutup
onWidgetVisibilityChange	Tidak	Callback yang dijalankan saat status visibilitas widget berubah

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

Selain memeriksa hasilnya, disarankan untuk menggunakan onFinish guna menangani status front-end aplikasi:

• Hindari perulangan. Mencegah pembuatan ulang proses yang langsung dan tidak perlu jika pengguna memicu alur lagi tepat setelah journey berakhir.
• Pengelolaan alur. Pastikan pengguna diarahkan ke langkah berikutnya dalam aplikasi, menghindari terjebak di layar tanpa jalan keluar setelah journey ditutup.

peringatan

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

Callback onFinish menerima sebuah 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 saat type bernilai 'FINISH'; undefined saat type bernilai 'CLOSE'
transaction.id	string	Pengidentifikasi proses (sama dengan transactionId yang diberikan)
transaction.redirectUrl	string	URL untuk mengarahkan pengguna setelah journey

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

ByUnicoSDK.open({
  transactionId: '9bc22bac-1e64-49a5-94d6-9e4f8ec9a1bf',
  token: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...',
  onFinish: ({ transaction, type }) => {
    if (type === 'FINISH') {
      // Journey selesai (transaction = { id, redirectUrl }): lanjutkan alur Anda di sini.
    }
    // type === 'CLOSE' → pengguna menutup sebelum selesai;
  },
  // Opsional: hanya diperlukan jika aplikasi Anda menampilkan UI yang dapat menutupi widget.
  onWidgetVisibilityChange: (visible) => {
    // sembunyikan atau pulihkan modal Anda berdasarkan visibilitas widget
  },
});

// Untuk menutup SDK secara eksplisit kapan saja:
ByUnicoSDK.close();

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

Keamanan

Cakupan bagian ini

Justifikasi keamanan ini berlaku khusus untuk Web App Integration (idpay-b2b-sdk). Web SDK (unico-webframe) menggunakan model yang berbeda: ia berjalan sepenuhnya dalam konteks halaman dan memang memerlukan CSP. Keduanya adalah dua produk berbeda dengan arsitektur keamanan yang berbeda.

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

Saat journey dimuat, kedua belah pihak melakukan handshake untuk membangun komunikasi. Dalam proses ini, aplikasi Unico memvalidasi asal pesan injeksi data yang diterima melalui postMessage terhadap daftar tertutup domain yang diizinkan, yang disegmentasi berdasarkan lingkungan (UAT dan PROD). Pesan dari asal yang tidak disetujui langsung dibuang, sehingga mencegah journey disematkan pada 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 yang diterbitkan dan ditandatangani oleh backend Unico. Ini memastikan bahwa bahkan asal yang sah pun tidak dapat beroperasi dengan token yang kedaluwarsa, digunakan ulang, atau dipalsukan.

Setelah handshake, token disuntikkan ke dalam iFrame dan tidak ada lagi informasi sensitif yang mengalir di antara kedua belah pihak. Seluruh komunikasi selebihnya hanya berfungsi untuk kontrol antarmuka (membuka, menutup, dan transisi layar), sehingga mencegah data proses disadap atau bocor selama journey.

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

Berdasarkan desain, CSP tidak diterapkan dalam model integrasi ini. Domain yang diizinkan merupakan bagian dari konfigurasi keamanan setiap klien, dan pengungkapannya secara publik di header dapat memudahkan pemetaan infrastruktur oleh pihak yang berniat jahat. Karena identifikasi klien baru terjadi pada saat init, tidak mungkin menyuntikkan domain-domain ini secara dinamis ke dalam header sebelum titik tersebut, sehingga membuat CSP tidak dapat diterapkan tanpa mengorbankan privasi ini. Semua jaminan keamanan disediakan oleh protokol handshake yang dijelaskan di atas.

Pemecahan masalah khusus SDK

Bagian ini membahas masalah paling umum yang dijumpai selama integrasi serta cara yang disarankan untuk menyelidikinya.

Perilaku tak terduga atau alur terputus

Periksa apakah ada skrip aplikasi yang memanipulasi iFrame secara langsung di DOM. SDK membuat dan mengelola iFrame di body halaman, dan setiap modifikasi eksternal (baik pada cakupan, posisi, maupun atribut) dapat mengganggu siklus hidup journey dan menyebabkan perilaku yang tak terduga.

Pengalaman visual berbeda dari yang diharapkan

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

Berkas pustaka SDK dimodifikasi secara langsung

Periksa apakah ada berkas pustaka yang dimodifikasi di luar pengelola dependensi. Pustaka harus dikelola secara eksklusif melalui npm atau yarn, tanpa pengeditan langsung pada berkas yang terpasang. Modifikasi manual dapat menghasilkan perilaku tidak normal yang sulit direproduksi dan membuat dukungan dari tim Unico tidak dapat membantu.

Jangan biarkan DevTools terbuka selama pengujian pengambilan

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

Integrasi yang tidak didukung

Model yang dijelaskan dalam dokumentasi ini (akses langsung dan SDK Journeys) 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, serta tidak akan dicakup oleh dukungan Unico.

Beberapa contoh pendekatan yang tidak didukung:

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

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