[google_maps_flutter] Add ability to perform Google Maps SDK warmup

packages/google_maps_flutter/google_maps_flutter_android/CHANGELOG.md

@@ -1,3 +1,7 @@
+## 2.18.0
+
+* Adds GoogleMapsFlutterAndroid.warmup().
+
 ## 2.17.0
 
 * Updates `com.google.android.gms:play-services-maps` to 19.2.0.

packages/google_maps_flutter/google_maps_flutter_android/README.md

@@ -61,6 +61,14 @@ the issue in the TLHC mode.
 | Heatmap.maximumZoomIntensity |     x     |
 | HeatmapGradient.colorMapSize |     ✓     |
 
+## Warmup
+
+The first time a map is shown, the Google Maps SDK may briefly block 
+the main thread, which could cause UI jank. 
+If you prefer to control when this happens, you can call
+`GoogleMapsFlutterAndroid.warmup()` at some point before showing any maps to
+pre-warm the SDK. See this plugin's example code for one way of using this API.
+
 [1]: https://pub.dev/packages/google_maps_flutter
 [2]: https://flutter.dev/to/endorsed-federated-plugin
 [3]: https://docs.flutter.dev/development/platform-integration/android/platform-views

packages/google_maps_flutter/google_maps_flutter_android/android/src/main/java/io/flutter/plugins/googlemaps/GoogleMapInitializer.java

@@ -5,16 +5,19 @@
 package io.flutter.plugins.googlemaps;
 
 import android.content.Context;
+import android.util.Log;
 import androidx.annotation.NonNull;
 import androidx.annotation.Nullable;
 import androidx.annotation.VisibleForTesting;
+import com.google.android.gms.maps.MapView;
 import com.google.android.gms.maps.MapsInitializer;
 import com.google.android.gms.maps.OnMapsSdkInitializedCallback;
 import io.flutter.plugin.common.BinaryMessenger;
 
 /** GoogleMaps initializer used to initialize the Google Maps SDK with preferred settings. */
 final class GoogleMapInitializer
     implements OnMapsSdkInitializedCallback, Messages.MapsInitializerApi {
+  private static final String TAG = "GoogleMapInitializer";
   private final Context context;
   private static Messages.Result<Messages.PlatformRendererType> initializationResult;
   private boolean rendererInitialized = false;
@@ -41,6 +44,25 @@ public void initializeWithPreferredRenderer(
     }
   }
 
+  @Override
+  public void warmup(@NonNull Messages.VoidResult result) {
+    Log.i(TAG, "Google Maps warmup started.");
+    try {
+      // This creates a fake map view in order to trigger the SDK's
+      // initialization. For context, see
+      // https://github.com/flutter/flutter/issues/28493#issuecomment-2919150669.
+      MapView mv = new MapView(context);
+      mv.onCreate(null);
+      mv.onResume();
+      mv.onPause();
+      mv.onDestroy();
+      Log.i(TAG, "Maps warmup complete.");
+      result.success();
+    } catch (Exception e) {
+      result.error(new Messages.FlutterError("Could not warm up", e.toString(), null));
+    }
+  }
+
   /**
    * Initializes map renderer to with preferred renderer type.
    *

packages/google_maps_flutter/google_maps_flutter_android/android/src/main/java/io/flutter/plugins/googlemaps/Messages.java

@@ -7657,6 +7657,14 @@ public interface MapsInitializerApi {
      */
     void initializeWithPreferredRenderer(
         @Nullable PlatformRendererType type, @NonNull Result<PlatformRendererType> result);
+    /**
+     * Asks the Google Maps SDK to do the thread-blocking work it normally does when a map is shown
+     * for the first time.
+     *
+     * <p>This gives the developer the option to move that jank to a different part of the map
+     * (typically, the app startup, where missed frames aren't going to be noticed).
+     */
+    void warmup(@NonNull VoidResult result);
 
     /** The codec used by MapsInitializerApi. */
     static @NonNull MessageCodec<Object> getCodec() {
@@ -7706,6 +7714,36 @@ public void error(Throwable error) {
           channel.setMessageHandler(null);
         }
       }
