feat: Improve GoogleMapsInitializer error handling and retries (#778)

* fix: Improve GoogleMapsInitializer error handling and allow retries

Refactored the error handling within `GoogleMapsInitializer` to make it more robust against initialization failures.

Previously, any exception during the `initialize` call would permanently set the state to `FAILURE`, preventing any subsequent attempts.

This change introduces more granular error handling:
- Unrecoverable errors, such as `GooglePlayServicesMissingManifestValueException`, will correctly set the state to `FAILURE`.
- Other exceptions, which may be transient, will now reset the state to `UNINITIALIZED`, allowing the initialization to be attempted again.

Additionally, a `forceInitialization` parameter has been added to the `initialize` function to allow bypassing the initial state check for re-initialization scenarios.

* feat: More improvements to GoogleMapsInitializer

Introduced a new `preferredRenderer` parameter to the `initialize` function.

Key changes:
- The `initialize` function now accepts a `preferredRenderer` to specify which Maps renderer to use.
- The `try-catch` block within the `initialize` function has been refactored to be more idiomatic.

The `AdvancedMarkersActivity` example has been updated to use this improved initializer. It now calls `GoogleMapsInitializer.initialize` within a `LaunchedEffect`, making the initialization asynchronous and tied to the composable's lifecycle.

* refactor: Remove preferredRenderer from Maps initialization

The `preferredRenderer` parameter has been removed from the `GoogleMapsInitializer.initialize()` function. The Maps SDK for Android now automatically selects the latest available renderer, making this parameter redundant.

This change simplifies the initialization API. The explicit initialization call in the `AdvancedMarkersActivity` sample has also been removed to reflect this simplification.

* feat(maps-compose): Introduce interface-based GoogleMapsInitializer

This commit refactors the `GoogleMapsInitializer` from a static object to an interface-based dependency provided via a `CompositionLocal`.

This architectural change offers several key benefits:
- **Improved Testability:** The initialization logic can now be easily mocked and tested in isolation, as demonstrated by the new unit tests using `mockk`.
- **Dependency Injection:** It aligns with modern dependency injection principles, making the `GoogleMap` composable more configurable and less reliant on a global singleton.
- **Robustness:** The error handling has been made more granular, distinguishing between unrecoverable manifest errors and transient, recoverable issues.

The new `DefaultGoogleMapsInitializer` provides the concrete implementation, ensuring backward compatibility for existing usages while enabling advanced testing and customization scenarios.

Author: dkhawk

gradle/libs.versions.toml

@@ -4,7 +4,7 @@ agp = "8.13.0"
 androidCore = "1.7.0"
 androidx-core = "1.17.0"
 androidxtest = "1.7.0"
-compose-bom = "2025.08.01"
+compose-bom = "2025.09.01"
 dokka = "2.0.0"
 espresso = "3.7.0"
 gradleMavenPublishPlugin = "0.34.0"
@@ -16,7 +16,10 @@ kotlinxCoroutines = "1.10.2"
 leakcanaryAndroid = "2.14"
 mapsecrets = "2.0.1"
 mapsktx = "5.2.0"
-material3 = "1.3.2"
+material3 = "1.4.0"
+materialIconsExtendedAndroid = "1.7.8"
+mockk = "1.14.5"
+mockkAndroid = "1.14.5"
 org-jacoco-core = "0.8.13"
 screenshot = "0.0.1-alpha11"
 constraintlayout = "2.2.1"
@@ -30,6 +33,7 @@ androidx-compose-activity = { module = "androidx.activity:activity-compose", ver
 androidx-compose-bom = { module = "androidx.compose:compose-bom", version.ref = "compose-bom" }
 androidx-compose-foundation = { module = "androidx.compose.foundation:foundation" }
 androidx-compose-material = { module = "androidx.compose.material:material" }
+androidx-compose-material-icons-extended-android = { module = "androidx.compose.material:material-icons-extended-android", version.ref = "materialIconsExtendedAndroid" }
 androidx-compose-material3 = { module = "androidx.compose.material3:material3", version.ref = "material3" }
 androidx-compose-ui = { module = "androidx.compose.ui:ui" }
 androidx-compose-ui-preview-tooling = { module = "androidx.compose.ui:ui-tooling-preview" }
@@ -52,6 +56,8 @@ leakcanary-android = { module = "com.squareup.leakcanary:leakcanary-android", ve
 maps-ktx-std = { module = "com.google.maps.android:maps-ktx", version.ref = "mapsktx" }
 maps-ktx-utils = { module = "com.google.maps.android:maps-utils-ktx", version.ref = "mapsktx" }
 maps-secrets-plugin = { module = "com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin", version.ref = "mapsecrets" }
+mockk = { module = "io.mockk:mockk", version.ref = "mockk" }
+mockk-android = { module = "io.mockk:mockk-android", version.ref = "mockkAndroid" }
 org-jacoco-core = { module = "org.jacoco:org.jacoco.core", version.ref = "org-jacoco-core" }
 test-junit = { module = "junit:junit", version.ref = "junit" }
 androidx-constraintlayout = { group = "androidx.constraintlayout", name = "constraintlayout", version.ref = "constraintlayout" }

maps-app/build.gradle.kts

@@ -45,7 +45,6 @@ android {
         compose = true
     }
 
-
     kotlin {
         compilerOptions {
             jvmTarget.set(JvmTarget.JVM_1_8)
@@ -75,6 +74,8 @@ dependencies {
     implementation(libs.androidx.compose.ui.preview.tooling)
     implementation(libs.androidx.constraintlayout)
     implementation(libs.material)
+    implementation(libs.androidx.compose.material.icons.extended.android)
+
     implementation(libs.screenshot.validation.api)
     debugImplementation(libs.androidx.compose.ui.tooling)
     debugImplementation(libs.leakcanary.android)
@@ -103,6 +104,10 @@ dependencies {
     implementation(project(":maps-compose"))
     implementation(project(":maps-compose-widgets"))
     implementation(project(":maps-compose-utils"))
+
+    testImplementation(libs.mockk)
+    testImplementation(libs.mockk.android)
+    testImplementation(kotlin("test"))
 }
 
 secrets {

maps-app/src/androidTest/java/com/google/maps/android/compose/GoogleMapViewTests.kt

@@ -17,7 +17,7 @@ package com.google.maps.android.compose
 import android.content.Context
 import androidx.compose.foundation.layout.Box
 import androidx.compose.foundation.layout.fillMaxSize
-import androidx.compose.material.Text
+import androidx.compose.material3.Text
 import androidx.compose.runtime.Composable
 import androidx.compose.runtime.mutableStateOf
 import androidx.compose.ui.Modifier
@@ -31,7 +31,7 @@ import com.google.android.gms.maps.model.CameraPosition
 import com.google.android.gms.maps.model.LatLng
 import com.google.common.truth.Truth.assertThat
 import com.google.maps.android.compose.LatLngSubject.Companion.assertThat
-import com.google.maps.android.compose.internal.GoogleMapsInitializer
+import com.google.maps.android.compose.internal.DefaultGoogleMapsInitializer
 import com.google.maps.android.compose.internal.InitializationState
 import kotlinx.coroutines.runBlocking
 import org.junit.Before
@@ -54,12 +54,13 @@ class GoogleMapViewTests {
         val countDownLatch = CountDownLatch(1)
 
         val appContext: Context = InstrumentationRegistry.getInstrumentation().targetContext
+        val googleMapsInitializer = DefaultGoogleMapsInitializer()
 
         runBlocking {
-            GoogleMapsInitializer.initialize(appContext)
+            googleMapsInitializer.initialize(appContext)
         }
 
-        assertThat(GoogleMapsInitializer.state.value).isEqualTo(InitializationState.SUCCESS)
+        assertThat(googleMapsInitializer.state.value).isEqualTo(InitializationState.SUCCESS)
 
         composeTestRule.setContent {
             GoogleMapView(

…oid/compose/GoogleMapsInitializerTest.kt …se/internal/GoogleMapsInitializerTest.ktmaps-app/src/androidTest/java/com/google/maps/android/compose/GoogleMapsInitializerTest.kt renamed to maps-app/src/androidTest/java/com/google/maps/android/compose/internal/GoogleMapsInitializerTest.kt maps-app/src/androidTest/java/com/google/maps/android/compose/GoogleMapsInitializerTest.kt renamed to maps-app/src/androidTest/java/com/google/maps/android/compose/internal/GoogleMapsInitializerTest.kt

@@ -11,28 +11,31 @@
 // 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.compose
+package com.google.maps.android.compose.internal
 
 import android.content.Context
 import android.os.StrictMode
 import androidx.test.ext.junit.runners.AndroidJUnit4
 import androidx.test.platform.app.InstrumentationRegistry
 import com.google.common.truth.Truth.assertThat
-import com.google.maps.android.compose.internal.GoogleMapsInitializer
-import com.google.maps.android.compose.internal.InitializationState
 import kotlinx.coroutines.ExperimentalCoroutinesApi
+import kotlinx.coroutines.delay
+import kotlinx.coroutines.launch
 import kotlinx.coroutines.test.runTest
 import org.junit.After
 import org.junit.Test
 import org.junit.runner.RunWith
+import kotlin.time.Duration.Companion.milliseconds
 
 @OptIn(ExperimentalCoroutinesApi::class)
 @RunWith(AndroidJUnit4::class)
 class GoogleMapsInitializerTest {
 
+    private val googleMapsInitializer = DefaultGoogleMapsInitializer()
+
     @After
     fun tearDown() = runTest {
-        GoogleMapsInitializer.reset()
+        googleMapsInitializer.reset()
     }
 
     @Test
@@ -64,11 +67,56 @@ class GoogleMapsInitializerTest {
                 .build()
         )
 
-        GoogleMapsInitializer.initialize(context)
+        googleMapsInitializer.initialize(context)
+
+        StrictMode.setThreadPolicy(threadPolicy)
+        StrictMode.setVmPolicy(vmPolicy)
+
+        assertThat(googleMapsInitializer.state.value).isEqualTo(InitializationState.SUCCESS)
+    }
+
+    @Test
+    fun testInitializationCancellationLeavesStateUninitialized() = runTest {
+        // In an instrumentation test environment, Google Play services are available.
+        // Therefore, we expect the initialization to succeed.
+
+        val context: Context = InstrumentationRegistry.getInstrumentation().targetContext
+
+        // Note: we need to establish the Strict Mode settings here as there are violations outside
+        // of our control if we try to set them in setUp
+        val threadPolicy = StrictMode.getThreadPolicy()
+        val vmPolicy = StrictMode.getVmPolicy()
+
+        StrictMode.setThreadPolicy(
+            StrictMode.ThreadPolicy.Builder()
+                .detectDiskReads()
+                .detectAll()
+                .penaltyLog()
+                .penaltyDeath()
+                .build()
+        )
+        StrictMode.setVmPolicy(
+            StrictMode.VmPolicy.Builder()
+                .detectAll()
+                .detectLeakedClosableObjects()
+                .penaltyLog()
+                .penaltyDeath()
+                .build()
+        )
+
+        val job = launch {
+            googleMapsInitializer.reset()
+            googleMapsInitializer.initialize(context)
+        }
+
+        // Allow the initialization coroutine to start before we cancel it.
+        delay(1.milliseconds)
+        job.cancel()
+        job.join()
 
         StrictMode.setThreadPolicy(threadPolicy)
         StrictMode.setVmPolicy(vmPolicy)
 
-        assertThat(GoogleMapsInitializer.state.value).isEqualTo(InitializationState.SUCCESS)
+        assertThat(googleMapsInitializer.state.value).isEqualTo(InitializationState.UNINITIALIZED)
     }
 }

maps-app/src/main/java/com/google/maps/android/compose/markerexamples/AdvancedMarkersActivity.kt

@@ -62,7 +62,6 @@ class AdvancedMarkersActivity : ComponentActivity(), OnMapsSdkInitializedCallbac
     @SuppressLint("SetTextI18n")
     override fun onCreate(savedInstanceState: Bundle?) {
         super.onCreate(savedInstanceState)
-        MapsInitializer.initialize(applicationContext, MapsInitializer.Renderer.LATEST, this)
         enableEdgeToEdge()
         setContent {
             // Observing and controlling the camera's state can be done with a CameraPositionState

maps-app/src/test/java/com/google/maps/android/compose/GoogleMapsInitializerTest.kt

@@ -0,0 +1,122 @@
+// 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.compose.internal
+
+import android.content.Context
+import com.google.android.gms.common.ConnectionResult
+import com.google.android.gms.common.GooglePlayServicesMissingManifestValueException
+import com.google.android.gms.maps.MapsInitializer
+import com.google.android.gms.maps.MapsApiSettings
+import io.mockk.every
+import io.mockk.mockk
+import io.mockk.mockkStatic
+import io.mockk.verify
+import kotlinx.coroutines.ExperimentalCoroutinesApi
+import kotlinx.coroutines.launch
+import kotlinx.coroutines.test.TestDispatcher
+import kotlinx.coroutines.test.UnconfinedTestDispatcher
+import kotlinx.coroutines.test.runTest
+import org.junit.Assert.assertEquals
+import org.junit.Before
+import org.junit.Test
+import kotlin.test.assertFailsWith
+
+@OptIn(ExperimentalCoroutinesApi::class)
+class GoogleMapsInitializerTest {
+
+    private val mockContext: Context = mockk(relaxed = true)
+    private lateinit var testDispatcher: TestDispatcher
+    private lateinit var googleMapsInitializer: GoogleMapsInitializer
+
+    @Before
+    fun setUp() {
+        // Mock the static methods we depend on
+        mockkStatic(MapsInitializer::class)
+        mockkStatic(MapsApiSettings::class)
+
+        // Default happy path behavior for mocks
+        every { MapsInitializer.initialize(any()) } returns ConnectionResult.SUCCESS
+        every { MapsApiSettings.addInternalUsageAttributionId(any(), any()) } returns Unit
+
+        testDispatcher = UnconfinedTestDispatcher()
+        googleMapsInitializer = DefaultGoogleMapsInitializer(testDispatcher)
+    }
+
+    @Test
+    fun `initialize - when coroutine is cancelled - state resets to UNINITIALIZED`() = runTest {
+        val job = launch {
+            googleMapsInitializer.initialize(mockContext)
+        }
+        job.cancel()
+        assertEquals(InitializationState.UNINITIALIZED, googleMapsInitializer.state.value)
+    }
+
+    @Test
+    fun `initialize - on first call - successfully initializes and state becomes SUCCESS`() = runTest {
+        // Arrange
+        assertEquals(InitializationState.UNINITIALIZED, googleMapsInitializer.state.value)
+
+        // Act
+        googleMapsInitializer.initialize(mockContext)
+
+        // Assert
+        assertEquals(InitializationState.SUCCESS, googleMapsInitializer.state.value)
+        verify(exactly = 1) { MapsInitializer.initialize(mockContext) }
+        verify(exactly = 1) { MapsApiSettings.addInternalUsageAttributionId(any(), any()) }
+    }
+
+    @Test
+    fun `initialize - when called concurrently - initialization only runs once`() = runTest {
+        // Act: Launch two calls concurrently
+        val job1 = launch { googleMapsInitializer.initialize(mockContext) }
+        val job2 = launch { googleMapsInitializer.initialize(mockContext) }
+
+        job1.join()
+        job2.join()
+
+        // Assert: The actual initialization method should only have been called once
+        // thanks to the mutex and double-check logic.
+        verify(exactly = 1) { MapsInitializer.initialize(mockContext) }
+        assertEquals(InitializationState.SUCCESS, googleMapsInitializer.state.value)
+    }
+
+    @Test
+    fun `initialize - on unrecoverable failure - state becomes FAILURE`() = runTest {
+        // Arrange
+        val error = GooglePlayServicesMissingManifestValueException()
+        every { MapsInitializer.initialize(any()) } throws error
+
+        // Act
+        assertFailsWith<GooglePlayServicesMissingManifestValueException> {
+            googleMapsInitializer.initialize(mockContext)
+        }
+
+        // Assert: The state should be FAILURE and the exception should be re-thrown
+        assertEquals(InitializationState.FAILURE, googleMapsInitializer.state.value)
+    }
+
+    @Test
+    fun `initialize - on recoverable failure - state resets to UNINITIALIZED and exception is thrown`() = runTest {
+        // Arrange
+        val error = RuntimeException("A network error occurred!")
+        every { MapsInitializer.initialize(any()) } throws error
+
+        // Act & Assert
+        assertFailsWith<RuntimeException> {
+            googleMapsInitializer.initialize(mockContext)
+        }
+        assertEquals(InitializationState.UNINITIALIZED, googleMapsInitializer.state.value)
+    }
+}