Cache management
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. The disk cache is located in the maps data directory defined in ResourceOptions.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.
Cache behavior
Cache behavior follows HTTP best practices and is optimized to not transfer data when not needed. For example, entity tags (or ETags) are used so that the server properly responds when data is not modified.
All map resources have expiry timestamps. The engine will try to verify with the backend if the rendered resource is still up-to-date for the tile to be re-rendered. See our Troubleshooting page on Maps API Caching for more details on updating rendered resources.
Below you can find a simplified flow chart describing map engine behavior when loading a tile.
The response for the "update network tile" request is stored in the disk cache when received. The ETag is used to determine if the data on the client is still valid. If the ETag in the request matches the ETag on the server, a "Not Modified" response is sent along with the new expiration timestamp. In this case, the data payload is not sent, saving network traffic.
Storage & volatile tiles
By default, when a tile is requested, the responses are saved to the disk cache (in other words, they are persisted) and they are cached in memory. The SDK provides an option to change this behavior so that tile responses are not saved to the disk cache, but still get cached in memory. This property is defined by setting the source to volatile - either through SDK methods or by adding "volatile": true to the tile JSON. This makes it so volatile resources are not saved between application runs.
Volatile tiles are stored in a non-persistent in-memory cache. The main behavioral difference of this scheme, compared to the scheme of non-volatile tiles, is that expired tiles are not shown. Below you can find a simplified flow chart describing map engine behavior when loading a volatile tileset.
Default cache location
The disk cache (map_data.db) is located at ./files/.mapbox/map_data/map_data.db.
Clearing the cache
The clearData method can be used to clear the temporary map data from the data path defined in the given resource options.
Tile loading
Whether you’re loading tiles from Mapbox or a third-party tile hosting service, you can use the subscribeResourceRequest event to observe all resource requests the map makes. This enables developers to note requests the map makes even after the map has fully loaded or to troubleshoot load failures.
For modifying the default tile requesting behavior for vector, raster and raster-dem sources, you may use the following methods:
minimumTileUpdateInterval: Overrides the server expiration time on the client in cases where it may be expiring too often or too rarely.tileRequestsDelay: Sets a delay for tile requests to any local storage (both disk cache and tile store), represented by a floating point value in milliseconds.tileNetworkRequestsDelay: Sets a delay for tile requests from the network, represented by a floating point value in milliseconds.