Memulai•Quickstart

Mulai Cepat: Integrasi 4 Langkah

Panduan ringkas ini cukup untuk mengintegrasikan **aktivasi dan login pertama pengguna** ke dalam aplikasi mobile native kamu. Alurnya selalu terdiri dari 4 langkah berurutan.

Langkah 1 — Dapatkan String Signature (Cukup Sekali)

Sebelum WebView pernah dibuka, aplikasi memanggil endpoint /api/init-linkage untuk memperoleh satu string Signature terenkripsi yang berisi identitas pengguna dan perangkat fisik. WebView memakai string ini untuk mengenali siapa yang sedang membukanya.

POST{BASE_URL_SEAMLESS}/api/init-linkage

Payload Request /api/init-linkage

Parameter	Tipe Data	Status	Deskripsi & Contoh
userFullname	string	Wajib	Nama lengkap user sesuai data aplikasi client. Contoh: `ERWIN RUDIYANTO`
userPhone	string	Wajib	Nomor handphone user terdaftar. Contoh: `081234567890`
deviceId	string	Wajib	ID unik perangkat fisik. Harus stabil per perangkat dan tidak boleh berubah. Contoh: `a8f9c2d1-e5b7-4a6c-9f8d-1234567890ab`
installId	string	Wajib	FCM token atau instance ID instalasi aplikasi client. Contoh: `fcm_token_client_12345`
deviceBrand	string	Wajib	Merek perangkat (maksimal 100 karakter). Contoh: `samsung`
deviceModel	string	Wajib	Model perangkat (maksimal 100 karakter). Contoh: `SM-G991B`
clientId	string	Wajib	Client ID kredensial resmi dari Qoin.
clientSecret	string	Wajib	Client Secret resmi dari Qoin (wajib dirahasiakan).

Contoh Response Sukses:

JSON

{
  "signature": "eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkEyNTZHQ00iLC..."
}

Penting: Simpan & Pakai Ulang Signature

Simpan string signature tersebut di penyimpanan aman lokal client (Secure Storage / SharedPreferences / Keychain). Gunakan kembali nilai yang sama setiap kali membuka WebView. Hanya panggil ulang jika user login dengan nomor baru atau perangkat di-reinstall.

Langkah 2 — Siapkan Izin Lokasi GPS Perangkat (WAJIB)

Proses aktivasi dan verifikasi PIN mewajibkan lokasi geografis (GPS) perangkat aktif. Lokasi ini digunakan sistem keamanan backend Qoin untuk validasi anti-fraud berstandar Bank Indonesia.

WebView Butuh Izin Akses dari Native Host

Halaman web di dalam WebView tidak bisa memunculkan pop-up izin lokasi Android/iOS sendiri. Host native app wajib:

Meminta izin lokasi di tingkat OS (Manifest Android / Info.plist iOS).
Memastikan GPS / Layanan Lokasi perangkat menyala saat WebView dibuka.
Mengizinkan WebView mengakses geolocation (pasang handler callback geolocation).

Langkah 3 — Buka WebView ke Root URL & Kirim postMessage

Buka WebView ke alamat root {BASE_URL_SEAMLESS}/ (bukan langsung ke /activate atau /qoincash). Sistem resolver webview sendiri yang akan otomatis menentukan apakah pengguna perlu aktivasi baru, cukup memasukkan PIN re-autentikasi, atau langsung masuk ke halaman utama.

Setelah halaman selesai dimuat (event onPageFinished / onLoadStop), suntikkan pesan ke WebView:

postMessage Injection

// Kirim segera setelah halaman selesai dimuat
window.postMessage(JSON.stringify({
  Signature: "<signature_dari_langkah_1>",
  Palette: "original" // Pilihan: original, blue-ocean, red-lava, green-forest, dark-blue
}), "*");

// REKOMENDASI: Kirim ulang ±500ms kemudian untuk memastikan listener siap
setTimeout(() => {
  window.postMessage(JSON.stringify({
    Signature: "<signature_dari_langkah_1>",
    Palette: "original"
  }), "*");
}, 500);

Langkah 4 — Menangkap Balasan Event dari WebView

WebView akan mengirimkan pesan status balik ke host native app menggunakan JavaScript Bridge. Host harus memproses event tersebut sesuai tabel berikut:

Daftar Balasan yang Diterima Native Host

Parameter	Tipe Data	Status	Deskripsi & Contoh
{"STATUS":"TRUE","FOR":"ACTIVATE"}	event	Wajib	Layar aktivasi berhasil tampil di WebView. PENTING: Jangan tutup webview di event ini!
{"close":true,"STATUS":"TRUE","FOR":"ACTIVATE"}	close event	Wajib	User menekan tombol 'Selesai' di layar akhir aktivasi sukses. TUTUP WebView sekarang dan tandai akun user sebagai terhubung.
{"close":true,"STATUS":"FALSE","FOR":"ACTIVATE"}	close event	Wajib	Aktivasi gagal atau dibatalkan oleh pengguna. Tutup WebView.

Pengenalan Kredensial & Lingkungan