Mapbox Android インテグレーション パターン

Kotlin、Jetpack Compose、View システムを使用した Mapbox Maps SDK v11 の Android への統合パターン。

このスキルを使用する場合:

• Mapbox Maps SDK for Android のインストールと設定
• マップへのマーカーとアノテーションの追加
• ユーザーの位置情報を表示し、カメラでトラッキング
• カスタムデータ (GeoJSON) をマップに追加
• マップスタイル、カメラ、またはユーザーインタラクションの操作
• フィーチャーインタラクションとタップの処理

公式リソース:

• Android Maps Guides
• API Reference
• Example Apps

---

インストール & セットアップ

必要条件

• Android SDK 21+
• Kotlin または Java
• Android Studio
• Mapbox の無料アカウント

ステップ 1: アクセストークンの設定

app/res/values/mapbox_access_token.xml を作成:

<?xml version="1.0" encoding="utf-8"?>
<resources xmlns:tools="http://schemas.android.com/tools">
    <string name="mapbox_access_token" translatable="false"
        tools:ignore="UnusedResources">YOUR_MAPBOX_ACCESS_TOKEN</string>
</resources>

トークンを取得: mapbox.com でサインイン

ステップ 2: Maven リポジトリを追加

settings.gradle.kts で:

dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
        maven {
            url = uri("https://api.mapbox.com/downloads/v2/releases/maven")
        }
    }
}

ステップ 3: 依存関係を追加

モジュール build.gradle.kts で:

android {
    defaultConfig {
        minSdk = 21
    }
}

dependencies {
    implementation("com.mapbox.maps:android:11.18.1")
}

Jetpack Compose の場合:

dependencies {
    implementation("com.mapbox.maps:android:11.18.1")
    implementation("com.mapbox.extension:maps-compose:11.18.1")
}

---

マップ初期化

Jetpack Compose パターン

基本的なマップ:

import androidx.compose.runtime.*
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.ui.Modifier
import com.mapbox.maps.extension.compose.*
import com.mapbox.maps.Style
import com.mapbox.geojson.Point

@Composable
fun MapScreen() {
    MapboxMap(
        modifier = Modifier.fillMaxSize()
    ) {
        // MapEffect でカメラを初期化 (Style.STANDARD はデフォルトで読み込まれます)
        MapEffect(Unit) { mapView ->
            // 初期カメラ位置を設定
            mapView.mapboxMap.setCamera(
                CameraOptions.Builder()
                    .center(Point.fromLngLat(-122.4194, 37.7749))
                    .zoom(12.0)
                    .build()
            )
        }
    }
}

装飾付き:

MapboxMap(
    modifier = Modifier.fillMaxSize(),
    scaleBar = {
        ScaleBar(
            enabled = true,
            position = Alignment.BottomStart
        )
    },
    compass = {
        Compass(enabled = true)
    }
) {
    // Style.STANDARD はデフォルトで読み込まれます
}

View システム パターン

レイアウト XML (activity_map.xml):

<?xml version="1.0" encoding="utf-8"?>
<androidx.constraintlayout.widget.ConstraintLayout
    xmlns:android="http://schemas.android.com/apk/res/android"
    android:layout_width="match_parent"
    android:layout_height="match_parent">

    <com.mapbox.maps.MapView
        android:id="@+id/mapView"
        android:layout_width="match_parent"
        android:layout_height="match_parent" />

</androidx.constraintlayout.widget.ConstraintLayout>

Activity:

import android.os.Bundle
import androidx.appcompat.app.AppCompatActivity
import com.mapbox.maps.MapView
import com.mapbox.maps.Style
import com.mapbox.geojson.Point

class MapActivity : AppCompatActivity() {
    private lateinit var mapView: MapView

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_map)

        mapView = findViewById(R.id.mapView)

        mapView.mapboxMap.setCamera(
            CameraOptions.Builder()
                .center(Point.fromLngLat(-122.4194, 37.7749))
                .zoom(12.0)
                .build()
        )

        mapView.mapboxMap.loadStyle(Style.STANDARD)
    }

    override fun onStart() {
        super.onStart()
        mapView.onStart()
    }

    override fun onStop() {
        super.onStop()
        mapView.onStop()
    }

    override fun onDestroy() {
        super.onDestroy()
        mapView.onDestroy()
    }
}

---

マーカー追加 (ポイントアノテーション)

ポイントアノテーションはマップ上に位置をマークする最も一般的な方法です。

Jetpack Compose:

