メインコンテンツまでスキップ

開始方法

追加の開発者リソース

このドキュメントでは、Maps SDK の最新の安定バージョンをインストールし、Mapbox 依存関係をプロジェクトに追加して、Android アプリケーションで地図を素早く動作させる手順を説明します。

前提条件​

  • Mapbox アカウント: Mapbox で無料アカウントに登録するか、ログインしてください。
  • Android 開発用 IDE: Android Studio のような Android アプリケーションを編集・ビルドするためのプログラム。

パート1: 認証情報の作成と設定​

Maps SDK を使用してアプリケーションの開発を開始する前に、認証情報を作成して設定する必要があります。

SDK をインストールする前に、適切なクレデンシャルを集める必要があります。

この SDK は、Mapbox アカウントからの2つの重要な情報が必要です（またはサインアップしてアカウントを作成してください）：

  • パブリックアクセス トークン：アカウントのトークン ページから、デフォルトのパブリック トークン をコピーするか、 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=YOUR_SECRET_MAPBOX_ACCESS_TOKEN

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

SDK は、アプリのリソースを通じて、または実行時に設定することで、アクセス トークンを提供する複数の方法をサポートしています。

リソース​

Mapbox SDK にパブリック トークンを提供する方法の一つは、Android 文字列リソース として追加することです。

これを行うには、アプリモジュール (例：app/src/main/res/values/mapbox_access_token.xml) に新しい文字列リソース ファイルを作成し、パブリック Mapbox API トークンを配置します：

<?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>

この場合、アクセス トークンを回転させたい場合は、アプリを再リリースする必要があります。 アクセス トークンの回転に関する詳細は、アクセス トークン情報ページ を参照してください。

実行時​

トークンを提供するもう一つの方法は、以下のコードを使って実行時に行う方法です：

MapboxOptions.accessToken = YOUR_MAPBOX_ACCESS_TOKEN

このオプションは、実行時にトークンを回転させたい場合や、トークンを apk に保存する代わりにバックエンドから取得したい場合に便利です。

SDK と通信する前に、トークン が有効であることを 設定する必要があることに注意してください。そうしないと、SDK はトークンを使用できません。

たとえば、ナビゲーション SDK の場合、最初にトークンを設定し、その後で初期化を行います。

マップ SDK の場合、MapView をインフレートする前に（Activity#onCreate での setContentView 呼び出しかもしれません）、トークンを設定します。

一度実行時にトークンを変更すると、その時点からすべての SDK が新しいトークンを使用します。

たとえば、長期間実行されるアプリがあり、48時間ごとにトークンを回転させたい場合は、以下のようなアプローチを検討することができます：

  1. 初回アプリ起動時に、バックエンドへトークンのネットワークリクエストを行います。
  2. トークンを受け取った後、ナビゲーション コンポーネントをロードし、ナビゲーション SDK をインスタンス化し、MapView をインフレートします。
  3. アプリ ファイルにトークンを保存します。
  4. 次回アプリを起動する際に、ファイルからトークンを読み込みます。
  5. トークンが利用できない場合（例えば、アプリ データがクリアされている場合）、バックエンドへの別のリクエストを行い、ナビゲーション コンポーネントの読み込みを遅らせます。
  6. 48時間ごとに、バックエンドにトークンをチェックするリクエストを行います。
  7. トークンが変更された場合は、アプリのライフサイクルの任意の時点で、以下を呼び出します：
MapboxOptions.accessToken = YOUR_NEW_PUBLIC_MAPBOX_ACCESS_TOKEN

この時点から、すべての Mapbox SDK が新しいトークンを使用します。

  1. 新しいトークンをアプリのディレクトリに保存します。

トークンの新しい値を作成する方法についての情報は、アクセス トークン情報ページ を参照してください。

権限の設定​

マップ上にユーザーの位置情報を表示するか、ユーザーの位置情報を取得する予定がある場合、アプリケーションの AndroidManifest.xml に ACCESS_COARSE_LOCATION の権限を追加する必要があります。正確な位置へのアクセスが必要な場合は、 ACCESS_FINE_LOCATION 権限も追加する必要があります。ユーザーが位置情報の権限を付与しているかどうかを確認し、まだ付与していない場合は PermissionsManager を使用して権限をリクエストすることができます。

<manifest ... >
  <!-- この権限は常に含める -->
  <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />

  <!-- アプリが正確な位置情報アクセスから利益を得る場合のみ含める -->
  <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
</manifest>

パート2: 依存関係を追加​

認証情報が準備できたら、プロジェクトに依存関係を追加しましょう。

Mapbox は Maven を介して Maps SDK を提供しています。

Maps SDK を依存関係として追加するには、ビルド設定を変更して、Mapbox Maven リポジトリから直接 SDK をダウンロードする必要があります。

