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

Swift、SwiftUI、UIKit を使用した Mapbox Maps SDK v11 を iOS に統合するための公式パターン。

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

• Mapbox Maps SDK for iOS のインストールと設定
• マップへのマーカーとアノテーションの追加
• ユーザーロケーションの表示とカメラでの追跡
• カスタムデータ(GeoJSON)のマップへの追加
• マップスタイル、カメラ、またはユーザーインタラクションの操作
• フィーチャーインタラクションとタップの処理

公式リソース:

• iOS Maps Guides
• API Reference
• Example Apps

---

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

要件

• iOS 14+
• Xcode 15+
• Swift 5.9+
• 無料の Mapbox アカウント

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

Info.plist にパブリックトークンを追加します:

<key>MBXAccessToken</key>
<string>pk.your_mapbox_token_here</string>

トークンを取得: mapbox.com にサインインします

ステップ2: Swift Package の依存関係を追加

1. File → Add Package Dependencies
2. URL を入力: https://github.com/mapbox/mapbox-maps-ios.git
3. バージョン: 11.0.0 から "Up to Next Major"
4. 確認 4つの依存関係が表示されます: MapboxCommon、MapboxCoreMaps、MapboxMaps、Turf

代替方法: CocoaPods または直接ダウンロード (インストールガイド)

---

マップの初期化

SwiftUI パターン

基本的なマップ:

import SwiftUI
import MapboxMaps

struct ContentView: View {
    @State private var viewport: Viewport = .camera(
        center: CLLocationCoordinate2D(latitude: 37.7749, longitude: -122.4194),
        zoom: 12
    )

    var body: some View {
        Map(viewport: $viewport)
            .mapStyle(.standard)
    }
}

オーナメント付き:

Map(viewport: $viewport)
    .mapStyle(.standard)
    .ornamentOptions(OrnamentOptions(
        scaleBar: .init(visibility: .visible),
        compass: .init(visibility: .adaptive),
        logo: .init(position: .bottomLeading)
    ))

UIKit パターン

import UIKit
import MapboxMaps

class MapViewController: UIViewController {
    private var mapView: MapView!

    override func viewDidLoad() {
        super.viewDidLoad()

        let options = MapInitOptions(
            cameraOptions: CameraOptions(
                center: CLLocationCoordinate2D(latitude: 37.7749, longitude: -122.4194),
                zoom: 12
            )
        )

        mapView = MapView(frame: view.bounds, mapInitOptions: options)
        mapView.autoresizingMask = [.flexibleWidth, .flexibleHeight]
        view.addSubview(mapView)

        mapView.mapboxMap.loadStyle(.standard)
    }
}

---

マーカーの追加

SDK はマップにポイントを配置するための3つの方法を提供しています。最も適切なものを選択してください。

どの API を使うべき?

API	用途	プラットフォーム	注記
Marker (Markers API)	デフォルトピンが必要で、カスタム画像アセットがない場合	SwiftUI のみ	画像アセットは不要。実験的な SPI — @_spi(Experimental) import MapboxMaps が必要。100個未満のマーカーに最適。
PointAnnotation	カスタム画像があり、レイヤーレベルの配置が必要な場合	SwiftUI + UIKit	シンボルレイヤーに支援され、数百のマーカーまでスケーリングします。UIKit がレンダリングできる任意の UIImage を受け入れます。
ビューアノテーション (ViewAnnotation / MapViewAnnotation)	座標に固定されたフルネイティブビュー(カード、バッジ、アニメーション コンテンツ)をレンダリングしたい場合	SwiftUI + UIKit	SwiftUI は MapViewAnnotation を使用。UIKit は mapView.viewAnnotations を使用して ViewAnnotation を使用。各アノテーションは実ビュー — スケール時は PointAnnotation より コストが高い。

数百または数千のフィーチャーの場合、アノテーションの代わりにスタイルレイヤー(GeoJSONSource 上の SymbolLayer)を使用します。

Markers API (シンプルなケースに推奨、SwiftUI)

import SwiftUI
@_spi(Experimental) import MapboxMaps

struct ContentView: View {
    var body: some View {
        Map {
            Marker(coordinate: CLLocationCoordinate2D(latitude: 37.7749, longitude: -122.4194))
                .color(.red)
                .text("San Francisco")
        }
    }
}

コレクションから複数のマーカー:

Map {
    ForEvery(locations, id: \.id) { location in
        Marker(coordinate: location.coordinate)
            .color(.red)
            .text(location.name)
    }
}

