문서 / 설정 / Android / MapLibre

MapLibre 설정

MapLibre Native Android를 MapConductor에서 쓰는 절차입니다. MapLibre 자체에 API 키는 없고, 지도의 겉모습은 스타일 JSON의 배포처로 정해집니다. 가장 짧은 절차로 움직일 수 있는 프로바이더입니다.

MODULE

com.mapconductor:for-maplibre

API KEY

불필요

VIEW

MapLibreMapView

TIME

5분

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

데모 보기매장 지도 · React ↗

시작하기 전에

Android 개발 환경(Android Studio)

스타일 JSON의 URL(데모 타일, 상용 서비스, 또는 자체 호스트)

STEP 01

타일의 출처를 정한다

MapLibre는 렌더러이지 타일의 제공처가 아닙니다. 동작 확인만이라면 MapLibreDesign의 데모용 스타일로 충분하지만, 본번에서는 배포처를 명시적으로 고를 필요가 있습니다.

무료・커뮤니티: OpenStreetMap 계열의 타일, Protomaps(셀프 호스트 가능)
상용: MapTiler Cloud, Stadia Maps(둘 다 무료 구간 있음)
셀프 호스트: tileserver-gl 등으로 자체 배포

주의

데모 타일은 동작 확인용입니다. 본번 트래픽을 흘려보내서는 안 됩니다. 또 대부분의 타일 제공처는 귀속 표시(예: © OpenStreetMap contributors)를 요구합니다. 이용 약관을 확인해 UI에 내 주세요.

STEP 02

의존 관계를 추가한다

MapLibre SDK는 Maven Central에서 취득할 수 있으므로, 추가 저장소 설정은 필요 없습니다.

settings.gradle.ktsKotlin

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

app/build.gradle.ktsKotlin

dependencies {
    // MapLibre Native Android SDK
    implementation("org.maplibre.gl:android-sdk:13.4.1")

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

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

STEP 03

매니페스트에 퍼미션을 더한다

키의 주입이 없으므로, 필요한 것은 퍼미션뿐입니다.

AndroidManifest.xmlXML

<manifest>
    <!-- Add internet permission for tile loading -->
    <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>
        <!-- no key to inject for MapLibre -->
    </application>
</manifest>

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

동작 확인

여기까지 보이면 완료

스타일을 지정해 지도를 냅니다. 타일이 읽히고, 줌・팬・회전이 들으면 완료입니다.

TestMapLibre.ktJetpack Compose

@Composable
fun TestMapLibre(modifier: Modifier = Modifier) {
    val mapState = rememberMapLibreMapViewState(
        cameraPosition = MapCameraPosition(
            position = GeoPoint(35.6762, 139.6503),
            zoom = 12.0,
        ),
        mapDesign = MapLibreDesign.OpenMapTiles,
    )

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

지도 디자인

MapLibreDesign은 스타일 JSON의 URL을 감싼 상수입니다. 자체 스타일을 쓰는 경우도 같은 타입을 만들어 넘깁니다.

MapLibreDesign

Notes

DemoTiles

MapLibre 공식의 데모 타일. 키 불필요로 최단으로 동작

OsmBright / OsmBrightEn / OsmBrightJa

OSM Bright. 라벨의 언어 차이

MapTilerTonerEn / MapTilerTonerJa

고대비의 Toner 스타일

MapTilerBasicEn / MapTilerBasicJa

정보량을 줄인 Basic 스타일

OpenMapTiles

범용의 OpenMapTiles 스타일

잘 안 될 때

지도가 새하얀 채로

스타일 URL에 도달할 수 있는지, JSON이 타당한지 확인합니다.
INTERNET 퍼미션이 붙어 있는지 확인합니다.
Logcat에 네트워크 또는 파싱 오류가 나오고 있지 않은지 봅니다.

타일만 읽히지 않는다

타일 서버의 URL을 확인합니다.
무료 서비스의 레이트 제한에 걸리고 있지 않은지 확인합니다.
상용 프로바이더를 쓰고 있는 경우는, 스타일 URL에 넣은 키가 유효한지 확인합니다.

빌드가 통과하지 않는다

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

벡터 타일은 래스터보다 가볍고, 렌더링도 빨라집니다. 오프라인 이용이 필요하다면 타일의 캐시를 검토하세요.