Mapbox リポジトリへのアクセスには、有効なユーザー名とパスワードが必要です。前のセクションで、gradle.properties ファイルにパスワードを追加しました（パート1: 認証情報の作成と設定 を参照してください）。これで、そのトークンを使ってリモートリポジトリにアクセスできます。

  1. Android Studio でプロジェクトを開きます。
  2. プロジェクトの settings.gradle ファイルに移動し、Gradle Scripts セクションの settings.gradle.kts ファイルを開きます。
  3. dependencyResolutionManagement.repositories 内に新しい maven {...} 定義を追加します。以下のスニペットの隠された部分は、settings.gradle.kts ファイルの一部で、スニペットをどこに配置するかを示しています。
 
        // Mapbox Maven repository
 
        maven {
 
            url = uri("https://api.mapbox.com/downloads/v2/releases/maven")
 
            // Do not change the username below. It should always be "mapbox" (not your username).
 
            credentials.username = "mapbox"
 
            // Use the secret token stored in gradle.properties as the password
 
            credentials.password = providers.gradleProperty("MAPBOX_DOWNLOADS_TOKEN").get()
 
            authentication { basic(BasicAuthentication) }
 
        }
  1. モジュールレベル の Gradle 設定ファイル（例: app > GradleScripts > build.gradle.kts）を開き、プロジェクトの minSdk が 21 以上であることを確認します。

android {
  ...
  defaultConfig {
      minSdk 21
      ...
  }
}
  1. 同じ モジュールレベル （例: app > GradleScripts > build.gradle.kts）の Gradle 設定ファイルに、Android 用 Mapbox SDK の依存関係を追加します。

dependencies {
  ...
  implementation 'com.mapbox.maps:android:11.8.0'
  ...
}
  1. （オプション）Jetpack Compose を使用してアプリを構築する場合は、同じ モジュールレベル（例: app/build.gradle.kts）の Gradle 設定ファイルに、Mapbox SDK Jetpack Compose Extension の依存関係を追加します。

android {
  buildFeatures {
    compose true
  }
  composeOptions {
    kotlinCompilerExtensionVersion = "1.3.2"
  }
}
dependencies {
  ...
  implementation 'com.mapbox.maps:android:11.8.0'
  // Compose を使用する場合、Compose 拡張機能も追加します。
  implementation 'com.mapbox.extension:maps-compose:11.8.0'
  ...
}
  1. Gradle ファイルを編集したので、Android Studio で File > Sync Project with Gradle Files をクリックしてください。
トラブルシューティング
  • 競合する推移的依存関係が発生する場合があります。必要に応じて、exclude group を使用して特定の依存関係を削除できます（推移的依存関係を除外 を参照）。
  • settings.gradle.kts ファイルのユーザー名フィールドは常に "mapbox" である必要があります。
  • プロジェクト全体で変更が同期されていない可能性がある場合は、File > Sync Project with Gradle Files を実行してください。

パート3: マップを追加​

アプリケーションにマップを追加しましょう。これは 3 つの方法のいずれかで実行できます:

Jetpack Compose

Jetpack Compose​

