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

Installation Guide

追加の開発者リソース

Before starting to develop your application with the Navigation SDK, you'll need to configure your credentials and add the SDK as a dependency.

Configure credentials​

Step 1: Log in/Sign up for a Mapbox account​

If you haven't done so already, sign up for a Mapbox account and log into it.

You can sign up or sign in by clicking the buttons in the top right corner of your browser or going to https://account.mapbox.com/sign-up.

This account will allow you to create tokens and will create a default public token for you upon creation.

Step 2: Create a secret token​

A secret token can enable access to various products/services at Mapbox, including the ability to download an SDK. To allow download access to an SDK, follow these steps:

  1. Go to your account's tokens page.
  2. Click the Create a token button.
  3. Name your token, for this example we've used InstallTokenAndroid.
  4. Scroll down to the Secret Scope section and check the Downloads:Read scope box.
  5. Click the Create token button at the bottom of the page to create your token.
  6. Enter your password to confirm the creation of your token.
  7. Now, you'll be returned to your account's tokens page, where you can copy your created token. Note, this token is a secret token, which means you will only have one opportunity to copy it, so save this token somewhere secure.

This video also walks through the steps above:

Protect secret access tokens

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).

Step 3: Configure your secret token​

To avoid exposing your secret token, let's add it as an environment variable using gradle:

Installing Gradle

If you do not already have gradle installed, follow the Gradle Install guide to install gradle onto your computer.

To configure your secret token, follow these steps:

  1. Check if you already have a gradle.properties file in your Gradle user home folder.
  • Open the Gradle user home folder at /Users/USERNAME/.gradle.
  • Note that you may not be able to see this folder and need to be reveal it.
    • If on Mac, press Command + Shift + . to show hidden folders.
    • If on Windows, click View in the Explorer Window, and then click Show > Hidden Items.
  • With the folder revealed, you'll be able to open your .gradle folder and check for your gradle.properties file.
  1. If the gradle.properties file doesn't exist, create the file.
    • If you already have this file skip this step and go onto Step 3.
    • For Mac, open a terminal in your .gradle folder and type touch gradle.properties.
    • For Windows, open a command window in your .gradle folder and type echo >> gradle.properties.
  2. Open your gradle.properties file and copy and paste the snippet below into the file:
MAPBOX_DOWNLOADS_TOKEN=YOUR_SECRET_MAPBOX_ACCESS_TOKEN
  1. Grab the secret token you made before and replace the text YOUR_SECRET_MAPBOX_ACCESS_TOKEN with the secret token.
Learn more about Gradle

More details about Gradle properties in the official Gradle documentation.

Step 4: Configure your public token​

Next let's provide an access token to the SDK by adding the token as an Android string resource.

To do this, follow these steps:

  1. Open your project folder or create a new project in Android Studio.
  • If creating a new project, we recommend using the Empty Activity project type.
  1. Go to the folder structure in the left side of Android Studio and open your resource folder located at app/res/values.
  2. Create a new resource file, by left clicking on the folder, selecting New > Values Resource File
  3. Name the file mapbox_access_token.xml and click the Ok button.
  4. In the new file, copy and paste the code from below.
  5. Make sure your token is included in the code snippet. The token should start with the letter pk. If you see YOUR_MAPBOX_ACCESS_TOKEN in your code, log into your mapbox account and then copy the snippet again.
    • When you're logged into your account, your public mapbox token is automatically added to code snippet. You can also grab your default by going to your account's tokens page.
<?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>
Advanced Topics: Best Practices, Rotating Tokens & Adding Tokens at Runtime
GUIDE
Access token best practices

Learn how to keep access tokens private in mobile apps.

Adding Tokens at Runtime

You can also implement tokens at runtime, but this requires you to have a separate server to store your tokens. This is helpful if you want to rotate your tokens or add additional security by storing your tokens outside of the APK, but is a much more complex method of implementation.

If you do choose to follow this method, we recommend calling MapboxOptions.accessToken = YOUR_PUBLIC_MAPBOX_ACCESS_TOKEN before inflating the MapView, otherwise the app will crash.

Rotating Tokens

For more information on access token rotation, consult the Access Tokens Information page.

Step 5: Configure permissions​

If you need to access user's location on the map or get the user's location information you will need to do the following:

  1. Open app > manifests > AndroidManifest.mxl
  2. Determine the permissions you need. If you only need general user location access, add the ACCESS_COARSE_LOCATION permission. If also need access to a more precise location you will need to also call ACCESS_FINE_LOCATION.
  • Note: You must call ACCESS_COARSE_LOCATION to access location at all, while ACCESS_FINE_LOCATION is only needed for more specific access.
  1. Add the permissions you need as seen in the code snippet to the AndroidManifest.xml.
  • This should be added at the top of the manifest, below the opening manifest tag and above the opening <application> tag.
 
