Panduan ini menjelaskan cara memasang dan menampilkan Livechat Barantum di project Android Anda. Project sample-app hanya digunakan sebagai acuan untuk memastikan contoh kode sesuai dengan API SDK; Anda tidak perlu menjalankan atau menyalin seluruh sample project.

1. Gambaran integrasi

SDK menyediakan BarantumWidgetView, yaitu komponen Android yang menampilkan antarmuka Livechat di dalam WebView. Aplikasi Anda membuat konfigurasi, memasang listener, lalu memuat konfigurasi tersebut ke widget.

• Aplikasi Android membuat BarantumWidgetView.
• BarantumWidgetConfig menghubungkan widget ke inbox tujuan.
• Widget memuat halaman https://livechat.barantum.com/widget/.
• Pesan pengunjung diteruskan ke inbox agent Barantum.
• Event dari Livechat diterima aplikasi melalui BarantumWidgetListener.

2. Prasyarat

• Project Android dengan minSdk 23 atau lebih baru.
• AndroidX Activity sudah digunakan oleh aplikasi.
• File SDK Android atau akses ke repository artifact Barantum.
• Inbox Identifier dari inbox Livechat yang telah dibuat.
• Permission internet pada aplikasi.

URL customer bersifat tetap: https://livechat.barantum.com. Jangan mengganti URL ini dengan domain lain. Android SDK juga menggunakan halaman widget tetap https://livechat.barantum.com/widget/.

3. Menambahkan SDK dari paket ZIP

SDK Android diberikan dalam paket ZIP. Ekstrak paket tersebut ke dalam project Android Anda, kemudian daftarkan direktori library Android sebagai module Gradle.

Ekstrak paket SDK

Ekstrak file ZIP ke dalam folder libs pada root project Android. Contoh struktur direktorinya:

my-android-app/

├── app/

├── libs/

│ └── sdk-services/

│   └── packages/

│     └── android/

│       └── widget/

├── settings.gradle.kts

└── build.gradle.kts

Library yang digunakan oleh aplikasi berada pada direktori packages/android/widget. Jika nama atau lokasi folder hasil ekstraksi berbeda, sesuaikan path module pada langkah berikutnya.

Daftarkan module SDK

Tambahkan konfigurasi berikut pada settings.gradle.kts di root project Android:

include(":barantum-widget")

project(":barantum-widget").projectDir =

    file("libs/sdk-services/packages/android/widget")

Konfigurasi tersebut memberi nama module :barantum-widget dan mengarahkannya ke source library Android di dalam paket SDK.

Tambahkan dependency ke aplikasi

Pada file app/build.gradle.kts, tambahkan module SDK sebagai dependency:

dependencies {

    implementation(project(":barantum-widget"))

}

Jalankan Gradle Sync setelah konfigurasi disimpan. Jika import dari package com.barantum.widget dapat dikenali oleh Android Studio, SDK telah berhasil ditambahkan.

4. Menambahkan permission internet

Tambahkan permission INTERNET pada AndroidManifest.xml, di luar elemen <application>:

<manifest xmlns:android="http://schemas.android.com/apk/res/android">

    <uses-permission android:name="android.permission.INTERNET" />

    <application

        android:usesCleartextTraffic="false"

        ... >

    </application>

</manifest>

Livechat menggunakan HTTPS sehingga android:usesCleartextTraffic dapat tetap bernilai false.

5. Menambahkan widget ke layout

Buat layout res/layout/activity_live_chat.xml dan tambahkan BarantumWidgetView sebagai container Livechat:

<?xml version="1.0" encoding="utf-8"?>

<FrameLayout

    xmlns:android="http://schemas.android.com/apk/res/android"

    android:layout_width="match_parent"

    android:layout_height="match_parent">

    <com.barantum.widget.BarantumWidgetView

        android:id="@+id/barantumWidget"

        android:layout_width="match_parent"

        android:layout_height="match_parent" />

</FrameLayout>

Widget dapat ditempatkan sebagai layar penuh atau di dalam container pada desain aplikasi Anda.

6. Membuat Activity Livechat

Buat LiveChatActivity.kt. Contoh berikut sudah mencakup file chooser, listener, konfigurasi inbox, dan pembersihan resource:

package com.example.app

import android.os.Bundle

import android.util.Log

import androidx.activity.ComponentActivity

import com.barantum.widget.BarantumConversationStatus

import com.barantum.widget.BarantumWidgetConfig

import com.barantum.widget.BarantumWidgetListener

import com.barantum.widget.BarantumWidgetView

class LiveChatActivity : ComponentActivity() {

    private lateinit var widgetView: BarantumWidgetView

    override fun onCreate(savedInstanceState: Bundle?) {

        super.onCreate(savedInstanceState)

        setContentView(R.layout.activity_live_chat)

        widgetView = findViewById(R.id.barantumWidget)

        // Wajib dipanggil di onCreate sebelum widget dimuat.

        widgetView.registerFileChooser(this)

        widgetView.listener = object : BarantumWidgetListener {

            override fun onReady() {

                Log.d("Livechat", "Widget siap digunakan")

            }

            override fun onCloseRequested() {

                finish()

            }

            override fun onUnreadChanged(count: Int) {

                Log.d("Livechat", "Pesan belum dibaca: " + count)

            }

            override fun onConversationStatusChanged(

                status: BarantumConversationStatus,

            ) {

                Log.d("Livechat", "Status percakapan: " + status)

            }

            override fun onError(message: String) {

                Log.e("Livechat", message)

            }

        }

        val config = BarantumWidgetConfig.Builder()

            .widgetUrl("https://livechat.barantum.com/widget/")

            .livechat(

                "https://livechat.barantum.com",

                "INBOX_IDENTIFIER_ANDA",

            )

            .locale("id")

            .preChat(false)

            .title("Livechat")

            .subtitle("Kami siap membantu Anda")

            .color("#0F766E")

            .build()

        widgetView.load(config)

    }

    override fun onDestroy() {

        widgetView.listener = null

        widgetView.release()

        super.onDestroy()

    }

}

Ganti INBOX_IDENTIFIER_ANDA dengan identifier milik inbox Livechat Anda. Jangan memakai URL widget.js pada Android; file tersebut hanya digunakan oleh integrasi web.

7. Penjelasan konfigurasi

• widgetUrl(...) menentukan halaman widget yang dimuat oleh WebView. Gunakan https://livechat.barantum.com/widget/.
• livechat(baseUrl, inboxIdentifier) menghubungkan widget ke server dan inbox tujuan. baseUrl harus tetap https://livechat.barantum.com.
• locale("id") menentukan bahasa antarmuka. Gunakan "en" untuk bahasa Inggris.
• preChat(false) membuka percakapan tanpa form pra-chat. Ubah menjadi true jika nama, email, atau telepon perlu diminta sebelum chat.
• title(...), subtitle(...), color(...), dan logoUrl(...) bersifat opsional untuk menyesuaikan tampilan.
• load(config) memuat halaman Livechat dan mengirim konfigurasi setelah halaman siap.

8. Menangani event dari Livechat

Semua callback listener bersifat opsional dan dijalankan pada main thread. Override hanya callback yang diperlukan:

• onReady() — sesi Livechat berhasil terhubung; cocok untuk menyembunyikan indikator loading.
• onCloseRequested() — pengunjung menekan tombol tutup; Activity atau navigation host menentukan cara menutup layar.
• onUnreadChanged(count) — jumlah pesan agent yang belum dibaca berubah; gunakan untuk memperbarui badge.
• onConversationStatusChanged(status) — status percakapan berubah menjadi PENDING, PROGRESS, atau DONE.
• onError(message) — inisialisasi atau koneksi gagal; tampilkan pesan retry dan catat detail untuk diagnosis.

9. Identitas pengguna dan HMAC (opsional)

