[google_maps_flutter] Add ability to perform Google Maps SDK warmup (#9674)

The Android Google Maps SDK janks when the first map is shown, completely blocking the app thread. This PR introduces `GoogleMapsFlutterAndroid.warmup()` which lets Flutter developers do what Android developers do to mitigate this: a fake show of a Google Map that forces the SDK to initialize. This is typically done at app startup so that the jank is less visible than during, say, a page transition.

More info: flutter/flutter#28493 (comment)

This PR also introduces injecting `MapsInitializerApi` to the `GoogleMapsFlutterAndroid` constructor, for testing, and adds a basic test for `initializeWithRenderer`, too.

Fixes flutter/flutter#28493

## Pre-Review Checklist

**Note**: The Flutter team is currently trialing the use of [Gemini Code Assist for GitHub](https://developers.google.com/gemini-code-assist/docs/review-github-code). Comments from the `gemini-code-assist` bot should not be taken as authoritative feedback from the Flutter team. If you find its comments useful you can update your code accordingly, but if you are unsure or disagree with the feedback, please feel free to wait for a Flutter team member's review for guidance on which automated comments should be addressed.

[^1]: Regular contributors who have demonstrated familiarity with the repository guidelines only need to comment if the PR is not auto-exempted by repo tooling.

Author: filiph

packages/google_maps_flutter/google_maps_flutter_android/CHANGELOG.md

@@ -1,3 +1,8 @@
+## 2.18.0
+
+* Adds support for warming up the Google Maps SDK 
+  via `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,24 @@ public void initializeWithPreferredRenderer(
     }
   }
 
+  @Override
+  public void warmup() {
+    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.");
+    } catch (Exception e) {
+      throw 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,11 @@ public interface MapsInitializerApi {
      */
     void initializeWithPreferredRenderer(
         @Nullable PlatformRendererType type, @NonNull Result<PlatformRendererType> result);
+    /**
+     * Attempts to trigger any thread-blocking work the Google Maps SDK normally does when a map is
+     * shown for the first time.
+     */
+    void warmup();
 
     /** The codec used by MapsInitializerApi. */
     static @NonNull MessageCodec<Object> getCodec() {
@@ -7706,6 +7711,29 @@ 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<>();
+                try {
+                  api.warmup();
+                  wrapped.add(0, null);
+                } catch (Throwable exception) {
+                  wrapped = wrapError(exception);
+                }
+                reply.reply(wrapped);
+              });
+        } 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,21 @@ 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,
     };
   }
 
+  /// Attempts to trigger any thread-blocking work
+  /// the Google Maps SDK normally does when a map is shown for the first time.
+  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?)!;
     }
   }
+
+  /// Attempts to trigger any thread-blocking work
+  /// the Google Maps SDK 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,10 @@ abstract class MapsInitializerApi {
   @async
   PlatformRendererType initializeWithPreferredRenderer(
       PlatformRendererType? type);
+
+  /// Attempts to trigger any thread-blocking work
+  /// the Google Maps SDK normally does when a map is shown for the first time.
+  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 =