# Before
dependencies:
  flutter_background_geolocation: ^5.x.x

dependencies:
  tracelet: ^3.6.14

// Before
import 'package:flutter_background_geolocation/flutter_background_geolocation.dart' as bg;
 
// After — short & sweet ✅
import 'package:tracelet/tracelet.dart' as tl;

// Before
bg.BackgroundGeolocation.ready(bg.Config(...));
 
// After
tl.Tracelet.ready(tl.Config.balanced().copyWith(...));

// Before — flat config
bg.Config(
  desiredAccuracy: bg.Config.DESIRED_ACCURACY_HIGH,
  distanceFilter: 10.0,
  stopOnTerminate: false,
  startOnBoot: true,
  stopTimeout: 5,
  url: 'https://api.example.com/locations',
  batchSync: true,
  autoSync: true,
  headers: {'Authorization': 'Bearer $token'},
  heartbeatInterval: 60,
  notification: bg.Notification(title: 'Tracking', text: 'Active'),
  debug: true,
  logLevel: bg.Config.LOG_LEVEL_VERBOSE,
);
 
// After — organized by section 🏠
tl.Config(
  geo: tl.GeoConfig(
    desiredAccuracy: tl.DesiredAccuracy.high,   // typed enums!
    distanceFilter: 10.0,
  ),
  app: tl.AppConfig(
    stopOnTerminate: false,
    startOnBoot: true,
    heartbeatInterval: 60,
  ),
  android: tl.AndroidConfig(
    foregroundService: tl.ForegroundServiceConfig(
      notificationTitle: 'Tracking',
      notificationText: 'Active',
    ),
  ),
  motion: tl.MotionConfig(
    stopTimeout: 5,
  ),
  http: tl.HttpConfig(
    url: 'https://api.example.com/locations',
    batchSync: true,
    autoSync: true,
    headers: {'Authorization': 'Bearer $token'},
  ),
  logger: tl.LoggerConfig(
    debug: true,
    logLevel: tl.LogLevel.verbose,   // readable enum instead of int constants
  ),
);

Before                              → Tracelet
─────────────────────────────────────────────────────────────
desiredAccuracy (int: -2…100)       → geo.desiredAccuracy (DesiredAccuracy enum)
                                      .high / .medium / .low / .veryLow / .passive
distanceFilter                      → geo.distanceFilter (default 10m)
stationaryRadius                    → geo.stationaryRadius (default 25m)
locationTimeout                     → geo.locationTimeout (default 60s)
disableElasticity                   → geo.disableElasticity
elasticityMultiplier                → geo.elasticityMultiplier (default 1.0)
stopAfterElapsedMinutes             → geo.stopAfterElapsedMinutes (-1 = disabled)
enableTimestampMeta                 → geo.enableTimestampMeta
maxMonitoredGeofences               → geo.maxMonitoredGeofences (-1 = platform default)

Before                              → Tracelet
─────────────────────────────────────────────────────────────
locationUpdateInterval              → android.locationUpdateInterval (1000ms)
fastestLocationUpdateInterval       → android.fastestLocationUpdateInterval (500ms)
deferTime                           → android.deferTime
allowIdenticalLocations             → android.allowIdenticalLocations
geofenceModeHighAccuracy            → geofence.geofenceModeHighAccuracy (cross-platform; android.* is deprecated)
scheduleUseAlarmManager             → android.scheduleUseAlarmManager

Before                              → Tracelet
─────────────────────────────────────────────────────────────
activityType                        → ios.activityType (LocationActivityType enum)
useSignificantChangesOnly           → ios.useSignificantChangesOnly
showsBackgroundLocationIndicator    → ios.showsBackgroundLocationIndicator
pausesLocationUpdatesAutomatically  → ios.pausesLocationUpdatesAutomatically
locationAuthorizationRequest        → ios.locationAuthorizationRequest
disableLocationAuthorizationAlert   → ios.disableLocationAuthorizationAlert
preventSuspend                      → ios.preventSuspend

