Integrasi Pulse SDK

Pulse SDK adalah library native yang menghubungkan aplikasi mobile Anda dengan dashboard Pulse. Sekali dipasang, SDK:

• Monitoring: mencatat crash, error, request HTTP, sesi, screen, dan event kustom, lalu menampilkannya di menu Monitoring.
• Informasi in-app: mengambil maintenance, fitur baru, dan banner yang Anda buat di dashboard, lalu menampilkannya sebagai popup, banner, atau badge.
• Push: berlangganan topic FCM per aplikasi dan build, sehingga informasi bisa dikirim sebagai push tanpa menyimpan token perangkat.

SDK tersedia native untuk Kotlin/Java dan Swift/Objective-C, serta sebagai plugin Flutter. Semua method aman dipanggil dari thread mana pun dan tidak pernah melempar exception ke aplikasi.

1. Ambil workspace key. Login ke dashboard Pulse → Pengaturan → Workspace → Workspace key → Tampilkan. Key berawalan pk_.
2. Pasang SDK sesuai platform (lihat Instalasi).
3. Panggil start sekali saat aplikasi dibuka, dengan workspace key tersebut.
4. Jalankan aplikasi, lalu buka menu Monitoring di dashboard. Sesi pertama muncul dalam beberapa detik.

Untuk compileSdk 37 gunakan Android Gradle Plugin 9.1.1 atau lebih baru.

Tambahkan dependency dari Maven Central (pastikan mavenCentral() ada di daftar repository).

dependencies {
    implementation("io.github.mhmadidris:pulse-monitoring:0.1.2")
}

Panggil start sekali, sedini mungkin, agar crash dan sesi pertama ikut tercatat. Jika aplikasi memakai Firebase atau Crashlytics, inisialisasi Firebase lebih dulu lalu mulai Pulse. Handler crash sebelumnya tetap dipanggil.

import android.app.Application
import dev.pulse.monitoring.PulseConfig
import dev.pulse.monitoring.PulseMonitoring

class App : Application() {
    override fun onCreate() {
        super.onCreate()
        PulseMonitoring.start(
            this,
            PulseConfig(
                workspaceKey = "pk_…",       // Pengaturan → Workspace
                debug = BuildConfig.DEBUG,   // log ke Logcat, tag "PulseMonitoring"
            ),
        )
    }
}

<application android:name=".App" />

Jika aplikasi sudah punya kelas Application, tambahkan pemanggilan di kelas itu; jangan membuat kelas kedua. Package ID, versi, dan build dibaca otomatis dari aplikasi.

Setelah login, set ID internal user yang stabil, dan kosongkan saat logout agar event berikutnya tidak tertaut ke akun sebelumnya. Event kustom muncul di Monitoring → perilaku pengguna.

PulseMonitoring.setUser("user_123")   // setelah login
PulseMonitoring.trackEvent("document_sent", mapOf("document_count" to 2, "success" to true))
PulseMonitoring.setUser(null)         // saat logout

Hindari email, nama lengkap, isi dokumen, token, atau data sensitif lain di event dan pesan error.

Uncaught exception JVM dicatat otomatis sebagai crash dan dikirim saat aplikasi dibuka lagi. Crash native (NDK/sinyal) belum ditangkap. Untuk exception yang Anda tangani sendiri:

try {
    upload()
} catch (e: Exception) {
    PulseMonitoring.recordError(e)
}

Error dengan jenis dan lokasi yang sama dikelompokkan menjadi satu issue di dashboard. Jangan melaporkan exception yang sama dua kali lewat catch dan handler global.

Request HTTP menghasilkan durasi, status, dan error rate per endpoint. URL dikirim tanpa query string, fragment, dan kredensial.

val client = OkHttpClient.Builder()
    .addInterceptor(PulseOkHttpInterceptor())
    .build()

// Klien lain: catat manual
PulseMonitoring.recordHttp("GET", url, 200, durationMs, requestBytes = null, responseBytes = 2048)

Catat setiap request satu kali saja, dan jangan memasukkan ID sensitif ke path URL.

Dengan autoScreens = true (default), setiap Activity yang tampil dicatat dengan nama kelasnya. Untuk Compose atau fragment, panggil manual:

PulseMonitoring.trackScreen("Checkout")

Pakai satu cara saja untuk screen yang sama agar tidak tercatat ganda.

Maintenance, fitur baru, dan banner yang Anda terbitkan di dashboard aktif otomatis setelah start. Tidak ada setup tambahan. SDK mengambil feed saat start, setiap aplikasi kembali ke foreground, dan saat push masuk, lalu menyimpannya agar tetap tampil saat offline.

