Location Tracking Configuration

The SDK now supports advanced configuration for location tracking behavior, particularly for handling zoom changes that typically deactivate user location tracking.

Problem Solved

By default, when users change the zoom level on the map, the location tracking (CameraMode.TRACKING_GPS) is automatically deactivated. This new configuration allows automatic reactivation of tracking after zoom changes.

Basic Configuration

val lzMapConfig = LazarilloMapConfig()
lzMapConfig.apply {
    parentPlaceId = "your_place_id"
    center = LatLng(40.4168, -3.7038)
    zoom = 17
 
    // Configure tracking behavior
    trackingConfig = TrackingConfig(
        enableReactivation = true,           // Enable automatic reactivation
        reactivationDelayMs = 1000L,        // Wait 1 second before reactivating
        preserveTrackingParams = true,       // Preserve original tracking parameters
        maxReactivationAttempts = 3,         // Maximum 3 reactivation attempts
        enableDebugLogging = false           // Enable debug logs (recommended for development)
    )
}

Configuration Parameters

enableReactivation (Boolean, default: false)

• true: Automatically reactivates tracking after zoom changes
• false: Maintains current behavior (tracking deactivates on zoom change)

reactivationDelayMs (Long, default: 1000)

• Time in milliseconds to wait before reactivating tracking
• Recommended values:
  • 500ms: For navigation apps (fast reactivation)
  • 1000ms: For general use (balanced)
  • 2000ms: For stability-focused apps

preserveTrackingParams (Boolean, default: true)

• true: Maintains original tracking parameters (pitch, zoom, padding)
• false: Uses default parameters when reactivating

maxReactivationAttempts (Int, default: 3)

• Maximum number of consecutive reactivation attempts
• After reaching this limit, automatic reactivation is disabled
• Recommended values:
  • 3: For general use
  • 5: For navigation apps
  • 10: For special cases requiring persistence

enableDebugLogging (Boolean, default: false)

• true: Shows detailed logs of the reactivation process
• false: No additional logs (recommended for production)

Configuration Examples

For Navigation Apps:

trackingConfig = TrackingConfig(
    enableReactivation = true,
    reactivationDelayMs = 500L,
    preserveTrackingParams = true,
    maxReactivationAttempts = 10,
    enableDebugLogging = true
)

For General Use:

trackingConfig = TrackingConfig(
    enableReactivation = true,
    reactivationDelayMs = 1000L,
    preserveTrackingParams = true,
    maxReactivationAttempts = 3,
    enableDebugLogging = false
)

Conservative (Current Behavior):

trackingConfig = TrackingConfig(
    enableReactivation = false  // Maintains current behavior
)

JSON Configuration

You can also configure tracking from JSON for dynamic configurations:

{
  "width": 400,
  "height": 300,
  "zoom": 15,
  "center": {
    "lat": 40.4168,
    "lng": -3.7038
  },
  "trackingConfig": {
    "enableReactivation": true,
    "reactivationDelayMs": 1000,
    "preserveTrackingParams": true,
    "maxReactivationAttempts": 3,
    "enableDebugLogging": false
  }
}

Usage with followUserLocation

When using followUserLocation with tracking configuration enabled:

// Start following user location
lzMap.followUserLocation(
    value = true,
    pitch = 45.0,
    zoom = 18.0,
    padding = doubleArrayOf(0.0, 0.0, 0.0, 0.0)
)
 
// With trackingConfig.enableReactivation = true:
// - Tracking will automatically reactivate after zoom changes
// - Original parameters (pitch, zoom, padding) will be preserved
// - Reactivation will happen after the configured delay
// - Maximum attempts limit will be respected

Default Behavior

By default, enableReactivation = false, which means:

• Current behavior is maintained without changes
• No automatic tracking reactivation
• No performance impact
• Full compatibility with existing implementations

Performance Considerations

• Automatic reactivation only runs when enableReactivation = true
• Configurable delay prevents too frequent reactivations
• Attempt limit prevents infinite loops
• Reactivation jobs are properly cancelled to prevent memory leaks