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.

🌍 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)
  • actions: List<String> (Default: [])

🔔 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+).

📍 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).

📡 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)

🏢 Enterprise Configurations

AuditConfig (config.audit)

  • enabled: bool (Default: false) Creates a cryptographic, tamper-proof blockchain of location hashes.
  • hashAlgorithm: HashAlgorithm (Default: HashAlgorithm.sha256)
  • includeExtrasInHash: bool (Default: false)

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)
Enterprise FeaturesDiagnostic Tools