Item yang ditargetkan ke versi tertentu hanya tampil di build yang cocok: SDK mengirim build number aplikasi (versionCode) saat mengambil feed.

Membaca feed dan menangani aksi

PulseInformation.items()             // item aktif
PulseInformation.activeMaintenance() // maintenance aktif, atau null
PulseInformation.addListener { items -> /* main thread */ }
PulseInformation.refresh()

// Buka deep link sendiri; true = sudah ditangani (default: browser)
PulseInformation.setActionHandler { uri -> router.open(uri) }

Ingin menampilkan popup sendiri? Set autoPopups ke false, lalu panggil showPopups di layar yang Anda pilih.

Selain popup, maintenance bisa ditampilkan sebagai komponen siap pakai yang muncul dan hilang sendiri mengikuti jadwal di dashboard.

<dev.pulse.monitoring.PulseMaintenanceBanner
    android:layout_width="match_parent"
    android:layout_height="wrap_content"
    android:layout_margin="16dp" />

<dev.pulse.monitoring.PulseMaintenanceBadge
    android:layout_width="wrap_content"
    android:layout_height="wrap_content">
    <ImageView android:src="@drawable/ic_home"
        android:layout_width="24dp" android:layout_height="24dp" />
</dev.pulse.monitoring.PulseMaintenanceBadge>

Jika maintenance ditampilkan sebagai chip atau badge sendiri, matikan popup otomatisnya dengan autoMaintenancePopups = false. Feed dan listener tetap berjalan, dan menekan chip tetap bisa membuka detail maintenance.

Push memakai Firebase Cloud Messaging milik aplikasi Anda. SDK tidak menambahkan dependency Firebase dan tidak mengirim token ke server. Saat Firebase Messaging tersedia, SDK berlangganan topic:

pulse.<package_id>.<platform>.all
pulse.<package_id>.<platform>.b<build>

Dashboard mengirim ke topic ini sesuai target versi informasi. Teruskan setiap pesan ke SDK; nilai true berarti pesan milik Pulse sudah ditangani.

class AppMessagingService : FirebaseMessagingService() {
    override fun onMessageReceived(message: RemoteMessage) {
        if (PulseInformation.handlePush(message.data)) return
        // push lain milik aplikasi
    }
}

Tanpa Firebase, langganan topic dilewati dan monitoring tetap berjalan normal.

Menu Push & distribusi → Kirim notifikasi mengirim notifikasi ke semua pengguna aplikasi lewat topic pulse.<package>.<platform>.all, lengkap dengan gambar opsional dan link yang dibuka saat ditekan. Pesan ini membawa pulse_type=notification dan, bila diisi, url.

Android tidak menampilkan notifikasi saat aplikasi terbuka. Teruskan pesan ke PulseNotifications.handle: SDK menampilkannya (beserta gambar) dan, saat ditekan, membuka url lewat action handler yang sama dengan tombol informasi. Di Android 13+, aplikasi perlu meminta izin POST_NOTIFICATIONS.

override fun onMessageReceived(message: RemoteMessage) {
    if (PulseInformation.handlePush(message.data)) return
    if (PulseNotifications.handle(message.data, message.notification?.title,
            message.notification?.body, message.notification?.imageUrl?.toString())) return
    // push lain milik aplikasi
}

// Activity singleTop: teruskan intent baru
override fun onNewIntent(intent: Intent) {
    super.onNewIntent(intent)
    PulseNotifications.handleTap(this, intent)
}

Setiap tap dicatat sekali sebagai event pulse_notification_opened dengan properti has_url, tanpa isi pesan atau URL.

Pengiriman data

• Event diantrikan di disk (maks. 1000), lalu dikirim per batch (maks. 100 event / 512 KiB, gzip).
• Batch dikirim tiap 30 detik, saat 50 event mengantri, saat aplikasi ke background, atau saat flush() dipanggil.
• Gagal jaringan, 429, atau 5xx dicoba ulang dengan jeda bertambah (5 detik hingga 5 menit).

Yang dikumpulkan otomatis: package/bundle ID, versi dan build aplikasi, model perangkat, versi OS, locale, serta ID instalasi acak (bukan ID hardware, IDFA, atau IDFV). Isi request/response, query string, email, dan nama tidak dikumpulkan.

ID user, event kustom, dan pesan error berasal dari aplikasi Anda, jadi pastikan tidak berisi data sensitif. SDK iOS menyertakan PrivacyInfo.xcprivacy; deklarasi privasi aplikasi tetap perlu mencerminkan data kustom yang Anda kirim.

Pertanyaan integrasi? Hubungi idris3097@gmail.com.