+      {
+        BasicMessageChannel<Object> channel =
+            new BasicMessageChannel<>(
+                binaryMessenger,
+                "dev.flutter.pigeon.google_maps_flutter_android.MapsInitializerApi.warmup"
+                    + messageChannelSuffix,
+                getCodec());
+        if (api != null) {
+          channel.setMessageHandler(
+              (message, reply) -> {
+                ArrayList<Object> wrapped = new ArrayList<>();
+                VoidResult resultCallback =
+                    new VoidResult() {
+                      public void success() {
+                        wrapped.add(0, null);
+                        reply.reply(wrapped);
+                      }
+
+                      public void error(Throwable error) {
+                        ArrayList<Object> wrappedError = wrapError(error);
+                        reply.reply(wrappedError);
+                      }
+                    };
+
+                api.warmup(resultCallback);
+              });
+        } else {
+          channel.setMessageHandler(null);
+        }
+      }
     }
   }
   /**

packages/google_maps_flutter/google_maps_flutter_android/example/lib/main.dart

@@ -85,7 +85,8 @@ void main() {
 
 Completer<AndroidMapRenderer?>? _initializedRendererCompleter;
 
-/// Initializes map renderer to the `latest` renderer type.
+/// Initializes map renderer to the `latest` renderer type, and calls
+/// [GoogleMapsFlutterAndroid.warmup()].
 ///
 /// The renderer must be requested before creating GoogleMap instances,
 /// as the renderer can be initialized only once per application context.
@@ -100,11 +101,13 @@ Future<AndroidMapRenderer?> initializeMapRenderer() async {
 
   WidgetsFlutterBinding.ensureInitialized();
 
-  final GoogleMapsFlutterPlatform platform = GoogleMapsFlutterPlatform.instance;
-  unawaited((platform as GoogleMapsFlutterAndroid)
+  final GoogleMapsFlutterAndroid platform =
+      GoogleMapsFlutterPlatform.instance as GoogleMapsFlutterAndroid;
+  unawaited(platform
       .initializeWithRenderer(AndroidMapRenderer.latest)
       .then((AndroidMapRenderer initializedRenderer) =>
-          completer.complete(initializedRenderer)));
+          completer.complete(initializedRenderer))
+      .then((_) => platform.warmup()));
 
   return completer.future;
 }

packages/google_maps_flutter/google_maps_flutter_android/lib/src/google_maps_flutter_android.dart

@@ -65,7 +65,9 @@ class GoogleMapsFlutterAndroid extends GoogleMapsFlutterPlatform {
   /// Creates a new Android maps implementation instance.
   GoogleMapsFlutterAndroid({
     @visibleForTesting MapsApi Function(int mapId)? apiProvider,
-  }) : _apiProvider = apiProvider ?? _productionApiProvider;
+    @visibleForTesting MapsInitializerApi? initializerApi,
+  })  : _apiProvider = apiProvider ?? _productionApiProvider,
+        _initializerApi = initializerApi ?? MapsInitializerApi();
 
   /// Registers the Android implementation of GoogleMapsFlutterPlatform.
   static void registerWith() {
@@ -77,6 +79,8 @@ class GoogleMapsFlutterAndroid extends GoogleMapsFlutterPlatform {
   // A method to create MapsApi instances, which can be overridden for testing.
   final MapsApi Function(int mapId) _apiProvider;
 
+  final MapsInitializerApi _initializerApi;
+
   /// The per-map handlers for callbacks from the host side.
   @visibleForTesting
   final Map<int, HostMapMessageHandler> hostMapHandlers =
@@ -532,16 +536,25 @@ class GoogleMapsFlutterAndroid extends GoogleMapsFlutterPlatform {
         preferredRenderer = null;
     }
 
-    final MapsInitializerApi hostApi = MapsInitializerApi();
-    final PlatformRendererType initializedRenderer =
-        await hostApi.initializeWithPreferredRenderer(preferredRenderer);
+    final PlatformRendererType initializedRenderer = await _initializerApi
+        .initializeWithPreferredRenderer(preferredRenderer);
 
     return switch (initializedRenderer) {
       PlatformRendererType.latest => AndroidMapRenderer.latest,
       PlatformRendererType.legacy => AndroidMapRenderer.legacy,
     };
   }
 
+  /// Asks the Google Maps SDK to do the thread-blocking work it normally does
+  /// when a map is shown for the first time.
+  ///
+  /// This gives the developer the option to move that jank to a different
+  /// part of the map (typically, the app startup, where missed frames
+  /// aren't going to be noticed).
+  Future<void> warmup() async {
+    await _initializerApi.warmup();
+  }
+
   Widget _buildView(
     int creationId,
     PlatformViewCreatedCallback onPlatformViewCreated, {

packages/google_maps_flutter/google_maps_flutter_android/lib/src/messages.g.dart

@@ -3104,6 +3104,32 @@ class MapsInitializerApi {
       return (pigeonVar_replyList[0] as PlatformRendererType?)!;
     }
   }
+
+  /// Asks the Google Maps SDK to do the thread-blocking work it normally does
+  /// when a map is shown for the first time.
+  Future<void> warmup() async {
+    final String pigeonVar_channelName =
+        'dev.flutter.pigeon.google_maps_flutter_android.MapsInitializerApi.warmup$pigeonVar_messageChannelSuffix';
+    final BasicMessageChannel<Object?> pigeonVar_channel =
+        BasicMessageChannel<Object?>(
+      pigeonVar_channelName,
+      pigeonChannelCodec,
+      binaryMessenger: pigeonVar_binaryMessenger,
+    );
+    final List<Object?>? pigeonVar_replyList =
+        await pigeonVar_channel.send(null) as List<Object?>?;
+    if (pigeonVar_replyList == null) {
+      throw _createConnectionError(pigeonVar_channelName);
+    } else if (pigeonVar_replyList.length > 1) {
+      throw PlatformException(
+        code: pigeonVar_replyList[0]! as String,
+        message: pigeonVar_replyList[1] as String?,
+        details: pigeonVar_replyList[2],
+      );
+    } else {
+      return;
+    }
+  }
 }
 
 /// Dummy interface to force generation of the platform view creation params,

packages/google_maps_flutter/google_maps_flutter_android/pigeons/messages.dart

@@ -786,6 +786,15 @@ abstract class MapsInitializerApi {
   @async
   PlatformRendererType initializeWithPreferredRenderer(
       PlatformRendererType? type);
+
+  /// Asks the Google Maps SDK to do the thread-blocking work it normally does
+  /// when a map is shown for the first time.
+  ///
+  /// This gives the developer the option to move that jank to a different
+  /// part of the map (typically, the app startup, where missed frames
+  /// aren't going to be noticed).
+  @async
+  void warmup();
 }
 
 /// Dummy interface to force generation of the platform view creation params,

packages/google_maps_flutter/google_maps_flutter_android/pubspec.yaml

@@ -2,7 +2,7 @@ name: google_maps_flutter_android
 description: Android implementation of the google_maps_flutter plugin.
 repository: https://github.com/flutter/packages/tree/main/packages/google_maps_flutter/google_maps_flutter_android
 issue_tracker: https://github.com/flutter/flutter/issues?q=is%3Aissue+is%3Aopen+label%3A%22p%3A+maps%22
-version: 2.17.0
+version: 2.18.0
 
 environment:
   sdk: ^3.6.0

packages/google_maps_flutter/google_maps_flutter_android/test/google_maps_flutter_android_test.dart

@@ -15,7 +15,8 @@ import 'package:mockito/mockito.dart';
 
 import 'google_maps_flutter_android_test.mocks.dart';
 
-@GenerateNiceMocks(<MockSpec<Object>>[MockSpec<MapsApi>()])
+@GenerateNiceMocks(
+    <MockSpec<Object>>[MockSpec<MapsApi>(), MockSpec<MapsInitializerApi>()])
 void main() {
   TestWidgetsFlutterBinding.ensureInitialized();
 
@@ -32,6 +33,40 @@ void main() {
     expect(GoogleMapsFlutterPlatform.instance, isA<GoogleMapsFlutterAndroid>());
   });
 
+  test('normal usage does not call MapsInitializerApi', () async {
+    final MockMapsApi api = MockMapsApi();
+    final MockMapsInitializerApi initializerApi = MockMapsInitializerApi();
+    final GoogleMapsFlutterAndroid maps = GoogleMapsFlutterAndroid(
+        apiProvider: (_) => api, initializerApi: initializerApi);
+    const int mapId = 1;
+    maps.ensureApiInitialized(mapId);
+    await maps.init(1);
+
+    verifyZeroInteractions(initializerApi);
+  });
+
+  test('initializeWithPreferredRenderer forwards the initialization call',
+      () async {
+    final MockMapsApi api = MockMapsApi();
+    final MockMapsInitializerApi initializerApi = MockMapsInitializerApi();
+    final GoogleMapsFlutterAndroid maps = GoogleMapsFlutterAndroid(
+        apiProvider: (_) => api, initializerApi: initializerApi);
+    await maps.initializeWithRenderer(AndroidMapRenderer.latest);
+
+    verify(initializerApi
+        .initializeWithPreferredRenderer(PlatformRendererType.latest));
+  });
+
+  test('warmup forwards the initialization call', () async {
+    final MockMapsApi api = MockMapsApi();
+    final MockMapsInitializerApi initializerApi = MockMapsInitializerApi();
+    final GoogleMapsFlutterAndroid maps = GoogleMapsFlutterAndroid(
+        apiProvider: (_) => api, initializerApi: initializerApi);
+    await maps.warmup();
+
+    verify(initializerApi.warmup());
+  });
+
   test('init calls waitForMap', () async {
     final MockMapsApi api = MockMapsApi();
     final GoogleMapsFlutterAndroid maps =