Before                                → Tracelet
─────────────────────────────────────────────────────────────
stopTimeout                            → motion.stopTimeout (default 5 min)
motionTriggerDelay                     → motion.motionTriggerDelay
disableMotionActivityUpdates           → motion.disableMotionActivityUpdates
                                         (set true for accelerometer-only, no permission!)
isMoving                               → motion.isMoving (initial state)
activityRecognitionInterval            → motion.activityRecognitionInterval (10000ms)
minimumActivityRecognitionConfidence   → motion.minimumActivityRecognitionConfidence (75)
disableStopDetection                   → motion.disableStopDetection
stopDetectionDelay                     → motion.stopDetectionDelay
stopOnStationary                       → motion.stopOnStationary
triggerActivities                      → motion.activityTypes (Set<ActivityType>)

Before                   → Tracelet
─────────────────────────────────────────────────────────────
stopOnTerminate          → app.stopOnTerminate (default true)
startOnBoot              → app.startOnBoot (default false)
heartbeatInterval        → app.heartbeatInterval (default 60s)
schedule                 → app.schedule (cron-like expressions)

Before (Notification)     → Tracelet (AndroidConfig.foregroundService)
─────────────────────────────────────────────────────────────
title                     → android.foregroundService.notificationTitle
text                      → android.foregroundService.notificationText
color                     → android.foregroundService.notificationColor
smallIcon                 → android.foregroundService.notificationSmallIcon
largeIcon                 → android.foregroundService.notificationLargeIcon
priority                  → android.foregroundService.notificationPriority
channelName               → android.foregroundService.channelName
channelId                 → android.foregroundService.channelId
sticky                    → android.foregroundService.notificationOngoing
actions                   → android.foregroundService.actions
enabled                   → android.foregroundService.enabled

Before                    → Tracelet
─────────────────────────────────────────────────────────────
url                       → http.url (null = sync disabled)
method                    → http.method (HttpMethod.post / .put)
headers                   → http.headers
httpRootProperty          → http.httpRootProperty (default 'location')
batchSync                 → http.batchSync
maxBatchSize              → http.maxBatchSize
autoSync                  → http.autoSync
autoSyncThreshold         → http.autoSyncThreshold
httpTimeout               → http.httpTimeout (default 60000ms)
params                    → http.params
extras                    → http.extras
locationsOrderDirection   → http.locationsOrderDirection (LocationOrder enum)

Before                        → Tracelet
─────────────────────────────────────────────────────────────
geofenceProximityRadius       → geofence.geofenceProximityRadius (default 1000m)
geofenceInitialTriggerEntry   → geofence.geofenceInitialTriggerEntry (default true)

Before                        → Tracelet
─────────────────────────────────────────────────────────────
persistMode                   → persistence.persistMode (.all / .location / .geofence / .none)
maxDaysToPersist              → persistence.maxDaysToPersist (-1 = forever)
maxRecordsToPersist           → persistence.maxRecordsToPersist (-1 = unlimited)
locationTemplate              → persistence.locationTemplate (Mustache-style)
geofenceTemplate              → persistence.geofenceTemplate (Mustache-style)
disableProviderChangeRecord   → persistence.disableProviderChangeRecord
extras                        → persistence.extras

Before                 → Tracelet
─────────────────────────────────────────────────────────────
logLevel (int const)   → logger.logLevel (.verbose / .debug / .info / .warning / .error)
logMaxDays             → logger.logMaxDays (default 3)
debug                  → logger.debug (alert sounds — fun at demos, terrifying at 3 AM)

Before (int constants)                    → Tracelet (typed enum)
─────────────────────────────────────────────────────────────
Config.DESIRED_ACCURACY_NAVIGATION        → DesiredAccuracy.high
Config.DESIRED_ACCURACY_HIGH              → DesiredAccuracy.high
Config.DESIRED_ACCURACY_MEDIUM            → DesiredAccuracy.medium
Config.DESIRED_ACCURACY_LOW               → DesiredAccuracy.low
Config.DESIRED_ACCURACY_VERY_LOW          → DesiredAccuracy.veryLow
Config.DESIRED_ACCURACY_LOWEST            → DesiredAccuracy.passive

