chore(demo): add DemoApplication for API key/Map ID validation (#1600)

* chore(demo): add DemoApplication for API key/Map ID validation

Introduces a centralized mechanism to validate the Maps API key and configure a Map ID, which is required for features like Advanced Markers.

This change adds a new `DemoApplication` class that runs two checks on startup:
- `checkApiKey()`: Validates that a non-default API key is present in the manifest metadata.
- `getMapId()`: Retrieves a Map ID, prioritizing `secrets.properties` (via `BuildConfig`) and falling back to `strings.xml`.

`BaseDemoActivity` is refactored to:
- Get the Map ID from `DemoApplication`.
- Programmatically create the `SupportMapFragment` using `GoogleMapOptions` to apply the `mapId`.

This replaces the previous method of inflating the map from an XML layout, which didn't allow for easy programmatic Map ID configuration.

Documentation in `README.md` is updated to reflect the new configuration options for setting the Map ID.

* chore: add missing header

* chore(demo): Initialize map fragment when map ID is null

Allows the demo application to run even when a map ID is not provided by instantiating the `SupportMapFragment` without `GoogleMapOptions`.

* chore: Reorder string resource to put map_id as last item

* chore: Adds a link to the map id documentation.

* docs: address review comment

Author: dkhawk

README.md

@@ -65,6 +65,27 @@ To run the demo app, ensure you've met the requirements above then:
 1. Add a single line to `local.properties` that looks like `MAPS_API_KEY=YOUR_API_KEY`, where `YOUR_API_KEY` is the API key you obtained earlier
 1. Build and run the `debug` variant for the Maps SDK for Android version
 
+### Setting up the Map ID
+
+Some of the features in the demo app, such as Advanced Markers, require a Map ID. You can learn more about map IDs in the [official documentation](https://developers.google.com/maps/documentation/android-sdk/map-ids/mapid-over). You can set the Map ID in one of the following ways:
+
+1.  **`secrets.properties`:** Add a line to your `secrets.properties` file with your Map ID:
+    ```
+    MAP_ID=YOUR_MAP_ID
+    ```
+
+2.  **`strings.xml`:** Alternatively, you can set the Map ID in the `demo/src/main/res/values/strings.xml` file:
+    ```xml
+    <string name="map_id">YOUR_MAP_ID</string>
+    ```
+
+3.  **XML Layout Files:** You can also hardcode the Map ID directly in the XML layout files where a map is defined, by setting the `map:mapId` attribute:
+    ```xml
+    <androidx.fragment.app.FragmentContainerView
+        map:mapId="YOUR_MAP_ID" 
+        />
+    ```
+
 ## Documentation
 
 See the [documentation] for a full list of classes and their methods.
@@ -74,6 +95,7 @@ Full guides for using the utilities are published in
 
 ## Usage
 
+<details>
   <summary>Marker utilities</summary>
 
 ### Marker utilities
@@ -82,7 +104,6 @@ Full guides for using the utilities are published in
 - Marker clustering [source](https://github.com/googlemaps/android-maps-utils/tree/main/library/src/main/java/com/google/maps/android/clustering), [guide](https://developers.google.com/maps/documentation/android-sdk/utility/marker-clustering)
 - Advanced Markers clustering [source](https://github.com/googlemaps/android-maps-utils/tree/main/library/src/main/java/com/google/maps/android/clustering), [sample code](https://github.com/googlemaps/android-maps-utils/blob/main/demo/src/main/java/com/google/maps/android/utils/demo/CustomAdvancedMarkerClusteringDemoActivity.java)
 - Marker icons [source](https://github.com/googlemaps/android-maps-utils/blob/main/library/src/main/java/com/google/maps/android/ui/IconGenerator.java), [sample code](https://github.com/googlemaps/android-maps-utils/blob/main/demo/src/main/java/com/google/maps/android/utils/demo/IconGeneratorDemoActivity.java)
-
 </details>
 
 <details>

demo/src/main/AndroidManifest.xml

@@ -35,6 +35,7 @@
         android:required="true" />
 
     <application
+        android:name=".DemoApplication"
         android:allowBackup="false"
         android:icon="@drawable/ic_launcher"
         android:label="@string/app_name"

demo/src/main/java/com/google/maps/android/utils/demo/BaseDemoActivity.java

@@ -26,11 +26,10 @@
 import androidx.fragment.app.FragmentActivity;
 
 import com.google.android.gms.maps.GoogleMap;
+import com.google.android.gms.maps.GoogleMapOptions;
 import com.google.android.gms.maps.OnMapReadyCallback;
 import com.google.android.gms.maps.SupportMapFragment;
 
-import java.util.Objects;
-
 import androidx.core.graphics.Insets;
 import androidx.core.view.ViewCompat;
 import androidx.core.view.WindowCompat;
@@ -79,7 +78,7 @@ public void onCreate(Bundle savedInstanceState) {
             // Return CONSUMED to signal that we've handled the insets.
             return WindowInsetsCompat.CONSUMED;
         });
-        setUpMap();
+        setUpMap(savedInstanceState);
     }
 
     @Override
@@ -91,8 +90,37 @@ public void onMapReady(@NonNull GoogleMap map) {
         startDemo(mIsRestore);
     }
 
-    private void setUpMap() {
-        ((SupportMapFragment) Objects.requireNonNull(getSupportFragmentManager().findFragmentById(R.id.map))).getMapAsync(this);
+    private void setUpMap(Bundle savedInstanceState) {
+        // 1. Get the Application instance and cast it
+        DemoApplication app = (DemoApplication) getApplication();
+
+        // 2. Call the getMapId() method
+        String mapId = app.getMapId();
+
+        // Create a new SupportMapFragment instance
+        SupportMapFragment mapFragment;
+
+        if (mapId == null) {
+            mapFragment = SupportMapFragment.newInstance();
+        } else {
+            // Create the map options
+            GoogleMapOptions mapOptions = new GoogleMapOptions();
+            mapOptions.mapId(mapId);
+            // Create a new SupportMapFragment instance
+            mapFragment = SupportMapFragment.newInstance(mapOptions);
+        }
+
+        // Add the fragment to the container (R.id.map)
+        // Check savedInstanceState to prevent re-adding on rotation
+        if (savedInstanceState == null) {
+            getSupportFragmentManager()
+                    .beginTransaction()
+                    .add(R.id.map, mapFragment)
+                    .commit();
+        }
+
+        // Get the map
+        mapFragment.getMapAsync(this);
     }
 
     /**

demo/src/main/java/com/google/maps/android/utils/demo/CustomAdvancedMarkerClusteringDemoActivity.java

@@ -78,21 +78,22 @@ public AdvancedMarkerRenderer() {
         protected void onBeforeClusterItemRendered(@NonNull Person person,
                                                    @NonNull AdvancedMarkerOptions markerOptions) {
             markerOptions
-                    .icon(BitmapDescriptorFactory.fromPinConfig(getPinConfig().build()))
+                    .icon(BitmapDescriptorFactory.fromPinConfig(getPinConfig(person).build()))
                     .title(person.name);
         }
 
         @Override
         protected void onClusterItemUpdated(@NonNull Person person, @NonNull Marker marker) {
             // Same implementation as onBeforeClusterItemRendered() (to update cached markers)
-            marker.setIcon(BitmapDescriptorFactory.fromPinConfig(getPinConfig().build()));
+            marker.setIcon(BitmapDescriptorFactory.fromPinConfig(getPinConfig(person).build()));
             marker.setTitle(person.name);
         }
 
-        private PinConfig.Builder getPinConfig() {
+        private PinConfig.Builder getPinConfig(Person person) {
             PinConfig.Builder pinConfigBuilder = PinConfig.builder();
             pinConfigBuilder.setBackgroundColor(Color.MAGENTA);
             pinConfigBuilder.setBorderColor(getResources().getColor(R.color.colorPrimaryDark));
+            pinConfigBuilder.setGlyph(new PinConfig.Glyph(BitmapDescriptorFactory.fromResource(person.profilePhoto)));
             return pinConfigBuilder;
         }
 

demo/src/main/java/com/google/maps/android/utils/demo/DemoApplication.java

@@ -0,0 +1,100 @@
+/*
+ * Copyright 2025 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.google.maps.android.utils.demo;
+
+import android.app.Application;
+import android.util.Log;
+import android.content.pm.ApplicationInfo;
+import android.content.pm.PackageManager;
+import android.os.Bundle;
+import android.widget.Toast;
+import androidx.annotation.Nullable;
+import java.util.Objects;
+
+/**
+ * {@code DemoApplication} is a custom Application class for the API demo.
+ *
+ * <p>This class is responsible for application-wide initialization and setup,
+ * such as checking for the presence and validity of the API key during the
+ * application's startup.</p>
+ *
+ * <p>It extends the {@link Application} class and overrides the {@link #onCreate()}
+ * method to perform these initialization tasks.</p>
+ */
+public class DemoApplication extends Application {
+    private static final String TAG = "DemoApplication";
+    private boolean mapIdSet = false;
+    private String mapId = null;
+
+    @Override
+    public void onCreate() {
+        super.onCreate();
+        checkApiKey();
+    }
+
+    /**
+     * Checks if the API key for Google Maps is properly configured in the application's metadata.
+     * <p>
+     * This method retrieves the API key from the application's metadata, specifically looking for
+     * a string value associated with the key "com.google.android.geo.API_KEY".
+     * The key must be present, not blank, and not set to the placeholder value "DEFAULT_API_KEY".
+     * <p>
+     * If any of these checks fail, a Toast message is displayed indicating that the API key is missing or
+     * incorrectly configured, and a RuntimeException is thrown.
+     * <p>
+     */
+    private void checkApiKey() {
+        try {
+            ApplicationInfo appInfo = getPackageManager().getApplicationInfo(getPackageName(), PackageManager.GET_META_DATA);
+            Bundle bundle = Objects.requireNonNull(appInfo.metaData);
+
+            String apiKey = bundle.getString("com.google.android.geo.API_KEY"); // Key name is important!
+
+            if (apiKey == null || apiKey.isBlank() || apiKey.equals("DEFAULT_API_KEY")) {
+                Toast.makeText(this, "API Key was not set in secrets.properties", Toast.LENGTH_LONG).show();
+                throw new RuntimeException("API Key was not set in secrets.properties");
+            }
+        } catch (PackageManager.NameNotFoundException e) {
+            Log.e(TAG, "Package name not found.", e);
+            throw new RuntimeException("Error getting package info.", e);
+        } catch (NullPointerException e) {
+            Log.e(TAG, "Error accessing meta-data.", e); // Handle the case where meta-data is completely missing.
+            throw new RuntimeException("Error accessing meta-data in manifest", e);
+        }
+    }
+
+    /**
+     * Retrieves the map ID from the BuildConfig or string resource.
+     *
+     * @return The valid map ID or null if no valid map ID is found.
+     */
+    @Nullable
+    public String getMapId() {
+        if (!mapIdSet) {
+            if (!BuildConfig.MAP_ID.equals("MAP_ID")) {
+                mapId = BuildConfig.MAP_ID;
+            } else if (!getString(R.string.map_id).equals("DEMO_MAP_ID")) {
+                mapId = getString(R.string.map_id);
+            } else {
+                Log.w(TAG, "Map ID is not set. See README for instructions.");
+                Toast.makeText(this, "Map ID is not set. Some features may not work. See README for instructions.", Toast.LENGTH_LONG).show();
+            }
+            mapIdSet = true;
+        }
+        return mapId;
+    }
+}

demo/src/main/res/layout/activity_cluster_algorithms_demo.xml

@@ -20,7 +20,7 @@
     android:layout_height="match_parent">
 
     <!-- Map Fragment -->
-    <androidx.fragment.app.FragmentContainerView xmlns:android="http://schemas.android.com/apk/res/android"
+    <androidx.fragment.app.FragmentContainerView
         xmlns:map="http://schemas.android.com/apk/res-auto"
         android:id="@+id/map"
         android:name="com.google.android.gms.maps.SupportMapFragment"

demo/src/main/res/values/strings.xml

@@ -35,4 +35,7 @@
     <string name="button_opacity">Opacity</string>
     <string name="bad_maps_api_key">The Google Maps API key looks invalid or is missing. If you are sure your key is correct, you can remove this check from the demo.</string>
     <string name="percentage_format">%1$d%%</string>
+
+    <!-- This should be set here or in secrets.properties. -->
+    <string name="map_id">DEMO_MAP_ID</string>
 </resources>

local.defaults.properties

@@ -1,2 +1,3 @@
 MAPS_API_KEY=YOUR_API_KEY
 PLACES_API_KEY=YOUR_API_KEY
+MAP_ID=MAP_ID