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

dependencies:
  vietmap_tracking_plugin: ^1.1.3

flutter pub get

<uses-permission android:name="android.permission.INTERNET" />
<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" />
<!-- Bắt buộc để hiện notification trên Android 13+ -->
<uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
<!-- Bắt buộc để đặt lại notification sau khi khởi động lại máy -->
<uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED" />

<receiver android:exported="false"
    android:name="com.dexterous.flutterlocalnotifications.ScheduledNotificationReceiver" />
<receiver android:exported="false"
    android:name="com.dexterous.flutterlocalnotifications.ScheduledNotificationBootReceiver">
    <intent-filter>
        <action android:name="android.intent.action.BOOT_COMPLETED"/>
        <action android:name="android.intent.action.MY_PACKAGE_REPLACED"/>
        <action android:name="android.intent.action.QUICKBOOT_POWERON" />
        <action android:name="com.htc.intent.action.QUICKBOOT_POWERON"/>
    </intent-filter>
</receiver>
<receiver android:exported="false"
    android:name="com.dexterous.flutterlocalnotifications.ActionBroadcastReceiver" />

allprojects {
    repositories {
        maven { url 'https://jitpack.io' }
    }
}

<key>NSLocationWhenInUseUsageDescription</key>
<string>Ứng dụng cần GPS để theo dõi vị trí 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-processing</string>
    <string>background-fetch</string>
</array>

<key>BGTaskSchedulerPermittedIdentifiers</key>
<array>
    <string>com.vietmaptrackingsdk.location-sync</string>
    <string>com.vietmaptrackingsdk.background-location</string>
</array>

# ios/Podfile
platform :ios, '15.0'

cd ios && pod install

import 'package:flutter/services.dart';
import 'package:vietmap_tracking_plugin/vietmap_tracking_plugin.dart';

final controller = VietmapTrackingController.instance;

Future<void> initSdk() async {
  try {
    // Xác thực API key phía server — throw INVALID_API_KEY nếu bị từ chối
    await controller.initializeTracking(
      'YOUR_API_KEY',
      baseURL: 'https://live.fleetwork.vn/api/v1', // tuỳ chọn
    );
    // Đăng ký lifecycle observer để SDK tự chuyển background/foreground
    controller.registerLifecycleObserver();
  } on PlatformException catch (e) {
    if (e.code == 'INVALID_API_KEY') {
      print('API key không hợp lệ: ${e.message}');
    }
  }
}

// Bước 1 — quyền vị trí foreground
final result = await controller.requestLocationPermissions();
if (!result.granted) return;

// Bước 2 — quyền background (Android 10+ hiện popup riêng)
await controller.requestAlwaysLocationPermissions();

// Bước 3 — quyền notification (Android 13+ / iOS)
// Android
await Permission.notification.request();
// iOS
await FlutterLocalNotificationsPlugin()
    .resolvePlatformSpecificImplementation<IOSFlutterLocalNotificationsPlugin>()
    ?.requestPermissions(alert: true, sound: true, badge: false);

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

await controller.startTracking(
  LocationTrackingConfig(
    userId: 'user-123',            // bắt buộc
    intervalMs: 30000,             // 30 giây / lần
    accuracy: LocationAccuracy.high,
    backgroundMode: true,
    notificationTitle: 'Đang theo dõi hành trình',
    notificationMessage: 'Chạm để mở ứng dụng',
  ),
);

// Hoặc dùng preset dựng sẵn:
await controller.startTracking(
  TrackingPresets.general().copyWith(userId: 'user-123'),
);

// Hoặc để native SDK tự quyết định tần suất (timer 10 giây / sàn 25 mét):
await controller.startTracking(
  LocationTrackingConfig.sdkDefault(userId: 'user-123'),
);

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

TrackingPresets.navigation()    //  5 giây  — theo dõi xe thời gian thực / dẫn đường
TrackingPresets.fitness()       // 10 giây  — hoạt động ngoài trời
TrackingPresets.general()       // 30 giây  — cân bằng cho đội xe (mặc định)
TrackingPresets.batterySaver()  //  5 phút  — xe đỗ hoặc pin yếu

TrackingPresets.navigationDistance()    // mỗi  25 m — sàn khoảng cách của SDK
TrackingPresets.fitnessDistance()       // mỗi  50 m
TrackingPresets.generalDistance()       // mỗi  70 m
TrackingPresets.batterySaverDistance()  // mỗi 120 m

await controller.startTracking(
  TrackingPresets.general().copyWith(userId: 'user-123'),
);

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)

// Đổi config mà không cần restart tracking
await controller.updateTrackingConfig(
  LocationTrackingConfig(
    userId: 'user-123',
    intervalMs: 60000,
    accuracy: LocationAccuracy.medium,
    backgroundMode: true,
  ),
);

// Đặt profile ưu tiên khi xe đang di chuyển (mặc định: general)
controller.setSmartBatteryPreferredProfile(SmartBatteryProfile.navigation);

await controller.startTracking(config, enableSmartBattery: true);

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

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

await controller.enableSmartBatteryOptimization();   // áp preset của profile hiện tại
controller.disableSmartBatteryOptimization();        // chỉ teardown phía Dart
await controller.updateTrackingConfig(myConfig);     // …nên khôi phục lại config sau khi tắt

// Đăng ký trước startTracking — yêu cầu Smart Battery áp lại config của bạn
// thay vì chuyển sang preset native ở mỗi lần đổi profile.
SmartBatteryManager.instance.customGeneralConfigOverride = () async {
  await controller.updateTrackingConfig(myCustomConfig);
};