MapboxMap(modifier = Modifier.fillMaxSize()) {
    MapEffect(Unit) { mapView ->
        // まずスタイルを読み込む
        mapView.mapboxMap.loadStyle(Style.STANDARD)

        // アノテーションマネージャーを作成してマーカーを追加
        val annotationManager = mapView.annotations.createPointAnnotationManager()
        val pointAnnotation = PointAnnotationOptions()
            .withPoint(Point.fromLngLat(-122.4194, 37.7749))
            .withIconImage("custom-marker")
        annotationManager.create(pointAnnotation)
    }
}

// 注: Compose には宣言的な PointAnnotation コンポーネントがありません
// マーカーは MapEffect を介して命令型で追加する必要があります

View システム:

// アノテーションマネージャーを作成 (1回、更新時に再利用)
val pointAnnotationManager = mapView.annotations.createPointAnnotationManager()

// マーカーを作成
val pointAnnotation = PointAnnotationOptions()
    .withPoint(Point.fromLngLat(-122.4194, 37.7749))
    .withIconImage("custom-marker")

pointAnnotationManager.create(pointAnnotation)

複数のマーカー:

val locations = listOf(
    Point.fromLngLat(-122.4194, 37.7749),
    Point.fromLngLat(-122.4094, 37.7849),
    Point.fromLngLat(-122.4294, 37.7649)
)

val annotations = locations.map { point ->
    PointAnnotationOptions()
        .withPoint(point)
        .withIconImage("marker")
}

pointAnnotationManager.create(annotations)

---

ユーザーの位置情報を表示

ステップ 1: AndroidManifest.xml にパーミッションを追加:

<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />

ステップ 2: パーミッションをリクエストして位置情報を表示:

// まずパーミッションをリクエスト (ActivityResultContracts を使用)

// ロケーションパックを表示
mapView.location.updateSettings {
    enabled = true
    puckBearingEnabled = true
}

---

パフォーマンスベストプラクティス

アノテーションマネージャーの再利用

// 新しいマネージャーを繰り返し作成しないでください
// val manager = mapView.annotations.createPointAnnotationManager() // 毎回呼び出し

// 1回作成して再利用
val pointAnnotationManager = mapView.annotations.createPointAnnotationManager()

fun updateMarkers() {
    pointAnnotationManager.deleteAll()
    pointAnnotationManager.create(markers)
}

アノテーション更新のバッチ処理

// すべて一度に作成
pointAnnotationManager.create(allAnnotations)

// ループで 1 つずつ作成しないこと

ライフサイクル管理

// 常にライフサイクルメソッドを呼び出す
override fun onStart() {
    super.onStart()
    mapView.onStart()
}

override fun onStop() {
    super.onStop()
    mapView.onStop()
}

override fun onDestroy() {
    super.onDestroy()
    mapView.onDestroy()
}

Standard スタイルを使用

// Standard スタイルは最適化されており推奨されています
Style.STANDARD

// 特定のユースケースで必要な場合のみ他のスタイルを使用
Style.STANDARD_SATELLITE // 衛星画像

---

トラブルシューティング

マップが表示されない

確認事項:

1. mapbox_access_token.xml にトークンがある
2. トークンが有効 (mapbox.com でテスト)
3. Maven リポジトリが設定されている
4. 依存関係が正しく追加されている
5. マニフェストにインターネットパーミッションがある

スタイルが読み込まれない

mapView.mapboxMap.subscribeStyleLoaded { _ ->
    Log.d("Map", "Style loaded successfully")
    // ここでレイヤーとソースを追加
}

パフォーマンスの問題

• Style.STANDARD を使用 (推奨かつ最適化)
• 表示されるアノテーションをビューポートに制限
• アノテーションマネージャーを再利用
• 頻繁なスタイルの再読み込みを回避
• ライフサイクルメソッド (onStart, onStop, onDestroy) を呼び出す
• アノテーション更新をバッチ処理

---

リファレンスファイル

特定のトピックについての詳細なパターンが必要な場合は、以下のリファレンスを読み込んでください:

• references/compose.md -- Jetpack Compose: 依存関係、トークン設定、MapboxMap、クリック付きアノテーション、GeoJSON、MapEffect
• references/annotations.md -- サークル、ポリライン、ポリゴンアノテーションパターン
• references/location-tracking.md -- カメラでユーザーの位置をフォロー + 現在位置の 1 回取得
• references/custom-data.md -- GeoJSON ソースとレイヤー: ライン、ポリゴン、ポイント、更新/削除
• references/camera-styles.md -- カメラコントロール (設定、アニメーション、フィット) + マップスタイル (ビルトインおよびカスタム)
• references/interactions.md -- フィーチャーセットインタラクション、カスタムレイヤータップ、長押し、ジェスチャー

---

追加リソース

• Android Maps Guides
• API Reference
• Interactions Guide
• Jetpack Compose Guide
• Example Apps
• Migration Guide (v10 -> v11)