--- 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/dual-api/developers/sdks-and-tools/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 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. :::tip[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](https://developer.mozilla.org/en-US/docs/Web/API/Window/open) untuk detail tentang API tersebut. ```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 ``` 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. ```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 ``` ### 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. ```bash 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. :::tip[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 | ```javascript 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. :::warning 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. ```javascript 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: ```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 sampel | Bahasa / Framework | Deskripsi | Repository | | --------------------- | ------------ | ---------- | | Angular | PoC dalam Angular yang mengimplementasikan SDK Journeys | [GitHub — unico-cbu-poc-angular](https://github.com/unico-labs/unico-cbu-poc-angular) | | JS Vanilla | PoC dalam JS Vanilla yang mengimplementasikan SDK Journeys | [GitHub — unico-cbu-poc-js](https://github.com/unico-labs/unico-cbu-poc-js) | | React | PoC dalam React yang mengimplementasikan SDK Journeys | [GitHub — unico-cbu-poc-react](https://github.com/unico-labs/unico-cbu-poc-react) | | Vue JS | PoC dalam Vue JS yang mengimplementasikan SDK Journeys | [GitHub — unico-cbu-poc-vuejs](https://github.com/unico-labs/unico-cbu-poc-vuejs) | #### Keamanan :::note[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](/dual-api/developers/sdks-and-tools/web/web-sdk/installation). 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). :::warning[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 `