Legacy
Android Plugins

Offline

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-v9:0.8.0'
}
  1. 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.

// Define region of map tiles
OfflineTilePyramidRegionDefinition definition = new OfflineTilePyramidRegionDefinition(
styleUrl,
new LatLngBounds.Builder()
.include(new LatLng(latitudeNorth, longitudeEast))
.include(new LatLng(latitudeSouth, longitudeWest))
.build(),
minZoom,
maxZoom,
getResources().getDisplayMetrics().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.

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

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

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

Offline tile estimator

An app can download multiple regions for offline use, but the total offline download is capped at a maximum tile count “ceiling” across all downloaded regions. The plugin set the tile ceiling to 6,000 tiles. Use our Tile Count Estimator to calculate the number of tiles required for your offline use case. Six thousand tiles cover a region roughly the size of Greater London within the M25 at zoom levels 0–15 or the contiguous United States at zoom levels 0–9. The size of these tiles on disk will vary according to the selected style.