ArcGIS Runtime SDK for macOS

Create an offline map

ArcGIS Runtime allows your users to continue working and interacting with their maps and data if network connectivity is poor or non-existent. You can provide this capability with one of the following patterns:

  • The Services pattern: If you want to build apps that allow your users to take a map offline from ArcGIS Online or ArcGIS Enterprise, use the Services pattern. When you take a map offline this way, you download a web map, to your device, as a mobile map package (.mmpk file). Your users can interact with this offline map, edit operational data, and, when connectivity is restored, synchronize changes with the online services. All of these tasks can be undertaken by the app that you build. The Services pattern supports two workflows: a preplanned workflow, where the map's author creates the offline map in advance of users downloading it, and an on-demand workflow, where the field worker creates the offline map and downloads it.
  • The Desktop pattern: In this pattern, you use ArcGIS Pro to author and create a read-only mobile map package file that you can deliver to individual devices.

Both patterns use the mobile map package format to take maps offline. The mobile map package is a common map definition that specifies how the map is displayed and how it can be used in an app on the device. The format can exist as either a single, .mmpk file or as an unpacked directory.

For details on these patterns, see Offline. If you want to take individual layers offline instead of the map, see Create an offline layer.

Services pattern

The Services pattern allows you to build apps that can download areas of ArcGIS Online or ArcGIS Enterprise web maps to your device. Each offline map is stored as a mobile map within an unpacked mobile map package. Since the mobile map conforms to the web map specification, it can be used by the API to reconstruct the map using the basemap data, operational layers, symbology definitions, pop-up configurations, and other data stored within the mobile map package. This pattern also allows your users to edit operational data offline and synchronize it with the online service when connectivity is restored. There are two workflows available:

  • The preplanned workflow: where the map author defines a map area and generates the offline map ahead of time; so that your field workers can download the map and take into the field.
  • The on-demand workflow: where the field worker defines the map area, generates the offline map content, and downloads the map to their device.

These are described more fully in the Offline topic.

When a web map is created to be taken offline, the author must ensure that all the services used by the map have been enabled for offline use. If this is not done, your offline map may not contain all the layers and tables that you expect.

Enable services for offline use

The author of the web map must ensure that all services contained in the web map can be taken offline. The author can set these options when publishing, or later using any of the service management tools.

Raster and vector tiled services

You can allow tiled services data to be downloaded and used offline by following the instructions here:

Feature services

You can allow feature service data to be downloaded, edited, and changes synchronized by following the instructions here:

The map author must confirm that ArcGIS Online can access these tiled and feature services. The services must have public access and be shared with everyone.

You can now adopt the preplanned or on-demand workflow and create an offline map.

Note:

As of the 100.2 release, the Services pattern supports taking the following services offline:

  • Tiled and vector tiled services that have the exportTiles capability enabled.
  • Feature services that have sync enabled.
  • Feature collections that are read only and are stored along with the map information.

Preplanned workflow

The preplanned workflow allows an organization to prepare an offline map so that can be taken into the field, as required. The map author creates a map area by defining a specific geographical area of work, generating the associated data files and storing them in a mobile map package. This mobile map package resides in ArcGIS Online or ArcGIS Enterprise until the field workers are ready to download it. Once the download job completes the field worker can disconnect their device and work with the map offline. The main advantages of this workflow are:

  • The map author can define and manage very specific map areas.
  • It is quicker for the user to obtain the preplanned map area because its mobile map package has already been generated by the author. In contrast, during the on-demand workflow the user has to both generate and download the mobile map package to their device.
  • Since the mobile map package has already been created it is available to be downloaded by any number of users.

The preplanned workflow is discussed in the following steps:

  1. Create preplanned map areas
  2. Identify a map area to download
  3. Download the map area
  4. Open the offline map

Create preplanned map areas

The preplanned workflow allows you to create a mobile map, in advance, so that it can be downloaded by any field workers when they need it. To do this you need to specify the area of interest, create a map area from a web map, and generate the data packages for the services defined in the web map.

ArcGIS Online and ArcGIS Enterprise provide a user interface to allow you to manually create these preplanned map areas. You can find the step by step instructions here in the Take web maps offline ArcGIS Online guide.

