Manage Content

_{Estimated reading time: 8 minutes}

The Maps SDK for Flutter offers comprehensive functionality for managing offline content.

The supported downloadable content types are defined in the ContentType enum:

• viewStyleHighRes: High-dpi screen optimized map styles that can be applied offline. These include both a selection of default styles and user-created styles from the studio, based on the API key.
• viewStyleLowRes: Low-dpi screen map styles, optimized for smaller file sizes while maintaining essential details.
• roadMap : Offline maps covering countries and regions. Within a downloaded region, users can perform searches, calculate routes, and navigate without an internet connection.

tip

For most use cases, the high-resolution map styles option is recommended over its low-resolution counterpart.

At this time, other values within the ContentType enum are not fully supported by the Flutter SDK.

The ContentStore class is responsible for managing and providing a list of downloadable items. Each item is represented by the ContentStoreItem class, which encapsulates details such as name, image, type, version, and size. Additionally, it offers operations for downloading and deleting content.

warning

Ensure that the API token is both set and valid. Some operations might return GemError.busy if no valid API key is set.

warning

Modifying downloaded maps (download, delete, update) may interrupt ongoing operations such as search, route calculation, or navigation. If this occurs, the onComplete callback will be triggered with a GemError.invalidated value.

List Online Content

To retrieve a list of available content from the Magic Lane servers, use the asyncGetStoreContentList method from the ContentStore class. This method returns a ProgressListener?, which allows the operation to be stopped if needed. If the operation fails to start, it returns null.

The method accepts the content type as an argument and a callback that provides:

• The operation error code
• A list of ContentStoreItem objects
• A flag indicating whether the list is cached

final ProgressListener? listener = ContentStore.asyncGetStoreContentList(ContentType.roadMap, (err, items, isCached){
    if (err != GemError.success){
    showSnackbar("Failed to get list of content store items: $err");
    } else {
        /// Do something with the items and isCached flag.
    }
});

note

The asyncGetStoreContentList method should be called only when an active internet connection is available and the current offline version is not expired. If no internet connection is available or if the current offline map version is expired, use the getLocalContentList method to retrieve the offline content list instead.

warning

Calling asyncGetStoreContentList inside onMapCreated callback doesn't work.

List Local Content

The getLocalContentList method can be used to get the list of local content available offline.

final List<ContentStoreItem> items = ContentStore.getLocalContentList(ContentType.roadMap);
/// Do something with the items

Note

The getLocalContentList method returns content store items that are either ready for use or currently downloading, as well as those pending download.

Content Store Item Fields

Fields Containing General Information

Field Name	Description
name	The name of the associated product, automatically translated.
id	The unique ID of the item in the content store.
type	The type of the product as a ContentType value.
fileName	The full path to the content data file.
totalSize	The total size of the content in bytes.
availableSize	The downloaded size of the content.
updateSize	The update size if an update is available.
status	The current status of the item as a ContentStoreItemStatus.
contentParameters	Additional information about an item is the form of a SearchableParameterList object
imgPreview	The image associated with the content store item. The user is responsible to check if the image is valid

tip

For checking if a ContentStoreItem is downloaded/available/downloading/updating use the status field value:

• unavailable: The content store item is not downloaded and cannot be used.
• completed: The content store item has been downloaded and is ready to be used.
• paused: The download operation has been paused by the user.
• downloadQueued: The download is queued and will proceed once resources are available.
• downloadWaitingNetwork: No internet connection is established, and the download will proceed once a network connection is available.
• downloadWaitingFreeNetwork: The SDK is waiting for a free network connection to continue the download.
• downloadRunning: The download is actively in progress.
• updateWaiting: An update operation is underway.

The contentParameters field provides information such as:

• For roadMap type:
  • Copyright : value of type String containing the copyright information for the road map
  • MapData provider : value of type String containing the name of the map data provider
  • Release date : value of type String containing the release date for the road map in DD.MM.YYYY format
  • Default name : value of type String containing the name of the item
