# Installation

> **Note (legacy): A newer version of the Maps SDK is available**
> 
> This page uses v9.7.1 of the Mapbox Maps SDK. A newer version of the SDK is available. Learn about the latest version, v11.30.0, in the [Maps SDK documentation](https://docs.mapbox.com/android/maps/guides/install/).

Before starting to develop your application with the Maps SDK, you'll need to configure your credentials and add the SDK as a dependency. This document describes the steps to install the stable version of the Maps SDK, but you can also use the nightly build (as in SNAPSHOT) or the beta version, if one is available. Find more information about how to do this inside the project's [GitHub repository](https://github.com/mapbox/mapbox-gl-native-android/blob/master/README.md).

> **Note: Android's 64K method count limit**
> 
> If your application is over the 64K method limit, you can [shrink, obfuscate, and optimize your code](https://developer.android.com/studio/build/shrink-code) with R8 or ProGuard. If those steps do not lower your method count below 64K, you can also [enable multidex](https://developer.android.com/studio/build/multidex).

## Part 1: Configure credentials

### Step 1: Configure your public token

Your app must have a public access token configured to associate its usage of Mapbox resources with your account.

Follow these steps to add a public access token from your Mapbox account as an [Android string resource](https://developer.android.com/guide/topics/resources/string-resource#String).

1.  Locate the resource folder:

-   In the project explorer, find and expand your resource folder located at `app/res/values`.

2.  Create a new string resource file :

-   Right click on the `values` folder
-   Select **New > Values Resource File**
-   Name the file `mapbox_access_token.xml`
-   Click the **OK** button.

3.  In the new file, copy and paste the code snippet below.

-   Make sure you are signed in to docs.mapbox.com. This will insert your default public token into the code snippet (a long string that starts with `pk.`).
-   If you are not signed in, you will need to replace the placeholder `YOUR_MAPBOX_ACCESS_TOKEN` with a token from your account's [tokens page](https://console.mapbox.com/account/access-tokens/).

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

Your Mapbox public access token is now available for use in your Android project. The Maps SDK for Android automatically looks for the `mapbox_access_token` string resource when you initialize a map, so you don't need to do anything else to use the token in your app.

Details

**Advanced Topics: Best Practices, Rotating Tokens & Adding Tokens at Runtime**

> **Related content (guide): [Access token best practices](https://docs.mapbox.com/help/troubleshooting/private-access-token-android-and-ios/)**
> 
> 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](https://docs.mapbox.com/help/how-mapbox-works/access-tokens/).

### Step 2: (Optional) Configure permissions

If you need to access the user's location to show it on the map, follow the steps below. If you do not need to access the user's location, skip to [Part 2: Add the dependency](#part-2-add-the-dependency).

1.  Open the Android Manifest.
    -   In the project explorer, find and open `app/manifests/AndroidManifest.xml`.
2.  Determine the level of location access you need.
    -   If you only need general user location access, copy the first line of code below - the `ACCESS_COARSE_LOCATION` permission.
    -   If you also need access to more precise location data, copy the entire code snippet, including the `ACCESS_FINE_LOCATION` permission. The `ACCESS_FINE_LOCATION` will not work without also requesting `ACCESS_COARSE_LOCATION` access.
3.  Add the permissions you copied to the Android Manifest.
    -   This code should be added to the top of `AndroidManifest.xml`, below the opening manifest tag and above the opening `<application>` tag.

```xml
<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
xmlns:tools="http://schemas.android.com/tools">

<!-- 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" />

<application...>
```

You can check whether the user has granted location permission and request permissions if the user hasn't granted them yet using the [`PermissionsManager`](https://docs.mapbox.com/android/maps/guides/user-location/permissions#using-the-maps-sdk-permission-utilities).

> **Related content (guide): [Access token best practices](https://docs.mapbox.com/help/troubleshooting/private-access-token-android-and-ios/)**
> 
> Learn how to keep access tokens private in mobile apps.

## Part 2: Add the dependency

Mapbox provides the Maps SDK via **Maven**.

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

1.  Open your project in Android Studio.
2.  Open up your *module-level* `build.gradle` file.
3.  Make sure that your project's `minSdkVersion` is at API 14 or higher.

```groovy
android {
  ...
  defaultConfig {
      minSdkVersion 14
  }
}
```

4.  Under dependencies, add a new build rule for the latest `mapbox-android-sdk`.

```groovy
dependencies {
  implementation 'com.mapbox.mapboxsdk:mapbox-android-sdk:9.7.1'
}
```

5.  Open up your *project-level* `build.gradle` file. Declare the Mapbox Downloads API's `v2/releases/maven` endpoint in the repositories block. To download the Maps SDK dependency, you must authenticate your request with a valid username and password. In the previous section, you added these to a gradle.properties file in your Gradle user home folder.

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

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

*Note: You might have mismatching Gradle dependencies once you add the Mapbox Maps SDK for Android. If necessary, you can use `exclude group` to remove certain dependencies:*

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

Additionally, running `gradle app_module_name_here:dependencies` in your command line will print a list of dependencies. `./gradlew app:dependencies` works if you have a Gradle wrapper. They are helpful for troubleshooting nimble Gradle configurations when various libraries are included in a single project. You can see the dependencies that specific libraries are bringing and where conflicts might be happening.

## Add a map

Open the activity you'd like to add a map to and use the code below.

**Java**

```java
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


      	}
      });

    }
  });
}
```

**Kotlin**

```kt
private var mapView: MapView? = null

override fun onCreate(savedInstanceState: Bundle?) {
  super.onCreate(savedInstanceState)

  Mapbox.getInstance(this, getString(R.string.mapbox_access_token))

  setContentView(R.layout.activity_main)

  mapView = findViewById(R.id.mapView)
  mapView?.onCreate(savedInstanceState)
  mapView?.getMapAsync { mapboxMap ->

  	mapboxMap.setStyle(Style.MAPBOX_STREETS) {

      // Map is set up and the style has loaded. Now you can add data or make other map adjustments


  	}

  }
}
```

Open the activity's XML layout file and add the following:

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

The `MapView` contains its own lifecycle methods for managing Android's OpenGL lifecycle, which must be called directly from the containing Activity. For your app to correctly call the MapView's lifecycle methods, you must override the following lifecycle methods in the Activity that contains the MapView and call the respective MapView method. The following lifecycle methods must be overridden and include the matching `MapView` method. If you're using a fragment, call `mapview.onDestroy()` inside the fragment's `onDestroyView()` method rather than inside `onDestroy()`.

**Java**

```java
@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();
}
```

**Kotlin**

```kt
override fun onStart() {
	super.onStart()
	mapView?.onStart()
}

override fun onResume() {
	super.onResume()
	mapView?.onResume()
}

override fun onPause() {
	super.onPause()
	mapView?.onPause()
}

override fun onStop() {
	super.onStop()
	mapView?.onStop()
}

override fun onSaveInstanceState(outState: Bundle) {
	super.onSaveInstanceState(outState)
	mapView?.onSaveInstanceState(outState)
}

override fun onLowMemory() {
	super.onLowMemory()
	mapView?.onLowMemory()
}

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

> **Note**
> 
> To override a fragment's `onDestroyView()` method:
> 
> **Kotlin**
> 
> ```kt
> override fun onDestroyView() {
> 	super.onDestroyView()
> 	mapView?.onDestroy()
> }
> ```