Before                     → Tracelet                     Callback Type
─────────────────────────────────────────────────────────────────────────
onLocation(cb)             → onLocation(cb)               Location
onMotionChange(cb)         → onMotionChange(cb)           Location
onActivityChange(cb)       → onActivityChange(cb)         ActivityChangeEvent
onProviderChange(cb)       → onProviderChange(cb)         ProviderChangeEvent
onGeofence(cb)             → onGeofence(cb)               GeofenceEvent
onGeofencesChange(cb)      → onGeofencesChange(cb)        GeofencesChangeEvent
onHeartbeat(cb)            → onHeartbeat(cb)              HeartbeatEvent
onHttp(cb)                 → onHttp(cb)                   HttpEvent
onSchedule(cb)             → onSchedule(cb)               State
onPowerSaveChange(cb)      → onPowerSaveChange(cb)        bool
onConnectivityChange(cb)   → onConnectivityChange(cb)     ConnectivityChangeEvent
onEnabledChange(cb)        → onEnabledChange(cb)          bool
onNotificationAction(cb)   → onNotificationAction(cb)     String
onAuthorization(cb)        → onAuthorization(cb)          AuthorizationEvent
N/A                        → 🆕 onTrip(cb)                TripEvent (auto-detected trips!)
N/A                        → 🆕 onRemoteConfig(cb)        Config (remote config applied)
removeListeners()          → removeListeners()            Cancels all subscriptions

// Before — so many characters...
bg.BackgroundGeolocation.onLocation((bg.Location location) {
  print('[location] $location');
});
 
// After — ahh, much better
tl.Tracelet.onLocation((tl.Location location) {
  print('[location] $location');
});

Before                                → Tracelet
─────────────────────────────────────────────────────────────
bg.BackgroundGeolocation.ready(cfg)   → tl.Tracelet.ready(cfg)
bg.BackgroundGeolocation.start()      → tl.Tracelet.start()
bg.BackgroundGeolocation.stop()       → tl.Tracelet.stop()
bg.BackgroundGeolocation.startGeofences()  → tl.Tracelet.startGeofences()
N/A                                   → 🆕 tl.Tracelet.startPeriodic()
bg.BackgroundGeolocation.getState()   → tl.Tracelet.getState()
bg.BackgroundGeolocation.setConfig()  → tl.Tracelet.setConfig()
bg.BackgroundGeolocation.reset()      → tl.Tracelet.reset()
N/A                                   → 🆕 tl.Tracelet.getHealth()

Before                     → Tracelet
─────────────────────────────────────────────────────────────
getCurrentPosition(...)    → getCurrentPosition(...)
                             same params: desiredAccuracy, timeout,
                             maximumAge, persist, samples, extras
N/A                        → 🆕 getLastKnownLocation() — zero battery cost!
watchPosition(cb, ...)     → watchPosition(cb, ...) — returns watchId
stopWatchPosition(id)      → stopWatchPosition(id)
changePace(isMoving)       → changePace(isMoving)
N/A                        → 🆕 updateLocationProviderOptions() — live
                             accuracy/filter override, no pipeline restart
getOdometer()              → getOdometer()
setOdometer(value)         → setOdometer(value)
resetOdometer()            → setOdometer(0) — one less method to remember

Before              → Tracelet
─────────────────────────────────────────────────────────────
addGeofence(g)      → addGeofence(g)
addGeofences(list)  → addGeofences(list)
removeGeofence(id)  → removeGeofence(id)
removeGeofences()   → removeGeofences()
getGeofences()      → getGeofences()
N/A                 → 🆕 getGeofence(id) — get one without fetching all
N/A                 → 🆕 geofenceExists(id) — quick existence check

Before                   → Tracelet
─────────────────────────────────────────────────────────────
getLocations()           → getLocations([SQLQuery?]) — optional filtering!
getCount()               → getCount()
destroyLocations()       → destroyLocations()
destroyLocation(uuid)    → destroyLocation(uuid)
insertLocation(params)   → insertLocation(params) — returns UUID
sync()                   → sync()