Mapbox Maps Compose 拡張機能を使用して、Composable にマップを追加できます。 build.gradle.kts` ファイルに次の行が含まれていることを確認してください:

implementation ("com.mapbox.extension:maps-compose:11.6.0")
 
      MapboxMap(
 
        Modifier.fillMaxSize(),
 
        mapViewportState = rememberMapViewportState {
 
          setCameraOptions {
 
            zoom(2.0)
 
            center(Point.fromLngLat(-98.0, 39.5))
 
            pitch(0.0)
 
            bearing(0.0)
 
          }
 
        },
 
      )
Jetpack Compose Extension の使用

Mapbox Jetpack Compose Extension は MapView をラップします。すべての API が Jetpack Compose Extension を通じて公開されているわけではないため、MapEffect 内で MapView への参照を取得し、フル API サーフェスにアクセスできます。

MapEffect の使用には注意が必要です
MapEffect 内で MapView API を使用すると、Compose の状態と競合する可能性があり、予期しないまたは未定義の動作につながる場合があります。

次の例では、MapEffect を使用してカメラの状態を制御しています。

 
          // Changes inside `MapEffect` may conflict with Compose states.
 
          // For example, to enable debug mode:
 
          mapView.debugOptions = setOf(
 
            MapViewDebugOptions.TILE_BORDERS,
 
            MapViewDebugOptions.PARSE_STATUS,
 
            MapViewDebugOptions.TIMESTAMPS,
 
            MapViewDebugOptions.COLLISION,
 
            MapViewDebugOptions.STENCIL_CLIP,
 
            MapViewDebugOptions.DEPTH_BUFFER,
 
            MapViewDebugOptions.MODEL_BOUNDS,
 
            MapViewDebugOptions.TERRAIN_WIREFRAME,
 
          )
 
        }
Jetpack Compose 拡張を使用する

Mapbox Jetpack Compose Extension は MapView をラップしています。Jetpack Compose Extension ではすべての API が公開されていないため、MapEffect 内で MapView の参照を取得して、完全な API サーフェスにアクセスすることができます。

MapEffect 使用時の注意
MapEffect 内で MapView API を使用すると、内部状態の変化が Compose の状態と競合し、予期しない動作や定義されていない動作が発生する可能性があります。

次の例は、MapEffect を使用してデバッグ機能をオンにする方法を示しています:

 
      MapboxMap(modifier = Modifier.fillMaxSize()) {
 
        // Get reference to the raw MapView using MapEffect
 
        MapEffect(Unit) { mapView ->
 
          // Use mapView to access the Mapbox Maps APIs not in the Compose extension.
 
          // Changes inside `MapEffect` may conflict with Compose states.
 
          // For example, to enable debug mode:
 
          mapView.debugOptions = setOf(
 
            MapViewDebugOptions.TILE_BORDERS,
 
            MapViewDebugOptions.PARSE_STATUS,
 
            MapViewDebugOptions.TIMESTAMPS,
 
            MapViewDebugOptions.COLLISION,
 
            MapViewDebugOptions.STENCIL_CLIP,
 
            MapViewDebugOptions.DEPTH_BUFFER,
 
            MapViewDebugOptions.MODEL_BOUNDS,
 
            MapViewDebugOptions.TERRAIN_WIREFRAME,
 
          )
 
        }
Jetpack Compose 拡張を使用する際の重大な変更
Mapbox Jetpack Compose Extension を使用する場合、コンパス、スケールバー、ロゴ、アトリビューション、ライフサイクルなどの一部のマッププラグインが Jetpack Compose 対応のものに置き換えられます。そのため、mapView.compass、mapView.scalebar、mapView.logo、mapView.attribution、mapView.lifecycle などの API は動作せず、実行時例外が発生する可能性があります。これらの問題を避けるために、対応する Compose API を使用してください。
ビュー内のレイアウト: XML を使用する

XML レイアウト​

アクティビティの XML レイアウトファイルを開き、レイアウト内に com.mapbox.maps.MapView 要素を追加します:

<FrameLayout xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto"
    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"
        app:mapbox_cameraTargetLat="39.5"
        app:mapbox_cameraTargetLng="-98.0"
        app:mapbox_cameraZoom="2.0"
        app:mapbox_cameraPitch="0.0"
        app:mapbox_cameraBearing="0.0" />

</FrameLayout>
ビュー内のレイアウト: 実行時にインスタンス化する

実行時レイアウト​

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

 
        // Create a map programmatically and set the initial camera
 
        mapView = MapView(this)
 
        mapView.mapboxMap.setCamera(
 
            CameraOptions.Builder()
 
                .center(Point.fromLngLat(-98.0, 39.5))
 
                .pitch(0.0)
 
                .zoom(2.0)
 
                .bearing(0.0)
 
                .build()
 
        )
 
        // Add the map view to the activity (you can also add it to other views as a child)
 
        setContentView(mapView)

上記のいずれかの方法に従った後、コードの上の再生ボタンを押してエミュレータを起動できます。起動後、エミュレータには次のようにマップが表示されます:

実装が期待通りに動作しない場合は、トラブルシューティングセクションを確認してください:

トラブルシューティング
  • settings.gradle.kts ファイルのユーザー名フィールドは常に "mapbox" にする必要があります。
  • 変更を見逃していないか確認するために、File > Save All をクリックしてください。
  • プロジェクト全体で同期されていない変更があった場合に備えて、File > Sync Project with Gradle Files を実行してみてください。
  • mapbox ライブラリがインポートされていない場合、以下を確認してください:
    • app/res/values/mapbox_access_token.xml にトークンがあり、「YOUR_MAPBOX_ACCESS_TOKEN」と表示されていないことを確認してください。
    • settings.gradle.kts ファイルと build.gradle.kts に必要な依存関係が追加されており、Part 2: Add the dependency で示されたサンプルスニペットと一致していることを確認してください。
  • MainActivity ファイルに正しいライブラリがインポートされていることを、サンプルコードを参考に確認してください。
  • デフォルトの Pixel Fold でマップが表示されない場合は、仮想デバイスを切り替えてみてください。
  • 競合する伝播依存関係があるか確認してください。必要に応じて、exclude group を使用して特定の依存関係を削除できます（伝播依存関係の除外 を参照）。

次のステップ​

マップが動作するようになったら、他の Android 関連コンテンツを読んでみてください:

GUIDE
マップにマーカーを追加する

マップにデフォルトのマーカーを追加する方法を学びましょう。
GUIDE
ユーザーの位置を特定する方法

ユーザーの位置を特定し、プライバシー権を理解し、アプリにユーザー位置機能を追加する方法を学びましょう。

追加の開発者リソース
この{Type}は役に立ちましたか？