はじめに
Mapbox Maps SDK for iOSは非常に多機能です。ドキュメントを読むだけでは実装イメージが湧かない場合、公式リポジトリにある「Examples（サンプルアプリ）」を手元で動かすのが理解への近道です。
本記事では、公式リポジトリをクローンしてシミュレーターで動かす手順と、収録されている主要なサンプルコードの内容を解説します。
動作環境
- Xcode: 15.3以上推奨
- iOS Simulator: iPhone 17 等 (ビルドターゲットに設定)
- Mapbox Maps SDK for iOS: v11系 (最新安定版 v11.17.0 など)
手順
1. Mapboxアカウントの作成とトークンの取得
サンプルアプリを動かすにはMapboxのアクセストークンが必要です。
- Mapboxの公式サイトでアカウントを作成（またはログイン）します。
- Accountページにある Default Public Token をコピーしておきます。
2. リポジトリのクローン
GitHubからソースコードをローカルにダウンロードします。
ターミナルを開き、以下のコマンドを実行してください。
git clone https://github.com/mapbox/mapbox-maps-ios.git
cd mapbox-maps-ios
※ GitHub上のURLは https://github.com/mapbox/mapbox-maps-ios.git です。
3. プロジェクトを開く
ダウンロードしたフォルダ内にある Examples.xcodeproj をXcodeで開きます。
4. アクセストークンの設定
アプリをビルドする前に、Info.plist にトークンを設定する必要があります。
- Xcodeのプロジェクトナビゲータ（左側）でプロジェクトファイルを選択します。
- ターゲットリストから Examples アプリのターゲットを探して選択します。
- Info タブを開きます。
- Keyに
MBXAccessTokenがあるか確認します（なければ+ボタンで追加し、Key名をMBXAccessTokenにします）。 - Valueの欄に、手順1でコピーした Default Public Token をペーストします。
5. ビルドと実行
- Xcode上部のデバイス選択メニューで、My Mac ではなく iPhone 16 などの具体的なiOSシミュレーターを選択します。
-
Cmd + Rまたは再生ボタンを押してビルドを実行します。
収録されているサンプル紹介
Examplesアプリには多数の実装例が含まれています。ここでは特に開発のヒントになる重要な機能をカテゴリ別に紹介します。
1. マーカーとアノテーション (Annotations)
地図上に情報を表示する機能です。
- Point Annotations: 地図上の特定の座標に画像アイコン（マーカー）を表示します。
- View Annotations: ネイティブなUIViewを地図上に表示します。マーカータップ時のポップアップ表示などに利用されます。
2. カメラとアニメーション (Camera & Animations)
地図の視点を制御する機能です。
- Camera Control: 緯度経度、ズーム、回転などをコードから制御します。
- Animations: 視点を滑らかに移動させるアニメーションの実装例です。
3. オフラインマップ (Offline Maps)
- インターネット接続がない環境でも地図を表示するために、事前にデータをダウンロード・管理する実装例です。
4. ユーザー位置情報 (User Location)
- Location Puck: ユーザーの現在地を取得し、地図上に追従するアイコン（Puck）を表示します。
5. SceneKit Example (3Dモデルの統合)
AppleのフレームワークであるSceneKitを使って、地図上に3Dモデルを表示するサンプルです。
-
仕組み: Mapboxの
CustomLayer機能を使用し、地図のカメラ（位置、ズーム、傾き）とSceneKitのカメラを同期させることで、地図上に3Dオブジェクト（アヒルや飛行機など）が実在するかのようにレンダリングする処理を行っています。
コードの読み方
Xcodeのプロジェクトナビゲータ内にある Examples フォルダを展開すると、各機能に対応したSwiftファイルが格納されています。
アプリ上で「SceneKit Example」などのタイトルを確認し、同名のファイル（例: SceneKitExample.swift）を探すことで、具体的な実装ロジックを確認できます。
トラブルシューティング
ビルドに失敗したり、地図が表示されない場合は以下を確認してください。
-
ライブラリ不足: ターゲット設定の
Frameworks, Libraries, and Embedded ContentにMapboxMaps,MapboxCommon,MapboxCoreMaps,Turfの4つが含まれているか確認してください。 -
トークンエラー:
Info.plistのMBXAccessTokenが正しく入力されているか確認してください。
おわりに
公式Examplesは、ドキュメントだけでは分かりにくい「動的な挙動」を確認できる最高の教材です。まずはシミュレーターで一通り触ってみて、実装したい機能に近いサンプルコードをコピー＆ペーストすることから始めてみてください。またMapboxのサポートに問い合わせをする際には、サンプルコードをベースにして問題を再現、報告すると話が非常に早く進むのでおすすめです。