เอกสาร / การตั้งค่า / Android / Mapbox

การตั้งค่า Mapbox

ขั้นตอนการใช้ Mapbox Maps SDK สำหรับ Android กับ MapConductor Mapbox แจกจ่ายผ่านที่เก็บ Maven เฉพาะและส่งโทเค็นการเข้าถึงผ่านไฟล์ Manifest

MODULE

com.mapconductor:for-mapbox

API KEY

โทเค็นการเข้าถึง

VIEW

MapboxMapView

TIME

15 นาที

ผู้ให้บริการเดียวกัน แพลตฟอร์มอื่นiOS React

ดูเดโมแผนที่ร้านค้า · React ↗

ก่อนเริ่ม

สภาพแวดล้อมการพัฒนา Android (Android Studio)

บัญชี Mapbox

โทเค็นการเข้าถึงสาธารณะ (ขึ้นต้นด้วย pk.)

STEP 01

รับโทเค็นการเข้าถึง

สร้างบัญชี Mapbox
เปิด Access tokens ใน Account Dashboard
ใช้โทเค็นสาธารณะเริ่มต้นหรือสร้างโทเค็นใหม่

ข้อควรระวัง

อย่าฝังโทเค็นลับ (ขึ้นต้นด้วย sk.) ในแอป แอปจะใช้โทเค็นสาธารณะ

STEP 02

เพิ่มที่เก็บ Maven ของ Mapbox

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

กำหนดค่าไฟล์ Manifest และโทเค็น

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

ข้อควรระวัง

อย่า commit 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 อยู่หรือไม่

ไม่สามารถแก้ไขการพึ่งพาได้

ตรวจสอบว่ามีที่เก็บ Maven ของ Mapbox ใน settings.gradle.kts หรือไม่
ตรวจสอบว่าระบุตัวแปร NDK27 (com.mapbox.maps:android-ndk27) ไว้หรือไม่

การสร้างล้มเหลว

ตรวจสอบว่าพิกัดและเวอร์ชันของ Map SDK ตรงกับที่ระบุในแคตตาล็อกเวอร์ชันหรือไม่
ตรวจสอบว่ามีคำจำกัดความของที่เก็บใน settings.gradle.kts หรือไม่ (หาก repositoriesMode เป็น FAIL_ON_PROJECT_REPOS ระบบจะละเว้น repositories ด้านโมดูล)
หากมีหลายแผนที่ SDK พร้อมกัน ให้ตรวจสอบความขัดแย้งของการพึ่งพาด้วย ./gradlew :app:dependencies

เมื่อ MapboxMapView ปรากฏขึ้น คุณสามารถซ้อนทับซ้อนทับได้เหมือนกับผู้ให้บริการรายอื่น คุณยังสามารถระบุสไตล์ที่ไม่ใช่ของโฮสต์ Mapbox ได้