Cài đặt Flutter App

Yêu cầu

Flutter SDK — Phiên bản phù hợp với VieLang IoT (xem ma trận tương thích)
IDE — VS Code (khuyến nghị) hoặc Android Studio
Android Studio — Cần để chạy Android emulator
Xcode — Cần để chạy iOS simulator (chỉ macOS)
VieLang IoT backend — Đang chạy tại http://localhost:8080

Cài đặt Flutter

Dùng FVM (Flutter Version Manager) — Khuyến nghị

FVM cho phép chuyển đổi phiên bản Flutter dễ dàng:

# Cài FVM
dart pub global activate fvm

# Cài phiên bản Flutter phù hợp (xem .fvmrc trong project)
fvm install 3.29.0
fvm use 3.29.0

# Kiểm tra
fvm flutter --version

Cài trực tiếp

Tải Flutter SDK tại flutter.dev và làm theo hướng dẫn cho hệ điều hành của bạn.

flutter --version
flutter doctor  # Kiểm tra môi trường

Clone và cấu hình

Bước 1: Clone repository

git clone https://github.com/vielang/vielang-mobile.git
cd vielang-mobile

Bước 2: Tạo Bundle trong Mobile Center

Đăng nhập vào VieLang IoT dashboard
Vào Mobile Center → tab Bundle → + Add bundle
Nhập tên bundle (ví dụ: My IoT App)
Click Create new cho Android:
- Package name: com.yourcompany.iotapp
- Application Secret: Auto-generate
- Status: Draft
Click Next → Add

Bước 3: Tải file cấu hình

Từ ThingsBoard 4.2+ / VieLang IoT:

Vào Mobile Center → chọn Bundle vừa tạo
Click Download configuration
Lưu file configs.json vào thư mục gốc của project Flutter

Bước 4: Cài dependencies

flutter pub get
# Hoặc nếu dùng FVM:
fvm flutter pub get

Bước 5: Chạy ứng dụng

# Bắt buộc dùng flag --dart-define-from-file
flutter run --dart-define-from-file configs.json

# Nếu dùng FVM:
fvm flutter run --dart-define-from-file configs.json

Quan trọng: Phải dùng flag --dart-define-from-file configs.json khi build. Không dùng sẽ app không kết nối được backend.

Kiểm tra log — phải thấy dòng:

Invoked tbMobileReadyHandler

Cấu hình VS Code

Tạo file .vscode/launch.json:

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "VieLang Mobile (Debug)",
      "request": "launch",
      "type": "dart",
      "args": [
        "--dart-define-from-file",
        "configs.json"
      ]
    },
    {
      "name": "VieLang Mobile (Profile)",
      "request": "launch",
      "type": "dart",
      "flutterMode": "profile",
      "args": [
        "--dart-define-from-file",
        "configs.json"
      ]
    }
  ]
}

Xử lý lỗi thường gặp

App không build được

Nguyên nhân: Sai phiên bản Flutter.

# Kiểm tra phiên bản cần dùng
cat .fvmrc

# Chuyển sang đúng phiên bản
fvm use $(cat .fvmrc | tr -d '"')
fvm flutter pub get

Không đăng nhập được

Nguyên nhân: Sai phiên bản hoặc backend chưa chạy.

Kiểm tra backend: curl http://localhost:8080/api/v1/info
Kiểm tra configs.json có đúng URL backend không
Kiểm tra ma trận tương thích phiên bản

Push notification không hoạt động

Nguyên nhân: Firebase chưa cấu hình.

# Xóa cấu hình cũ và tạo lại
rm lib/firebase_options.dart
flutterfire configure

Dashboard không load

Kiểm tra: Tìm trong log:

Có Invoked tbMobileReadyHandler → Lỗi từ mobile app
Không có → Lỗi từ backend

Bước tiếp theo

Mobile Center — Quản lý bundle và apps
Push Notifications — Cài đặt Firebase FCM
Tùy chỉnh icon & splash — Branding app