await controller.startTracking(myCustomConfig, enableSmartBattery: true);

await controller.stopTracking();
SmartBatteryManager.instance.customGeneralConfigOverride = null;

{
  "time": 1777876800000,
  "lat": 10.762219,
  "lng": 106.656956,
  "packages": ["#10001", "#10002"],
  "metadata": {}
}

await controller.setPackages(['#10001', '#10002']);

// Danh sách rỗng = xoá trường — payload bỏ hẳn field, không gửi []
await controller.setPackages([]);

// Tắt auto upload để tự kiểm soát
await controller.setAutoUpload(false);

final pending   = await controller.getCachedLocationsCount(); // số điểm chờ gửi
final sizeBytes = await controller.getDatabaseSizeBytes();    // kích thước cache

// Cấu hình giới hạn cache
await controller.configureCacheLimits(
  maxRecords: 5000,
  maxDbSizeBytes: 50 * 1024 * 1024, // 50 MB
  batchSize: 50,
);

// Gửi cache ngay / xoá toàn bộ cache (không hoàn tác)
await controller.uploadCachedLocationsManually();
await controller.clearCachedLocations();

await controller.startTracking(
  TrackingPresets.general().copyWith(
    userId: 'user-123',
    allowMockLocation: false, // bật kiểm tra fake GPS ở native
  ),
);
await controller.setFakeGpsPolicy(FakeGpsPolicy.warn);

await controller.setFakeGpsPolicy(FakeGpsPolicy.warn);

controller.onFakeGpsDetected.listen((FakeGpsEvent ev) {
  print('Fake GPS: lat=${ev.lat}, lng=${ev.lng}, reason=${ev.reason}');
});

await controller.setFakeGpsNotificationConfig(
  title: 'Phát hiện GPS giả',
  message: 'Vui lòng tắt ứng dụng giả lập vị trí để dữ liệu được ghi nhận chính xác.',
);

await controller.startTracking(
  TrackingPresets.general().copyWith(
    userId: 'user-123',
    enableSpeedFallback: false, // mặc định true
  ),
);

// Gọi sau initializeTracking
await controller.configureAlertAPI('your-alert-api-key', 'your-alert-api-id');

await controller.turnOnAlert();
await controller.turnOffAlert();

await controller.setTrackingInterruptedNotificationEnabled(true);
await controller.setTrackingInterruptedNotificationConfig(
  title: 'Theo dõi bị gián đoạn',
  message: 'Vui lòng mở ứng dụng và bật lại theo dõi hành trình.',
);

controller.onTrackingInterrupted.listen((TrackingInterruptedEvent ev) {
  print('${ev.reason} — recovered: ${ev.recovered}');
});

controller.onLocationUpdate            // Stream<LocationData>
controller.onTrackingStatusChanged     // Stream<TrackingStatus>
controller.onFakeGpsDetected           // Stream<FakeGpsEvent>
controller.onTrackingInterrupted       // Stream<TrackingInterruptedEvent>
controller.onSmartBatteryProfileChanged // Stream<SmartBatteryProfile>

controller.onLocationUpdate.listen((LocationData loc) {
  print('${loc.latitude}, ${loc.longitude} @ ${loc.speed} m/s');
});

controller.onTrackingStatusChanged.listen((TrackingStatus s) {
  print('Tracking: ${s.isTracking}');
});

controller.onFakeGpsDetected.listen((FakeGpsEvent ev) {
  print('Fake GPS tại ${ev.lat}, ${ev.lng}');
});

final List<GpsLocation> history = await controller.getTrackingHistory(
  userId: 'user-123',
  fromTimestamp: DateTime(2026, 5, 1).millisecondsSinceEpoch,  // tuỳ chọn
  toTimestamp: DateTime(2026, 5, 12).millisecondsSinceEpoch,   // tuỳ chọn
  pageNumber: 1,
  pageSize: 50,
  sortDescending: true,
);

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

// Khoảng cách Haversine (mét)
LocationUtils.calculateDistance(lat1, lng1, lat2, lng2);
LocationUtils.distanceBetween(location1, location2);

// Định dạng toạ độ
LocationUtils.formatCoordinates(21.0285, 105.8542);
// → "21.028500° N, 105.854200° E"

// Đổi đơn vị tốc độ
LocationUtils.metersPerSecondToKmh(25.0);  // → 90.0
LocationUtils.kmhToMetersPerSecond(90.0);  // → 25.0

// Kiểm tra geofence
LocationUtils.isWithinRadius(location, targetLat, targetLng, radiusMetres);

┌──────────────────────────────────────────────────┐
│                   Flutter App                    │
│          VietmapTrackingController               │
│          SmartBatteryManager                     │
├──────────────────────────────────────────────────┤
│           Platform Interface (Dart)              │
│    MethodChannel: vietmap_tracking_plugin        │
│    EventChannel:  /location_updates              │
│    EventChannel:  /tracking_status               │
│    EventChannel:  /fake_gps                      │
├──────────────────────┬───────────────────────────┤
│   iOS Native Bridge  │  Android Native Bridge    │
│   Swift              │  Kotlin                   │
├──────────────────────┼───────────────────────────┤
│  VietmapTrackingSDK  │  vietmap-tracking-sdk     │
│  1.5.1 (CocoaPods)   │  1.5.2 (JitPack)          │
└──────────────────────┴───────────────────────────┘

post_install do |installer|
  Dir.glob(File.join(installer.sandbox.root, '**', '._*')).each { |f| FileUtils.rm_f(f) }
end