Optimize an offline map

You can optimize working with an offline map by specifying various parameters:

  • Whether to download the basemap or use a vector tile package or image tile package that is already on the device.
  • Map options such as whether to support synchronization.
  • Per-layer overrides such as which layers are included, and whether to filter their content by SQL expression or geographic area.

These parameters can help reduce the size of an offline map and the time needed to generate it, download it, and later synchronize it.

Use a local tile package as a basemap

When you download an offline map, it typically includes a significant amount of data for its basemap. You can choose to download the offline map without this basemap data, and instead configure it to use a separate tile package that is already present on the device. This tile package can be a vector tile package (VTPK) or image tile package (TPKX or TPK) and you could download it, sideload it, or even include it with the application install.

Using a local tile package for the basemap can significantly reduce the download size of an offline map. In the case of an on-demand offline map, it can also reduce the time taken to generate it.

How to use a local tile package

To use a local basemap package instead of downloading basemap data, the filename of a vector tile package (VTPK) or image tile package (TPKX or TPK) is configured in a web map's item page This configuration setting can be found in the Settings tab of the web map's item page, under "Offline" > "Advanced options" > "Use a tile package for the offline basemap".. When an offline application downloads an offline map from a web map, the ArcGIS Runtime API reads this filename. If a matching local package exists, the ArcGIS Runtime API does not include basemap data with the downloaded offline map, and the offline map will access and display the local package instead.

The steps to use a local tile package as a basemap

  1. Configure the web map to specify the filename of a tile package to use as a basemap in any offline map This configuration setting can be found in the Settings tab of the web map's item page, under "Offline" > "Advanced options" > "Use a tile package for the offline basemap".. Ensure a tile package with that filename exists on the device.
  2. Create an Offline Map Task referencing the web map.
  3. Create default Download Preplanned Offline Map Parameters or Generate Offline Map Parameters.
  4. Set the Reference Basemap Directory parameter to the on-device folder containing the vector tile package (VTPK) or image tile package (TPKX or TPK) to be used as the basemap (see step 1).
  5. Create a Download Preplanned Offline Map Job or Generate Offline Map Job_ with the modified parameters.
  6. Start the job and wait for it to complete, returning a Map, which is ready for use.

If a web map has not been configured with a local package name, you can still choose to use an on-device tile package instead of downloading basemap data. You can also use this approach if you have a local tile package that does not match the filename that is configured on the web map.

The steps to use a local tile package as a basemap (application driven)

  1. Create an Offline Map Task referencing the web map.
  2. Create default Download Preplanned Offline Map Parameters or Generate Offline Map Parameters.
  3. Set the Include Basemap parameter to false.
  4. Set the Reference Basemap Directory parameter to the on-device folder containing the vector tile package (VTPK) or image tile package (TPKX or TPK) to be used as the basemap. The name of this file should match what has been configured in the web map settings.
  5. Set the Reference Basemap Filename parameter to the filename of vector tile package (VTPK) or image tile package (TPKX or TPK) to be used as the basemap.
  6. Create a Download Preplanned Offline Map Job or Generate Offline Map Job_ with the modified parameters.
  7. Start the job and wait for it to complete, returning a Map, which is ready for use.

Map options

You can control certain parameters at the offline map level when generating an on-demand offline map.

These parameters include:

  • Whether to support synchronizing offline edits.
  • Whether attachments are included in the offline data.
  • Whether to download optimized styles for layers in the basemap layer service. By default, a vector tile basemap layer in the basemap layer service uses a full set of fonts for multiple languages. Applications that only need Latin fonts can opt-in to downloading a smaller set of fonts. This typically reduces the size of the downloaded fonts by about 80MB.
  • Whether to download data in a feature layer that meets the layer's SQL definition expression filter (the default), or download all data.
  • Whether to include data content, or just download empty tables (useful for feature collection applications).
  • For related tables: whether to only include records related to included geographic data, or to include all records.
  • Whether to include layers that cannot have their content downloaded as references to online data, or to exclude those layers from the offline map entirely.

The typical steps to set per-map parameters

  1. Create an Offline Map Task referencing the web map.
  2. Create a set of Generate Offline Map Parameters.
  3. Update the parameters as needed.
  4. Create a Generate Offline Map Job with the modified parameters.
  5. Start the job and wait for it to complete, returning a Map, which is ready for use.

Per-layer overrides

On-demand offline maps also allow you to control specific layer-by-layer behavior when the offline map is generated. Some of this behavior also influences how offline edits are synchronized with the source web map. These settings also apply to non-spatial tables that are included in the offline map.

These layer-by-layer/table-by-table overrides include:

  • Whether to include a specific layer.
  • The geographic area to download for a layer.
  • Whether attachments are included in the offline data.
  • Whether to support uploading new attachments even if no attachments are downloaded.
  • Whether related records are downloaded.
  • Whether to include any data, or just download an empty table (useful for feature collection applications).
  • A SQL where clause to filter data that is downloaded (offline edits that do not match the filter will be discarded upon synchronization).
  • Whether to discard offline edits that lie outside the original offline map area when synchronizing.
  • Whether to allow synchronization control on a layer-by-layer basis or to force synchronization to include all layers.This applies only if multiple layers were downloaded from a single feature service.

The typical steps to set per-layer/per-table overrides

  1. Create an Offline Map Task referencing the web map.
  2. Create a set of Generate Offline Map Parameters with the geographic area you will download.
  3. Use the Offline Map Task to convert these parameters into fine-grained settings for downloading each layer or table in the web map.
  4. Override any of these settings on a per-layer or per-table basis as needed.
  5. Create a Generate Offline Map Job with the parameters and overrides.
  6. Start the job and wait for it to complete, returning a Map, which is ready for use.