Offline

Join the Mapbox Developers Discord Communityarrow-right

Not compatible with the Maps SDK v10

This plugin is not compatible with the Maps SDK v10 or higher. The Maps SDK v10 and higher comes with offline functionality built in. See the Offline guide.

The Offline Plugin for Android allows you to provide a seamless experience to your users even when their devices don't have a strong enough internet connection to download and view map tiles.

This plugin offers a convenient way to send information to the Maps SDK's OfflineManager class and use the manager in a background service to download map tiles for offline use. Once you define and initialize the offline download region, the plugin handles everything else for you. Because the plugin uses a service, it will continue to download map data even if your application is running in the background.

For more information about how the Mapbox Maps SDK for Android handles offline mapping, see our offline guide.

Install the Offline Plugin

To start developing an application using the Offline Plugin, you'll need to add the appropriate dependencies inside of your build.gradle file. This dependency includes the Maps SDK for Android. You can find all dependencies given below on MavenCentral.

Android's 64K method count limit

If your application is over the 64K method limit, you can shrink, obfuscate, and optimize your code with R8 or ProGuard. If those steps do not lower your method count below 64K, you can also enable multidex.

Add the dependency

To install the offline plugin, head over to the Mapbox Plugin Overview page which will walk you through adding the dependency.

1. Start Android Studio.
2. Open up your application's build.gradle file.
3. Make sure that your project's minSdkVersion is API 14 or higher.
4. Under dependencies, add a new build rule for the latest mapbox-android-plugin-offline-v9.

repositories {
  mavenCentral()
}

dependencies {
  implementation 'com.mapbox.mapboxsdk:mapbox-android-plugin-offline-{{constants. PLUGIN_PREFIX}}:0.8.0'
}

5. Click the Sync Project with Gradle Files near the toolbar in Studio.

Add the Offline Plugin

The Offline Plugin requires no permissions and is initialized by eventually passing in a built OfflineDownloadOptions object. But before you do that, you'll want to define the map region that you want to download.

Java

Kotlin

// Define region of map tiles
val definition = OfflineTilePyramidRegionDefinition(
	styleUrl, LatLngBounds.Builder()
	    .include(LatLng(latitudeNorth, longitudeEast))
	    .include(LatLng(latitudeSouth, longitudeWest))
	    .build(),
	minZoom,
	maxZoom,
	resources.displayMetrics.density
)

Build a NotificationOptions object if you want to show some sort of notification at the top of the device's screen during the download.

Java

Kotlin

// Customize the download notification's appearance
val notificationOptions = NotificationOptions.builder(this)
	.smallIconRes(R.drawable.mapbox_logo_icon)
	.returnActivity(MainActivity::class.java!!.getName())
	.build()

Finally, start the actual download of the map tiles. The NotificationsOptions object is required to start the download.

Java

Kotlin

// Start downloading the map tiles for offline use
OfflinePlugin.getInstance(this).startDownload(
	OfflineDownloadOptions.builder()
		.definition(definition)
		.metadata(OfflineUtils.convertRegionName(regionName))
		.notificationOptions(notificationOptions)
		.build()
)

Join the Mapbox Developers Discord Communityarrow-right

Was this page helpful?