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

filiph · 2025-07-25T15:30:50Z

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

If you need help, consider asking for advice on the #hackers-new channel on Discord.

Note: The Flutter team is currently trialing the use of Gemini Code Assist for GitHub. 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.

Regular contributors who have demonstrated familiarity with the repository guidelines only need to comment if the PR is not auto-exempted by repo tooling. ↩ ↩² ↩³

gemini-code-assist

Code Review

This PR introduces a warmup method to mitigate the initial jank on Android, along with dependency injection for testing. Adding onResume() to the MapView lifecycle methods in the warmup process would ensure it's as effective as possible.

...lutter_android/android/src/main/java/io/flutter/plugins/googlemaps/GoogleMapInitializer.java

…d-warmup

filiph · 2025-07-28T17:49:08Z

Hey maintainers, I've finalized this PR and removed the WIP tag. I see that one of the test suites failed with a timeout, but I think maybe that's not my fault.

reidbaker · 2025-07-28T18:08:07Z

Hey maintainers, I've finalized this PR and removed the WIP tag. I see that one of the test suites failed with a timeout, but I think maybe that's not my fault.

Yeah I dont think that should prevent review.

reidbaker

Thank you for your contribution!

...lutter_android/android/src/main/java/io/flutter/plugins/googlemaps/GoogleMapInitializer.java

reidbaker · 2025-07-28T18:54:59Z

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.17.1


@stuartmorgan-g should this be a minor version bump not a patch version bump?
I reviewed https://github.com/flutter/flutter/blob/master/docs/ecosystem/contributing/README.md but didnt see anything more specific than my general understadning of sem-ver.

Yes, since it adds new public API semver requires it to be a minor API bump. (That's not a repo policy, it's basic semver.)

@filiph I think this is still blocking.

I think this was already addressed in 8b9878e ? Or at least I see this as addressed both locally and here on github.

...s/google_maps_flutter/google_maps_flutter_android/test/google_maps_flutter_android_test.dart

...le_maps_flutter/google_maps_flutter_android/test/google_maps_flutter_android_test.mocks.dart

…google_maps_flutter_android_test.dart Co-authored-by: Reid Baker <[email protected]>

packages/google_maps_flutter/google_maps_flutter_android/README.md

packages/google_maps_flutter/google_maps_flutter_android/pigeons/messages.dart

stuartmorgan-g · 2025-07-29T15:01:04Z

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.17.1


Yes, since it adds new public API semver requires it to be a minor API bump. (That's not a repo policy, it's basic semver.)

filiph · 2025-08-01T12:33:15Z

Thanks for the feedback. Implemented.

packages/google_maps_flutter/google_maps_flutter_android/CHANGELOG.md

stuartmorgan-g · 2025-08-04T19:17:39Z

...ges/google_maps_flutter/google_maps_flutter_android/lib/src/google_maps_flutter_android.dart

+  ///
+  /// 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).


Please remove the parenthetical here, per the discussion in the README.

stuartmorgan-g · 2025-08-04T19:19:28Z

...ges/google_maps_flutter/google_maps_flutter_android/lib/src/google_maps_flutter_android.dart


    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


How about "Attempts to trigger any thread-blocking work the Google Maps SDK normally does when a map is shown for the first time."

It's not actually asking the SDK to do this; that implies some officially supported API intended for this purpose. Instead it's trying to trigger it via reliance on internal implementation details of the SDK that could change at any time.

I really like this, thanks for the suggestion! Implemented.

stuartmorgan-g · 2025-08-04T19:20:13Z

packages/google_maps_flutter/google_maps_flutter_android/CHANGELOG.md

@@ -1,3 +1,7 @@
+## 2.18.0
+
+* Adds GoogleMapsFlutterAndroid.warmup().


Nit: backticks around the code.

Also, this should provide some client-facing context about what this is, rather than someone needing to go read the API docs to understand what this method is for.

I came up with

* Adds support for warming up the Google Maps SDK via `GoogleMapsFlutterAndroid.warmup()`.

I try to balance the laconic style of the changelog with giving some context, but I feel I'm botching it?

…d-warmup2

stuartmorgan-g · 2025-08-06T17:48:59Z

packages/google_maps_flutter/google_maps_flutter_android/pigeons/messages.dart

+
+  /// Attempts to trigger any thread-blocking work
+  /// the Google Maps SDK normally does when a map is shown for the first time.
+  @async


Sorry, I missed this in previous review: why is this marked @async? There's no async step in the Java code, it's all synchronous. Without the @async annotation the Java code would be simpler, without the possibility of accidentally not calling the result.

Ah! Damn, sorry I missed it. The original code was async but then I found out it wouldn't work so I made it synchronous — and promptly forgot about this being async.

Addressed.

stuartmorgan-g

LGTM

