Integrasi Aplikasi Web
Halaman ini mencakup dua pendekatan integrasi sisi klien untuk kontrak Web & SDK: mengarahkan pengguna ke journey yang dihosting Unico, dan menyematkan journey melalui iFrame SDK.
- Mengarahkan pengguna
- iFrame
Setelah membuat proses, respons menyertakan URL yang mengarah ke journey yang dihosting Unico. Gunakan URL ini untuk mengarahkan pengguna ke pengalaman pengambilan gambar. Ada dua cara untuk mengelola transisi ini:
1. Redirect standar
Arahkan pengguna langsung ke URL journey. Saat pengguna menyelesaikan proses, Unico akan mengarahkan mereka kembali ke URL yang Anda tentukan saat pembuatan proses.
2. Tab baru dengan window.open()
Buka journey di tab browser baru sehingga pengguna tetap berada dalam konteks terpisah. Pantau perubahan URL ke URL kembali Anda dan tutup tab tersebut saat proses selesai.
Untuk detail tentang API window.open(), lihat dokumentasi MDN.
Integrasi yang tidak mengikuti standar dalam dokumentasi ini dapat menyebabkan gangguan tak terduga dan tidak akan dicakup oleh dukungan Unico.
Contoh pendekatan yang tidak didukung: menyematkan SDK di dalam WebView, atau memuat iFrame langsung melalui tag HTML.
Cara Memulai
Langkah 1 — Instalasi
SDK by Unico menggunakan paket yang sama dengan IDPay:
npm install idpay-b2b-sdk
Instal tanpa menyematkan versi tertentu agar manajer paket Anda selalu mengambil rilis minor dan patch terbaru secara otomatis.
Sebelum memulai, daftarkan domain Anda ke tim dukungan Unico. Semua domain harus menggunakan HTTPS.
Langkah 2 — Panggil init(options)
Menginisialisasi SDK dan memuat aset lebih awal, menciptakan pengalaman yang lebih lancar bagi pengguna akhir. Panggil ini sedini mungkin dalam alur Anda.
| Parameter | Wajib | Deskripsi |
|---|---|---|
type | Ya | Atur ke 'IFRAME' untuk alur by Unico |
token | Ya | Token proses yang dikembalikan oleh API Pembuatan Proses |
env | Tidak | Atur ke 'uat' hanya untuk lingkungan pengujian |
import { ByUnicoSDK } from "idpay-b2b-sdk";
ByUnicoSDK.init({
type: 'IFRAME',
token,
// env: 'uat' // only for test environments
});
Langkah 3 — Panggil open(options)
Menampilkan iFrame yang telah dimuat sebelumnya dan memulai alur pesan antara halaman Anda dan journey Unico.
| Parameter | Wajib | Deskripsi |
|---|---|---|
transactionId | Ya | ID proses yang dikembalikan oleh API Pembuatan Proses |
token | Ya | Token proses yang dikembalikan oleh API Pembuatan Proses |
onFinish | Ya | Callback yang dieksekusi saat journey berakhir atau ditutup |
Callback onFinish menerima objek proses dengan ID transaksi, URL redirect, dan jenis penyelesaian.
ByUnicoSDK.open({
transactionId: '9bc22bac-1e64-49a5-94d6-9e4f8ec9a1bf',
token: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...',
onFinish: (process) => {
console.log('Process finished', process);
// process.transaction.redirectUrl — use this to navigate the user
},
});
// To close the SDK explicitly at any point:
ByUnicoSDK.close();
Diagram urutan di bawah ini menunjukkan cara menggunakan SDK dan hasil API untuk mengonfigurasi iFrame:
Keamanan
Pilih solusi iFrame dengan token autentikasi daripada CSP
Setelah analisis yang cermat, pendekatan yang dipilih menggunakan iframe dengan token autentikasi daripada mengimplementasikan Content Security Policy (CSP). Keputusan ini didorong oleh persyaratan keamanan dan fleksibilitas yang diperlukan untuk memenuhi kebutuhan klien.
Konteks dan tantangan dengan CSP
Content Security Policy adalah alat yang ampuh untuk melindungi aplikasi web dari serangan XSS dan injeksi kode. Namun, mengonfigurasi kebijakan CSP memerlukan penetapan daftar domain tepercaya yang ketat. Pendekatan ini efektif ketika domain bersifat tetap dan dapat diprediksi — tetapi bagi klien yang menggunakan domain dinamis dan variabel, konfigurasi kaku ini menghadirkan tantangan yang signifikan.
Kerentanan dengan domain dinamis
Domain dinamis menimbulkan risiko keamanan yang substansial saat menggunakan CSP. Ketika klien memiliki domain yang sering berubah atau dibuat secara dinamis, kebijakan CSP harus terus diperbarui untuk menyertakan domain baru. Hal ini tidak hanya meningkatkan beban pemeliharaan tetapi juga mengekspos setiap domain yang terdaftar dalam kebijakan sebagai potensi permukaan serangan jika tidak dikelola dengan baik.
Solusi dengan iFrame dan token autentikasi
Untuk memitigasi risiko ini dan memenuhi fleksibilitas yang diperlukan oleh klien, solusi yang dipilih menggabungkan iframe dengan token autentikasi, memberikan lapisan keamanan tambahan tanpa memerlukan daftar domain statis.
Cara kerjanya:
- Autentikasi aman — setiap iFrame dimuat dengan token autentikasi unik per transaksi, memastikan hanya pengguna yang berwenang yang dapat mengakses konten. Token diverifikasi secara real-time.
- Isolasi konten — iFrame berjalan dalam konteks penjelajahan terpisah, mengurangi risiko interferensi antara asal yang berbeda dan memitigasi potensi serangan.
- Fleksibilitas untuk domain dinamis — dengan tidak bergantung pada kebijakan CSP statis, solusi ini beradaptasi dengan domain klien yang dinamis tanpa memerlukan pembaruan kebijakan yang terus-menerus.