<!-- Include this permission to grab user's general location -->
 
<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" />

You can check whether the user has granted location permission and request permissions if the user hasn't granted them yet using the PermissionsManager.

If your app targets Android 13 or higher, POST_NOTIFICATIONS permission is required to show notifications to the user. Navigation SDK shows the notification during both Free Drive and Active Guidance, if you don't explicitly disable the foreground service launch by calling MapboxNavigation#startTripSession(false). That's why the Navigation SDK declares this permission in its AndroidManifest.xml:

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

The notification contains some useful trip progress information and UI controls. So it's highly recommended that you request the permission in runtime. The Navigation SDK will continue working and receiving location updates when minimized even if the permission is not granted, but there will be no trip notification displayed.

Handle location permissions
The Navigation SDK makes use of the Android manifest merge feature. The SDK's manifest file already has both the course and fine location permission lines, which means you don't have to declare any location permissions inside your project's manifest file or in some other way. If your project targets Android API 23 or higher, make sure to check the user location permission in runtime using PermissionsManager.

Add Mapbox Repository​

Mapbox provides the Navigation SDK via Maven.

To add the Navigation SDK as a dependency, you will need to configure your build to download the Navigation SDK from Mapbox directly. This requires a valid username and password.

  1. Open your project in Android Studio.

  2. Declare the Mapbox Downloads API's releases/maven endpoint. To download the Navigation SDK dependency, you must authenticate your request with a valid username and password. In the previous section, you added the password to a gradle.properties file in your Gradle user home folder. The username field should always be "mapbox". It should not be your personal username used to create the secret token. The placement of these declarations depends on the versions of Android Studio and Gradle that your project is using:

    • Android Studio less than Arctic Fox (2020.3.1) and Gradle less than v6.0: Open up your project-level build.gradle file, and add the code below to declare the endpoint in the repositories block:

      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'] ?: ""
                    }
                }
          }
      }

    • Android Studio Arctic Fox (2020.3.1) or later and Gradle v6.0 or later: You may need to make these declarations in your settings.gradle file instead. If you see build errors with the build.gradle process described above, then instead declare the Mapbox's Maven repository in your settings.gradle file like below:

      dependencyResolutionManagement {
          repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
          repositories {
              google()
              mavenCentral()
              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 = MAPBOX_DOWNLOADS_TOKEN
                }
              }
          }
      }

  3. Open up your module-level build.gradle file.

  4. The Navigation SDK uses Java 8 features. To enable Java 8 in your project, add the following compileOptions.

    android {
        compileOptions {
            sourceCompatibility JavaVersion.VERSION_1_8
            targetCompatibility JavaVersion.VERSION_1_8
        }
        // Add the block below if you're using Kotlin
        kotlinOptions {
        	jvmTarget = "1.8"
    	}
        ...
    }

  5. Make sure that your project's minSdkVersion is at API 21 or higher.

    android {
        ...
        defaultConfig {
            minSdkVersion 21
        }
    }

Add dependency​

  1. Add the dependency under dependencies. The Navigation SDK offers a range of components, each with its own dependency name:

    • Navigation component allows you to access the primary interface for engaging with the Navigation SDK
    dependencies {
    	implementation "com.mapbox.navigationcore:navigation:3.5.2"
    }
    • Mapbox Copilot is a component that collects detailed trace files of navigation sessions together with search analytics data
    dependencies {
    	implementation "com.mapbox.navigationcore:copilot:3.5.2"
    }
    • Maps component provides a set of classes that can enhance the navigation experience for your users, for example, Navigation Camera to simplify management of the map's camera object, or Route Line to render a route line on a map
    dependencies {
    	implementation "com.mapbox.navigationcore:ui-maps:3.5.2"
    }
    • Voice component allows users to access Voice API
    dependencies {
    	implementation "com.mapbox.navigationcore:voice:3.5.2"
    }
    • Trip Data component provides convenient API to request maneuver instructions, route shields, speed limit, and trip progress data.
    dependencies {
    	implementation "com.mapbox.navigationcore:tripdata:3.5.2"
    }
    • Android component provides all the listed above components
    dependencies {
    	implementation "com.mapbox.navigationcore:android:3.5.2"
    }
    • UI components module provides pre-built UI widgets
    dependencies {
    	implementation "com.mapbox.navigationcore:ui-components:3.5.2"
    }

    The detailed documentation about all the Navigation SDK components is coming soon.

  2. Because you've edited your Gradle files, Android Studio will ask you whether you want to sync the Gradle files. You can sync now.

Method limit
If you've added the Navigation SDK, finished all the installation steps above, and see an Android Studio error saying that you've reached maximum method count, try enabling Multidex following the official Android guides to using multidex and optimizing your code.
追加の開発者リソース
この{Type}は役に立ちましたか？