Panduan menambahkan Livechat sebagai fitur dukungan di aplikasi Flutter Android dan iOS

Panduan ini menjelaskan cara memasang paket barantum_widget dari paket SDK, menghubungkannya ke Inbox Livechat Barantum, dan menempatkan layar chat di alur aplikasi Anda. Integrasi menggunakan koneksi langsung melalui Inbox Identifier.

1. Gambaran integrasi

BarantumWidget adalah widget Flutter berbasis WebView yang memuat antarmuka Livechat Barantum. Aplikasi Anda membuat BarantumWidgetConfig, meneruskan identitas visitor bila tersedia, lalu menangani callback yang diterima dari SDK.

• Aplikasi membuka halaman bantuan atau rute Livechat.
• BarantumWidgetConfig menghubungkan widget ke server Livechat dan inbox tujuan.
• BarantumWidget memuat halaman https://livechat.barantum.com/widget/.
• Pesan visitor diteruskan ke inbox agent Barantum.
• Callback SDK dapat memperbarui loading, badge unread, status percakapan, dan error di aplikasi.

2. Prasyarat

• Flutter SDK versi 3.10 atau lebih baru.
• Dart SDK versi 3.0 atau lebih baru.
• Project Flutter untuk Android dan/atau iOS.
• Inbox Livechat Barantum yang telah dibuat dan aktif beserta Inbox Identifier-nya.
• Paket SDK Barantum yang memuat folder packages/flutter.
• Koneksi internet pada perangkat atau emulator.

3. Menambahkan SDK Flutter dari paket ZIP

Ekstrak paket SDK ke dalam project Flutter. Contoh struktur direktori:

my_flutter_app/

├── lib/

├── pubspec.yaml

└── libs/

    └── sdk-services/

        └── packages/

            └── flutter/

                ├── lib/

                └── pubspec.yaml

Daftarkan paket lokal pada pubspec.yaml aplikasi:

dependencies:

  flutter:

    sdk: flutter

  barantum_widget:

    path: libs/sdk-services/packages/flutter

Kemudian jalankan perintah berikut dari root project Flutter:

flutter pub get

Paket ini sudah membawa dependensi WebView dan URL launcher yang diperlukan. Import SDK pada halaman yang menampilkan chat:

import 'package:barantum_widget/barantum_widget.dart';

4. Konfigurasi Android

Untuk build Android release, pastikan AndroidManifest.xml aplikasi memiliki permission internet di luar elemen application:

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

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

    <application ...>

        ...

    </application>

</manifest>

Livechat menggunakan HTTPS. Gunakan URL widget https://livechat.barantum.com/widget/ dan base URL https://livechat.barantum.com; jangan menggantinya dengan domain aplikasi Anda atau file widget.js.

5. Membuat halaman Livechat

Buat halaman Flutter khusus untuk Livechat. Contoh berikut memakai koneksi langsung ke inbox dan menangani callback utama:

import 'package:barantum_widget/barantum_widget.dart';

import 'package:flutter/material.dart';

class LiveChatPage extends StatefulWidget {

  const LiveChatPage({super.key, required this.visitor});

  final BarantumVisitor visitor;

  @override

  State<LiveChatPage> createState() => _LiveChatPageState();

}

class _LiveChatPageState extends State<LiveChatPage> {

  bool _ready = false;

  String? _error;

  @override

  Widget build(BuildContext context) {

    final config = BarantumWidgetConfig(

      widgetUrl: 'https://livechat.barantum.com/widget/',

      livechat: const BarantumLivechatConfig(

        baseUrl: 'https://livechat.barantum.com',

        inboxIdentifier: 'INBOX_IDENTIFIER_ANDA',

        appId: 'my-flutter-app',

      ),

      locale: 'id',

      preChat: false,

      color: '#0F766E',

      title: 'Live Chat',

      subtitle: 'Kami siap membantu Anda',

      visitor: widget.visitor,

    );

    return Scaffold(

      appBar: AppBar(title: const Text('Live Chat')),

      body: Stack(

        children: [

          BarantumWidget(

            config: config,

            onReady: () => setState(() {

              _ready = true;

              _error = null;

            }),

            onCloseRequested: () => Navigator.of(context).pop(),

            onUnreadChanged: (count) {

              debugPrint('Pesan belum dibaca: $count');

            },

            onConversationStatusChanged: (status) {

              debugPrint('Status percakapan: ' + status.wireValue);

            },

            onError: (message) => setState(() => _error = message),

          ),

          if (!_ready && _error == null)

            const LinearProgressIndicator(),

          if (_error != null)

            Center(child: Text(_error!)),

        ],

      ),

    );

  }

}

Ganti INBOX_IDENTIFIER_ANDA dengan identifier milik inbox Livechat Anda. appId bersifat opsional, tetapi sebaiknya diisi dengan ID stabil untuk membedakan sumber percakapan dalam inbox yang sama.

