Android用Mapbox Maps SDK
Android用Mapbox Maps SDKは、Androidアプリケーション内にマップを表示するためのオープンソースのツールセットです。
Google PlayストアのMapboxのデモアプリには、Android用Mapbox Maps SDKの使用方法の例が多く含まれています。デモアプリとサンプルページはAndroid用Mapbox Maps SDKのパワーを示しています。
Android用Mapbox Maps SDKの古いバージョンから新しいバージョンへの移行については以下をご参照ください:
- v7.x.xからv8.x.x: このバージョン変更により、毎月のアクティブユーザーのカウント方法が改善されました。移行ガイドは不要ですが、これらの変更詳細に関しては、変更ログと製品別価格ガイドをご参照ください。
- v6.x.xからv7.x.x
- v5.x.xからv6.x.x
- v4.x.xからv5.x.x
Maps SDKのインストール
Maps SDKを使用してアプリ開発開始前に、SDKを依存関係として追加する必要があります。MavenCentralリポジトリには、以下の依存関係があります。このドキュメントでは、プロジェクト内に安定板版のMaps SDKを挿入する方法を示していますが、ナイトリービルド (つまり、SNAPSHOT)または使用可能な場合ベータ版を使用することもできます。これを行う方法詳細に関しては、プロジェクトのGitHubリポジトリをご参照ください。
アプリケーションが65,000のメソッドカウント制限に近い場合、または超える場合、アプリケーション内でProGuardを有効にすることでこの問題を軽減できます。ProGuardディレクティブは必要なクラスを保持するためにAndroidの依存関係に含まれています。APK分割を使用して、ファイルAPKのファイルサイズも縮小できます。
1. 依存関係の追加
- Android Studioを開く。
- アプリケーションのbuild.gradleファイルを開く。
- プロジェクトのminSdkVersionがAPI 14以降であることを確認する。
- 依存関係の下、最新mapbox-android-coreバージョンの新しいビルドルールを追加する(以下参照)。
- Android Studioのツールバー近くにある[Sync Project with Gradle Files]をクリックする。
repositories {
mavenCentral()
}
dependencies {
implementation 'com.mapbox.mapboxsdk:mapbox-android-sdk:'
}
注: Android用 Maps SDKを追加すると、Gradle依存関係が一致しない場合があります。特定依存関係を削除するために、以下のような除外グループを使用できないことに注意してください。
implementation ('com.mapbox.mapboxsdk:mapbox-android-sdk:'){
exclude group: 'group_name', module: 'module_name'
}
さらに、コマンドラインでgradle app_module_name_here:dependencies
を実行すると、依存関係のリストが出力されます。./gradlew app:dependencies
は、Gradleラッパーがある場合に機能します。様々なライブラリが単一プロジェクトに含まれている場合、機敏なGradle構成のトラブルシューティングに役立ちます。特定ライブラリがもたらす依存関係と、競合が発生する可能性のある場所を確認できます。
2. アクセストークンの取得
Mapboxアカウントをお持ちでない場合、サインアップしてから、アカウントページに移動します。デフォルトの公開トークンをクリップボードにコピーします。Androidプロジェクト内にMaps SDKを依存関係として追加するとR.strings.xmlファイルを開き、新しいStringリソースを作成しアクセストークンを貼り付けます。
<string name="mapbox_access_token">MAPBOX_ACCESS_TOKEN</string>
次に、これをMaps SDKに渡すため、アプリケーションのonCreate()
メソッド内にアクセストークンを配置します。
public class MyApplication extends Application { @Overridepublic void onCreate() {super.onCreate(); // Mapbox Access tokenMapbox.getInstance(getApplicationContext(), getString(R.string.mapbox_access_token));}}
Maps SDKには、実行時Mapboxアクセストークンを切り替えるための setToken()
メソッドも用意されています。特定Mapbox APIには、中国のマップ等特別なMapboxトークンが必要です。新しいトークンを設定すると、複数のMapboxツールを相互に組み合わせて使用できます。この方法では、特定Mapboxツールを使用する前にトークンを設定できます。トークンを最初に設定し、全てのMapbox関連リクエストに同じトークンを使用する必要があります。
Mapbox.setAccessToken(MAPBOX_ACCESS_TOKEN);
3. セットアップ許可
Maps SDKバージョン5.0以降では、マニフェストマージ機能を使用してアプリケーションのマニフェストファイル内にMaps SDKに必要なものを含める必要性を減らすことができます。ユーザーロケーションをマップ上に表示したり、ユーザーロケーション情報を取得したりする場合、FineまたはCoarseロケーション許可のいずれかを追加する必要があります。実行時に、PermissionsManager
を使用して、ユーザーロケーションの許可も確認する必要があります。
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
4. マップの追加
マップを含めるアクティビティのJavaファイルを開き、以下のコードをファイルに追加します。
private MapView mapView; @Overrideprotected void onCreate(Bundle savedInstanceState) {super.onCreate(savedInstanceState); Mapbox.getInstance(this, getString(R.string.mapbox_access_token); setContentView(R.layout.activity_main); mapView = (MapView) findViewById(R.id.mapView);mapView.onCreate(savedInstanceState);mapView.getMapAsync(new OnMapReadyCallback() {@Overridepublic void onMapReady(@NonNull MapboxMap mapboxMap) { mapboxMap.setStyle(Style.MAPBOX_STREETS, new Style.OnStyleLoaded() { @Override public void onStyleLoaded(@NonNull Style style) { // Map is set up and the style has loaded. Now you can add data or make other map adjustments }}); }});}
アクティビティのXMLレイアウトファイルを開き、レイアウト内にmapView
を追加します。
<com.mapbox.mapboxsdk.maps.MapView
android:id="@+id/mapView"
android:layout_width="match_parent"
android:layout_height="match_parent"
/>
5. ライフサイクルメソッド
MapView
には、AndroidのOpenGLライフサイクルを管理するための独自ライフサイクルメソッドが含まれており、包含アクティビティから直接呼び出す必要があります。アプリがMapViewのライフサイクルメソッドを正しく呼び出すには、MapViewを含むアクティビティで次のライフサイクルメソッドをオーバーライドし、それぞれのMapViewメソッドを呼ぶ必要があります。例えば、onStart()
メソッドは次のようになります:
@Overrideprotected void onStart() { super.onStart(); mapView.onStart();}
上記onStart()
オーバーライドと同様に、次のライフサイクルメソッドもオーバーライドし、一致するMapView
メソッドを含める必要があります:
@Overrideprotected void onResume() { super.onResume(); mapView.onResume();} @Overrideprotected void onPause() { super.onPause(); mapView.onPause();} @Overrideprotected void onStop() { super.onStop(); mapView.onStop();} @Overrideprotected void onSaveInstanceState(Bundle outState) {super.onSaveInstanceState(outState);mapView.onSaveInstanceState(outState);} @Overridepublic void onLowMemory() {super.onLowMemory();mapView.onLowMemory();} @Overrideprotected void onDestroy() { super.onDestroy(); mapView.onDestroy();}
フラグメントを使用している場合、onDestroy()
内ではなく、フラグメントのonDestroyView()
メソッド内でmapview.onDestroy()
を呼び出します:
@Overridepublic void onDestroyView() { super.onDestroyView(); mapView.onDestroy(); }
属性
Android用Mapbox Maps SDKを使用するマップには、Mapboxワードマークと属性表示を含める必要があります。SDKは必要な全ての情報を含む属性レイアウトを提供し、xmlまたはUiSettings
オブジェクトを使用してカスタマイズできます。
Mapboxワードマークと属性表示の位置を調整できますが、それらはマップ上に表示されたままでなければなりません。また、デザインの美観に合わせて属性表示の背景とテキストの色を変更することも可能です。
それ以外の場合、Mapboxワードマークまたはテキストの属性表示を変更することはできません。Mapboxワードマークを移動または削除する場合、 営業チームに連絡してエンタープライズプランで利用可能なオプションについてご相談ください。
テレメトリのオプトアウト
Mapbox Telemetryは、このSDKに含まれる強力なロケーション分析プラットフォームです。デフォルトでは、SDKはホストアプリが収集するたびに匿名化された場所と使用状況データをMapboxに送信します。Mapbox利用規約では、属性コントロールの一部として自動的に提供されるMapbox Telemetryを個別にオプトアウトする方法をユーザーに提供することをアプリに要求しています。属性コントロールを非表示にする場合、ユーザーが使用する場合オプトアウトを提供する必要があります。
MapView XML属性
XML属性をXML MapView
に追加して、開始カメラ位置の設定、傾斜の有効か、画面上のコンパス位置の調整など、マップ動作をさらにカスタマイズできます。全てのMapView
XML属性は、他のライブラリと被らないように名前空間がmapbox_
で始まります。Android Studioの設計により、入力してMapView
属性を自動生成することはできません。MapView属性の完全なリストはこちらでご参照ください。
MapView属性の例は以下です:
<com.mapbox.mapboxsdk.maps.MapView
mapbox:mapbox_cameraTargetLat="-36.84"
mapbox:mapbox_cameraTargetLng="174.76"
mapbox:mapbox_cameraZoom="10"
mapbox:mapbox_cameraBearing="34.33"
mapbox:mapbox_cameraTilt="50.25"
mapbox:mapbox_cameraZoomMax="12.41"
mapbox:mapbox_cameraZoomMin="6"
mapbox:mapbox_uiRotateGestures="false"/>