スケーリングの注記。 Marker と PointAnnotation はそれぞれ、ピンごとに独自のビューまたはシンボルエントリを作成します — 約100個のマーカーまで問題ありません。より大きなデータセット(数百または数千のフィーチャー — オープンエンドの GeoJSON フィードで一般的)の場合、データを GeoJSONSource に読み込み、SymbolLayer でレンダリングしてください。これは数千のフィーチャーにスケーリングし、クラスタリングを有効にします。

PointAnnotation (カスタム画像)

SwiftUI:

Map(viewport: $viewport) {
    PointAnnotation(coordinate: CLLocationCoordinate2D(latitude: 37.7749, longitude: -122.4194))
        .image(.init(image: UIImage(named: "marker")!, name: "marker"))
}

UIKit:

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

// マーカーを作成
var annotation = PointAnnotation(coordinate: CLLocationCoordinate2D(latitude: 37.7749, longitude: -122.4194))
annotation.image = .init(image: UIImage(named: "marker")!, name: "marker")
annotation.iconAnchor = .bottom

// マップに追加
pointAnnotationManager.annotations = [annotation]

複数のマーカー:

let annotations = locations.map { coordinate in
    var annotation = PointAnnotation(coordinate: coordinate)
    annotation.image = .init(image: UIImage(named: "marker")!, name: "marker")
    return annotation
}

pointAnnotationManager.annotations = annotations

---

ユーザーロケーションの表示

ステップ1: ロケーション権限を Info.plist に追加:

<key>NSLocationWhenInUseUsageDescription</key>
<string>Show your location on the map</string>

ステップ2: 権限をリクエストしてロケーションを表示:

import CoreLocation

// 権限をリクエスト
let locationManager = CLLocationManager()
locationManager.requestWhenInUseAuthorization()

// ユーザーロケーションパック を表示
mapView.location.options.puckType = .puck2D()
mapView.location.options.puckBearingEnabled = true

---

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

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

// ❌ 繰り返し新しいマネージャーを作成しない
func updateMarkers() {
    let manager = mapView.annotations.makePointAnnotationManager()
    manager.annotations = markers
}

// ✅ 1回作成して再利用
let pointAnnotationManager: PointAnnotationManager

init() {
    pointAnnotationManager = mapView.annotations.makePointAnnotationManager()
}

func updateMarkers() {
    pointAnnotationManager.annotations = markers
}

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

// ✅ すべてを一度に更新
pointAnnotationManager.annotations = newAnnotations

// ❌ 1つずつ更新しない
for annotation in newAnnotations {
    pointAnnotationManager.annotations.append(annotation)
}

メモリ管理

// クロージャで weak self を使用
mapView.gestures.onMapTap.observe { [weak self] context in
    self?.handleTap(context.coordinate)
}.store(in: &cancelables)

// deinit でクリーンアップ
deinit {
    cancelables.forEach { $0.cancel() }
}

標準スタイルを使用

// ✅ 標準スタイルは最適化済みで推奨
.mapStyle(.standard)

// 特定のユースケースが必要な場合のみ他のスタイルを使用
.mapStyle(.standardSatellite) // 衛星画像

---

トラブルシューティング

マップが表示されない

確認:

1. ✅ Info.plist に MBXAccessToken がある
2. ✅ トークンが有効(mapbox.com でテスト)
3. ✅ MapboxMaps フレームワークが import されている
4. ✅ MapView がビュー階層に追加されている
5. ✅ 正しいフレーム/制約が設定されている

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

mapView.mapboxMap.onStyleLoaded.observe { [weak self] _ in
    print("Style loaded successfully")
    // レイヤーとソースをここに追加
}.store(in: &cancelables)

パフォーマンスの問題

• .standard スタイルを使用(推奨で最適化)
• 表示可能なアノテーションをビューポートに限定
• アノテーションマネージャーを再利用
• スタイルの頻繁な再読み込みを回避
• アノテーション更新をバッチ処理

---

リファレンスファイル

タスクが詳細なパターンを必要とする場合、これらのリファレンスを読み込みます:

• references/annotations.md — Circle、Polyline、Polygon Annotations
• references/location-tracking.md — カメラでユーザーをフォロー + 現在位置を取得
• references/custom-data.md — GeoJSON: Lines、Polygons、Points、更新/削除
• references/camera-styles.md — カメラコントロール + マップスタイル
• references/interactions.md — Featureset Interactions、カスタムレイヤータップ、長押し、ジェスチャー

---

追加リソース

• iOS Maps Guides
• API Reference
• Interactions Guide
• SwiftUI User Guide
• Example Apps
• Migration Guide (v10 → v11)