📘 Mục lục #

👤 Dành cho người sử dụng #

🧑‍💻 Dành cho nhà phát triển #

MiChat SDK for Flutter #

MiChat SDK giúp bạn dễ dàng tích hợp tính năng chat (Live Chat) vào ứng dụng Flutter. SDK hỗ trợ việc khởi tạo, xác thực appKey, tự động nhận diện platform và hiển thị giao diện chat linh hoạt (trong app hoặc mở trình duyệt).

Dành cho người sử dụng #

🚀 Tính năng chính #

• Khởi tạo SDK với appKey, domain.
• Tự động phát hiện nền tảng (platform).
• Xác thực đơn giản qua SDK.
• Mở giao diện chat từ URL (dưới dạng WebView hoặc mở trình duyệt).
• Hỗ trợ web, Android, iOS, desktop.

📅 Cài đặt #

Trong pubspec.yaml:

dependencies:
  michat_sdk: ^0.1.0-beta

Hướng dẫn lấy appKey #

Để sử dụng được SDK bạn cần phải appKey được cấp từ phía nhà phát triển. Hãy liên hệ: https://mitek.vn/ để lấy appKey.

⚙️ Khởi tạo SDK #

• Sau khi lấy appKey thành công, bạn cần khởi tạo SDK trong hàm main() hoặc initState() của app.
• Bạn cần cung cấp thêm domain, chính là dịch vụ bạn muốn sử dụng. Ví dụ: https://uat-chatbot.midesk.vn/test/livechatmobie.

import 'package:michat_sdk/michat_sdk.dart';

void main() async {
  try {
    await MiChat().init(
      appKey: "123456",
      domain:
          "https://uat-chatbot.midesk.vn/test/livechatmobie",
    );
    runApp(const MyApp());
  } catch (e) {
    runApp(MaterialApp(home: ErrorView(errorDetails: e.toString())));
  }
}

❗ Nếu không khởi tạo đúng hoặc xác thực thất bại, người dùng sẽ không thể truy cập giao diện chat.

✔️ Có thể sử dụng ErrorView(errorDetails: "Chi tiết lỗi") để hiển thị lỗi khi khởi tạo SDK lên giao diện. Lưu ý: Phải đảm bảo ErrorView được bọc trong MaterialApp.

🔍 Error Code Reference #

📘 Thuộc tính truy cập của MiChat SDK #

Sau khi gọi MiChat().init(...) thành công, bạn có thể truy cập các thông tin cấu hình của SDK qua các thuộc tính sau:

⚙️ Thuộc tính #

🔒 Lưu ý #

Tất cả các thuộc tính (trừ isInitialized) đều yêu cầu SDK phải được khởi tạo. Nếu không, chúng sẽ ném ra lỗi:

💬 Mở giao diện Chat #

Sử dụng ChatScreen để hiển thị giao diện chat:

import 'package:michat_sdk/chat_screen.dart';

Navigator.push(
  context,
  MaterialPageRoute(
    builder: (_) => ChatScreen(
      name: 'Nguyễn Văn A',
      phone: '0123456789',
      email: 'test@example.com',
    ),
  ),
);

✅ SDK sẽ hiển thị trang chat lên WebView.

⚠️ Lưu ý: Tất cả name, phone, email đều là tham số tuỳ chọn, có thể truyền vào hoặc không. Nếu 3 tham số không tồn tại WebView sẽ tự động hiển thị trang nhập thông tin. (Dành cho khách hàng chưa đăng nhập)

📄 Tham số ChatScreen #

🛡️ Kiểm tra khởi tạo #

Bạn có thể kiểm tra SDK đã khởi tạo chưa:

if (MiChat().isInitialized) {
  // OK
} else {
  // Hiển thị thông báo lỗi
}

📌 Ghi chú #

• SDK sẽ được xác thực thành công chỉ khi sử dụng đúng appKey và đúng domain mà bạn được cấp quyền sử dụng.
• Mỗi phiên bản MiChat() là singleton.
• Có thể dùng SDK trên cả nền tảng mobile, web và desktop.

