feat: Introduce a robust Google Maps initializer

This commit refactors the map initialization logic to be more robust and
test-friendly.

Previously, the map initialization was coupled with the attribution ID
logic, which made it difficult to handle initialization failures,
especially in test environments where the Maps SDK might be mocked.

This change introduces a new `GoogleMapsInitializer` object that manages
the initialization process with a state machine. This provides more
control over the initialization process and allows for better error
handling.

The key changes are:

- A new `GoogleMapsInitializer` object that manages the initialization
  of the Google Maps SDK.
- An `InitializationState` enum that represents the different states of
  the initialization process.
- An `initialize` function that starts the initialization process on a
  background thread.
- A `reset` function that allows for re-initialization in test
  environments.
- The `GoogleMap` composable now uses the `GoogleMapsInitializer` to
  ensure that the map is only displayed after the SDK has been
  successfully initialized.

Author: dkhawk

gradle/libs.versions.toml

@@ -20,6 +20,8 @@ org-jacoco-core = "0.8.13"
 screenshot = "0.0.1-alpha11"
 constraintlayout = "2.2.1"
 material = "1.12.0"
+robolectric = "4.12.1"
+truth = "1.1.3"
 
 [libraries]
 android-gradle-plugin = { module = "com.android.tools.build:gradle", version.ref = "agp" }
@@ -53,6 +55,8 @@ test-junit = { module = "junit:junit", version.ref = "junit" }
 androidx-constraintlayout = { group = "androidx.constraintlayout", name = "constraintlayout", version.ref = "constraintlayout" }
 material = { group = "com.google.android.material", name = "material", version.ref = "material" }
 screenshot-validation-api = { group = "com.android.tools.screenshot", name = "screenshot-validation-api", version.ref = "screenshot" }
+robolectric = { module = "org.robolectric:robolectric", version.ref = "robolectric" }
+truth = { module = "com.google.truth:truth", version.ref = "truth" }
 
 [plugins]
 android-application = { id = "com.android.application", version.ref = "agp" }

maps-app/build.gradle.kts