6. Membuka layar dari fitur aplikasi

Livechat sebaiknya ditempatkan sebagai salah satu fitur aplikasi, misalnya dari halaman Bantuan atau tombol Hubungi Kami:

Navigator.of(context).push(

  MaterialPageRoute(

    builder: (_) => LiveChatPage(

      visitor: BarantumVisitor(

        externalId: currentUser.id,

        name: currentUser.name,

        email: currentUser.email,

        phone: currentUser.phone,

        attributes: const {

          'source': 'flutter-app',

          'membership': 'gold',

        },

      ),

    ),

  ),

);

Gunakan externalId yang stabil dari sistem pengguna Anda. Jangan memakai email atau nomor telepon sebagai externalId apabila nilainya dapat berubah.

7. Penjelasan konfigurasi

• widgetUrl wajib menunjuk ke halaman widget https://livechat.barantum.com/widget/.
• livechat menggunakan baseUrl https://livechat.barantum.com dan inboxIdentifier untuk menentukan inbox tujuan.
• appId opsional sebagai pemisah sesi atau asal percakapan per aplikasi dalam inbox yang sama.
• locale menerima id atau en.
• preChat bernilai false untuk membuka chat tanpa form pra-chat; ubah menjadi true bila aplikasi perlu meminta data sebelum chat.
• color, title, subtitle, dan logoUrl bersifat opsional untuk menyesuaikan tampilan.
• visitor menerima externalId, nama, email, telepon, dan attributes. Nilai attributes hanya boleh berupa String, angka berhingga, atau bool.

8. Identitas visitor dan HMAC

Untuk visitor yang sudah login, teruskan data profil saat membuat BarantumVisitor. Bila identity verification diaktifkan, aplikasi harus memperoleh identifierHash dari backend:

final identifierHash = await livechatApi.getIdentifierHash(currentUser.id);

final config = BarantumWidgetConfig(

  livechat: BarantumLivechatConfig(

    baseUrl: 'https://livechat.barantum.com',

    inboxIdentifier: 'INBOX_IDENTIFIER_ANDA',

    identifierHash: identifierHash,

    appId: 'my-flutter-app',

  ),

  visitor: BarantumVisitor(

    externalId: currentUser.id,

    name: currentUser.name,

  ),

);

Jangan pernah membuat HMAC atau menyimpan HMAC secret di aplikasi Flutter, --dart-define, source code, maupun APK/IPA. Backend harus membuat hash dari externalId yang sama persis dengan nilai yang dikirim sebagai visitor.externalId.

9. Callback SDK

• onReady dipanggil ketika sesi Livechat benar-benar siap; gunakan untuk menghentikan loading.
• onCloseRequested dipanggil ketika visitor menekan tombol tutup; host menentukan apakah layar ditutup atau dinavigasikan kembali.
• onUnreadChanged menerima jumlah pesan agent yang belum dibaca; gunakan untuk memperbarui badge di host app.
• onConversationStatusChanged menerima status pending, progress, atau done.
• onError menerima pesan kegagalan inisialisasi atau koneksi; tampilkan aksi coba lagi dan catat detail diagnosis.

10. Pengujian integrasi

• Jalankan flutter pub get, lalu flutter run pada emulator atau perangkat fisik.
• Buka halaman Livechat dan pastikan indikator loading hilang setelah onReady dipanggil.
• Kirim pesan percobaan dan pastikan pesan masuk ke inbox yang tepat.
• Balas melalui dashboard agent dan pastikan balasan serta callback unread/status diterima aplikasi.
• Uji tombol tutup, buka ulang halaman chat, pergantian akun, dan koneksi jaringan yang tidak tersedia.
• Jika menggunakan visitor terverifikasi, uji bahwa HMAC dibuat di backend dan tidak ada secret pada aplikasi.

11. Troubleshooting

Widget kosong atau terus memuat

Periksa koneksi internet, Inbox Identifier, dan URL widget. widgetUrl harus menggunakan https://livechat.barantum.com/widget/, bukan widget.js.

Pesan masuk ke inbox yang salah

Periksa inboxIdentifier tanpa spasi tambahan. Nilai ini menentukan inbox tujuan.

Identitas visitor tidak terverifikasi

Pastikan identifierHash berasal dari backend, menggunakan secret inbox yang benar, dan input HMAC sama persis dengan visitor.externalId.

Callback tidak memperbarui UI

Perbarui state aplikasi dari callback, misalnya melalui setState atau state management yang digunakan aplikasi Anda. Hindari membuat ulang halaman chat saat state callback berubah.

12. Ringkasan

Untuk meng-embed Livechat Barantum di Flutter: tambahkan paket SDK pada pubspec.yaml, jalankan flutter pub get, buat BarantumWidgetConfig dengan URL Barantum dan Inbox Identifier, tampilkan BarantumWidget di halaman bantuan, lalu tangani callback sesuai kebutuhan aplikasi.