문서 / 설정 / Android / Google Maps

Google Maps 설정

Google Maps SDK for Android를 MapConductor에서 쓰는 절차입니다. API 키의 취득부터, Secrets Gradle Plugin으로 키를 주입하고, GoogleMapView가 표시되는 곳까지를 다룹니다.

MODULE

com.mapconductor:for-googlemaps

API KEY

필요

VIEW

GoogleMapView

TIME

15분

같은 프로바이더, 다른 플랫폼iOS React

데모 보기매장 지도 · React ↗

시작하기 전에

Android 개발 환경(Android Studio)

Google Cloud Console 계정

Google Cloud 프로젝트에서 Maps SDK for Android가 활성화되어 있을 것

STEP 01

API 키를 취득한다

Google Cloud Console에 접속합니다.
프로젝트를 새로 만들거나, 기존의 것을 고릅니다.
Maps SDK for Android를 활성화합니다.
「인증 정보」에서 API 키를 만듭니다.
키를 앱의 패키지 이름과 SHA-1 인증서 지문으로 제한합니다.

디버그 빌드와 릴리스 빌드에서는 서명 인증서가 다르므로, SHA-1도 각각 등록할 필요가 있습니다.

STEP 02

Secrets Gradle Plugin을 넣는다

키를 소스 관리에 두지 않기 위한 구조입니다. 플러그인이 secrets.properties를 읽고, 빌드 시에 AndroidManifest.xml의 플레이스홀더에 값을 끼워 넣습니다.

(root)/build.gradle.ktsKotlin

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

STEP 03

의존 관계를 추가한다

Google Maps SDK 본체와 MapConductor의 모듈을 앱에 추가하고, Secrets Gradle Plugin을 적용합니다. MapConductor의 버전은 BOM이 일괄로 정합니다.

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.3.1"))

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

STEP 04

매니페스트와 키를 설정한다

매니페스트에는 플레이스홀더만 쓰고, 실제 값은 secrets.properties에 둡니다. 빌드 시에 플러그인이 바꿔 넣습니다.

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

위치 정보를 쓰지 않는 앱에서는 ACCESS_*_LOCATION은 불필요합니다. 타일의 취득에는 INTERNET만이 필요합니다.

주의

secrets.properties는 버전 관리에 커밋하지 마세요. .gitignore에 추가해 두면 사고를 막을 수 있습니다. CI에서는 환경 변수 등 다른 안전한 경로로 넘깁니다.

STEP 05

ProGuard / R8을 설정한다(해당하는 경우)

난독화를 활성화하고 있는 경우는, Play Services Maps의 클래스를 남깁니다.

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.**

동작 확인

여기까지 보이면 완료

이 화면을 빌드해 실행하고, 지도가 나오고 줌과 팬이 들으면 셋업은 완료입니다.

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)
}

지도 디자인

GoogleMapDesign은 Google의 맵 타입을 그대로 옮긴 것입니다.

GoogleMapDesign

Notes

Normal

통상의 도로 지도(roadmap)

Satellite

위성 화상

Hybrid

위성 화상＋도로와 라벨

Terrain

지형도

None

베이스맵 없음

잘 안 될 때

지도가 나오지 않는다(회색 화면)

secrets.properties의 API 키가 올바른지 확인합니다.
Google Cloud Console에서 Maps SDK for Android가 활성화되어 있는지 확인합니다.
키의 제한이, 실제의 패키지 이름과 SHA-1에 일치하는지 확인합니다.

로그에 API 키 오류가 나온다

키의 값과 유효 기한을 확인합니다.
Console 쪽의 제한 설정을 재검토합니다.

빌드가 통과하지 않는다

지도 SDK의 좌표와 버전이 버전 카탈로그의 지정과 일치하는지 확인합니다.
저장소 정의가 settings.gradle.kts에 있는지 확인합니다(repositoriesMode가 FAIL_ON_PROJECT_REPOS이면, 모듈 쪽의 repositories는 무시됩니다).
여러 지도 SDK를 동시에 넣고 있는 경우는, 의존의 충돌이 없는지 ./gradlew :app:dependencies로 확인합니다.

GoogleMapView가 나오면, Marker・Polyline・Circle 같은 오버레이는 공통 API로 쓸 수 있습니다. 프로바이더를 교체해도, 그 부분의 코드는 달라지지 않습니다.