• For viewStyleHighRes type:
  • Background-Color : value of type String containing the background color in decimal format (ex: 4294957738 which when converted to hex corresponds with #FFFFDAAA). Can be used to check if a style is a dark-mode or light-mode recommended style by checking the brightness of this value

The image can be got via the imgPreview getter:

final bool isImagePreviewAvailable = contentStoreItem.isImagePreviewAvailable;
if (isImagePreviewAvailable) {
    final Img previewImage = contentStoreItem.imgPreview;
    final Uint8List? bytes = previewImage.getRenderableImageBytes(
    size: Size(80, 80)
);
// Do something with the preview image.
}

warning

Content store items of type roadMap do not have an image preview. The MapDetails.getCountryFlagImg method can be used to get the flag image associated with a country code instead.

Use the countryCodes getter to obtain the country codes associated with a content store item of type roadMap.

Fields Containing Download and Update Information

Field Name	Description
clientVersion	The client version of the content.
updateVersion	The update version if an update is available. Returns a dummy object with fields set to 0 if no new version is available
downloadProgress	The current download progress as a percentage.
updateItem	The corresponding update item if an update is in progress.
isCompleted	Checks if the item has been completely downloaded.
isUpdatable	Checks if the item has a newer version available.
canDeleteContent	Checks if the content can be deleted.

While the download is in progress, you can retrieve details about the downloaded content:

• isCompleted: Returns true if the download is completed; otherwise, returns false (indicating that the download has not started or has started but not yet completed).
• downloadProgress: Returns the download progress as an integer between 0 and 100. It returns 0 if the download has not started.
• status: Returns the current status of the content store item.

Fields Relevant Only to ContentType.roadMap Type Items

Field Name	Description
chapterName	Some large countries are divided into multiple content store items (e.g., the USA is split into states). All items within the same country share the same chapter. This chapter is empty if the item is not of the RoadMap type or if the country is not divided into multiple items.
countryCodes	A list of country codes (ISO 3166-1 alpha-3) associated with the product.
language	The full language code for the product.

Download Content Store Item

For downloading a content store item, the asyncDownload method can be used:

contentStoreItem.asyncDownload(
    (error) {
        showSnackbar("Download completed with code $error");
    },
    onProgressCallback: (progress){
        print("Download progress: ${progress.toString()} / 100");
    },
);

The onCompleteCallback is invoked at the end of the operation, returning the result of the download. If the item is successfully downloaded, err is set to GemError.success. In case of an error, other values may be returned (e.g., GemError.io if the item is already downloaded).

Additionally, users can provide an optional onProgressCallback to receive real-time progress updates. This callback is triggered with the current download progress, represented as an integer between 0 and 100.

Download on Extra Charged Networks

The SDK includes functionality to restrict downloads on networks with additional charges, which may cause downloads to not work as expected.

To enable downloads on such networks, use the setAllowOffboardServiceOnExtraChargedNetwork method from the SdkSettings class.

SdkSettings.setAllowOffboardServiceOnExtraChargedNetwork(ServiceGroupType.contentService, true);

Alternatively, the asyncDownload method can be called with allowChargedNetworks set to true, bypassing the value set via setAllowOffboardServiceOnExtraChargedNetwork.

If a download operation is requested while the user is on an extra-charged network, and setAllowOffboardServiceOnExtraChargedNetwork is set to false for the content service without passing the true value for the allowChargedNetworks optional parameter, the download will be automatically scheduled and will proceed once the user switches to a non-extra-charged network. In this case, the status field of the corresponding ContentStoreItem object will be set to ContentStoreItemStatus.downloadQueued.

Pause download

The download can be paused using the pauseDownload method. This method takes an optional callback which gets called when the pause operation is completed. In order to resume the download call asyncDownload as shown above.

warning

No further operations should be performed on the ContentStoreItem object until the pause operation has completed and the corresponding callback has been invoked.

Delete Downloaded Content

Downloaded content can be removed from local storage by calling the deleteContent method on the corresponding ContentStoreItem object, after checking if the item can be removed:

if (contentStoreItem.canDeleteContent){
    final error = contentStoreItem.deleteContent();
    showSnackbar("Item ${contentStoreItem.name} deletion resulted with code $error");
} else {
    showSnackbar("Item cannot be deleted");
}