Offline
If your user base spends most of their time off the grid, use the Mapbox Maps SDK's offline features to download and store pre-selected regions for use when there is a loss of connectivity. The maps they download will be fully functional and include the styles, tiles, and other resources you specify.
An offline map requires two main components:
- Style data, which is organized into style packs. Use the Offline Manager API to manage style packs.
- Map data, which is organized into preassembled tile packs. Use the tile store to manage tile packs.
These are a few key terms and concepts you may need to reference when working with offline maps:
- Offline Manager: The Offline Manager API provides a configuration interface and entrypoint for offline map functionality. It is used to manage style packs and to produce tileset descriptors that can be used with a tile store.
- Tileset descriptor: A tileset descriptor contains metadata about the tilesets, zoom ranges, and pixel ratio that cached tile packs should include. You can create tileset descriptors with the Offline Manager. Each time you create a tile pack, you will provide both a tileset descriptor and a tile region before tile data can be fetched for offline use.
- Tile region: A tile region is a geographic area for which offline data is needed. Tile regions are used by tile stores to fetch and manage tile packs necessary to provide offline support in that area. To create a tile region, a developer must specify a geometry describing each region's boundaries, source tileset(s), and zoom range(s).
- Tile pack: Tile packs are binary files made up of a parent tile and its descendant tiles covering a specific range of zoom levels and over a predefined geographic area. Because they have less per-tile and per-connection overhead, they are more efficient to transfer over the network and store on the file system than individual tiles. Tile packs only store tiles. The Offline Manager API handles metadata and descriptors related to tilesets.
- Tile Store: The tile store manages retrieving and organizing tile packs. The Maps SDK uses the tile store for the offline data such as tile regions or style pack resources. The tile store does not share tiles with the disk cache (see note on disk cache below). Although the Offline Manager manages style packs and handles creating tileset descriptors, it is the job of the tile store to manage tile regions.
- Style pack: A style pack contains a map style and the non-tile resources it depends upon, including loaded sources, fonts, sprites, and 3d models. Collectively, these resources are used to transform map data stored in tiles into a rendered map with a particular look and feel. Style packs are identified by their style URL.
When a user loads and interacts with a map on their device, any visible tiles
and style resources (style JSON, fonts, sprites, etc.) are placed in the
device's disk cache, which is located in the maps data directory defined in
the MapsResourceOptions.dataPath
. The disk cache observes when these
resources are used and makes intelligent guesses about which resources may be
needed again. When a user revisits a place on the map, it will load more
quickly if the associated resources are still present in the disk cache,
because the device will not have to request those resources from the server to
render the map.Resources are not permanently stored in the disk cache. There
are no guarantees about how long these resources will be cached, but the
least-recently used resources are normally removed to make room for newer
resources.
Limits
The cumulative number of unique maps tile packs used in the offline regions cannot be greater than 750. The SDK will not load tile regions if it would lead to exceeding the tile pack limit.
Our terms of service do not allow developers or end users to redistribute offline maps downloaded from Mapbox servers. Users of the SDK must retrieve Mapbox data intended for offline use from Mapbox servers--the data may not be preloaded, bundled or otherwise redistributed.
Specifying the style and areas that will be used offline
To render a complete map in an offline environment, the device needs to fetch two main components: a style and the required map tiles, each of which needs to be configured ahead of time.
Define a style pack
To render a map offline, the SDK must be able to fetch the non-tile resources that the map requires. This includes loaded sources, fonts, styles and sprites. The SDK calculates which resources it needs based on the StylePackLoadOptions
you specify and pass to the Offline Manager API.
let options = StylePackLoadOptions(glyphsRasterizationMode: .ideographsRasterizedLocally,
metadata: ["my-key": "my-value"],
acceptExpired: false)
Define a tileset descriptor and tile region
The tileset descriptor associates tile data (stored in a tile pack) with a given style (stored in a style pack). Use the tileset descriptor to define a tileset's zoom ranges and pixel ratio.
The tile region is a geographic region and its metadata. It is used to calculate which tile packs will be necessary to provide offline functionality in that region.
// When creating an OfflineManager instance, you must ensure that
// an access token is initialised, if you are not using a default
// from the application's Info.plist
MapboxOptions.accessToken = accessToken
let offlineManager = OfflineManager()
// 1. Create the tile set descriptor
let options = TilesetDescriptorOptions(styleURI: .outdoors, zoomRange: 0...16)
let tilesetDescriptor = offlineManager.createTilesetDescriptor(for: options)
// 2. Create the TileRegionLoadOptions
let tileRegionLoadOptions = TileRegionLoadOptions(
geometry: Geometry(coordinate: tokyoCoord),
descriptors: [tilesetDescriptor],
acceptExpired: false)
Metadata
You may provide arbitrary metadata for both style packs and tile regions. You may want to provide metadata to distinguish the various regions your users download from one another or for other record-keeping requirements within your app. This data will be associated with the style packs and regions that the system fetches and stores locally. While optional, providing a metadata object with at least a region name is encouraged. Besides a region name, you can store any arbitrary serializable information you'd like as long as it can be wrapped into a JSON
object. For example, you might wish to store the record ID of a travel itinerary that a user has created in another part of your app, and for which the offline region is being retrieved, to link the two together. The contents of the metadata you specify will only be available inside your app and will not affect your tile region download.
Add metadata to the style pack with StylePackLoadOptions
.
let metadata = ["my-key": "my-style-pack-value"]
let options = StylePackLoadOptions(glyphsRasterizationMode: .ideographsRasterizedLocally,
metadata: metadata)
Add metadata to the tile region with TileRegionLoadOptions
.
let metadata = [
"name": "my-region",
"my-other-key": "my-other-tile-region-value"]
let tileRegionLoadOptions = TileRegionLoadOptions(
geometry: Geometry(coordinate: tokyoCoord),
descriptors: [],
metadata: metadata,
acceptExpired: false)
Working with downloads
Once the above steps are complete, the system has the information necessary to know what to resources must be downloaded. The next step is to start downloads for each of your style packs and tile packs.