Docs / Setup / Android / Google Maps

Google Maps setup

How to drive the Google Maps SDK for Android through MapConductor — obtaining an API key, injecting it with the Secrets Gradle Plugin, and getting GoogleMapView on screen.

MODULE

com.mapconductor:for-googlemaps

API KEY

Required

VIEW

GoogleMapView

TIME

15 min

Same provider, other platformsiOS React

View demoStore Map · React ↗

Before you start

An Android development environment (Android Studio)

A Google Cloud Console account

Maps SDK for Android enabled on your Google Cloud project

STEP 01

Get an API key

Open the Google Cloud Console.
Create a project or select an existing one.
Enable the Maps SDK for Android API.
Create an API key under Credentials.
Restrict the key to your app's package name and SHA-1 certificate fingerprint.

Debug and release builds are signed with different certificates, so register both SHA-1 fingerprints.

STEP 02

Add the Secrets Gradle Plugin

This is how the key stays out of source control: the plugin reads secrets.properties and substitutes the value into the AndroidManifest.xml placeholder at build time.

(root)/build.gradle.ktsKotlin

plugins {
    id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin") version "2.0.1" apply false
}

STEP 03

Add the dependencies

Add the Google Maps SDK itself plus the MapConductor modules, and apply the Secrets plugin. The BOM pins every MapConductor module version at once.

app/build.gradle.ktsKotlin

plugins {
    // ... other plugins
    id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin")
}

dependencies {
    // Google Maps SDK
    implementation("com.google.android.gms:play-services-maps:20.0.0")

    // MapConductor BOM pins every module below
    implementation(platform("com.mapconductor:mapconductor-bom:1.2.0"))

    implementation("com.mapconductor:core")
    implementation("com.mapconductor:for-googlemaps")
    // Optional: compose / icons / heatmap / marker-clustering / geojson / kml
}

STEP 04

Wire the manifest and the key

The manifest only ever holds a placeholder; the real value lives in secrets.properties and is substituted at build time.

AndroidManifest.xmlXML

<manifest>
    <!-- Add location permissions -->
    <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />

    <application>
        <!-- Google Maps API Key -->
        <meta-data
            android:name="com.google.android.geo.API_KEY"
            android:value="${GOOGLE_MAPS_API_KEY}" />
    </application>
</manifest>

secrets.propertiesProperties

GOOGLE_MAPS_API_KEY=your_actual_api_key

The ACCESS_*_LOCATION permissions are only needed if your app uses location. Fetching tiles needs INTERNET alone.

CAUTION

Never commit secrets.properties. Add it to .gitignore so it cannot slip in, and feed the value through environment variables (or another secure channel) in CI.

STEP 05

Configure ProGuard / R8 (if applicable)

If you shrink and obfuscate, keep the Play Services Maps classes.

proguard-rules.proProGuard

# Google Play Services
-keep class com.google.android.gms.maps.** { *; }
-keep interface com.google.android.gms.maps.** { *; }
-dontwarn com.google.android.gms.**

VERIFY

What you should see

Build and run this screen. If the map renders and you can zoom and pan, the setup is done.

TestGoogleMaps.ktJetpack Compose

@Composable
fun TestGoogleMaps(modifier: Modifier = Modifier) {
    val mapState = rememberGoogleMapViewState(
        cameraPosition = MapCameraPosition(
            position = GeoPoint(35.6762, 139.6503),
            zoom = 12.0,
        ),
    )

    // If the map appears, the setup is correct.
    GoogleMapView(modifier = modifier, state = mapState)
}

Map designs

GoogleMapDesign mirrors Google's own map type ids.

GoogleMapDesign

Notes

Normal

The standard road map (roadmap)

Satellite

Satellite imagery

Hybrid

Satellite imagery with roads and labels

Terrain

Terrain map

None

No basemap tiles

Troubleshooting

The map does not appear (grey screen)

Check the API key in secrets.properties.
Confirm Maps SDK for Android is enabled in the Google Cloud Console.
Verify the key restrictions match your actual package name and SHA-1.

An API key error shows in the log

Re-check the key value and that it has not expired.
Review the key restrictions in the Console.

The build fails

Check that the map SDK coordinates and version match what your version catalog declares.
Make sure the repository is declared in settings.gradle.kts — with repositoriesMode set to FAIL_ON_PROJECT_REPOS, per-module repositories blocks are ignored.
If several map SDKs are present at once, look for dependency clashes with ./gradlew :app:dependencies.

Once GoogleMapView renders, markers, polylines and circles are written against the shared API — that code survives a provider swap untouched.