TrackingConfig

data class TrackingConfig(var enableReactivation: Boolean = false, var reactivationDelayMs: Long = 1000, var preserveTrackingParams: Boolean = true, var maxReactivationAttempts: Int = 3, var enableDebugLogging: Boolean = false)

Configuration for automatic location tracking reactivation after zoom changes.

Why this exists: By default, when users change zoom level on the map, location tracking (CameraMode.TRACKING_GPS) is automatically deactivated. This can be frustrating during navigation when users accidentally zoom and lose tracking. This configuration enables automatic reactivation to maintain a smooth navigation experience.

Problem solved: Without this configuration, users must manually re-enable location following after zoom changes, interrupting navigation flow. With reactivation enabled, tracking automatically resumes after a brief delay, providing seamless navigation.

How it works:

• When zoom changes occur during active tracking, tracking is deactivated (MapLibre behavior)
• If enableReactivation is true, the SDK waits reactivationDelayMs milliseconds
• Tracking is then automatically reactivated with preserved parameters (if preserveTrackingParams is true)
• After maxReactivationAttempts consecutive reactivations, auto-reactivation stops (prevents loops)

When to use:

• Navigation apps: Enable reactivation for seamless navigation experience
• General use: Enable if users frequently zoom during location tracking
• Conservative apps: Disable to maintain current behavior (no automatic reactivation)

Performance: Reactivation only occurs when enableReactivation is true, so there’s no performance impact when disabled. The delay prevents too-frequent reactivations.

Constructors

Properties

enableDebugLogging

var enableDebugLogging: Boolean

If true, logs detailed reactivation information. Useful for debugging but should be disabled in production. Default: false.

enableReactivation

var enableReactivation: Boolean

If true, automatically reactivates tracking after zoom changes. Default: false (maintains current behavior). Set to true for navigation apps.

maxReactivationAttempts

var maxReactivationAttempts: Int

Maximum consecutive reactivation attempts before disabling auto-reactivation (default: 3). Prevents infinite reactivation loops. Recommended: - 3: General use - 5-10: Navigation apps requiring persistence

preserveTrackingParams

var preserveTrackingParams: Boolean

If true, maintains original tracking parameters (pitch, zoom, padding) when reactivating. If false, uses default parameters. Default: true.

reactivationDelayMs

var reactivationDelayMs: Long

Delay in milliseconds before reactivating (default: 1000ms). Prevents rapid reactivation cycles. Recommended values: - 500ms: Fast reactivation for navigation apps - 1000ms: Balanced (default) - 2000ms: Conservative, ensures zoom gesture completes

Functions

createSafeCopy

fun createSafeCopy(): TrackingConfig

Create a safe copy of the configuration with default values

isValid

fun isValid(): Boolean

Validate that the configuration is valid