Before               → Tracelet
─────────────────────────────────────────────────────────────
requestPermission()  → requestLocationAuthorization()
N/A                  → 🆕 getLocationAuthorization()
N/A                  → 🆕 hasBackgroundPermission (getter)
N/A                  → 🆕 getNotificationAuthorization()
N/A                  → 🆕 requestNotificationAuthorization()
N/A                  → 🆕 getMotionAuthorization()
N/A                  → 🆕 requestMotionAuthorization()
N/A                  → 🆕 requestTemporaryFullAccuracyAuthorization(purpose) — iOS 14+
N/A                  → 🆕 canScheduleExactAlarms() — Android 12+
N/A                  → 🆕 openExactAlarmSettings()
N/A                  → 🆕 openAppSettings()
N/A                  → 🆕 openLocationSettings()
N/A                  → 🆕 openBatterySettings()
N/A                  → 🆕 isIgnoringBatteryOptimizations()

Before              → Tracelet
─────────────────────────────────────────────────────────────
getLog()            → getLog([SQLQuery?]) — optional filtering
destroyLog()        → destroyLog()
emailLog(email)     → emailLog(email)
log(level, msg)     → log(level, msg)

Before                     → Tracelet
─────────────────────────────────────────────────────────────
startSchedule()            → startSchedule()
stopSchedule()             → stopSchedule()
startBackgroundTask()      → startBackgroundTask()
stopBackgroundTask(id)     → stopBackgroundTask(id)
registerHeadlessTask(cb)   → registerHeadlessTask(cb)

Before               → Tracelet
─────────────────────────────────────────────────────────────
getProviderState()   → getProviderState()
getSensors()         → getSensors()
getDeviceInfo()      → getDeviceInfo()
playSound(name)      → playSound(name)
isPowerSaveMode      → isPowerSaveMode
N/A                  → 🆕 getSettingsHealth() — detects OEM battery killers
N/A                  → 🆕 openOemSettings(label) — opens OEM settings page
N/A                  → 🆕 requestSettings(action)
N/A                  → 🆕 showSettings(action)

dependencies:
  tracelet: ^3.6.14

// Before
bg.BackgroundGeolocation.onLocation((bg.Location location) {
  print('[location] $location');
});
 
// After
tl.Tracelet.onLocation((tl.Location location) {
  print('[location] $location');
});

// Before
bg.BackgroundGeolocation.ready(config).then((bg.State state) {
  if (!state.enabled) bg.BackgroundGeolocation.start();
});
 
// After
tl.Tracelet.ready(config).then((tl.State state) {
  if (!state.enabled) tl.Tracelet.start();
});

// Before
@pragma('vm:entry-point')
void backgroundGeolocationHeadlessTask(bg.HeadlessEvent event) async {
  switch (event.name) {
    case bg.Event.LOCATION:
      bg.Location location = event.event;
      break;
  }
}
 
void main() {
  bg.BackgroundGeolocation.registerHeadlessTask(backgroundGeolocationHeadlessTask);
  runApp(MyApp());
}
 
// After — shorter function name is a bonus 😎
@pragma('vm:entry-point')
void headlessTask(tl.HeadlessEvent event) async {
  switch (event.name) {
    case 'location':
      tl.Location location = event.event as tl.Location;
      break;
  }
}
 
void main() {
  tl.Tracelet.registerHeadlessTask(headlessTask);
  runApp(MyApp());
}

{
  "location": {
    "coords": { "latitude": 37.42, "longitude": -122.08, "accuracy": 12.3 },
    "timestamp": "2026-03-06T10:30:00.000Z",
    "is_moving": true,
    "uuid": "abc-123",
    "odometer": 1234.5,
    "activity": { "type": "walking", "confidence": 85 },
    "battery": { "level": 0.72, "is_charging": false },
    "extras": { "custom_key": "custom_value" }
  }
}

{
  "location": {
    "coords": { "latitude": 37.42, "longitude": -122.08, "accuracy": 12.3 },
    "timestamp": "2026-03-06T10:30:00.000Z",
    "isMoving": true,
    "uuid": "abc-123",
    "odometer": 1234.5,
    "isMock": false,
    "activity": { "type": "walking", "confidence": 85 },
    "battery": { "level": 0.72, "isCharging": false },
    "extras": { "custom_key": "custom_value" }
  }
}