--- title: Integrasi Aplikasi Web description: Cara mengintegrasikan kontrak Web & SDK di sisi klien — alur redirect dan konfigurasi iFrame SDK. canonical: https://developer.unico.io/id/human-token/integrations/web/web-integration/ locale: id generated_by: markdown-export --- 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](https://developer.mozilla.org/en-US/docs/Web/API/Window/open) untuk detail tentang API. ```mermaid sequenceDiagram participant Unico as Unico backend service participant Backend as Customer backend server participant Frontend as Customer frontend application participant Hosted as Unico hosted frontend application Frontend->>Backend: start kyc flow Backend->>Unico: call createProcess Unico->>Backend: return Unico process info Backend->>Frontend: return Unico process info Frontend->>Hosted: redirect user to process url Note over Hosted: User journey Hosted->>Frontend: redirect user to callback url critical Get process result Frontend->>Backend: signals that journey was finished Backend->>Unico: call getProcess opt Webhook Note over Backend: In addition to getProcess, you can use the Webhook implementation to ensure a fallback in obtaining the process result. end end ``` 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. ```mermaid sequenceDiagram participant Unico as Unico backend service participant Backend as Customer backend server participant App as Customer mobile application participant Hosted as Unico hosted frontend application App->>Backend: start kyc flow Backend->>Unico: call createProcess Unico->>Backend: return Unico process info Backend->>App: return Unico process info App->>Hosted: open the process url in a webview Note over Hosted: User journey Hosted->>App: redirect user to the deeplink (callback url) critical Get process result App->>Backend: signals that journey was finished Backend->>Unico: call getProcess opt Webhook Note over Backend: In addition to getProcess, you can use the Webhook implementation to ensure a fallback in obtaining the process result. end end ``` ### 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. ```bash 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. :::tip[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"); ``` :::info 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 | ```javascript 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. :::warning 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. ```javascript 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: ```mermaid sequenceDiagram participant Unico as Unico backend service participant Backend as Customer backend server participant Frontend as Customer frontend application participant SDK as ByUnicoSDK Frontend->>Backend: start kyc flow Backend->>Unico: call createProcess Unico->>Backend: return Unico process info Backend->>Frontend: return Unico process info Note over Frontend: Initialize the Unico journey as soon as it is determined that the KYC flow is required critical Unico journey initialization Frontend->>SDK: byUnicoSDK.init SDK-->>Frontend: validates customer domain and initialize end critical Unico journey exhibition Frontend->>SDK: byUnicoSDK.open SDK-->>Frontend: show byUnico experience end Note over SDK: User journey critical Unico journey completion SDK-->>Frontend: call onFinish end critical Get process result Frontend->>Backend: signals that journey was finished Backend->>Unico: call getProcess opt Webhook Note over Backend: In addition to getProcess, you can use the Webhook implementation to ensure a fallback in obtaining the process result. end end ``` #### Aplikasi contoh | Bahasa / Framework | Deskripsi | Repositori | | --------------------- | ------------ | ---------- | | Angular | PoC di Angular yang mengimplementasikan Journeys SDK | [GitHub — unico-cbu-poc-angular](https://github.com/unico-labs/unico-cbu-poc-angular) | | JS Vanilla | PoC di JS Vanilla yang mengimplementasikan Journeys SDK | [GitHub — unico-cbu-poc-js](https://github.com/unico-labs/unico-cbu-poc-js) | | React | PoC di React yang mengimplementasikan Journeys SDK | [GitHub — unico-cbu-poc-react](https://github.com/unico-labs/unico-cbu-poc-react) | | Vue JS | PoC di Vue JS yang mengimplementasikan Journeys SDK | [GitHub — unico-cbu-poc-vuejs](https://github.com/unico-labs/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. :::warning[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 `