Alternatively, you can create a map area and its data packages programmatically using either Python scripts or the ArcGIS REST API.

Python scripts

The ArcGIS API for Python allows you how to write python scripts to create map areas and generate their associated data packages. This is described in the managing map areas Python topic along with other useful map area management functions:

  • Update a map area and any of its packages that have been deleted or contain newer data.
  • Delete an individual data package.
  • Delete a map area along with its associated packages.
  • Inspect any of the map area's packages.
  • List the web map's current map areas.

ArcGIS Rest API

If you require more control when creating your preplanned map areas we recommend that you use the ArcGIS REST API. To create a preplanned map area there are two stages:

  • To create a map area you must run the Create Map Area task providing a bookmark or geographical extent as the area of interest. Upon completion the task will generate a new portal item of type MapArea. This task requires that the web map is enabled for offline use. It is only available to the owner of the web map and organization administrators.
  • To create the data defined by the map area you must run the Setup Map Area task providing the map area portal item ID. This will create a set of data files such as tile packages, vector tile packages and SQLite geodatabases. For good data management, we strongly recommend that you also provide a folder to organize these files. This task is only available to the map area portal item owner and organization administrators.

Note:
The map's author can create up to 16 individual map areas per web map.

Once created the preplanned map areas, and their related data, will be ready to downloaded to your device. This download phase is carried out by the Runtime app that you build, as described in the following sections.

Identify a map area to download

As discussed above, each web map can provide one or more preplanned map areas. You may wish to build an app that allows the field worker to select and download a map area or you may wish to use the app logic to download a specific map area for the field worker. Follow these steps to identify the map area:

  1. Instantiate the offline map task by passing either a map (created from a web map) or a web map's portal item to the AGSOfflineMapTask constructor.
  2. Retrieve a list of the preplanned map areas from the web map using the getPreplannedMapAreas method on the AGSOfflineMapTask.
  3. Load the preplanned map area; AGSPreplannedMapArea.
  4. Display the map area titles and thumbnails in a list, or show the map area extents or just select a map area by name.

Download the map area

Once you have identified your map area you can download the unpacked mobile map package to your device. Do this using the AGSDownloadPreplannedOfflineMapJob as follows:

  1. Create a task from an online map
  2. Create parameters to control the map content
  3. Create a job to download the map area
  4. Run the job

Create a task from an online map

Create an AGSOfflineMapTask from either an online map or its portal item.

Create parameters to control the map content

You can control whether:

  • the map's basemaps are included in the offline map
  • to continue downloading the map if a single layer fails to be taken offline.
If you wish to apply these options construct the AGSDownloadPreplannedOfflineMapParameters object using the AGSPreplannedMapArea. Set the boolean values of the includeBasemap and/or the continueOnErrors properties. Use the AGSDownloadPreplannedOfflineMapParameters when you create the download job.

Note:

This step is optional. Only create and change these parameters if required by your workflow.

Inclusion of the map's basemap

You may want to only take the operational layers offline and exclude the basemap. If you do this the file sizes will be smaller, the package generation will be faster, and the download time reduced. If you set the includeBasemap property to false, the AGSOfflineMapTask will ignore all the layers included as part of the AGSMap's basemap.

If you exclude the basemap from your offline map you might need to add a basemap into your map after it has been loaded. For example, if you have a workflow where you are sideloading a basemap to the device, there is no need to generate and download a basemap with every offline map. You can just add it as a basemap to your offline map.

Continue downloading the map if a single layer or table fails

By default the AGSDownloadPreplannedOfflineMapJob will continue to take layers and tables offline even if a layer or table has failed. Whilst this ensures that the map is taken offline there can be missing data. When this job completes you should examine the job's result to identify if and why any layers have failed. At this point you can decide whether to continue working with the map.

If you want the job to stop immediately, if a layer or table fails to download, then set the ContinueOnErrors property to be false. In this case if a map is successfully taken offline it will contain all of its layers and tables.

The failure to take a layer or table offline may be due to an intermittent network connection, loss of the service or an unsupported layer type.

Create a job to download the map area

To download a preplanned map area you need to create the AGSDownloadPreplannedOfflineMapJob.