…K warmup (flutter/packages#9674)

flutter/packages@f0b2726...6efb759 2025-08-06 [email protected] [camera_android_camerax] Re-land "Force new Surface for each SurfaceRequest" (flutter/packages#9760) 2025-08-06 [email protected] [google_maps_flutter] Add ability to perform Google Maps SDK warmup (flutter/packages#9674) 2025-08-06 [email protected] Roll Flutter from 59fc766 to 9de63a0 (6 revisions) (flutter/packages#9764) 2025-08-06 [email protected] [webview_flutter_wkwebview] Extended Web View API on iOS to add flexibility when working with local HTML content (flutter/packages#8787) If this roll has caused a breakage, revert this CL and stop the roller using the controls here: https://autoroll.skia.org/r/flutter-packages-flutter-autoroll Please CC [email protected] on the revert to ensure that a human is aware of the problem. To file a bug in Flutter: https://github.com/flutter/flutter/issues/new/choose To report a problem with the AutoRoller itself, please file a bug: https://issues.skia.org/issues/new?component=1389291&template=1850622 Documentation for the AutoRoller is here: https://skia.googlesource.com/buildbot/+doc/main/autoroll/README.md

…r#173414) flutter/packages@f0b2726...6efb759 2025-08-06 [email protected] [camera_android_camerax] Re-land "Force new Surface for each SurfaceRequest" (flutter/packages#9760) 2025-08-06 [email protected] [google_maps_flutter] Add ability to perform Google Maps SDK warmup (flutter/packages#9674) 2025-08-06 [email protected] Roll Flutter from 59fc766 to 9de63a0 (6 revisions) (flutter/packages#9764) 2025-08-06 [email protected] [webview_flutter_wkwebview] Extended Web View API on iOS to add flexibility when working with local HTML content (flutter/packages#8787) If this roll has caused a breakage, revert this CL and stop the roller using the controls here: https://autoroll.skia.org/r/flutter-packages-flutter-autoroll Please CC [email protected] on the revert to ensure that a human is aware of the problem. To file a bug in Flutter: https://github.com/flutter/flutter/issues/new/choose To report a problem with the AutoRoller itself, please file a bug: https://issues.skia.org/issues/new?component=1389291&template=1850622 Documentation for the AutoRoller is here: https://skia.googlesource.com/buildbot/+doc/main/autoroll/README.md

filiph added 3 commits July 25, 2025 14:57

Add the new warmup() method signature

1c21fd5

Re-run Pigeon

8340c92

Add warmup()

0f7eb5e

filiph requested a review from reidbaker as a code owner July 25, 2025 15:30

github-actions bot added p: google_maps_flutter platform-android labels Jul 25, 2025

reidbaker requested a review from stuartmorgan-g July 25, 2025 15:31

gemini-code-assist bot reviewed Jul 25, 2025

View reviewed changes

...lutter_android/android/src/main/java/io/flutter/plugins/googlemaps/GoogleMapInitializer.java Outdated Show resolved Hide resolved

filiph added 6 commits July 28, 2025 14:02

Run warmup() from example

4fbb635

Run format tool

5d2fa59

Merge remote-tracking branch 'upstream/main' into feat/add-map-preloa…

2f88081

…d-warmup

Update CHANGELOG

c656c24

Clarify function of initializeMapRenderer

a995242

Add paragraph to README

6e6264c

filiph changed the title ~~[google_maps_flutter] [WIP] Add ability to perform Google Maps SDK warmup~~ [google_maps_flutter] Add ability to perform Google Maps SDK warmup Jul 28, 2025

reidbaker reviewed Jul 28, 2025

View reviewed changes

filiph and others added 4 commits July 29, 2025 10:09

Add onResume()

cf2db77

Update packages/google_maps_flutter/google_maps_flutter_android/test/…

fd4d680

…google_maps_flutter_android_test.dart Co-authored-by: Reid Baker <[email protected]>

Update packages/google_maps_flutter/google_maps_flutter_android/test/…

99d3bb1

…google_maps_flutter_android_test.dart Co-authored-by: Reid Baker <[email protected]>

Re-format

a4a6fe3

reidbaker approved these changes Jul 29, 2025

View reviewed changes

stuartmorgan-g requested changes Jul 29, 2025

View reviewed changes

Address feedback

8b9878e

reidbaker approved these changes Aug 1, 2025

View reviewed changes

reidbaker reviewed Aug 1, 2025

View reviewed changes

packages/google_maps_flutter/google_maps_flutter_android/CHANGELOG.md Outdated Show resolved Hide resolved

Merge branch 'main' into feat/add-map-preload-warmup

8fb6c08

stuartmorgan-g requested changes Aug 4, 2025

View reviewed changes

filiph added 3 commits August 6, 2025 14:06

Merge remote-tracking branch 'upstream/main' into feat/add-map-preloa…

5108d94

…d-warmup2

Improve docs and CHANGELOG

fd35ad3

Update docs in messages.dart

08d3ded

stuartmorgan-g reviewed Aug 6, 2025

View reviewed changes

Remove @async

0efe9d7

stuartmorgan-g approved these changes Aug 6, 2025

View reviewed changes

stuartmorgan-g added the autosubmit Merge PR when tree becomes green via auto submit App label Aug 6, 2025

auto-submit bot merged commit 091b87d into flutter:main Aug 6, 2025
80 checks passed

engine-flutter-autoroll added a commit to engine-flutter-autoroll/flutter that referenced this pull request Aug 7, 2025

091b87d51 [google_maps_flutter] Add ability to perform Google Maps SD…

b16daf5

…K warmup (flutter/packages#9674)

engine-flutter-autoroll mentioned this pull request Aug 7, 2025

Roll Packages from f0b272645902 to 6efb75994fc0 (4 revisions) flutter/flutter#173414

Merged

		@@ -1,3 +1,7 @@
		## 2.18.0

		* Adds GoogleMapsFlutterAndroid.warmup().

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

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

Conversation

filiph commented Jul 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Pre-Review Checklist

Footnotes

Uh oh!

gemini-code-assist bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

filiph commented Jul 28, 2025

Uh oh!

reidbaker commented Jul 28, 2025

Uh oh!

reidbaker left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

filiph commented Aug 1, 2025

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

stuartmorgan-g left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

filiph commented Jul 25, 2025 •

edited

Loading