開始する
アプリケーションの開発を始める前に、Maps SDKの認証情報を構成し、SDKをプロジェクトの依存関係として追加する必要があります。
このドキュメントでは、Maps SDKの最新の安定版をインストールする手順を説明します。
認証情報を構成する
Before installing the SDK, you will need to gather the appropriate credentials.
The SDK requires two pieces of sensitive information from your Mapbox account (or sign up to create one):
- A public access token: From your account's tokens page, you can either copy your default public token or click the Create a token button to create a new public token.
- A secret access token with the
Downloads:Read
scope.- From your account's tokens page, click the Create a token button.
- From the token creation page, give your token a name and make sure the box next to the
Downloads:Read
scope is checked. - Click the Create token button at the bottom of the page to create your token.
- The token you've created is a secret token, which means you will only have one opportunity to copy it somewhere secure.
You should not expose these access tokens in publicly-accessible source code where unauthorized users might find them. Instead, you should store them somewhere safe on your computer and take advantage of Gradle properties to make sure they're only added when your app is compiled (see next section).
Configure your secret token
To avoid exposing your secret token, add it as an environment variable:
- Find or create a
gradle.properties
file in your Gradle user home folder. The folder is located at«USER_HOME»/.gradle
. Once you have found or created the file, its path should be«USER_HOME»/.gradle/gradle.properties
. More details about Gradle properties in the official Gradle documentation. - Add your secret token your
gradle.properties
file:
MAPBOX_DOWNLOADS_TOKEN=YOUR_SECRET_MAPBOX_ACCESS_TOKEN
Configure your public token
The SDK supports multiple ways of providing an access token: through app resources or by setting it at runtime.
Resources
One way to provide your public token to Mapbox SDK is by adding it as an Android string resource.
To do so create a new string resource file in your app module (e.g. app/src/main/res/values/mapbox_access_token.xml
) with your public Mapbox API token:
<?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>
In this case, if you want to rotate an access token, you'll need to re-release your app. For more information on access token rotation, consult the Access Tokens Information page.
Runtime
Another way to provide a token is to do it at runtime with this code:
MapboxOptions.accessToken = YOUR_MAPBOX_ACCESS_TOKEN
You will find this option helpful in case you want to rotate your tokens at runtime or want to receive the token from your backend instead of storing it in your apk.
Note that you must set a valid token before any interaction with the SDK, including its initialization, otherwise the SDK will not be able to use your token.
For example, in case of Navigation SDK, first set the token and only then initialize it.
In case of Maps SDK, set the token before inflating the MapView (may be a setContentView
invocation in your Activity#onCreate
).
But once you change the token at runtime, the new one will be used by all the SDKs from that point on.
For example, if you have a long-living app and want to rotate the token every 48 hours, here is a possible approach you might want to consider:
- On the first app start make a network request to your backend for a token.
- When you receive a token, load the Navigation component in your app that will instantiate the Navigation SDK, inflate the MapView, etc.
- Store the token in your app files.
- On the next app launch you can read the token from file.
- If it's not available (for example, app data was cleared), make another request to your backend and delay loading the Navigation component.
- Every 48 hours make a request to your backend to check the token.
- If the token changed, at any point in your app's lifecycle invoke:
MapboxOptions.accessToken = YOUR_NEW_PUBLIC_MAPBOX_ACCESS_TOKEN
From this moment on it will be used by all the Mapbox SDKs.
- Store the new token in your app's directory.
For information on how you can create a new value for your token, consult the Access Tokens Information Page.
Configure permissions
If you plan to display the user's location on the map or get the user's location information you will need to add the ACCESS_COARSE_LOCATION
permission in your application's AndroidManifest.xml
. You also need to add ACCESS_FINE_LOCATION
permissions if you need access to precise location. You can check whether the user has granted location permission and request permissions if the user hasn't granted them yet using the PermissionsManager
.
<manifest ... >
<!-- Always include this permission -->
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<!-- Include only if your app benefits from precise location access. -->
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
</manifest>
モバイルアプリでアクセストークンを非公開に保つ方法を学びましょう。
依存関係を追加する
MapboxはMaps SDKをMaven経由で提供します。
Maps SDKを依存関係として追加するには、Mapboxのmavenリポジトリから直接Maps SDKをダウンロードするようにビルドを構成する必要があります。これには有効なユーザー名とパスワードが必要です(「認証情報を構成する」セクションを参照)。
-
Android Studioでプロジェクトを開きます。
-
Mapboxのリモートリポジトリを宣言します。
Mapboxリポジトリへのアクセスには有効なユーザー名とパスワードが必要です。前のセクションで、パスワードを
gradle.properties
ファイルに追加しました(「認証情報を構成する」セクションを参照)。ユーザー名フィールドには常に"mapbox"
を使用してください。デフォルトでは、新しいAndroid Studioプロジェクトは、Mavenリポジトリの場所をプロジェクトの
settings.gradle
ファイルに指定します:- トップレベルの
settings.gradle.kts
ファイルを開き、dependencyResolutionManagement.repositories
内に新しいmaven {...}
定義を追加します:
- トップレベルの
- モジュールレベル(例:
app/build.gradle.kts
)のGradle構成ファイルを開き、プロジェクトのminSdk
が21以上であることを確認します:
android {
...
defaultConfig {
minSdk 21
...
}
}
android {
...
defaultConfig {
minSdk = 21
...
}
}
- モジュールレベル(例:
app/build.gradle.kts
)のGradle構成ファイルにMapbox SDK for Androidの依存関係を追加します:
dependencies {
...
implementation 'com.mapbox.maps:android:11.6.1'
// Composeを使用している場合は、Compose拡張機能も追加します
// implementation 'com.mapbox.extension:maps-compose:11.6.1'
...
}
dependencies {
...
implementation("com.mapbox.maps:android:11.6.1")
// Composeを使用している場合は、Compose拡張機能も追加します
// implementation("com.mapbox.extension:maps-compose:11.6.1")
...
}
- Gradleファイルを編集したため、Android Studioで**「プロジェクトをGradleファイルと同期」**を実行します。
注:依存関係のトランジティブ設定に競合が発生する場合があります。必要に応じて、exclude group
を使用して特定の依存関係を削除することができます(トランジティブ依存関係の除外を参照)
マップを追加する
マップビューをアプリケーションに追加するには、Jetpack Composeまたはビューのレイアウトで(XMLを使用)を使用するか、ランタイムでインスタンス化を行います。
Jetpack Compose
Mapbox Maps compose拡張機能を使用して、composeにマップを追加することができます:
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>
ランタイムレイアウト
マップを追加したいアクティビティを開き、以下のコードを使用します: