Skip to Content
API Reference

Exhaustive API Reference

This page contains the absolute source of truth for Tracelet’s Configuration API. Every single parameter that can be passed to Tracelet.ready(Config) is listed here.

For real-world architectural scenarios explaining why you would use these parameters, click the “See Story 📖” links next to them.

Updating configuration at runtime — ready() vs setConfig()

There are two ways config reaches the plugin, and they mean different things.

Tracelet.ready(config) establishes the complete baseline. Every field is sent, resolved to its effective value. Call it once at startup — or again when you want to replace the whole configuration. Tracelet.reset(config) behaves the same way.

Tracelet.setConfig(config) is a partial update. Only the fields you actually set are transmitted; everything else keeps whatever the platform has persisted. This is what you want mid-session, when one thing needs to change:

// Changes one flag. The notification title from ready(), the HTTP URL,
// distanceFilter, stopOnTerminate — all keep their configured values.
await Tracelet.setConfig(const Config(
  android: AndroidConfig(
    foregroundService: ForegroundServiceConfig(
      showNotificationOnPauseOnly: true,
    ),
  ),
));
 
// Changes nothing at all.
await Tracelet.setConfig(const Config());

⚠️ Changed in 3.8.0. setConfig() previously replaced the entire configuration, so any field you did not mention silently reverted to its default — setConfig(const Config()) reset everything, including stopOnTerminate, the HTTP settings, the foreground-service notification and the iOS keep-alive flags. If you relied on that to reset state, call Tracelet.reset() or ready() instead (#320 , #321 ).

Setting a value back to its default still works. “Unset” means you did not provide the field, never the value equals the default — so ForegroundServiceConfig(showNotificationOnPauseOnly: false) does turn the flag off. Only a field you omit entirely is left alone.

Tracelet.activeConfig applies the same merge locally, so it always reflects what the platform actually holds rather than the defaults your last call left unset.

For changes that should not persist or restart the pipeline, use the targeted runtime APIs instead: updateLocationProviderOptions() for accuracy/distance, and updateNotification() to repost the live notification.

🌍 GeoConfig (config.geo)

Controls physical location, accuracy, and sampling logic. See Geo Story 📖

  • desiredAccuracy: DesiredAccuracy (Default: DesiredAccuracy.high) The target hardware accuracy. Use high for GPS, low for Cellular/Wi-Fi to save battery.
  • distanceFilter: double (Default: 10.0) Minimum horizontal meters to move before a point is recorded.

ℹ️ Changing desiredAccuracy or distanceFilter via setConfig() persists the values and restarts the tracking pipeline. For a temporary override while tracking (e.g. easing off GPS during a confirmed stationary period), use updateLocationProviderOptions() — it updates the running provider live, without a restart, and never touches the persisted config.

  • stationaryRadius: double (Default: 25.0) Radius around the user to be considered stationary (stops GPS drain).
  • locationTimeout: int (Default: 60) Maximum seconds to wait for a GPS lock before giving up.
  • disableElasticity: bool (Default: false) If true, disables dynamic speed-based distance scaling.
  • elasticityMultiplier: double (Default: 1.0) Multiplier for the dynamic distance filter when traveling at high speeds.
  • stopAfterElapsedMinutes: int (Default: -1) Auto-stops the engine after X minutes. -1 means run forever.
  • maxMonitoredGeofences: int (Default: -1) Max geofences to monitor concurrently.
  • enableTimestampMeta: bool (Default: false) Attaches exact nanosecond hardware timestamps.
  • enableAdaptiveMode: bool (Default: false) Auto-toggles settings based on battery level.
  • periodicLocationInterval: int (Default: 900) Seconds between periodic updates when stationary.
  • periodicDesiredAccuracy: DesiredAccuracy (Default: DesiredAccuracy.medium) Accuracy used during periodic background wakes.
  • enableSparseUpdates: bool (Default: false) Uses low-power cell-tower triangulation exclusively.
  • sparseDistanceThreshold: double (Default: 50.0) Meters to move in sparse mode.
  • sparseMaxIdleSeconds: int (Default: 300) Max time without a sparse update.
  • enableDeadReckoning: bool (Default: false) Uses Accelerometer/Gyroscope to guess location when GPS is lost (e.g. tunnels).
  • deadReckoningActivationDelay: int (Default: 0) Seconds of GPS loss before dead reckoning kicks in.
  • deadReckoningMaxDuration: int (Default: 0) Max seconds to allow dead reckoning before stopping.
  • resolveAddress: bool (Default: false) Automatically reverse-geocodes coordinates into a street address string.

🧹 LocationFilter (config.geo.filter)

Cleans up bad GPS data before it hits SQLite/Sync. See Filter Story 📖

  • trackingAccuracyThreshold: int (Default: 100) Points with accuracy worse than X meters are dropped.
  • maxImpliedSpeed: int (Default: 80) Rejects location jumps that imply speed > X m/s (80 m/s = 288 km/h).
  • odometerAccuracyThreshold: int (Default: 50) Points with accuracy worse than X meters do not add to total trip distance.
  • policy: LocationFilterPolicy (Default: LocationFilterPolicy.adjust) How to handle bad points (drop or adjust).
  • rejectMockLocations: bool (Default: false) Immediately drops locations generated by GPS spoofing apps.
  • mockDetectionLevel: int (Default: 1) Aggressiveness of fake GPS detection heuristics.
  • useKalmanFilter: bool (Default: false) Applies complex Kalman smoothing to the raw GPS trajectory.

📱 AppConfig (config.app)

Controls overall app lifecycle behavior.

  • stopOnTerminate: bool (Default: true) If true, tracking stops when the user swipes the app away. If false, it reboots in the background. See Terminate Story 📖
  • startOnBoot: bool (Default: false) If true, tracking starts automatically when the phone is restarted.
  • heartbeatInterval: int (Default: 60) Fires a “heartbeat” event every X seconds to prove the engine is alive.
  • schedule: List<String> (Default: []) CRON-like strings to automatically start/stop tracking at specific times.
  • remoteConfigUrl: String? (Default: null) HTTPS URL the SDK fetches a JSON config map from on ready(), applying it over the local config and refreshing in the background. Cached on-device for instant offline apply. See Remote Configuration.
  • remoteConfigHeaders: Map<String, String>? (Default: null) HTTP Headers for the remote config fetch.
  • remoteConfigTimeout: int (Default: 60000) Timeout for fetching remote config in ms.
  • remoteConfigRefreshInterval: int (Default: 1440) Minutes before fetching the remote config again.

🤖 AndroidConfig (config.android)

Android specific OS constraints. See Android Story 📖

  • locationUpdateInterval: int (Default: 1000) Ms between GPS pings.
  • batteryBudgetPerHour: double (Default: 0.0) Target max battery drain % per hour. 0.0 disables throttling.
  • releaseWakelockWhenStationary: bool (Default: false) When using MotionDetectionMode.smart, releases the tracking wakelock when the device is fully stationary to maximize deep sleep battery savings.
  • fastestLocationUpdateInterval: int (Default: 500) Fastest ms between GPS pings if another app requests them.
  • deferTime: int (Default: 0) Allows Android to batch location updates for X ms.
  • allowIdenticalLocations: bool (Default: false) If false, duplicate exact coordinates are dropped.
  • geofenceModeHighAccuracy: bool (Default: false) — ⚠️ Deprecated Forces GPS chip for geofences (heavy battery drain). Use the cross-platform GeofenceConfig.geofenceModeHighAccuracy (see the GeofenceConfig section below) instead — it now controls both iOS and Android. This Android-only flag is still honored for backward compatibility (if either is true, high-accuracy mode is enabled) but will be removed in a future major version.
  • periodicUseForegroundService: bool (Default: false) Forces a persistent notification during periodic wakes.
  • periodicUseExactAlarms: bool (Default: false) Uses AlarmManager for exact wakeups (Requires SCHEDULE_EXACT_ALARM manifest permission). See Exact Alarms 📖
  • scheduleUseAlarmManager: bool (Default: false) Uses exact alarms for CRON scheduling.

ForegroundServiceConfig (config.android.foregroundService)

  • enabled: bool (Default: true) Requires POST_NOTIFICATIONS permission on Android 13+. See Notification 📖
  • channelId: String (Default: 'tracelet_channel')
  • channelName: String (Default: 'Tracelet')
  • notificationTitle: String (Default: 'Tracelet')
  • notificationText: String (Default: 'Tracking location in background')
  • notificationColor: String? (Default: null) Hex color for the small icon background.
  • notificationSmallIcon: String? (Default: null) Name of the white-only PNG in your res/drawable folder.
  • notificationLargeIcon: String? (Default: null)
  • notificationPriority: NotificationPriority (Default: NotificationPriority.defaultPriority)
  • notificationOngoing: bool (Default: true)
  • showNotificationOnPauseOnly: bool (Default: false) Hides the notification while the app is on screen. Ignored while app.stopOnTerminate is false — hiding it demotes the foreground service, and a swipe from recents in that window kills the process (#378 ). The override is logged once per start(). See Hiding the notification 📖
  • actions: List<String> (Default: [])
  • notificationStartedAt: int? (Default: null) Epoch milliseconds (wall clock) the elapsed timer counts up from. Only rendered when notificationShowTimer is true. A value in the future is clamped to the current time each time the notification is posted, so a device clock correction self-heals. See Elapsed timer 📖
  • notificationShowTimer: bool (Default: false) Shows a self-ticking count-up clock from notificationStartedAt. Android advances it with no reposts from your app. No timer is shown if notificationStartedAt is absent.
  • notificationOnlyAlertOnce: bool (Default: false) Alerts the device only on the first post of the notification, so later content updates are silent. Useful for any notification whose text changes while tracking runs, not just timers. See Updating the text quietly 📖

🔔 To apply a notification change while tracking is already running, call Tracelet.updateNotification() after setConfig(). It reposts the live notification without restarting the pipeline (v3.6.8+). On iOS it refreshes the running Live Activity instead; on web it is a no-op.

🍎 IosConfig (config.ios)

iOS specific OS constraints. See iOS Story 📖

  • activityType: LocationActivityType (Default: LocationActivityType.other) Tells iOS what you are doing (e.g. fitness, navigation) so it knows when to pause tracking.
  • useSignificantChangesOnly: bool (Default: false) Relies entirely on cell-tower handoffs. Near-zero battery drain.
  • showsBackgroundLocationIndicator: bool (Default: false) Shows the Blue Pill indicator. Requires location Xcode capability. See Blue Pill 📖
  • pausesLocationUpdatesAutomatically: bool (Default: false) Allows iOS to kill the GPS chip if the user hasn’t moved in a while.
  • locationAuthorizationRequest: LocationAuthorizationRequest (Default: always) Which permission to request.
  • disableLocationAuthorizationAlert: bool (Default: false) Prevents the OS from prompting “Always Allow” if only “When In Use” is requested.
  • preventSuspend: bool (Default: false) Plays silent audio to keep the app alive 24/7. Requires audio Xcode capability. See Prevent Suspend 📖
  • useBackgroundActivitySession: bool (Default: false) Uses CLBackgroundActivitySession (iOS 17+) to maintain a background location session with only “When In Use” authorization. This replaces the traditional blue pill with a Dynamic Island indicator. Note: Apple App Store guidelines require apps using this to provide a clear explanation to users why background location is necessary.
  • liveActivityConfig: LiveActivityConfig? (Default: null) Opt into a Lock Screen / Dynamic Island Live Activity while tracking (iOS 16.1+, requires a Widget Extension). Takes a title and body. See Live Activities 📖. Refresh it at runtime with Tracelet.updateNotification() (v3.6.8+).

LiveActivityConfig (config.ios.liveActivityConfig)

  • title: String (Required) The static heading. ActivityKit attributes are immutable while an activity is running, so a change applies the next time one starts.

  • body: String (Required) The dynamic status line, updated in place by updateNotification().

  • startedAt: int? (Default: null) Epoch milliseconds (wall clock) the elapsed timer counts up from. Only rendered when showTimer is true. See Elapsed timer 📖

  • showTimer: bool (Default: false) Renders a self-ticking count-up clock from startedAt using Text(timerInterval:). iOS advances it with no updates from your app. No timer is shown if startedAt is absent.

    A custom Widget Extension only renders the timer if its own copy of TraceletActivityAttributes.ContentState declares startedAt and showTimer. Extensions written before these fields existed keep working — the extra values are simply ignored — but show no clock until you update the struct. See the updated snippet 📖

📍 GeofenceConfig (config.geofence)

Cross-platform geofencing behavior (iOS + Android).

  • geofenceModeHighAccuracy: bool (Default: false) Controls how geofence transitions are detected:

    • false (default) — uses the OS region-monitoring service. Low power, no iOS blue indicator, but the OS enforces a practical minimum radius (~100 m) and small or EXIT transitions can be unreliable.
    • true — evaluates transitions in-app from continuous GPS. Makes tight radii (e.g. 5–50 m) and EXIT events reliable, at the cost of higher battery use and — on iOS — the system “location in use” (blue) status-bar indicator (continuous GPS forces it). See Blue Pill 📖

    This supersedes the deprecated AndroidConfig.geofenceModeHighAccuracy; if either is true, high-accuracy mode is enabled.

  • geofenceInitialTrigger: bool (Default: true) Evaluate geofence state on registration.

  • geofenceInitialTriggerEntry: bool (Default: true) Fire an ENTER immediately if the device is already inside a geofence when it is registered.

  • geofenceProximityRadius: int (Default: 1000) Radius (meters) for proximity-based loading — only geofences within this distance are actively registered with the OS (lets you manage far more than the iOS 20-region limit).

  • geofenceExitAccuracyMax: int (Default: -1) Tunes the accuracy-aware EXIT gating in high-accuracy mode (no effect in standard mode). A circular geofence only EXITs once the whole GPS error circle clears the fence (distance - accuracy > radius + buffer), which prevents a single high-drift fix from firing a false EXIT while a device sits still inside a small fence — at the cost of delaying a genuine exit by roughly the GPS uncertainty.

    • -1 (default) — full gating; most resistant to false exits.
    • 0 — gating disabled; fastest exit, but drift-prone (pre-fix behavior).
    • N > 0 — clamp accuracy to N meters; absorbs drift up to N while bounding the worst-case exit delay to ~N meters. See GPS drift & false EXIT 📖

📡 HttpConfig (config.http)

Controls the network synchronization engine. See Sync Story 📖

  • url: String? (Default: null) Your backend endpoint.
  • method: HttpMethod (Default: HttpMethod.post)
  • headers: Map<String, String>? (Default: null) Custom auth headers. For dynamic JWT rotation, See Callbacks 📖
  • params: Map<String, Object?>? (Default: null)
  • extras: Map<String, Object?>? (Default: null) Static JSON data injected into every location payload.
  • httpRootProperty: String? (Default: 'location') The JSON root node.
  • autoSync: bool (Default: true) Uploads automatically. If false, you must call Tracelet.sync().
  • batchSync: bool (Default: false) Uploads arrays of locations instead of 1-by-1.
  • maxBatchSize: int (Default: 250)
  • autoSyncThreshold: int (Default: 0) Number of SQLite records required before triggering a sync.
  • autoSyncDelay: int (Default: 10000) Ms to wait before syncing after a location arrives.
  • syncInterval: int (Default: 0) Seconds between repeating, time-based flushes of the offline queue. When > 0, the SDK periodically uploads any pending locations on this cadence — independent of the autoSyncDelay debounce that fires on new inserts. Useful for time-driven flushing regardless of how many records have accumulated. 0 disables the interval timer.
  • httpTimeout: int (Default: 60000)
  • locationsOrderDirection: LocationOrderDirection (Default: LocationOrderDirection.ascending)
  • disableAutoSyncOnCellular: bool (Default: false) Only syncs when on Wi-Fi to save user data plans.
  • maxRetries: int (Default: 3)
  • retryBackoffBase: int (Default: 1000)
  • retryBackoffCap: int (Default: 60000)
  • enableDeltaCompression: bool (Default: false) Only sends the delta coordinates, reducing JSON payload size by 80%.
  • deltaCoordinatePrecision: int (Default: 5)
  • sslPinningFingerprints: List<String>? (Default: null)
  • sslPinningCertificates: List<String>? (Default: null)
  • syncTelematics: bool (Default: false) Uploads stored driving/impact events alongside your locations. Off by default, so an existing payload never changes underneath you. See Telematics Sync 📖
  • telematicsUrl: String? (Default: null) Sends telematics to their own endpoint as {"telematics": [...]} instead of attaching them to the location payload. Requires syncTelematics. Pass an empty string (not null) to go back to the attached path — config is merged, not replaced.

🏢 Enterprise Configurations

AuditConfig (config.audit)

  • enabled: bool (Default: false) Creates a cryptographic, tamper-proof blockchain of location hashes.
  • hashAlgorithm: HashAlgorithm (Default: HashAlgorithm.sha256) The chain currently always uses SHA-256; selecting another algorithm is not yet applied.
  • includeExtrasInHash: bool (Default: false) — ⚠️ Deprecated: not implemented. The chain always hashes the core location fields only, so this flag changes nothing. Wiring it up would invalidate every previously computed chain, so it needs a versioned chain migration rather than a silent behaviour change.

SecurityConfig (config.security)

  • encryptionKey: String? (Default: null) Encrypts the SQLite database using SQLCipher. See Encryption 📖

PrivacyZoneConfig (config.privacy)

  • zones: List<PolygonZone> (Default: []) Geographic polygons where tracking is automatically disabled. See Privacy Zones 📖

AttestationConfig (config.attestation)

  • enabled: bool (Default: false) Uses Play Integrity (Android) and App Attest (iOS) to cryptographically prove the device is real and not an emulator.
  • refreshInterval: int (Default: 86400)
  • verificationUrl: String? (Default: null) — ⚠️ Deprecated: not implemented. Nothing sends the attestation token anywhere for server-side verification. The token is already included in sync payloads — verify it on your own backend instead.
Enterprise FeaturesDiagnostic Tools