Add MapRecorder support for Flutter SDK (#1069)

Add MapRecorder support

Implements MapRecorder functionality to achieve feature parity with Android and iOS native SDKs.
- Add Pigeon-generated platform communication layer
- Implement MapRecorderController for Android and iOS platforms
- Create MapRecorder wrapper class with user-facing API
- Integrate into MapboxMap via recorder property
- Add working example demonstrating record/replay/pause features
- Mark API as @experimental matching native SDK status

Co-authored-by: protheeuz <[email protected]>

Author: pjleonard37

CHANGELOG.md

@@ -1,5 +1,7 @@
 ### main
 
+* Add experimental MapRecorder API to record and replay map interactions for debugging and performance testing.
+
 ### 2.17.0-rc.1
 
 * [iOS] Fix annotation interaction handlers (tap, drag etc.) not working after annotation update.

android/src/main/kotlin/com/mapbox/maps/mapbox_maps/MapRecorderController.kt

@@ -0,0 +1,90 @@
+package com.mapbox.maps.mapbox_maps
+
+import com.mapbox.maps.MapboxExperimental
+import com.mapbox.maps.MapboxMap
+import com.mapbox.maps.MapboxMapRecorder
+import com.mapbox.maps.mapbox_maps.pigeons.MapPlayerOptions
+import com.mapbox.maps.mapbox_maps.pigeons.MapRecorderOptions
+import com.mapbox.maps.mapbox_maps.pigeons._MapRecorderMessenger
+import java.nio.ByteBuffer
+
+/**
+ * Controller for MapRecorder functionality.
+ *
+ * Provides functions to record and replay API calls of a MapboxMap instance.
+ * These recordings can be used to debug issues which require multiple steps to reproduce.
+ * Additionally, playbacks can be used for performance testing custom scenarios.
+ */
+@OptIn(MapboxExperimental::class)
+class MapRecorderController(
+  private val mapboxMap: MapboxMap
+) : _MapRecorderMessenger {
+
+  private var recorder: MapboxMapRecorder? = null
+
+  /**
+   * Get or create the recorder instance.
+   */
+  private fun getRecorder(): MapboxMapRecorder {
+    if (recorder == null) {
+      recorder = mapboxMap.createRecorder()
+    }
+    return recorder!!
+  }
+
+  override fun startRecording(options: MapRecorderOptions) {
+    val nativeOptions = com.mapbox.maps.MapRecorderOptions.Builder()
+      .apply {
+        options.timeWindow?.let { timeWindow(it) }
+        loggingEnabled(options.loggingEnabled)
+        compressed(options.compressed)
+      }
+      .build()
+
+    getRecorder().startRecording(nativeOptions)
+  }
+
+  override fun stopRecording(callback: (Result<ByteArray>) -> Unit) {
+    try {
+      val data = getRecorder().stopRecording()
+      val bytes = ByteArray(data.remaining())
+      data.get(bytes)
+      callback(Result.success(bytes))
+    } catch (e: Exception) {
+      callback(Result.failure(e))
+    }
+  }
+
+  override fun replay(
+    recordedSequence: ByteArray,
+    options: MapPlayerOptions,
+    callback: (Result<Unit>) -> Unit
+  ) {
+    try {
+      val nativeOptions = com.mapbox.maps.MapPlayerOptions.Builder()
+        .playbackCount(options.playbackCount.toInt())
+        .playbackSpeedMultiplier(options.playbackSpeedMultiplier)
+        .avoidPlaybackPauses(options.avoidPlaybackPauses)
+        .build()
+
+      val buffer = ByteBuffer.wrap(recordedSequence)
+      getRecorder().replay(buffer, nativeOptions) {
+        callback(Result.success(Unit))
+      }
+    } catch (e: Exception) {
+      callback(Result.failure(e))
+    }
+  }
+
+  override fun togglePauseReplay() {
+    getRecorder().togglePauseReplay()
+  }
+
+  override fun getPlaybackState(): String {
+    return getRecorder().getPlaybackState()
+  }
+
+  fun dispose() {
+    recorder = null
+  }
+}

android/src/main/kotlin/com/mapbox/maps/mapbox_maps/MapboxMapController.kt

@@ -31,6 +31,7 @@ import com.mapbox.maps.mapbox_maps.pigeons._AnimationManager
 import com.mapbox.maps.mapbox_maps.pigeons._CameraManager
 import com.mapbox.maps.mapbox_maps.pigeons._LocationComponentSettingsInterface
 import com.mapbox.maps.mapbox_maps.pigeons._MapInterface
+import com.mapbox.maps.mapbox_maps.pigeons._MapRecorderMessenger
 import com.mapbox.maps.mapbox_maps.pigeons._PerformanceStatisticsApi
 import com.mapbox.maps.mapbox_maps.pigeons._ViewportMessenger
 import com.mapbox.maps.plugin.animation.camera
@@ -122,6 +123,7 @@ class MapboxMapController(
   private val compassController: CompassController
   private val viewportController: ViewportController
   private val performanceStatisticsController: PerformanceStatisticsController
+  private val mapRecorderController: MapRecorderController
 
   private val eventHandler: MapboxEventHandler
 
@@ -206,6 +208,7 @@ class MapboxMapController(
     compassController = CompassController(mapView)
     viewportController = ViewportController(mapView.viewport, mapView.camera, context, mapboxMap)
     performanceStatisticsController = PerformanceStatisticsController(mapboxMap, this.messenger, this.channelSuffix)
+    mapRecorderController = MapRecorderController(mapboxMap)
     changeUserAgent(pluginVersion)
 
     StyleManager.setUp(messenger, styleController, this.channelSuffix)
@@ -222,6 +225,7 @@ class MapboxMapController(
     CompassSettingsInterface.setUp(messenger, compassController, this.channelSuffix)
     _ViewportMessenger.setUp(messenger, viewportController, this.channelSuffix)
     _PerformanceStatisticsApi.setUp(messenger, performanceStatisticsController, this.channelSuffix)
+    _MapRecorderMessenger.setUp(messenger, mapRecorderController, this.channelSuffix)
 
     methodChannel = MethodChannel(messenger, "plugins.flutter.io.$channelSuffix")
     methodChannel.setMethodCallHandler(this)
@@ -288,6 +292,8 @@ class MapboxMapController(
     AttributionSettingsInterface.setUp(messenger, null, channelSuffix)
     _ViewportMessenger.setUp(messenger, null, channelSuffix)
     _PerformanceStatisticsApi.setUp(messenger, null, channelSuffix)
+    _MapRecorderMessenger.setUp(messenger, null, channelSuffix)
+    mapRecorderController.dispose()
   }
 
   override fun onMethodCall(call: MethodCall, result: MethodChannel.Result) {