[google_maps_flutter] Add Advanced Markers support #7882

aednlaxer · 2024-10-16T11:26:56Z

This PR adds Advanced Markers support to google_maps_flutter as discussed in #155526. The document from the issue offers several options to implement Advanced Markers support, this PR uses option 1 (Advanced Marker Dart class is a subclass Marker class).

Summary of changes:

Add map capability check
Add AdvancedMarker class
Add MarkerCollisionBehavior enum to control Advanced Marker's behavior when it collides with another marker
Add PinConfig bitmap descriptor for customizing Advanced Marker's pin and icon
Add markerType parameter to indicate that Advanced Markers should be used
Rename cloudMapId to mapId

Notes:

native implementations need to know what kind of marker should be used, this is needed to use correct marker options, cluster manager and marker controller. Indicating marker type is done by using a markerType option when creating a GoogleMap (could be marker or advancedMarker). Default option is marker
cloudMapId is deprecated in favor of mapId. New name follows SDKs, documentation and Cloud Console naming.
web implementation uses generics because gmaps.Marker and gmaps.AdvancedMarkerElement are not related to each other and should be handled differently
legacy markers are deprecated but still supported in Maps Javascript API. google_maps_flutter still uses them by default in this PR because of backward-compatibility. #130472 is related, package users will be able to use Advanced Markers to fix the deprecation warning
Advanced Markers example on iOS doesn't show advanced markers, seems to be a known issue
Using Flutter widget as Advanced Marker icon (so called View Marker) is not part of this PR, this was discussed in the document and later removed as we agreed that it should be a separate issue

Resolves #155526

Pre-launch Checklist

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

reidbaker

High level android code review. I am concerned by having to runtime type check class.

That said thank you for opening this pull request.

packages/google_maps_flutter/google_maps_flutter/example/android/app/build.gradle

reidbaker · 2024-10-28T15:39:31Z

...r_android/android/src/main/java/io/flutter/plugins/googlemaps/ClusterManagersController.java

