Hướng dẫn tích hợp Flutter SDK

dependencies:
  vietmap_tracking_plugin: ^1.0.7

flutter pub get

<manifest>
  <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
  <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
  <uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION" />
  <uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
  <uses-permission android:name="android.permission.FOREGROUND_SERVICE_LOCATION" />
  <uses-permission android:name="android.permission.WAKE_LOCK" />

  <application>
    <service
      android:name=".LocationTrackingService"
      android:enabled="true"
      android:exported="false"
      android:foregroundServiceType="location" />
  </application>
</manifest>

<dict>
  <key>NSLocationWhenInUseUsageDescription</key>
  <string>Ứng dụng cần GPS để theo dõi vị trí nhân viên khi đang chạy.</string>

  <key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
  <string>Ứng dụng cần GPS để tiếp tục theo dõi khi chạy nền.</string>

  <key>NSLocationAlwaysUsageDescription</key>
  <string>Ứng dụng cần GPS khi chạy nền.</string>

  <key>UIBackgroundModes</key>
  <array>
    <string>location</string>
    <string>background-fetch</string>
    <string>background-processing</string>
  </array>

  <!-- Bắt buộc cho background tracking trên iOS -->
  <key>BGTaskSchedulerPermittedIdentifiers</key>
  <array>
    <string>com.vietmaptrackingsdk.background-location</string>
    <string>com.vietmaptrackingsdk.location-sync</string>
  </array>
</dict>

import 'package:vietmap_tracking_plugin/vietmap_tracking_plugin.dart';

final controller = VietmapTrackingController.instance;

// Khởi tạo với API key
// baseURL là optional — SDK dùng URL production mặc định
await controller.initializeTracking('YOUR_API_KEY');

// Hoặc với custom server:
await controller.initializeTracking(
  'YOUR_API_KEY',
  baseURL: 'https://live.fleetwork.vn/api/v1',
);

// Đăng ký lifecycle observer (gọi 1 lần sau initializeTracking)
controller.registerLifecycleObserver();

final result = await controller.requestLocationPermissions();
print(result.granted);          // bool — đủ quyền foreground?
print(result.status.value);     // "granted" | "denied" | "not_granted"
print(result.fineLocation);     // bool
print(result.backgroundLocation); // bool

final status = await controller.requestAlwaysLocationPermissions();
// "granted" | "denied" | "when_in_use"

final result = await controller.hasLocationPermissions();
if (!result.granted) {
  // Dẫn user đến màn hình cấp quyền
}

// Bắt đầu tracking — timer mode (mỗi 10 giây)
await controller.startTracking(
  LocationTrackingConfig(
    intervalMs: 10000,        // Capture GPS mỗi 10 giây
    distanceFilter: 0,        // Tắt distance trigger
    accuracy: LocationAccuracy.high,
    backgroundMode: true,
    userId: 'user-001',
    vehicleId: 'vehicle-abc', // optional
    deviceId: 'device-001',   // optional
    notificationTitle: 'Đang theo dõi hành trình',   // Android only
    notificationMessage: 'Chạm để mở ứng dụng',      // Android only
  ),
);

// Bắt đầu tracking — distance mode (mỗi 15 mét)
await controller.startTracking(
  LocationTrackingConfig(
    intervalMs: 0,            // Tắt timer trigger
    distanceFilter: 15.0,     // Capture mỗi khi di chuyển ≥ 15m
    accuracy: LocationAccuracy.high,
    backgroundMode: true,
    userId: 'user-001',
  ),
);

// Dừng tracking
await controller.stopTracking();

final isActive = await controller.isTrackingActive(); // bool

final status = await controller.getTrackingStatus();
print(status.isTracking);          // bool
print(status.trackingDuration);    // int (ms kể từ startTracking)
print(status.lastLocationUpdate);  // int? (unix ms)

await controller.updateTrackingConfig(
  LocationTrackingConfig(
    intervalMs: 30000,
    distanceFilter: 0,
    accuracy: LocationAccuracy.medium,
    backgroundMode: true,
  ),
);

// Cập nhật ngay — không cần restart tracking
await controller.setVehicleId('vehicle-xyz');
await controller.setDriverId('user-002');

// Lấy giá trị hiện tại
final vehicleId = await controller.getVehicleId();
final driverId  = await controller.getDriverId();

// Đặt preferred profile khi xe đang di chuyển
controller.setSmartBatteryPreferredProfile(SmartBatteryProfile.navigation);

// Feed GPS vào SmartBattery để phát hiện góc cua và đứng yên
controller.onLocationUpdate.listen((LocationData loc) {
  controller.feedLocationToSmartBattery(loc.speed, heading: loc.heading);
});

// Lắng nghe khi profile thay đổi
controller.onSmartBatteryProfileChanged.listen((SmartBatteryProfile profile) {
  print('Profile changed: ${profile.name}');
});

// Cấu hình giới hạn cache (gọi trước startTracking)
await controller.configureCacheLimits(
  maxRecords: 5000,        // Số record tối đa
  maxDbSizeBytes: 52428800, // 50 MB
  batchSize: 50,           // Record mỗi lần upload
);

// Kiểm tra / quản lý cache
final count  = await controller.getCachedLocationsCount(); // số điểm chờ gửi
final bytes  = await controller.getDatabaseSizeBytes();    // kích thước cache

// Gửi cache ngay (không chờ timer 30s nội bộ)
await controller.uploadCachedLocationsManually();

// Bật / tắt auto upload
await controller.setAutoUpload(true);

// Xoá toàn bộ cache (không hoàn tác)
await controller.clearCachedLocations();

// Vị trí mới ghi nhận
controller.onLocationUpdate.listen((LocationData loc) {
  print('${loc.latitude}, ${loc.longitude}');
  print('Speed: ${loc.speed} m/s');     // m/s
  print('Heading: ${loc.heading}°');
});

// Thay đổi trạng thái tracking
controller.onTrackingStatusChanged.listen((TrackingStatus status) {
  print('isTracking: ${status.isTracking}');
});

// Profile Smart Battery thay đổi
controller.onSmartBatteryProfileChanged.listen((SmartBatteryProfile profile) {
  print('Battery profile: ${profile.name}');
});

enum SmartBatteryProfile {
  navigation,   // 5 giây — chính xác cao
  general,      // 30 giây — cân bằng mặc định
  batterySaver, // 10 phút — tiết kiệm pin tối đa
}