Mapbox Maps SDK for Android

Maps SDK for Androidは、Androidアプリケーション内にマップを表示するためのオープンソースのツールセットです。

Google PlayストアのMapboxのデモアプリには、Maps SDK for Androidの使用例が多く掲載されています。デモアプリとサンプルページでMaps SDK for Androidの機能性をご確認いただけます。

Maps SDKのインストール

Maps SDKを使用してアプリケーションを開発する前に、SDKを依存関係として追加する必要があります。このドキュメントでは、プロジェクト内に安定板版のMaps SDKを挿入する方法を示していますが、ナイトリービルド (SNAPSHOT)またはベータ版を使用することもできます。これを行う方法詳細に関しては、プロジェクトのGitHubリポジトリをご参照ください。

アプリケーションのメソッド数が65,536を超える場合、アプリケーション内でProGuardを有効にすることでこの問題を回避できます。ProGuardディレクティブはAndroidの依存関係に含まれています。APK分割を使用して、ファイルAPKのファイルサイズも縮小できます。

1. クレデンシャル情報の設定

SDKをインストールする前に、適切なクレデンシャル情報を収集する必要があります。SDKは、お客様のMapboxアカウントから2つの機密情報を必要とします。Mapboxアカウントをお持ちでない場合は、サインアップしてアカウントページに移動してください。以下の情報が必要となります。

• パブリックアクセストークン: アカウントのトークンページから、デフォルトのパブリックトークンをコピーするか、Create a tokenボタンをクリックして新しいパブリックトークンを作成することができます。

• Downloads:Read スコープを持つシークレット・アクセストークン

  1. アカウントのトークンページから、Create a tokenボタンをクリックします。
  2. トークン作成ページから、トークンに名前を付け、Downloads:Readスコープの隣のボックスがチェックされていることを確認してください。
  3. ページ下部のCreate tokenボタンをクリックして、トークンを作成します。
  4. 作成されたトークンはシークレットトークンのため、作成時のみトークン内容のコピーが可能です。コピー後は安全な場所に保管ください。

これらのアクセストークンは、権限のないユーザーに公開しないこと、又はソースコードにコミットしないことを強く推奨します。代わりに、コンピュータ上の安全な場所に保存し、Gradleのプロパティを利用して、アプリがコンパイルされたときにのみ追加されるようにしてください。この設定ステップが完了すると、アプリの他の部分でクレデンシャル情報を参照できるようになります。

シークレットトークンの設定

シークレットトークンを公開しないようにするには、環境変数として追加します。

1. Gradleのユーザーホームフォルダにあるgradle.propertiesファイルを使用するか、なければ作成してください。フォルダは «USER_HOME»/.gradleにあります。このファイルを使用するか、なければ作成してください。ファイルパスは «USER_HOME»/.gradle/gradle.propertiesとなります。Gradleのプロパティについては、Gradleの公式ドキュメントを参照してください。
2. シークレットトークンをgradle.propertiesファイルに追加します。

MAPBOX_DOWNLOADS_TOKEN=PASTE_YOUR_SECRET_TOKEN_HERE

パブリックトークンの設定

パブリックアクセストークンを設定する方法はたくさんあります。このサイトの例やコードスニペットの多くは、トークンが他の文字列値と一緒にプロジェクト内のファイルに保存されていることを前提としています。パブリックアクセストークンをこの方法で管理したい場合は、プロジェクトのR.string.xmlファイルを開き、以下の文字列リソースを追加してください。

<string name="mapbox_access_token">MAPBOX_ACCESS_TOKEN</string>

アクセストークンをローテートさせる必要がある場合は、R.string.xmlファイルのトークンの値を更新する必要があります。

権限の設定

マニフェストマージ機能により、SDKが必要とする権限のうちアプリケーションのマニフェストファイルに記載しなければならない項目はほとんどありません。マップ上にユーザーの位置を表示したり、ユーザーの位置情報を取得したりする場合は、Fine または Coarse location permission のいずれかを追加する必要があります。ユーザの位置情報利用許可は、PermissionsManagerを使用して実行時にもチェックする必要があります。

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

2. 依存関係の追加

MapboxはMaven経由でMaps SDKを提供します。

Mapbox Maps SDKを依存関係として追加するには、Mapboxから直接Maps SDKをダウンロードするようにビルドを設定する必要があります。これには有効なユーザー名とパスワードが必要です。

1. Android Studioでプロジェクトを開きます。
2. モジュールレベルのbuild.gradleファイルを開きます。
3. プロジェクトのminSdkVersionが API 14 以上であることを確認してください。

android {
  ...
  defaultConfig {
      minSdkVersion 14
  }
}

4. 依存関係の下に、最新のmapbox-android-sdk用の新しいビルドルールを追加します。

dependencies {
  implementation 'com.mapbox.mapboxsdk:mapbox-android-sdk:9.5.0'
}

