문서 / 설정 / Android / Mapbox

Mapbox 설정

Mapbox Maps SDK for Android를 MapConductor에서 쓰는 절차입니다. Mapbox는 전용 Maven 저장소에서의 배포이며, 액세스 토큰을 매니페스트 경유로 넘깁니다.

MODULE

com.mapconductor:for-mapbox

API KEY

액세스 토큰

VIEW

MapboxMapView

TIME

15분

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

데모 보기매장 지도 · React ↗

시작하기 전에

Android 개발 환경(Android Studio)

Mapbox 계정

퍼블릭 액세스 토큰(pk.로 시작하는 것)

STEP 01

액세스 토큰을 취득한다

Mapbox 계정을 만듭니다.
Account Dashboard의 Access tokens를 엽니다.
기본의 퍼블릭 토큰을 쓰거나, 새로 만듭니다.

주의

시크릿 토큰(sk.로 시작)은 앱에 넣지 마세요. 앱에서 쓰는 것은 퍼블릭 토큰입니다.

STEP 02

Mapbox의 Maven 저장소를 더한다

Mapbox Maps SDK는 Maven Central에는 없고, Mapbox 자신의 저장소에서 취득합니다.

settings.gradle.ktsKotlin

dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()

        // Mapbox Maven repository
        maven {
            url = uri("https://api.mapbox.com/downloads/v2/releases/maven")
        }
    }
}

STEP 03

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 04

의존 관계를 추가한다

MapConductor는 NDK27 배리언트에 대해 빌드하고 있습니다.

app/build.gradle.ktsKotlin

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

dependencies {
    // Mapbox Maps SDK (NDK27 variant)
    implementation("com.mapbox.maps:android-ndk27:11.28.0")

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

    implementation("com.mapconductor:core")
    implementation("com.mapconductor:for-mapbox")
}

STEP 05

매니페스트와 토큰을 설정한다

AndroidManifest.xmlXML

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

    <application>
        <!-- Mapbox Access Token -->
        <meta-data
            android:name="MAPBOX_ACCESS_TOKEN"
            android:value="${MAPBOX_ACCESS_TOKEN}" />
    </application>
</manifest>

secrets.propertiesProperties

MAPBOX_ACCESS_TOKEN=your_actual_access_token

주의

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

동작 확인

여기까지 보이면 완료

Mapbox의 스타일로 지도가 나오고, 줌・팬・회전이 들으면 완료입니다.

TestMapbox.ktJetpack Compose

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

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

잘 안 될 때

지도가 새하얀 채로

secrets.properties의 토큰이 올바른지, 실효되지 않았는지 확인합니다.
토큰이 pk.로 시작하는 퍼블릭 토큰인지 확인합니다.
토큰의 스코프에 maps:read가 포함되어 있는지 확인합니다.

의존이 해결되지 않는다

settings.gradle.kts에 Mapbox의 Maven 저장소가 있는지 확인합니다.
NDK27 배리언트(com.mapbox.maps:android-ndk27)를 지정하고 있는지 확인합니다.

빌드가 통과하지 않는다

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

MapboxMapView가 나오면, 다른 프로바이더와 같은 작성법으로 오버레이를 겹칠 수 있습니다. Mapbox 호스트 이외의 스타일도 지정할 수 있습니다.