MGLOfflineStorage
@interface MGLOfflineStorage : NSObject
MGLOfflineStorage implements a singleton (shared object) that manages offline packs and ambient caching. 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 in its packs
property.
Mapbox resources downloaded via this API are subject to separate Vector Tile and Raster Tile API pricing and are not included in the Maps SDK’s “unlimited” requests. See our pricing page for more information.
sharedOfflineStorage
Returns the shared offline storage object.
Declaration
Objective-C
@property (class, nonatomic, readonly)
MGLOfflineStorage *_Nonnull sharedOfflineStorage;
Swift
class var shared: MGLOfflineStorage { get }
Accessing the Delegate
delegate
The receiver’s delegate.
An offline storage object sends messages to its delegate to allow it to transform URLs before they are requested from the internet. This can be used add or remove custom parameters, or reroute certain requests to other servers or endpoints.
Declaration
Objective-C
@property (nonatomic, weak, readwrite, nullable) id<MGLOfflineStorageDelegate>
delegate;
Swift
@IBOutlet weak var delegate: MGLOfflineStorageDelegate? { get set }
Managing the Database of Offline Packs
databasePath
The file path at which offline packs and the ambient cache are stored.
To customize this path, specify the MGLOfflineStorageDatabasePath
key in Info.plist.
Declaration
Objective-C
@property (nonatomic, copy, readonly) NSString *_Nonnull databasePath;
Swift
var databasePath: String { get }
databaseURL
The file URL at which offline packs and the ambient cache are stored.
To customize this path, specify the MGLOfflineStorageDatabasePath
key in Info.plist.
Declaration
Objective-C
@property (nonatomic, copy, readonly) NSURL *_Nonnull databaseURL;
Swift
var databaseURL: URL { get }
-addContentsOfFile:withCompletionHandler:
Adds the offline packs located at the given file path to offline storage.
The file must be a valid offline pack database bundled with the application or downloaded separately.
The resulting packs are added or updated to the shared offline storage object’s packs
property, then the completion
block is executed.
Declaration
Objective-C
- (void)addContentsOfFile:(nonnull NSString *)filePath
withCompletionHandler:
(nullable MGLBatchedOfflinePackAdditionCompletionHandler)completion;
Swift
func addContents(ofFile filePath: String, withCompletionHandler completion: MGLBatchedOfflinePackAdditionCompletionHandler? = nil)
Parameters
filePath
A string representation of the file path. The file path must be writable as schema updates may be perfomed.
completion
The completion handler to call once the contents of the given file has been added to offline storage. This handler is executed asynchronously on the main queue.
-addContentsOfURL:withCompletionHandler:
Adds the offline packs located at the given URL to offline storage.
The file must be a valid offline pack database bundled with the application or downloaded separately.
The resulting packs are added or updated to the shared offline storage object’s packs
property, then the completion
block is executed.
Declaration
Objective-C
- (void)addContentsOfURL:(nonnull NSURL *)fileURL
withCompletionHandler:
(nullable MGLBatchedOfflinePackAdditionCompletionHandler)completion;
Swift
func addContents(of fileURL: URL, withCompletionHandler completion: MGLBatchedOfflinePackAdditionCompletionHandler? = nil)
Parameters
fileURL
A file URL specifying the file to add. The URL should be a valid system path. The URL must be writable as schema updates may be performed.
completion
The completion handler to call once the contents of the given file has been added to offline storage. This handler is executed asynchronously on the main queue.
Managing Offline Packs
packs
An array of all known offline packs, in the order in which they were created.
This property is set to nil
, indicating that the receiver does not yet know the existing packs, for an undefined amount of time starting from the moment the shared offline storage object is initialized until the packs are fetched from the database. After that point, this property is always non-nil, but it may be empty to indicate that no packs are present.
To detect when the shared offline storage object has finished loading its packs
property, observe KVO change notifications on the packs
key path. The initial load results in an NSKeyValueChangeSetting
change.
Declaration
Objective-C
@property (nonatomic, strong, readonly, nullable)
NSArray<MGLOfflinePack *> *packs;
Swift
var packs: [MGLOfflinePack]? { get }
-addPackForRegion:withContext:completionHandler:
Creates and registers an offline pack that downloads the resources needed to use the given region offline.
The resulting pack is added to the shared offline storage object’s packs
property, then the completion
block is executed with that pack passed in.
The pack has an initial state of MGLOfflinePackStateInactive
. To begin downloading resources, call -[MGLOfflinePack resume]
on the pack from within the completion handler. To monitor download progress, add an observer for MGLOfflinePackProgressChangedNotification
s about that pack.
To detect when any call to this method results in a new pack, observe KVO change notifications on the shared offline storage object’s packs
key path. Additions to that array result in an NSKeyValueChangeInsertion
change.
Declaration
Objective-C
- (void)addPackForRegion:(nonnull id<MGLOfflineRegion>)region
withContext:(nonnull NSData *)context
completionHandler:
(nullable MGLOfflinePackAdditionCompletionHandler)completion;
Parameters
region
A region to download.
context
Arbitrary data to store alongside the downloaded resources.
completion
The completion handler to call once the pack has been added. This handler is executed asynchronously on the main queue.
-removePack:withCompletionHandler:
Unregisters the given offline pack and allows resources that are no longer required by any remaining packs to be potentially freed.
As soon as this method is called on a pack, the pack becomes invalid; any attempt to send it a message will result in an exception being thrown. If an error occurs and the pack cannot be removed, do not attempt to reuse the pack object. Instead, if you need continued access to the pack, suspend all packs and use the -reloadPacks
method to obtain valid pointers to all the packs.
To detect when any call to this method results in a pack being removed, observe KVO change notifications on the shared offline storage object’s packs
key path. Removals from that array result in an NSKeyValueChangeRemoval
change.
When you remove an offline pack, any resources that are required by that pack, but not other packs, become eligible for deletion from offline storage. Because the backing store used for offline storage is also used as a general purpose cache for map resources, such resources may not be immediately removed if the implementation determines that they remain useful for general performance of the map.
Declaration
Objective-C
- (void)removePack:(nonnull MGLOfflinePack *)pack
withCompletionHandler:
(nullable MGLOfflinePackRemovalCompletionHandler)completion;
Swift
func removePack(_ pack: MGLOfflinePack, withCompletionHandler completion: MGLOfflinePackRemovalCompletionHandler? = nil)
Parameters
pack
The offline pack to remove.
completion
The completion handler to call once the pack has been removed. This handler is executed asynchronously on the main queue.
-invalidatePack:withCompletionHandler:
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.
Declaration
Objective-C
- (void)invalidatePack:(nonnull MGLOfflinePack *)pack
withCompletionHandler:(nonnull void (^)(NSError *_Nullable))completion;
Swift
func invalidatePack(_ pack: MGLOfflinePack, withCompletionHandler completion: @escaping (Error?) -> Void)
Parameters
pack
The offline pack to be invalidated.
completion
The completion handler to call once the pack has been removed. This handler is executed asynchronously on the main queue.
-reloadPacks
Forcibly, asynchronously reloads the packs
property. At some point after this method is called, the pointer values of the MGLOfflinePack
objects in the packs
property change, even if the underlying data for these packs has not changed. If this method is called while a pack is actively downloading, the behavior is undefined.
You typically do not need to call this method.
To detect when the shared offline storage object has finished reloading its packs
property, observe KVO change notifications on the packs
key path. A reload results in an NSKeyValueChangeSetting
change.
Declaration
Objective-C
- (void)reloadPacks;
Swift
func reloadPacks()
-setMaximumAllowedMapboxTiles:
Sets the maximum number of Mapbox-hosted tiles that may be downloaded and stored on the current device.
Once this limit is reached, an MGLOfflinePackMaximumMapboxTilesReachedNotification
is posted for every attempt to download additional tiles until already downloaded tiles are removed by calling the -removePack:withCompletionHandler:
method.
Declaration
Objective-C
- (void)setMaximumAllowedMapboxTiles:(uint64_t)maximumCount;
Swift
func setMaximumAllowedMapboxTiles(_ maximumCount: UInt64)
Parameters
maximumCount
The maximum number of tiles allowed to be downloaded.
countOfBytesCompleted
The cumulative size, measured in bytes, of all downloaded resources on disk.
The returned value includes all resources, including tiles, whether downloaded as part of an offline pack or due to caching during normal use of MGLMapView
.
Declaration
Objective-C
@property (nonatomic, readonly) unsigned long long countOfBytesCompleted;
Swift
var countOfBytesCompleted: UInt64 { get }
Managing the Ambient Cache
-setMaximumAmbientCacheSize:withCompletionHandler:
Sets the maximum ambient cache size in bytes. The default maximum cache size is 50 MB. To disable ambient caching, set the maximum ambient cache size to 0
. Setting the maximum ambient cache size does not impact the maximum size of offline packs.
This method does not limit the space available to offline packs, and data in offline packs does not count towards this limit. If you set the maximum ambient cache size to 30 MB then download 20 MB of offline packs, 30 MB will remain available for the ambient cache.
This method should be called before the map and map style have been loaded.
This method is potentially expensive, as the database will trim cached data in order to prevent the ambient cache from being larger than the specified amount.
Declaration
Objective-C
- (void)setMaximumAmbientCacheSize:(NSUInteger)cacheSize
withCompletionHandler:
(nonnull void (^)(NSError *_Nullable))completion;
Swift
func setMaximumAmbientCacheSize(_ cacheSize: UInt, withCompletionHandler completion: @escaping (Error?) -> Void)
Parameters
cacheSize
The maximum size in bytes for the ambient cache.
completion
The completion handler to call once the maximum ambient cache size has been set. This handler is executed synchronously on the main queue.
-invalidateAmbientCacheWithCompletionHandler:
Invalidates the ambient cache. This method checks that the tiles in the ambient cache match those from the server. If the local tiles do not match those on the server, they are re-downloaded.
This is recommended over clearing the cache or resetting the database because valid local tiles will not be downloaded again.
Resources shared with offline packs will not be affected by this method.
Declaration
Objective-C
- (void)invalidateAmbientCacheWithCompletionHandler:
(nonnull void (^)(NSError *_Nullable))completion;
Swift
func invalidateAmbientCache(completionHandler completion: @escaping (Error?) -> Void)
Parameters
completion
The completion handler to call once the ambient cache has been revalidated. This handler is executed asynchronously on the main queue.
-clearAmbientCacheWithCompletionHandler:
Clears the ambient cache by deleting resources. This method does not affect resources shared with offline regions.
Declaration
Objective-C
- (void)clearAmbientCacheWithCompletionHandler:
(nonnull void (^)(NSError *_Nullable))completion;
Swift
func clearAmbientCache(completionHandler completion: @escaping (Error?) -> Void)
Parameters
completion
The completion handler to call once resources from the ambient cache have been cleared. This handler is executed asynchronously on the main queue.
-resetDatabaseWithCompletionHandler:
Deletes the existing database, which includes both the ambient cache and offline packs, then reinitializes it.
You typically do not need to call this method.
Declaration
Objective-C
- (void)resetDatabaseWithCompletionHandler:
(nonnull void (^)(NSError *_Nullable))completion;
Swift
func resetDatabase(completionHandler completion: @escaping (Error?) -> Void)
Parameters
completion
The completion handler to call once the pack has database has been reset. This handler is executed asynchronously on the main queue.
-preloadData:forURL:modificationDate:expirationDate:eTag:mustRevalidate:
Inserts the provided resource into the ambient cache.
This method mimics the caching that would take place if the equivalent resource were requested in the process of map rendering. Use this method to pre-warm the cache with resources you know will be requested.
This method is asynchronous; the data may not be immediately available for in-progress requests, though subsequent requests should have access to the cached data.
To find out when the resource is ready to retrieve from the cache, use the -preloadData:forURL:modificationDate:expirationDate:eTag:mustRevalidate:completionHandler:
method.
Declaration
Objective-C
- (void)preloadData:(nonnull NSData *)data
forURL:(nonnull NSURL *)url
modificationDate:(nullable NSDate *)modified
expirationDate:(nullable NSDate *)expires
eTag:(nullable NSString *)eTag
mustRevalidate:(BOOL)mustRevalidate;
Swift
func preload(_ data: Data, for url: URL, modifiedOn modified: Date?, expiresOn expires: Date?, eTag: String?, mustRevalidate: Bool)
Parameters
data
Response data to store for this resource. The data is expected to be uncompressed; internally, the cache will compress data as necessary.
url
The URL at which the data can normally be found.
modified
The date the resource was last modified.
expires
The date after which the resource is no longer valid.
eTag
An HTTP entity tag.
mustRevalidate
A Boolean value indicating whether the data is still usable past the expiration date.
-preloadData:forURL:modificationDate:expirationDate:eTag:mustRevalidate:completionHandler:
Inserts the provided resource into the ambient cache, calling a completion handler when finished.
This method is asynchronous. The data is available for in-progress requests as soon as the completion handler is called.
This method is asynchronous; the data may not be immediately available for in-progress requests, though subsequent requests should have access to the cached data.
Declaration
Objective-C
- (void)preloadData:(nonnull NSData *)data
forURL:(nonnull NSURL *)url
modificationDate:(nullable NSDate *)modified
expirationDate:(nullable NSDate *)expires
eTag:(nullable NSString *)eTag
mustRevalidate:(BOOL)mustRevalidate
completionHandler:
(nullable MGLOfflinePreloadDataCompletionHandler)completion;
Swift
func preload(_ data: Data, for url: URL, modificationDate modified: Date?, expirationDate expires: Date?, eTag: String?, mustRevalidate: Bool, completionHandler completion: MGLOfflinePreloadDataCompletionHandler? = nil)
Parameters
data
Response data to store for this resource. The data is expected to be uncompressed; internally, the cache will compress data as necessary.
url
The URL at which the data can normally be found.
modified
The date the resource was last modified.
expires
The date after which the resource is no longer valid.
eTag
An HTTP entity tag.
mustRevalidate
A Boolean value indicating whether the data is still usable past the expiration date.
completion
The completion handler to call once the data has been preloaded. This handler is executed asynchronously on the main queue.
iOS SDK
Examples
SDK JS Reference
- MGLAnnotationImage
- MGLErrorCode
- MGLNetworkConfiguration
- MGLCircleStyleLayer
- MGLUserTrackingMode
- MGLTransition
- MGLCoordinateFormatter
- MGLImageSource
- MGLOrnamentPosition
- MGLAnnotation
- Other Type Definitions
- MGLAnnotationViewDragState
- NSValue(MGLCircleStyleLayerAdditions)
- MGLPolyline
- MGLCoordinateQuad
- MGLDEMEncoding
- Styling the Map
- MGLAttributionInfoStyle
- MGLTextTranslationAnchor
- MGLSymbolPlacement
- MGLOfflineStorage
- MGLHillshadeStyleLayer
- Other Functions
- MGLCompassButton
- MGLAttributionInfo
- MGLHeatmapStyleLayer
- Other Categories
- MGLSphericalPosition
- MGLCirclePitchAlignment
- User Interaction
- Location Updates
- MGLSphericalPosition
- Offline Maps
- MGLSymbolZOrder
- MGLIconRotationAlignment
- MGLLightAnchor
- MGLLocationManagerDelegate
- MGLAttributedExpression
- MGLLight
- MGLStyleLayer
- NSExpression(MGLAdditions)
- MGLAccountManager
- MGLShapeOfflineRegion
- Geometry
- MGLHillshadeIlluminationAnchor
- Info.plist Keys
- MGLBackgroundStyleLayer
- MGLSource
- MGLSymbolStyleLayer
- MGLResourceKind
- MGLCoordinateSpan
- MGLOrnamentVisibility
- NSValue(MGLFillExtrusionStyleLayerAdditions)
- NSValue(MGLHillshadeStyleLayerAdditions)
- MGLOfflineStorageDelegate
- MGLCluster
- Appendices
- MGLUserLocationAnnotationViewStyle
- NSValue(MGLLineStyleLayerAdditions)
- MGLStyle
- MGLMapSnapshotterDelegate
- MGLTextWritingMode
- MGLRasterResamplingMode
- MGLUserLocation
- MGLOfflinePackProgress
- MGLFillExtrusionTranslationAnchor
- MGLForegroundStyleLayer
- MGLLoggingConfiguration
- MGLTilePyramidOfflineRegion
- MGLRasterTileSource
- MGLAnnotationView
- Working with GeoJSON Data
- MGLVectorStyleLayer
- MGLMapSnapshotOptions
- MGLMapViewDelegate
- MGLMapDebugMaskOptions
- MGLMapSnapshotOverlay
- MGLIconTranslationAnchor
- Other Enumerations
- Other Protocols
- MGLTextRotationAlignment
- MGLUserLocationAnnotationView
- MGLTextPitchAlignment
- MGLCalloutViewDelegate
- Annotations
- MGLLineTranslationAnchor
- MGLShapeSource
- NSValue(MGLSymbolStyleLayerAdditions)
- MGLOfflinePackState
- MGLTextJustification
- Other Classes
- MGLMapSnapshotter
- MGLIconPitchAlignment
- MGLComputedShapeSource
- MGLRasterStyleLayer
- MGLCoordinateQuad
- MGLFeature
- MGLComputedShapeSourceDataSource
- MGLOfflineRegion
- MGLLineCap
- MGLLoggingLevel
- MGLFillExtrusionStyleLayer
- Style Content
- NSValue(MGLFillStyleLayerAdditions)
- NSValue(MGLRasterStyleLayerAdditions)
- MGLLocationManager
- MGLMapCamera
- MGLIconTextFit
- MGLLineStyleLayer
- MGLPointCollection
- MGLMultiPolygon
- MGLCircleTranslationAnchor
- Other Structures
- MGLFillStyleLayer
- MGLShapeCollection
- Primitive Shapes
- MGLTransition
- Information for Style Authors
- MGLLineJoin
- MGLPointAnnotation
- MGLTileSource
- MGLVectorTileSource
- MGLCoordinateBounds
- Gesture Recognizers
- NSValue(MGLAdditions)
- MGLCompassDirectionFormatter
- MGLIconAnchor
- Migrating to Expressions
- MGLPolygon
- MGLDistanceFormatter
- MGLFillTranslationAnchor
- MGLTextTransform
- MGLMultiPoint
- Customizing Fonts
- Maps
- MGLClockDirectionFormatter
- MGLCalloutView
- MGLTextAnchor
- MGLCircleScaleAlignment
- MGLCoordinateSpan
- MGLMapSnapshot
- MGLStylable
- MGLShape
- MGLOfflinePackProgress
- Style Primitives
- Predicates and expressions
- Formatters
- MGLMultiPolyline
- MGLTileCoordinateSystem
- MGLAnnotationVerticalAlignment
- MGLOverlay
- MGLCoordinateBounds
- Tile URL Templates
- MGLOfflinePack
- Style Layers
- MGLMapView
- Other Constants