📖 Ví dụ đầy đủ #

await MiChat().init(
  appKey: '123456',
  domain: 'https://uat-chatbot.midesk.vn/test/livechatmobie',
);

Navigator.push(
  context,
  MaterialPageRoute(
    builder: (_) => ChatScreen(
      name: 'Nguyễn Văn A',
      phone: '0987654321',
      email: 'user@example.com',
    ),
  ),
);

🧑‍💼 Liên hệ & Hỗ trợ #

• ☎ Hotline: [1900 1238](tel:1900 1238)
• 📨 Email: contact@mitek.vn
• 🌐 Website: https://michat.vn

📄 License #

MIT License.

Dành cho nhà phát triển #

Cấu trúc dự án #

lib/
  core.dart               // Khởi tạo và quản lý vòng đời SDK
  error_view.dart         // Giao diện hiện thị lỗi khi xử lý SDK (tuỳ chọn sử dụng)
  michat_sdk.dart         // Entry point của package
  src/                    // Các class nội bộ (internal chat_sdk.dart)
  chat_screen.dart        // Widget giao diện chat

Hướng dẫn thiết lập môi trường phát triển #

Yêu cầu hệ thống #

• Dart SDK: >= 3.0.0 < 4.0.0
• Flutter SDK: >= 3.10.0
• Nền tảng tối thiểu hỗ trợ:
  • ✅ Android: API 21+ (Android 5.0 trở lên)
  • ✅ iOS: iOS 11.0 trở lên
  • ✅ Web: Chrome, Safari, Firefox (modern browsers)

Thiết lập #

• Clone dự án:

git clone https://gitlab.mitek.vn/mobile-app/michatsdk-v2/michat_sdk-flutter.git

• Cập nhật:

cd michat_sdk-flutter
flutter pub get

Chạy thử dự án #

• Clone dự án (chạy terminal ở thư mục mong muốn):

git clone https://gitlab.mitek.vn/mobile-app/michatsdk-v2/michat_sdk_example-flutter.git

• Khởi chạy:

cd michat_sdk_example-flutter
flutter run

Đóng góp mã nguồn #

1. Fork repository
2. Tạo nhánh mới: git checkout -b feature/ten-chuc-nang
3. Commit theo chuẩn convention
4. Mở Pull Request lên nhánh main hoặc dev

Lưu ý:

• Kiểm tra định dạng: flutter format .
• Phân tích tĩnh: dart analyze

Kiểm thử và build #

flutter test          # chạy toàn bộ test
flutter build apk     # build app thử nghiệm

Cách thức SDK hoạt động #

• Bước 1: Yêu cầu người sử dụng cũng cấp appKey, domain để khởi tạo SDK. Trả về trạng thái thành công hoặc lỗi.
• Bước 2: Khởi tạo thành công, người dùng có thể mở ChatScreen, WebView tự động mở đường dẫn mà người dùng sử dụng để khởi tạo (xác thực).
• Bước 3: Trong ChatScreen, phần khởi tạo sẽ gọi ChatSDK xử lý URL sau đó trả về WebView dưới dạng Widget, sử dụng Widget này hiển thị lên màn hình ChatScreen.

Ghi chú phát triển #

• SDK sử dụng singleton: không cần khởi tạo lại nhiều lần.
• WebView được sử dụng cho giao diện chat.
• Các tham số name, phone, email là tuỳ chọn, nếu không truyền vào thì phía server web sẽ cung cấp phần nhập thông tin.

Cập nhật package #

Để phát hành phiên bản mới:

1. Tăng version trong pubspec.yaml:

version: 1.0.1 //Hiện tại là 0.1.0-beta

2. Chạy kiểm tra toàn bộ:

flutter test

3. Build tài liệu nếu cần:

dart doc .

4. Đăng package lên pub.flutter-io.cn:

flutter pub publish

Đảm bảo bạn đã đăng nhập với flutter pub login

License #

MIT License.