You can create the job using the downloadPreplannedOfflineMapJob method on the AGSOfflineMapTask. Pass in the AGSPreplannedMapArea and the download directory.

However, if you have created parameters to control the map content you must create the AGSDownloadPreplannedOfflineMapJob using the downloadPreplannedOfflineMapJob method on the AGSOfflineMapTask. Pass in the AGSDownloadPreplannedOfflineMapParameters and the download directory.

Run the job

To download the preplanned map area to your device start the AGSDownloadPreplannedOfflineMapJob. Upon completion the job will return an instance of the AGSDownloadPreplannedOfflineMapResult. If at least one table or layer failed to be taken offline the hasErrors property will be true. In this case you should examine the layerErrors and tableErrors dictionaries to identify the problem.

Remember that if the job's ContinueOnErrors parameter has been set to false then the job will be terminated immediately if a single layer or table fails to be taken offline.

If you want to display the map immediately then use the AGSDownloadPreplannedOfflineMapResult.offlineMap.

Note:
Note that the job will behave the same whether it was created with or without the AGSDownloadPreplannedOfflineMapParameters.

For more details on how to work with jobs, see the Tasks and jobs topic.

On-demand workflow

The on-demand workflow allows your field workers to define an area of a map and control the map content to be taken offline. Your app can specify parameters and overrides to control the map's area of interest, max and min scale, filter features, include attachments, determine editing characteristics, and many other aspects of the map content. The aim of these parameters is to ensure that only essential map content is taken offline. Here are the steps for this on-demand workflow:

  1. Create a task from an online map.
  2. Create parameters to control the map content
  3. Create a job to generate an offline map.
  4. Run the job.

Create a task from an online map

Create an AGSOfflineMapTask from either an online map or its portal item.

Note:

We recommend that you examine the map's offline capabilities before you attempt to take the map offline to ensure that all layers and tables in the map can be taken offline. See Examine offline capabilities.

Create parameters to control the map content

When you take a map offline you want the map to contain all the content that is relevant to the field worker. However, be aware that the size of the map will directly affect the time it takes to generate the offline map and download it to your device. You can control the size of this map by limiting the map's area of interest to just the geographical area that the field worker needs. You can also manage many other aspects of the map to suit your workflow such as:

To do this follow the steps outlined in Create generate offline map parameters.

If your particular use-case requires you to have more control over how individual layers and tables are treated, you can use the AGSGenerateOfflineMapParameterOverrides to make those specific adjustments. Follow the steps outlined in Create generate offline map parameter overrides.

Create generate offline map parameters

When you take a map offline you must specify the map's area of interest to ensure that the smallest effective map is downloaded. Create the AGSGenerateOfflineMapParameters by passing an area of interest to the defaultGenerateOfflineMapParameters method on the AGSOfflineMapTask.

Once you have obtained the parameters you can set any of its properties to control the offline map content.

The parameters are described as follows:

Area of interest

The size of an offline map directly affects the time it takes to generate the offline map and download it to a device. Therefore, you should limit the map's geographical area to just the area that you need. You can define this area by passing an AGSGeometry object to the areaofInterest property. Both polygon and envelope geometries are supported.

Scale range

Tiled layers are comprised of many tiles at different levels of detail. For a particular area of interest, the amount of space, generation time, and download time will increase significantly with every increased level of detail. It's strongly recommended that you only download the levels of detail that are relevant for your app. You can control this by setting the minimum and maximum scale parameters (minScale and maxScale). If possible, choose a maximum scale that is not too “zoomed in”, as this will generate a large number of unnecessary tiles. Each service has a limit to the number of tiles which can be taken offline. It's recommended that you always set a scale range to avoid hitting this limit.

Note:

On-demand workflow will honor the scale range of a tiled layer as specified by the web map. This behavior helps to ensure that only tile data required by the offline map will be downloaded.