@@ -81,6 +81,12 @@ dependencies {
     androidTestImplementation(libs.test.junit)
     androidTestImplementation(libs.androidx.test.compose.ui)
     androidTestImplementation(libs.kotlinx.coroutines.test)
+    androidTestImplementation(libs.truth)
+
+    testImplementation(libs.test.junit)
+    testImplementation(libs.robolectric)
+    testImplementation(libs.androidx.test.core)
+    testImplementation(libs.truth)
 
     screenshotTestImplementation(libs.androidx.compose.ui.tooling)
 

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

@@ -85,7 +85,7 @@ class GoogleMapViewTests {
     }
 
     @Test
-    fun testRighColorSchemeAfterChangingIt() {
+    fun testRightColorSchemeAfterChangingIt() {
         mapColorScheme = ComposeMapColorScheme.DARK
         initMap()
         mapColorScheme.assertEquals(ComposeMapColorScheme.DARK)

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

@@ -0,0 +1,48 @@
+// Copyright 2024 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
+
+import android.content.Context
+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 org.junit.After
+import org.junit.Test
+import org.junit.runner.RunWith
+
+@RunWith(AndroidJUnit4::class)
+class GoogleMapsInitializerTest {
+
+    @After
+    fun tearDown() {
+        GoogleMapsInitializer.reset()
+    }
+
+    @Test
+    fun testInitializationSuccess() {
+        // In an instrumentation test environment, Google Play services are available.
+        // Therefore, we expect the initialization to succeed.
+        val context: Context = InstrumentationRegistry.getInstrumentation().targetContext
+
+        GoogleMapsInitializer.initialize(context)
+
+        // Wait for the initialization to complete
+        Thread.sleep(1000)
+
+        assertThat(GoogleMapsInitializer.state.value).isEqualTo(InitializationState.SUCCESS)
+    }
+}

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

@@ -0,0 +1,48 @@
+// Copyright 2024 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
+
+import android.content.Context
+import androidx.test.core.app.ApplicationProvider
+import com.google.common.truth.Truth.assertThat
+import com.google.maps.android.compose.internal.GoogleMapsInitializer
+import com.google.maps.android.compose.internal.InitializationState
+import org.junit.After
+import org.junit.Test
+import org.junit.runner.RunWith
+import org.robolectric.RobolectricTestRunner
+
+@RunWith(RobolectricTestRunner::class)
+class GoogleMapsInitializerTest {
+
+    @After
+    fun tearDown() {
+        GoogleMapsInitializer.reset()
+    }
+
+    @Test
+    fun testInitializationFailure() {
+        // In a unit test environment, Google Play services are not available.
+        // Therefore, we expect the initialization to fail.
+        val context: Context = ApplicationProvider.getApplicationContext()
+
+        GoogleMapsInitializer.initialize(context)
+
+        // Wait for the initialization to complete
+        Thread.sleep(1000)
+
+        assertThat(GoogleMapsInitializer.state.value).isEqualTo(InitializationState.FAILURE)
+    }
+}

maps-compose/src/main/java/com/google/maps/android/compose/GoogleMap.kt

@@ -50,7 +50,8 @@ import com.google.android.gms.maps.MapView
 import com.google.android.gms.maps.model.LatLng
 import com.google.android.gms.maps.model.MapColorScheme
 import com.google.android.gms.maps.model.PointOfInterest
-import com.google.maps.android.compose.internal.MapsApiAttribution
+import com.google.maps.android.compose.internal.GoogleMapsInitializer
+import com.google.maps.android.compose.internal.InitializationState
 import com.google.maps.android.ktx.awaitMap
 import kotlinx.coroutines.CoroutineScope
 import kotlinx.coroutines.CoroutineStart
@@ -113,16 +114,16 @@ public fun GoogleMap(
         return
     }
 
-    val isInitialized by MapsApiAttribution.isInitialized
+    val initializationState by GoogleMapsInitializer.state
 
-    if (!isInitialized) {
+    if (initializationState != InitializationState.SUCCESS) {
         val context = LocalContext.current
         LaunchedEffect(Unit) {
-            MapsApiAttribution.addAttributionId(context)
+            GoogleMapsInitializer.initialize(context)
         }
     }
 
-    if (isInitialized) {
+    if (initializationState == InitializationState.SUCCESS) {
         // rememberUpdatedState and friends are used here to make these values observable to
         // the subcomposition without providing a new content function each recomposition
         val mapClickListeners = remember { MapClickListeners() }.also {

maps-compose/src/main/java/com/google/maps/android/compose/internal/GoogleMapsInitializer.kt

@@ -0,0 +1,121 @@
+package com.google.maps.android.compose.internal
+
+import android.content.Context
+import androidx.compose.runtime.State
+import androidx.compose.runtime.mutableStateOf
+import com.google.android.gms.common.ConnectionResult
+import com.google.android.gms.maps.MapsInitializer
+import com.google.android.gms.maps.MapsApiSettings
+import com.google.maps.android.compose.meta.AttributionId
+import kotlinx.coroutines.CoroutineScope
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.Job
+import kotlinx.coroutines.launch
+import kotlinx.coroutines.sync.Mutex
+import kotlinx.coroutines.sync.withLock
+
+/**
+ * Enum representing the initialization state of the Google Maps SDK.
+ */
+public enum class InitializationState {
+    /**
+     * The SDK has not been initialized.
+     */
+    UNINITIALIZED,
+
+    /**
+     * The SDK is currently being initialized.
+     */
+    INITIALIZING,
+
+    /**
+     * The SDK has been successfully initialized.
+     */
+    SUCCESS,
+
+    /**
+     * The SDK initialization failed.
+     */
+    FAILURE
+}
+
+/**
+ * A singleton object to manage the initialization of the Google Maps SDK.
+ *
+ * This object provides a state machine to track the initialization process and ensures that
+ * the initialization is performed only once. It also provides a mechanism to reset the
+ * initialization state, which can be useful in test environments.
+ *
+ * The initialization process consists of two main steps:
+ * 1. Calling `MapsInitializer.initialize(context)` to initialize the Google Maps SDK.
+ * 2. Calling `MapsApiSettings.addInternalUsageAttributionId(context, attributionId)` to add
+ *    the library's attribution ID to the Maps API settings.
+ *
+ * The state of the initialization is exposed via the `state` property, which is a [State] object
+ * that can be observed for changes.
+ */
+public object GoogleMapsInitializer {
+    private val _state = mutableStateOf(InitializationState.UNINITIALIZED)
+    public val state: State<InitializationState> = _state
+
+    private var initializationJob: Job? = null
+    private val mutex = Mutex()
+
+    /**
+     * The value of the attribution ID. Set this to the empty string to opt out of attribution.
+     *
+     * This must be set before calling the `initialize` function.
+     */
+    public var attributionId: String = AttributionId.VALUE
+
+    /**
+     * Initializes the Google Maps SDK.
+     *
+     * This function starts the initialization process on a background thread. The process is
+     * performed only once. If the initialization is already in progress or has completed,
+     * this function does nothing.
+     *
+     * The initialization state can be observed via the `state` property.
+     *
+     * @param context The context to use for initialization.
+     */
+    public fun initialize(context: Context) {
+        CoroutineScope(Dispatchers.IO).launch {
+            mutex.withLock {
+                if (_state.value != InitializationState.UNINITIALIZED) {
+                    return@withLock
+                }
+
+                _state.value = InitializationState.INITIALIZING
+                initializationJob = launch {
+                    try {
+                        if (MapsInitializer.initialize(context) == ConnectionResult.SUCCESS) {
+                            MapsApiSettings.addInternalUsageAttributionId(context, attributionId)
+                            _state.value = InitializationState.SUCCESS
+                        }
+                    } catch (e: Exception) {
+                        // In tests where the map is mocked, this can fail.
+                        _state.value = InitializationState.FAILURE
+                    }
+                }
+            }
+        }
+    }
+
+    /**
+     * Resets the initialization state.
+     *
+     * This function cancels any ongoing initialization and resets the state to `UNINITIALIZED`.
+     * This is useful in test environments where you might need to re-initialize the SDK
+     * multiple times.
+     */
+    public fun reset() {
+        CoroutineScope(Dispatchers.IO).launch {
+            mutex.withLock {
+                initializationJob?.cancel()
+                initializationJob = null
+                _state.value = InitializationState.UNINITIALIZED
+            }
+        }
+    }
+}