5. プロジェクトレベルのbuild.gradleファイルを開きます。repositoriesブロックでMapbox Downloads APIのv2/releases/mavenエンドポイントを指定します。Maps SDKの依存関係をダウンロードするには、有効なユーザー名とパスワードでリクエストを認証する必要があります。前のセクションで行った、Gradleユーザーのホームフォルダ内のgradle.propertiesファイルへの設定がこれに相当します。

allprojects {
  repositories {
    maven {
      url 'https://api.mapbox.com/downloads/v2/releases/maven'
      authentication {
          basic(BasicAuthentication)
      }
      credentials {
        // Do not change the username below.
        // This should always be `mapbox` (not your username). 
          username = 'mapbox'
          // Use the secret token you stored in gradle.properties as the password
          password = project.properties['MAPBOX_DOWNLOADS_TOKEN'] ?: ""
      }
    }
  }
}

6. Gradleファイルを編集したので、Android Studioでは、Gradleファイルを同期するかどうかを尋ねてきます。このタイミングで同期できます。注: Android用のMapbox Maps SDKを追加すると、Gradleの依存関係が不一致になる可能性があります。必要であれば、excludeグループを使用して特定の依存関係を削除することができます。

implementation ('com.mapbox.mapboxsdk:mapbox-android-sdk:9.5.0'){
    exclude group: 'group_name', module: 'module_name'
}

さらに、コマンドラインでgradle app_module_name_here:dependenciesを実行すると、依存関係のリストが出力されます。./gradlew app:dependenciesは、Gradleラッパーがある場合に機能します。これらは、様々なライブラリが単一プロジェクトに含まれているGradleの設定を迅速にトラブルシューティングする際に役立ちます。特定ライブラリがもたらす依存関係と、競合が発生する可能性のある場所を確認できます。

3. マップの追加

マップを追加するアクティビティを開き、以下のコードを使用します。

private MapView mapView;
 
@Override
protected 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() {
@Override
public 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レイアウトファイルを開き、以下を追加します。

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

4. ライフサイクルメソッド

MapViewには、AndroidのOpenGLライフサイクルを管理するための独自のライフサイクルメソッドが含まれており、アクティビティから直接呼び出す必要があります。アプリが MapViewのライフサイクル メソッドを正しく呼び出すためには、MapViewを含むアクティビティ内の以下のライフサイクル メソッドをオーバーライドして、それぞれの MapViewメソッドを呼び出す必要があります。以下のライフサイクルメソッドはオーバーライドして、一致するMapViewメソッドを含める必要があります。フラグメントを使用している場合は、onDestroy()の中ではなく、フラグメントのonDestroyView()メソッドの中でmapview.onDestroy()を呼び出します。

@Override
protected void onStart() {
super.onStart();
mapView.onStart();
}
 
@Override
protected void onResume() {
super.onResume();
mapView.onResume();
}
 
@Override
protected void onPause() {
super.onPause();
mapView.onPause();
}
 
@Override
protected void onStop() {
super.onStop();
mapView.onStop();
}
 
@Override
protected void onSaveInstanceState(Bundle outState) {
super.onSaveInstanceState(outState);
mapView.onSaveInstanceState(outState);
}
 
@Override
public void onLowMemory() {
super.onLowMemory();
mapView.onLowMemory();
}
 
@Override
protected void onDestroy() {
super.onDestroy();
mapView.onDestroy();
}

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

帰属表示

Maps SDK for Androidを使用するマップには、Mapboxのワードマークと帰属表示を含める必要があります。SDK は必要な情報をすべて含む帰属表示レイアウトを提供します。また、xmlまたはUiSettingsオブジェクトを使用してカスタマイズすることができます。

マップボックスのワードマークと帰属表示の位置を調整することができますが、それらはマップ上に見える状態で表示する必要があります。また、帰属表示の背景とテキストの色をデザインの美観に合わせて変更することもできますが、すべての情報は判別可能でなければなりません。

上記の調整以外に、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"/>

任意の MapViewXML属性を使用している場合は、XMLファイルのrootViewまたはViewGroup要素にxmlns:mapbox="http://schemas.android.com/tools"を追加します。

GeoJSONを理解する

Maps SDK for Androidの多くの部分は、地図データを表現するためのオープンな標準ファイル形式であるGeoJSONに基づいています。多くのMaps SDKメソッドは、GeoJSONジオメトリをパラメータとして取るか、GeoJSON機能を返します。例えば、Maps SDKには、マップスタイルにデータを追加するためのGeoJSONSourceクラスや、GeoJSONフィーチャのリストを返す便利なメソッドであるMaps SDKのクエリメソッドがあります。

Mapbox Java SDKのGeoJSONモジュールが、Maps SDKにGeoJSON機能を提供しています。Maps SDKを使用するために必要なものではありませんが、GeoJSONに精通することで、Maps SDKの理解と使用方法を大幅に向上させることができます。Java SDKのGeoJSONモジュールをMaps SDKで使用する方法をぜひご一読ください。