+   */
+  private void initializeRenderer(ClusterManager<MarkerBuilder> clusterManager) {
+    final ClusterRenderer<MarkerBuilder> renderer = clusterManager.getRenderer();
+    if (renderer.getClass() == MarkerClusterRenderer.class


Why do we need this reflection here? Can we use non null instead as a signal here?

I've removed this check - previously initializeRenderer (it was named differently) was called multiple times, now it's called once and there's no need to check if a renderer has been previously assigned

reidbaker · 2024-10-28T15:41:27Z

...r_android/android/src/main/java/io/flutter/plugins/googlemaps/ClusterManagersController.java

@@ -225,6 +256,35 @@ protected void onClusterItemRendered(@NonNull T item, @NonNull Marker marker) {
    }
  }

+  /** AdvancedMarkerClusterRenderer is a ClusterRenderer that supports AdvancedMarkers */
+  @VisibleForTesting
+  static class AdvancedMarkerClusterRenderer<T extends MarkerBuilder>


Does this need to be a different class? If it does can it extend MarkerClusterRenderer?

I worry about keeping the two in sync.

Yes, it does. android-maps-utils have two different renderers - one for each marker type (legacy and advanced). This new class extends DefaultAdvancedMarkersClusterRenderer which is meant to be used with AdvancedMarkers. As far as I remember, android-maps-utils recreates cluster markers under the hood so it has to know which marker type to use

reidbaker · 2024-10-28T15:43:58Z

...flutter_android/android/src/main/java/io/flutter/plugins/googlemaps/GoogleMapController.java

@@ -980,6 +984,18 @@ public Boolean isInfoWindowShown(@NonNull String markerId) {
    return lastSetStyleSucceeded;
  }

+  @Override
+  public @NonNull Boolean isAdvancedMarkersAvailable() {


Can this be bool instead of Boolean if it is non null?

Looks like it can't be done like this. This code uses Pigeon-generated code and Dart's bool isAdvancedMarkersAvailable() is translated into Java's @NonNull Boolean isAdvancedMarkersAvailable();

reidbaker · 2024-10-28T15:45:01Z

...ps_flutter_android/android/src/main/java/io/flutter/plugins/googlemaps/GoogleMapFactory.java

-    final String cloudMapId = mapConfig.getCloudMapId();
-    if (cloudMapId != null) {
-      builder.setMapId(cloudMapId);
+    final String mapId = mapConfig.getMapId();


For my own education can you share why we would want to use mapId instead of cloudMapId and why the change is safe (wont cause a regression in existing apps)

I've added a comment about renaming it here.. It's safe because cloudMapId can still be used by existing clients, it's marked as deprecated and uses mapId under the hood

reidbaker · 2024-10-28T15:46:05Z

...ps_flutter_android/android/src/main/java/io/flutter/plugins/googlemaps/MarkerController.java

@@ -143,6 +143,9 @@ public void setZIndex(float zIndex) {
    marker.setZIndex(zIndex);
  }

+  @Override
+  public void setCollisionBehavior(int collisionBehavior) {}


Please add a javadoc that describes the valid collisionBehavior int's or at least where they are defined.
Better yet convert int to something typesafe

stuartmorgan

I've only looked at the app-facing and platform interface packages so far, but there are some fundamental structure questions at the interface layer.

...ages/google_maps_flutter/google_maps_flutter/example/lib/readme_sample_advanced_markers.dart

packages/google_maps_flutter/google_maps_flutter/example/lib/clustering.dart

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

packages/google_maps_flutter/google_maps_flutter/example/lib/marker_icons.dart

stuartmorgan · 2024-11-21T20:28:13Z

packages/google_maps_flutter/google_maps_flutter_platform_interface/lib/src/types/glyph.dart

+
+  /// Color of the default glyph (circle)
+  final Color? color;
+}


Why are all of the different types of Glyph a single class with fields that are almost all unique to a single type, rather than using subclasses like, e.g., BitmapDescriptor?

This is a really good suggestion, thanks. I've changed all three named constructors to be separate classes extending BitmapDescriptor. They're all now in bitmap.dart

...gle_maps_flutter/google_maps_flutter_platform_interface/lib/src/types/map_configuration.dart

stuartmorgan · 2024-11-21T20:30:31Z

...gle_maps_flutter/google_maps_flutter_platform_interface/lib/src/types/map_configuration.dart

+  ///
+  /// See https://developers.google.com/maps/documentation/get-map-id
+  /// for more details.
+  @Deprecated('cloudMapId is deprecated. Use mapId instead')
  final String? cloudMapId;


The intent is to renamed cloudMapId, right? If so, the field should be removed, and it should store to and read from mapId, rather than having two potentially conflicting fields.

Yes, the intent is to rename cloudMapId to mapId, I've removed the field. Do you think it's okay to rename it and it should be done in this PR?

Why it should be renamed:

mapId is what Google Maps platform implementations use

"Map ID" is what Cloud Console uses on Map styles page

cloudMapId feels a bit like it's used for cloud styling which is true but after introduction of Advanced markers map ID is required to make Advanced markers work even if map is not using a custom style.

Removing cloudMapId from the interface (as in the current version of the PR) is a breaking change, which isn't something we want. What I was suggesting was replacing the field with a getter that reads from mapId, as that preserves the public API without having two difference sources of truth.

This should be fixed now

...s_flutter/google_maps_flutter_platform_interface/lib/src/types/map_widget_configuration.dart

packages/google_maps_flutter/google_maps_flutter_platform_interface/lib/src/types/marker.dart

stuartmorgan · 2025-01-07T20:01:50Z

Looks like some platform reviewers were dropped at some point on accident.

stuartmorgan · 2025-01-06T19:07:46Z

packages/google_maps_flutter/google_maps_flutter/README.md

@@ -121,6 +121,21 @@ the `GoogleMap`'s `onMapCreated` callback.
 The `GoogleMap` widget should be used within a widget with a bounded size. Using it
 in an unbounded widget will cause the application to throw a Flutter exception.

+### Advanced Markers
+
+[Advanced Markers](https://developers.google.com/maps/documentation/javascript/advanced-markers/overview) are map markers that offer extra customization options. [Map Id](https://developers.google.com/maps/documentation/get-map-id) is required in order to use Advanced Markers:


Nit: The official docs refer to this as "Map ID" not "Map Id".

Thanks, fixed

packages/google_maps_flutter/google_maps_flutter/README.md

stuartmorgan · 2025-01-06T19:10:31Z

packages/google_maps_flutter/google_maps_flutter/example/lib/place_advanced_marker.dart

+
+  /// Whether map supports advanced markers. Null indicates capability check
+  /// is in progress
+  bool? _isAdvancedMarkersAvailable;


That's unfortunate 😐. I agree though, matching the underlying SDK makes sense here.

stuartmorgan · 2025-01-06T19:24:51Z

...oogle_maps_flutter/google_maps_flutter_platform_interface/lib/src/types/advanced_marker.dart

+  }
+
+  @override
+  int get hashCode => markerId.hashCode;


Hrm, maybe that's intentional then. I'd need to dig into the SDK a lot more to be sure, but being consistent for now sounds good.

stuartmorgan · 2025-01-07T19:53:58Z

...gle_maps_flutter/google_maps_flutter_platform_interface/lib/src/types/map_configuration.dart

+  ///
+  /// See https://developers.google.com/maps/documentation/get-map-id
+  /// for more details.
+  @Deprecated('cloudMapId is deprecated. Use mapId instead')
  final String? cloudMapId;


Removing cloudMapId from the interface (as in the current version of the PR) is a breaking change, which isn't something we want. What I was suggesting was replacing the field with a getter that reads from mapId, as that preserves the public API without having two difference sources of truth.

packages/google_maps_flutter/google_maps_flutter_platform_interface/lib/src/types/bitmap.dart

...gle_maps_flutter_platform_interface/lib/src/types/utils/map_configuration_serialization.dart

stuartmorgan · 2025-01-08T18:41:46Z

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

@@ -28,14 +31,19 @@ import 'scrolling_map.dart';
 import 'snapshot.dart';
 import 'tile_overlay.dart';

+/// Map ID is required for some examples to use advanced markers.
+const String? _mapId = null;


I'm having trouble reconciling the comment and the line of code; if it's required for the examples, why is it null?

Is the idea that someone should put in their own map ID here and run the modified example? If so, the comment should be explicit about that.

Yes, the idea is that someone should put their own ID. I've updated the comment to

/// Place your map ID here. Map ID is required for pages that use advanced /// markers.

Hope it makes it clear what needs to be done and why.

stuartmorgan · 2025-01-08T18:44:27Z

packages/google_maps_flutter/google_maps_flutter/lib/src/google_map.dart

  final String? cloudMapId;

+  /// Indicates whether map should use [AdvancedMarker]s or [Marker]s.
+  final MarkerType markerType;


This still needs to be updated.

rajubhusani · 2025-01-11T00:45:29Z

I see Advanced merker icons are not rendering properly on the map.
Unhandled Exception: PlatformException(java.lang.IllegalArgumentException: Unable to interpret pin config as a valid image., IllegalArgumentException, Cause: java.lang.NullPointerException: null reference, Stacktrace: java.lang.IllegalArgumentException: Unable to interpret pin config as a valid image.

aednlaxer · 2025-01-13T09:50:16Z

@rajubhusani

I see Advanced merker icons are not rendering properly on the map. Unhandled Exception: PlatformException(java.lang.IllegalArgumentException: Unable to interpret pin config as a valid image., IllegalArgumentException, Cause: java.lang.NullPointerException: null reference, Stacktrace: java.lang.IllegalArgumentException: Unable to interpret pin config as a valid image.

Hi, thanks for checking it out. Could please provide more details?

Did you use one of the new examples from this PR? Which one?
Did you add your API key and map ID before running the app?
Did you build your own sample to test advanced markers? Can you share it or provide code that could help reproducing the issue?
What kind of image do you use? Would it be possible to test if this image works with legacy (non-advanced) markers?
Did you stop the Android app before running the code? Running app should be stopped and started again after checking out this PR's code. The reason is the platform-specific code that won't work using Flutter's hot-restart and should only work if native (Android) app is restarted.

ditman

Hey, thanks for the code! I took a quick look at the core plugin, the platform interface, but specially the web implementation.

Most of the stuff is stylistic choices, but I have a question:

Why do we even need the MarkerType when creating a Map? It seems that it can be inferred the first time a Marker is used, and the availability of Advanced Markers?

And an objection to the doXXXOnMarkerType pattern, which IMO should be proper inheritance (like you did on AdvancedMarker extends Marker).

Thanks for the PR, this is a highly requested feature!

ditman · 2025-01-16T22:23:50Z

packages/google_maps_flutter/google_maps_flutter/example/lib/advanced_marker_icons.dart

+  @override
+  Marker createMarker(


This is smart, and reduces code repetition, but I'm not sure people looking at an example will want to unravel this inheritance. This might be more useful for end users if there's a little bit of duplication across the examples?

I've updated all advanced examples not to do that, should be simpler now. Advanced marker icons example now shows several pin config variations

packages/google_maps_flutter/google_maps_flutter/example/lib/advanced_markers_clustering.dart

packages/google_maps_flutter/google_maps_flutter/example/lib/clustering.dart

ditman · 2025-01-16T22:32:38Z

packages/google_maps_flutter/google_maps_flutter/example/lib/clustering.dart

+          final Marker resetOld =
+              widget.copyWithSelectedStated(markers[previousMarkerId]!, false);


Instead of using !, I'd use an assert(marker != null, 'Some descriptive message'). Null assertion errors are quite cryptic (and more in the web, and even more in wasm :P), so I tend to avoid them if practical.

packages/google_maps_flutter/google_maps_flutter/example/lib/map_map_id.dart

packages/google_maps_flutter/google_maps_flutter_web/lib/src/marker.dart

packages/google_maps_flutter/google_maps_flutter_web/lib/src/marker_clustering.dart

packages/google_maps_flutter/google_maps_flutter_web/lib/src/marker_clustering_js_interop.dart

packages/google_maps_flutter/google_maps_flutter_web/lib/src/markers.dart

rajubhusani · 2025-01-17T10:19:50Z

@rajubhusani

I see Advanced merker icons are not rendering properly on the map. Unhandled Exception: PlatformException(java.lang.IllegalArgumentException: Unable to interpret pin config as a valid image., IllegalArgumentException, Cause: java.lang.NullPointerException: null reference, Stacktrace: java.lang.IllegalArgumentException: Unable to interpret pin config as a valid image.

Hi, thanks for checking it out. Could please provide more details?

Did you use one of the new examples from this PR? Which one?

Did you add your API key and map ID before running the app?

Did you build your own sample to test advanced markers? Can you share it or provide code that could help reproducing the issue?

What kind of image do you use? Would it be possible to test if this image works with legacy (non-advanced) markers?

Did you stop the Android app before running the code? Running app should be stopped and started again after checking out this PR's code. The reason is the platform-specific code that won't work using Flutter's hot-restart and should only work if native (Android) app is restarted.

@aednlaxer, Please find the responses,
I just cloned the code from your branch "CodemateLtd:feature/google-maps-advanced-markers-support". And directly ran the Android app from the google_maps_flutter_android/example project. I have not made any changes to that. I have used my own API key setup. All the options are working on the example except the Custom Marker & Cluster.

github-actions bot added p: google_maps_flutter platform-android platform-ios platform-web labels Oct 16, 2024

aednlaxer marked this pull request as ready for review October 21, 2024 07:12

aednlaxer requested review from cbracken, reidbaker, ditman and stuartmorgan as code owners October 21, 2024 07:13

reidbaker reviewed Oct 28, 2024

View reviewed changes

stuartmorgan added the triage-ios Should be looked at in iOS triage label Nov 21, 2024

stuartmorgan requested changes Nov 21, 2024

View reviewed changes

aednlaxer requested review from hellohuanlin, jmagman, tarrinneal, LouiseHsu, loic-sharma, bparrishMines, camsim99, matanlurey, gmackall, domesticmouse, yjbanov, jonahwilliams, Piinks, Hixie, gspencergoog, sokoloff06, chunhtai and goderbauer as code owners December 19, 2024 08:04

stuartmorgan added triage-android Should be looked at in Android triage triage-web Should be looked at in web triage labels Jan 7, 2025

stuartmorgan requested changes Jan 8, 2025

View reviewed changes

aednlaxer added 5 commits January 10, 2025 12:03

Tweak README content

2211ca6

Add cloudMapId getter

dd18653

Return false from isAdvancedMarkersAvailable

d7ad72a

Make AdvancedMarkerGlyph sealed

1fb2140

Revert cloudMapId serialization

7343ef9

Update mapId comment

40a7c75

ditman requested changes Jan 17, 2025

View reviewed changes

aednlaxer added 2 commits January 17, 2025 10:14

Fix method name typo

c15a5ea

Add GoogleMapMarkerType enum to the user-facing package

3fda55b

aednlaxer added 12 commits January 17, 2025 12:45

Fix test

f76e438

Use collection-if in advanced_marker.dart

7d15257

Use double-slash comments

08bfd5f

Use gmaps.Size instead of Size

ca6ccfe

Add advanced marker rotation

55a08fb

Use Object instead of dynamic

e12607c

Split controllers based on marker type

5a71e18

Use Object? instead of dynamic

adae844

Use _marker everywhere in MarkerController

5dadbb2

Get rid of _getOnMarkerType

4c51112

Make T extend JSObject

ea82733

Update advanced marker examples

c35eed5

aednlaxer requested review from ditman and stuartmorgan January 21, 2025 13:15

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[google_maps_flutter] Add Advanced Markers support #7882

[google_maps_flutter] Add Advanced Markers support #7882

aednlaxer commented Oct 16, 2024 •

edited

Loading

reidbaker left a comment

reidbaker Oct 28, 2024

aednlaxer Dec 20, 2024

reidbaker Oct 28, 2024

aednlaxer Dec 20, 2024

reidbaker Oct 28, 2024

aednlaxer Dec 20, 2024

reidbaker Oct 28, 2024

aednlaxer Dec 20, 2024

reidbaker Oct 28, 2024

stuartmorgan left a comment

stuartmorgan Nov 21, 2024

aednlaxer Dec 20, 2024

stuartmorgan Nov 21, 2024

aednlaxer Dec 20, 2024

stuartmorgan Jan 7, 2025

aednlaxer Jan 21, 2025

stuartmorgan commented Jan 7, 2025

stuartmorgan Jan 6, 2025

aednlaxer Jan 13, 2025

stuartmorgan Jan 6, 2025

stuartmorgan Jan 6, 2025

stuartmorgan Jan 7, 2025

stuartmorgan Jan 8, 2025

aednlaxer Jan 13, 2025

stuartmorgan Jan 8, 2025

rajubhusani commented Jan 11, 2025 •

edited

Loading

aednlaxer commented Jan 13, 2025 •

edited

Loading

ditman left a comment

ditman Jan 16, 2025

aednlaxer Jan 21, 2025

ditman Jan 16, 2025

rajubhusani commented Jan 17, 2025

		final Marker resetOld =
		widget.copyWithSelectedStated(markers[previousMarkerId]!, false);

[google_maps_flutter] Add Advanced Markers support #7882

Are you sure you want to change the base?

[google_maps_flutter] Add Advanced Markers support #7882

Conversation

aednlaxer commented Oct 16, 2024 • edited Loading

Pre-launch Checklist

reidbaker left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

stuartmorgan left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

stuartmorgan commented Jan 7, 2025

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

rajubhusani commented Jan 11, 2025 • edited Loading

aednlaxer commented Jan 13, 2025 • edited Loading

ditman left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

rajubhusani commented Jan 17, 2025

aednlaxer commented Oct 16, 2024 •

edited

Loading

rajubhusani commented Jan 11, 2025 •

edited

Loading

aednlaxer commented Jan 13, 2025 •

edited

Loading