mapbox-plugin-offline

An alternative to Mapbox offline plugin, written in Kotlin.

License	MIT
GroupId	io.github.xit0c
ArtifactId	mapbox-plugin-offline
Last Version	3.0.0
Release Date	May 16, 2021
Type	aar
Description	mapbox-plugin-offline An alternative to Mapbox offline plugin, written in Kotlin.
Project URL	https://github.com/xit0c/mapbox-plugin-offline
Source Code Management	https://github.com/xit0c/mapbox-plugin-offline

Download mapbox-plugin-offline

Filename	Size
mapbox-plugin-offline-3.0.0.pom
mapbox-plugin-offline-3.0.0-sources.jar	12 KB
mapbox-plugin-offline-3.0.0-javadoc.jar	44 KB

How to add to project

Apache Maven

<!-- https://jarcasting.com/artifacts/io.github.xit0c/mapbox-plugin-offline/ -->
<dependency>
    <groupId>io.github.xit0c</groupId>
    <artifactId>mapbox-plugin-offline</artifactId>
    <version>3.0.0</version>
    <type>aar</type>
</dependency>

Gradle Groovy

// https://jarcasting.com/artifacts/io.github.xit0c/mapbox-plugin-offline/
implementation 'io.github.xit0c:mapbox-plugin-offline:3.0.0'

Gradle Kotlin

// https://jarcasting.com/artifacts/io.github.xit0c/mapbox-plugin-offline/
implementation ("io.github.xit0c:mapbox-plugin-offline:3.0.0")

Apache Buildr

'io.github.xit0c:mapbox-plugin-offline:aar:3.0.0'

Apache Ivy

<dependency org="io.github.xit0c" name="mapbox-plugin-offline" rev="3.0.0">
  <artifact name="mapbox-plugin-offline" type="aar" />
</dependency>

Groovy Grape

@Grapes(
@Grab(group='io.github.xit0c', module='mapbox-plugin-offline', version='3.0.0')
)

Scala SBT

libraryDependencies += "io.github.xit0c" % "mapbox-plugin-offline" % "3.0.0"

Leiningen

[io.github.xit0c/mapbox-plugin-offline "3.0.0"]

Dependencies

runtime (4)

Group / Artifact	Type	Version
org.jetbrains.kotlin : kotlin-parcelize-runtime	jar	1.5.0
org.jetbrains.kotlin : kotlin-stdlib	jar	1.5.0
androidx.core » core-ktx	jar	1.3.2
com.mapbox.mapboxsdk : mapbox-android-sdk	jar	9.6.1

Project Modules

There are no modules declared in this project.

mapbox-plugin-offline

An alternative to Mapbox offline plugin for Android, written in Kotlin. Generated docs available here.

Getting Started

This plugin is published to Maven Central. Include it in your build.gradle file with

implementation 'io.github.xit0c:mapbox-plugin-offline:3.0.0'

Note: older versions (<= 2.2.3) were published to Bintray's JCenter before its shutdown as

implementation 'dev.micheleferretti:mapbox-plugin-offline:2.2.3'

Usage

OfflineService is the core of this plugin. It manages the downloads, shows notifications and dispatches events that OfflineDownloadReceiver(s) can listen to.

Its static methods OfflineService.startDownload() and OfflineService.cancelDownload(), as their names suggest, can be used to start and cancel a download respectively. While executing these actions, the service shows a notification to make the user aware of what's going on.

Start a download

Create a NotificationOptions: the options you provide will be used to build OfflineService's notifications.

val notificationOptions = NotificationOptions(
    R.drawable.small_icon, // @DrawableRes for notification's small icon
    contentTitle, // notification's content title
    downloadContentText, // notification's content text shown during download
    cancelContentText, // notification's content text shown during cancellation
    cancelActionText, // notification's cancel action text
    true, // whether or not to add a map snapshot of the region as notification's large icon
    MyReturnActivity::class.java // Activity to start on notification tap (can be null)
)

Then, together with an OfflineRegionDefinition and an optional metadata ByteArray, use it to create an OfflineDownloadOptions

val offlineDownloadOptions = OfflineDownloadOptions(
    offlineRegionDefinition, // the OfflineRegionDefinition to download
    notificationOptions, // the NotificationOptions created before
    metadata // can be null
)

Here's a tip!
OfflineDownloadOptions has a secondary constructor that takes a String as third argument. It's a convenient method to store the region's name as region metadata: all this secondary constructor does is convert the String via OfflineUtils.convertRegionName(), then use the result to call the primary.

Now a new download can be started with

OfflineService.startDownload(context, offlineDownloadOptions)

Cancel a download

To cancel an ongoing download just call

OfflineService.cancelDownload(context, regionId)

Listen to events

OfflineDownloadReceiver handles all the events the OfflineService send.

Its private activeDownloads property, accessible via getActiveDownloads(), is a list of OfflineDownload that gets updated by the receiver (once registered) when certain events occur and is cleared when unregister() is called.

Extend OfflineDownloadReceiver and override only the methods/events you need, then register it with register() to start listening.

Available methods/events list:

• onCreate(context: Context, download: OfflineDownload)
  Download created.

• onCreateError(context: Context, options: OfflineDownloadOptions, error: String?)
  Download creation failed.

• onDelete(context: Context, download: OfflineDownload)
  Download canceled and region deleted.

• onDeleteError(context: Context, download: OfflineDownload, error: String?)
  Download canceled but region deletion failed.

• onStatusChanged(context: Context, download: OfflineDownload)
  Download status changed (progression or completion).

• onObserverError(context: Context, download: OfflineDownload, reason: String?, message: String?)
  Download observer failure.

• onTileCountLimitExceeded(context: Context, download: OfflineDownload, limit: Long)
  Download tile count exceeded.

• onActiveDownloadsChanged(context: Context, activeDownloads: List<OfflineDownload>)
  The active downloads list has changed because one of the events above has occurred (except onCreateError(), since in that case the download never became active). Override this method when all you want to do is observe the active downloads, without knowing the reasons they change.

Versions

Version
3.0.0 May 16, 2021