Skip to content

Latest commit

 

History

History
264 lines (150 loc) · 7.47 KB

OfflineManager.md

File metadata and controls

264 lines (150 loc) · 7.47 KB

<MapboxGL.offlineManager />

OfflineManager implements a singleton (shared object) that manages offline packs. All of this class’s instance methods are asynchronous, reflecting the fact that offline resources are stored in a database. The shared object maintains a canonical collection of offline packs.

methods

createPack(options[, progressListener][, errorListener])

Creates and registers an offline pack that downloads the resources needed to use the given region offline.

arguments

Name Type Required Description
options OfflineCreatePackOptions Yes Create options for a offline pack that specifices zoom levels, style url, and the region to download.
progressListener Callback No Callback that listens for status events while downloading the offline resource.
errorListener Callback No Callback that listens for status events while downloading the offline resource.
const progressListener = (offlineRegion, status) => console.log(offlineRegion, status);
const errorListener = (offlineRegion, err) => console.log(offlineRegion, err);

await MapboxGL.offlineManager.createPack({
  name: 'offlinePack',
  styleURL: 'mapbox://...',
  minZoom: 14,
  maxZoom: 20,
  bounds: [[neLng, neLat], [swLng, swLat]]
}, progressListener, errorListener)

invalidatePack(name)

Invalidates the specified offline pack. This method checks that the tiles in the specified offline pack match those from the server. Local tiles that do not match the latest version on the server are updated.This is more efficient than deleting the offline pack and downloading it again. If the data stored locally matches that on the server, new data will not be downloaded.

arguments

Name Type Required Description
name String Yes Name of the offline pack.
await MapboxGL.offlineManager.invalidatePack('packName')

deletePack(name)

Unregisters the given offline pack and allows resources that are no longer required by any remaining packs to be potentially freed.

arguments

Name Type Required Description
name String Yes Name of the offline pack.
await MapboxGL.offlineManager.deletePack('packName')

invalidateAmbientCache()

Forces a revalidation of the tiles in the ambient cache and downloads a fresh version of the tiles from the tile server.
This is the recommend method for clearing the cache.
This is the most efficient method because tiles in the ambient cache are re-downloaded to remove outdated data from a device.
It does not erase resources from the ambient cache or delete the database, which can be computationally expensive operations that may carry unintended side effects.

arguments

Name Type Required Description
await MapboxGL.offlineManager.invalidateAmbientCache();

clearAmbientCache()

Erases resources from the ambient cache.
This method clears the cache and decreases the amount of space that map resources take up on the device.

arguments

Name Type Required Description
await MapboxGL.offlineManager.clearAmbientCache();

migrateOfflineCache()

Migrates the offline cache from pre-v10 SDKs to the new v10 cache location

arguments

Name Type Required Description
await MapboxGL.offlineManager.migrateOfflineCache()

setMaximumAmbientCacheSize(size)

Sets the maximum size of the ambient cache in bytes. Disables the ambient cache if set to 0.
This method may be computationally expensive because it will erase resources from the ambient cache if its size is decreased.

arguments

Name Type Required Description
size Number Yes Size of ambient cache.
await MapboxGL.offlineManager.setMaximumAmbientCacheSize(5000000);

resetDatabase()

Deletes the existing database, which includes both the ambient cache and offline packs, then reinitializes it.

arguments

Name Type Required Description
await MapboxGL.offlineManager.resetDatabase();

getPacks()

Retrieves all the current offline packs that are stored in the database.

arguments

Name Type Required Description
const offlinePacks = await MapboxGL.offlineManager.getPacks();

getPack(name)

Retrieves an offline pack that is stored in the database by name.

arguments

Name Type Required Description
name String Yes Name of the offline pack.
const offlinePack = await MapboxGL.offlineManager.getPack();

mergeOfflineRegions(path)

Sideloads offline db

arguments

Name Type Required Description
path String Yes Path to offline tile db on file system.
await MapboxGL.offlineManager.mergeOfflineRegions(path);

setTileCountLimit(limit)

Sets the maximum number of Mapbox-hosted tiles that may be downloaded and stored on the current device.
The Mapbox Terms of Service prohibit changing or bypassing this limit without permission from Mapbox.

arguments

Name Type Required Description
limit Number Yes Map tile limit count.
MapboxGL.offlineManager.setTileCountLimit(1000);

setProgressEventThrottle(throttleValue)

Sets the period at which download status events will be sent over the React Native bridge.
The default is 500ms.

arguments

Name Type Required Description
throttleValue Number Yes event throttle value in ms.
MapboxGL.offlineManager.setProgressEventThrottle(500);

subscribe(packName, progressListener, errorListener)

Subscribe to download status/error events for the requested offline pack.
Note that createPack calls this internally if listeners are provided.

arguments

Name Type Required Description
packName String Yes Name of the offline pack.
progressListener Callback Yes Callback that listens for status events while downloading the offline resource.
errorListener Callback Yes Callback that listens for status events while downloading the offline resource.
const progressListener = (offlinePack, status) => console.log(offlinePack, status)
const errorListener = (offlinePack, err) => console.log(offlinePack, err)
MapboxGL.offlineManager.subscribe('packName', progressListener, errorListener)

unsubscribe(packName)

Unsubscribes any listeners associated with the offline pack.
It's a good idea to call this on componentWillUnmount.

arguments

Name Type Required Description
packName String Yes Name of the offline pack.
MapboxGL.offlineManager.unsubscribe('packName')