Offline
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.
Add the dependency
To install the offline plugin, head over to the Mapbox Plugin Overview page which will walk you through adding the dependency.
- Start Android Studio.
- Open up your application's
build.gradlefile. - Make sure that your project's
minSdkVersionis API 14 or higher. - 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'
}
- 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
);
// 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.
// Customize the download notification's appearance
NotificationOptions notificationOptions = NotificationOptions.builder(this)
.smallIconRes(R.drawable.mapbox_logo_icon)
.returnActivity(MainActivity.class.getName())
.build();
// 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.
// Start downloading the map tiles for offline use
OfflinePlugin.getInstance(this).startDownload(
OfflineDownloadOptions.builder()
.definition(definition)
.metadata(OfflineUtils.convertRegionName(regionName))
.notificationOptions(notificationOptions)
.build()
);
// Start downloading the map tiles for offline use
OfflinePlugin.getInstance(this).startDownload(
OfflineDownloadOptions.builder()
.definition(definition)
.metadata(OfflineUtils.convertRegionName(regionName))
.notificationOptions(notificationOptions)
.build()
)