Jika aplikasi memiliki pengguna yang sudah login, kirim external ID yang stabil beserta profilnya. Identifier hash harus dibuat oleh backend menggunakan HMAC secret, kemudian hasil hash dikirim ke aplikasi.

val identifierHashDariBackend =

    livechatApi.getIdentifierHash(currentUser.id)

val config = BarantumWidgetConfig.Builder()

    .livechat(

        "https://livechat.barantum.com",

        "INBOX_IDENTIFIER_ANDA",

        identifierHashDariBackend,

    )

    .visitorExternalId(currentUser.id)

    .visitorName(currentUser.name)

    .visitorEmail(currentUser.email)

    .visitorPhone(currentUser.phone)

    .locale("id")

    .build()

widgetView.load(config)

HMAC secret tidak boleh disimpan di source code, resource, BuildConfig, local storage, atau APK. Aplikasi Android hanya menerima identifierHash hasil perhitungan backend. Nilai yang ditandatangani backend harus sama persis dengan nilai visitorExternalId.

Saat identitas visitor tersedia, form pra-chat akan dilewati. Jika pengguna berganti akun, buat ulang widget dan konfigurasi menggunakan visitorExternalId pengguna yang baru agar percakapan antar-akun tidak tercampur.

10. Lifecycle dan file chooser

• Panggil registerFileChooser(this) dari onCreate sebelum Activity mencapai state STARTED dan sebelum load(config).
• Pasang listener sebelum load(config) agar event awal tidak terlewat.
• Saat layar ditutup, set listener menjadi null lalu panggil release() pada onDestroy.
• Jangan menggunakan kembali instance BarantumWidgetView setelah release().
• Untuk tombol tutup dari widget, tangani onCloseRequested() dengan finish() atau navigasi kembali sesuai arsitektur aplikasi.

11. Membuka layar Livechat

Daftarkan Activity pada AndroidManifest.xml:

<activity

    android:name=".LiveChatActivity"

    android:exported="false" />

Kemudian buka dari tombol bantuan atau menu aplikasi:

startActivity(

    Intent(this, LiveChatActivity::class.java)

)

12. Pengujian integrasi

• Buka LiveChatActivity dan pastikan onReady() terpanggil.
• Kirim pesan dari aplikasi dan pastikan pesan masuk ke inbox yang sesuai.
• Balas melalui dashboard agent dan pastikan balasan muncul di aplikasi.
• Kirim lampiran dan pastikan Android document picker terbuka.
• Uji tombol tutup, tombol Back, rotasi layar, serta buka-tutup Activity berulang kali.
• Jika menggunakan identitas login, uji logout dan pergantian akun.
• Pastikan HMAC secret tidak ditemukan di source code maupun APK.

13. Troubleshooting

• Widget kosong atau onReady() tidak terpanggil

Periksa permission INTERNET, koneksi perangkat, Android System WebView, serta Logcat. Pastikan widgetUrl menggunakan https://livechat.barantum.com/widget/.

• Pesan masuk ke inbox yang salah

Periksa nilai INBOX_IDENTIFIER_ANDA. Identifier menentukan inbox tujuan dan tidak boleh memiliki spasi tambahan.

• File picker tidak terbuka

Pastikan registerFileChooser(this) dipanggil pada onCreate sebelum load(config).

• Livechat gagal terhubung setelah HMAC diaktifkan

Pastikan hash dibuat di backend dengan secret inbox yang benar dan input HMAC sama persis dengan visitorExternalId.

• Terjadi masalah setelah Activity ditutup

Pastikan listener dilepas dan widgetView.release() selalu dipanggil pada onDestroy.

14. Ringkasan

Untuk meng-embed Livechat Barantum di Android: tambahkan SDK ke module aplikasi, berikan permission internet, tempatkan BarantumWidgetView pada layout, buat BarantumWidgetConfig menggunakan URL Barantum yang tetap dan Inbox Identifier Anda, pasang listener, lalu panggil load(config). Lengkapi integrasi dengan registerFileChooser() dan release() agar lampiran serta lifecycle berjalan dengan benar.