For example, if the web map contains a tiled layer which is set to a min scale of 1:1,000,000 and a max scale of 1:10,000, these values will be applied to the scale range requested by the user. If a user requests the data with a scale range of 1:900,000 to 1:5,000, the minimum range of 1:900,000 (min scale defined in the user's parameters) to 1:10,000 (max scale defined on the web map) will be downloaded. If the user's parameters request the default scale values of 1:0, then the range from the web map will be applied.

Inclusion of the map's basemap

In some workflows, you may want to exclude the basemap from the map and only take the operational layers offline. This provides a smaller file size, faster package generation, and a reduced download time. If you set the includeBasemap property to false, the AGSOfflineMapTask will ignore all the layers included as part of the AGSMap's basemap.

If you exclude the basemap from your offline map, you will need to add a basemap into your map after it has been loaded. For example, if you have a workflow where you are sideloading a basemap to the device, there is no need to generate and download a basemap with every offline map. You can just add it as a basemap to your offline map.

Apply feature layer definition expression filters

Whilst taking a map offline the AGSGenerateOfflineMapJob will apply the feature layer's definition expression by default. Applying the definition expression may reduce the number of features taken offline for display and sync. If you do not want to apply the definition expression then set the boolean value of IsDefinitionExpressionFilterEnabled to be false.

Return all rows from a related table

If a map contains a layer or table that has a relationship with another table then you can choose to download all, or only the related rows from the destination table. The default is to download only the related rows. If you want to return all rows then you must set the value of the destinationTableRowFilter to be AGSDestinationTableRowFilterAll.

If the table is not the direct destination of a feature table, or it is a standalone table, or it is the source of a relationship then all rows are returned.

For more information, see Essentials of relating tables.

Continue downloading the map if a single layer or table fails

By default the AGSGenerateOfflineMapJob will continue to take layers and tables offline even if a layer or table has failed. Whilst this ensures that the map is taken offline there can be missing data. When this job completes you should examine the job's result to identify if and why any layers have failed. At this point you can decide whether to continue working with the map.

If you want the job to stop immediately, if a layer or table fails to download, then set the ContinueOnErrors property to be false. In this case if a map is successfully taken offline it will contain all of its layers and tables.

The failure to take a layer or table offline may be due to an intermittent network connection, loss of the service or an unsupported layer type.

Inclusion of feature attachments

Some feature services can add attachments (pictures, videos, and other documents) to individual features. Since these files can be large, you should consider your app's offline workflow to determine whether the attachments are needed by the app, and whether attachments need to be synchronized with the service when the app is next online. These two behaviors work in conjunction with each other, and are defined using the returnLayerAttachmentOption and attachmentSyncDirection properties on the AGSGenerateOfflineMapParameters class.

  • The return layer attachment property defines which layers should contain attachments in the offline map. The options are:
    • none - None of the layers will contain any attachments.
    • allLayers - All layers will have their attachments included.
    • readOnlyLayers - Layers without editing enabled will have attachments included.
    • editableLayers - Layers with editing enabled will have attachments included.
  • The attachment sync direction defines how the attachments are synchronized with the service. The options are:
    • none - Attachments are not synchronized as part of the synchronization operation.
    • upload - Attachments are uploaded from the client to the service, but any changes on the service are not downloaded to the client.
    • bidirectional - Attachments are uploaded from client to the service, and changes on the service are pulled down to the client.
    Note:

    Attachment sync direction was introduced with ArcGIS Server 10.4.

Here are some workflows that describe how these two parameters affect each other.

  • Workflow 1 - Download attachments for all layers in the map, allow the user to add or remove attachments from the layers, and then synchronize these changes between the service and the client when online. For example: multiple users collect data on the same area and they want to synchronize all the changes with the centralized services as well as sharing changes with other people in the field.
    • returnLayerAttachmentOption.allLayers
    • attachmentSyncDirection.bidirectional
  • Workflow 2 - Download attachments for all read-only layers and update these layers when online. For example: users are offline and viewing a layer of buildings with photos that show how the buildings look. If there are any new photos added to the service, these will be downloaded to the client during synchronization when online.
    • returnLayerAttachmentOption.readOnlyLayers
    • attachmentSyncDirection.bidirectional
  • Workflow 3 - Download attachments for editable layers only and upload them to the service when online. For example: users are offline and only need to view attachments for editable layers. If there are any read-only layers that provide context for the map, their attachments aren’t included to the local map. If users remove or add any new attachments, these changes can be synchronized to the service when online.
    • returnLayerAttachmentOption.editableLayers
    • attachmentSyncDirection.bidirectional
  • Workflow 4 - Do not download any attachments but allow any new attachments to be uploaded to the service when online. For example: users are offline and collecting new attachments in the field but do not need to view existing attachments.
    • returnLayerAttachmentOption.none
    • attachmentSyncDirection.upload

Inclusion of features from editable feature layers

If users are collecting new information in the field where they do not need to access previously created features, you can create an offline map with empty editable feature layers. Do this by setting the AGSGenerateOfflineMapParameters property returnSchemaOnlyForEditableLayers to true.

Update or replace map's metadata

You can access the online map's metadata from the itemInfo property. It includes portal item properties such as the title, description, short description, and thumbnail. This information is populated from the portal item that contains the map. You can override any of these metadata properties before you take the map offline. For example, if you are creating offline maps of different areas of interest on the same map, you may want to change the map's title to indicate which area it contains.

You can also create a new AGSOfflineMapItemInfo object and manually set all the details.

Once you are happy with the changes you have made to your parameters call the generateOfflineMap method on the OfflineMapTask to create a GenerateOfflineMapJob. This job is used to generate an offline map using the specified parameters.

Create generate offline map parameter overrides

Managing the map content may be sufficient for your workflow but in some cases you may also want to control how individual layers or tables are taken offline, such as:

  • reducing the amount of data (e.g. tile data) for a given layer
  • altering the spatial extent of a given layer (for example to give coverage beyond the study area)
  • filtering features (e.g. with a where clause) to only take those which are relevant to your field work
  • taking features with null geometry (e.g. where the attributes are populated in the office but the geometry needs to be captured on site)
  • omitting individual layers
If you need this fine-grained control then you must generate the AGSGenerateOfflineMapParameterOverrides object. This object gives you access to three dictionaries containing the generate geodatabase parameters, export tile cache parameters and export vector tile parameters. Adjust any of these parameters and create the AGSGenerateOfflineMapJob using the overrides object. To control the individual layers and tables that you take offline follow these steps:

  1. Generate and modify the AGSGenerateOfflineMapParameters as described in Create generate offline map parameters above.
  2. Generate the parameter overrides object (AGSGenerateOfflineMapParameterOverrides) using the generateOfflineMapParameterOverrides method on the AGSOfflineMapTask. Provide the AGSGenerateOfflineMapParameters generated from the previous step.
  3. If, however, you just want to look up a specific set of parameters for a specific layer or table, you can construct the key from the layer or the table and obtain the parameters from the dictionary.

Once you are happy with your changes, you can obtain a AGSGenerateOfflineMapJob by calling generateOfflineMap on the offline map task supplying both the parameters and the overrides.

Create a job to generate an offline map

To generate and download the offline map you need to create a AGSGenerateOfflineMapJob by passing the AGSGenerateOfflineMapParameters and a destination path (for the offline map) to the generateOfflineMapJob method on AGSOfflineMapTask.

If you want to control the individual layer and table content you also need to provide the AGSGenerateOfflineMapParameterOverrides as well as the AGSGenerateOfflineMapParameters to the generateOfflineMapJob method on AGSOfflineMapTask

Note:
Note that the job will behave the same whether it was created using just the AGSGenerateOfflineMapParameters or using the AGSGenerateOfflineMapParameterOverrides along with the AGSGenerateOfflineMapParameters.

See the Tasks and jobs topic for more details on how to work with jobs in general.

Run the job

To generate the offline map and download it to your device start the AGSGenerateOfflineMapJob . Upon completion the job will return an instance of the AGSGenerateOfflineMapResult. If at least one table or layer failed to be taken offline the hasErrors property will be true. In this case you should examine the layerErrors and tableErrors dictionaries to identify the problem.

Remember that if the job's ContinueOnErrors parameter has been set to false then the job will be terminated immediately if a single layer or table fails to be taken offline.

If you want to display the map immediately then use the AGSGenerateOfflineMapResult.offlineMap.

If you want to open the map offline in the field, open the mobile map package stored in the downloadDirectory.

Examine offline capabilities

We do not recommend that you take a map offline unless all its layers and tables can be taken offline, because the map will not be as complete as originally designed. If you do take a map offline anyway, you should be aware of which layers or tables are missing from the offline map.

Obtain the AGSOfflineMapCapabilites object by calling the getOfflineMapCapabilities method on the offline map task. The hasErrors boolean value will indicate whether at least one layer or table cannot be taken offline. Examine the LayerCapabilities and TableCapabilities to determine which layer or table cannot be taken offline along with the reason why.

For example, if the target map is using an ArcGIS map image layer (AGSArcGISMapImageLayer), then an error will be returned stating that the layer type is not supported by the AGSOfflineMapTask.

Although this step is optional, it's recommended that you examine these capabilities as this will avoid unnecessary work on the services side.

Limitations

  • Advanced symbols are supported only if they are defined in the original service. Any overrides with advanced symbols will result in empty symbols in an offline map.
  • Area-of-interest geometries that cross the dateline are not currently supported.
  • If more than one feature layer in a map refers to the same feature service endpoint, only one feature layer will be taken offline. The other feature layers will raise an error.

Open the offline map

Offline maps created by the preplanned workflow, the on-demand workflow are stored in an unpacked mobile map package. When your app goes into the field you will need to open the map directly from the mobile map package directory stored on your device. To create the mobile map package object, pass the mobile map package directory path to the AGSMobileMapPackage constructor.

Upon loading the offline map, its metadata is accessible using the AGSMap.item property. In some situations, you may want to access the metadata from the mobile map package without loading the map itself. You can access this from the MobileMapPackage.item property.

See Display a map for more details on how to access and display maps stored in mobile map packages.

Desktop pattern

The desktop pattern is based on self-contained read-only mobile map packages files that you create with ArcGIS Pro. The mobile map package (*.mmpk file) can contain many maps, their layers and their associated data such as geodatabases, tile packages, raster datasets, as well as network datasets and locators. Each mobile map package adheres to a common map definition thus allowing it to operate as a transfer mechanism to transports maps and data across the ArcGIS platforms. For more details on creating mobile map packages using ArcGIS Pro see Create Mobile Map Package.

Note:
If you'd like ready-to-use and regularly updated basemaps, locators, or network datasets for your area of interest, you can license StreetMap Premium data in mobile map package format. For details, see Add StreetMap Premium data.

Access the mobile map package

Mobile map packages created by ArcGIS Pro can be opened directly from the mobile map package file (*.mmpk) or from an unpacked directory. If the mobile map package does not contain a raster dataset then you can open the mobile map package directly from the file. If the mobile map package contains a raster dataset then you must unpack the mobile map package to a directory first before you open it into your app.

Note:

You can package a raster dataset into a mobile map package with version 2.1 or higher of ArcGIS Pro. These mobile map packages can be read with version 100.2.1 or higher of ArcGIS Runtime.

Direct read

Most mobile map package files do not contain a raster dataset so they can be read directly by instantiating the mobile map package directly from the file. You can confirm whether you can read the mobile map package directly by checking the value returned by checkDirectReadSupportForMobileMapPackage. We recommend that you check this before attempting to open the mobile map package. Reading the file directly will save space on the device and time for the unpack process to complete.

An error will be thrown if you try to load a mobile map package file where direct read is not supported. The supplied error message will advise you to unpack the mobile map package file.

Unpack

If your mobile map package contains a raster dataset it cannot be read directly. It must be unpacked into a directory location first. Check this by examining the value of checkDirectReadSupportForMobileMapPackage. If direct reading is not supported call the unpack method to unpack the mobile map package file (*.mmpk) into a directory. You can then instantiate mobile map package using this mobile map package directory location.

Unpacking a mobile map package file into a directory obviously occupies space. To avoid an unpacking error you may want to confirm that the device has sufficient space before you unpack the mobile map package file. To save space you could delete the original mobile map package file after unpacking completes (unless you need this file for another purpose).

Open Desktop based mobile map packages

If a mobile map package file has been provided by ArcGIS Pro (Desktop pattern) we strongly recommend that you confirm whether the mobile map package can be read directly before you attempt to read it. If it cannot be read directly then you must unpack the mobile map package into a directory before accessing it. Confirm this by calling the checkDirectReadSupportForMobileMapPackage method on the AGSMobileMapPackage.

Once you have instantiated and loaded the mobile map package you can access any of the maps within the package and display them by passing them to the map view.