Display an offline map (on-demand)

Learn how to download and display an offline map for a user-defined geographical area of a web map.

display offline map on demand

Offline maps allow users to continue working when network connectivity is poor or lost. If a web map is enabled for offline use, a user can request that ArcGIS generates an offline map for a specified geographic area of interest.

In this tutorial, you will download an offline map for an area of interest from the web map of the stormwater network within Naperville, IL, USA. You can then use this offline map without a network connection.

Prerequisites

The following are required for this tutorial:

An ArcGIS account to access your API keys. If you don't have an account, sign up for free.
Your system meets the system requirements.

Steps

Open the Xcode project

To start the tutorial, complete the Display a web map tutorial or download and unzip the solution.
Open the .xcodeproj file in Xcode.

If you downloaded the solution project, set your API key.

An API Key enables access to services, web maps, and web scenes hosted in ArcGIS Online.

Go to your developer dashboard to get your API key. For these tutorials, use your default API key. It is scoped to include all of the services demonstrated in the tutorials.
In Xcode, in the Project Navigator, click AppDelegate.swift.

In the editor, set the APIKey property on the AGSArcGISRuntimeEnvironment with your API key.

AppDelegate.swift
Expand
Use dark colors for code blocks
Change line
    func application(_ application: UIApplication,
                     didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        // Note: it is not best practice to store API keys in source code.
        // The API key is referenced here for the convenience of this tutorial.

        AGSArcGISRuntimeEnvironment.apiKey = "YOUR_API_KEY"

        return true
    }
Expand

Get the web map item ID

You can use ArcGIS tools to create and view web maps. Use the Map Viewer to identify the web map item ID. This item ID will be used later in the tutorial.

Go to the Naperville water network in the Map Viewer in ArcGIS Online. This web map displays a stormwater network within Naperville, Illinois, USA.
Make a note of the item ID at the end of the browser's URL.
The item ID should be 5a030a31e42841a89914bd7c5ecf4d8f.

Display the web map

You can display a web map using the web map's item ID. Create an AGSMap from the web map's AGSPortalItem, and display it in your app's AGSMapView.

In Xcode, in the Project Navigator, click ViewController.swift.

In the editor, modify the setupMap() function. Provide the web map's item ID.

The code creates an AGSPortalItem using the AGSPortal that references ArcGIS Online, and the web map's itemID. The portalItem is used to create an AGSMap that is displayed in the app's AGSMapView.

ViewController.swift
Expand
Use dark colors for code blocks
Change lineChange lineChange lineChange lineChange lineChange lineChange line
    private func setupMap() {

        let map = AGSMap(
            item: AGSPortalItem(
                portal: AGSPortal.arcGISOnline(withLoginRequired: false),
                itemID: "5a030a31e42841a89914bd7c5ecf4d8f"
            )
        )
        mapView.map = map

    }
Expand

Setup the UI

Setup your UI with a button that allows your users to select an area to download using an AGSGenerateOfflineMapJob. Then, add a UIProgressView that reports the job's progress to your user.

Create a method named userSelectedDownloadOfflineMap:() and assign it the @objc keyword. The @objc method keyword exposes the method to Objective-C, a necessary step for using the UIBarButtonItem API.
For now, leave the body of the method blank.

ViewController.swift
Expand
Use dark colors for code blocks
Add line.Add line.Add line.Add line.
    @objc
    func userSelectedDownloadOfflineMap(_ sender: UIBarButtonItem) {

    }
Expand

Create a private method to setup the app's UI. Within it, create a UIProgressView and assign it to navigationItem.titleView.

ViewController.swift
Expand
Use dark colors for code blocks
Add line.Add line.Add line.Add line.
    private func setupUI() {
        navigationItem.titleView = UIProgressView()

    }
Expand

Reveal the navigation controller's toolbar and create a UIBarButtonItem that allows your user to select an area of the map to take offline.

The code creates an array of three UIBarButtonItem objects. The first and last objects reserve flexible space within the toolbar and the middle object is the download button. The button's title reads, "Download Map Area", and tapping it performs the method userSelectedDownloadOfflineMap:().

ViewController.swift
Expand
Use dark colors for code blocks
Add line.Add line.Add line.Add line.Add line.Add line.Add line.
    private func setupUI() {
        navigationItem.titleView = UIProgressView()

        navigationController?.isToolbarHidden = false
        let items = [
            UIBarButtonItem(barButtonSystemItem: .flexibleSpace, target: nil, action: nil),
            UIBarButtonItem(title: "Download Map Area", style: .plain, target: self, action: #selector(userSelectedDownloadOfflineMap)),
            UIBarButtonItem(barButtonSystemItem: .flexibleSpace, target: nil, action: nil)
        ]
        setToolbarItems(items, animated: true)

    }
Expand

In the viewDidLoad() method, call setupUI().

ViewController.swift
Expand
Use dark colors for code blocks
Add line.
    override func viewDidLoad() {
        super.viewDidLoad()

        setupMap()

        setupUI()

    }
Expand

In Xcode, in the Project Navigator, click Main.storyboard.
In the editor, select ViewController, and in the menu bar, click Editor > Embed In > Navigation Controller.
Embedding ViewController within a Navigation Controller will place a navigation bar at the top of ViewController. Inside the navigation bar you will find the progress view.

Setup the offline area graphics

A graphics overlay is a container for graphics. A graphic is added to display the selected offline area on the map.

In Xcode, in the Project Navigator, click ViewController.swift.

In the editor, create a private AGSGraphicsOverlay property to contain an offline area graphic.

ViewController.swift
Expand
Use dark colors for code blocks
Add line.
    private let graphicsOverlay = AGSGraphicsOverlay()

Expand

Define a private method to setup the graphics overlay. In the method, create an AGSSimpleRenderer to render graphics. Define a symbol for the renderer using an AGSSimpleFillSymbol and an AGSSimpleLineSymbol.

ViewController.swift
Expand
Use dark colors for code blocks
Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.
    private let graphicsOverlay = AGSGraphicsOverlay()

    private func setupGraphicsOverlay() {
        graphicsOverlay.renderer = AGSSimpleRenderer(
            symbol: AGSSimpleFillSymbol(
                style: .solid,
                color: .clear,
                outline: AGSSimpleLineSymbol(
                    style: .solid,
                    color: .red,
                    width: 3
                )
            )
        )
        mapView.graphicsOverlays.add(graphicsOverlay)
    }

Expand

Define a private method named that adds a graphic to the graphics overlay for the supplied offlineArea geometry.

ViewController.swift
Expand
Use dark colors for code blocks
Add line.Add line.Add line.Add line.
    private let graphicsOverlay = AGSGraphicsOverlay()

    private func setupGraphicsOverlay() {
        graphicsOverlay.renderer = AGSSimpleRenderer(
            symbol: AGSSimpleFillSymbol(
                style: .solid,
                color: .clear,
                outline: AGSSimpleLineSymbol(
                    style: .solid,
                    color: .red,
                    width: 3
                )
            )
        )
        mapView.graphicsOverlays.add(graphicsOverlay)
    }

    private func addGraphic(for offlineArea: AGSGeometry) {
        let graphic = AGSGraphic(geometry: offlineArea, symbol: nil)
        graphicsOverlay.graphics.add(graphic)
    }
Expand

In the viewDidLoad() method, call setupGraphicsOverlay().

ViewController.swift
Expand
Use dark colors for code blocks
Add line.
    override func viewDidLoad() {
        super.viewDidLoad()

        setupMap()

        setupUI()

        setupGraphicsOverlay()

    }
Expand

Download the map for offline use

When a user specifies an area of the web map to take offline, a number of tasks are performed.

Create a private computed URL property named temporaryDirectoryURL. This computed property will generate a unique URL at which to store the offline map on the device.

ViewController.swift
Expand
Use dark colors for code blocks
Add line.Add line.Add line.Add line.
    @objc
    func userSelectedDownloadOfflineMap(_ sender: UIBarButtonItem) {

    }

    private var temporaryDirectoryURL: URL {
        FileManager.default.temporaryDirectory
            .appendingPathComponent(ProcessInfo().globallyUniqueString)
    }

Expand

Create a private, optional AGSOfflineMapTask property named offlineMapTask. The offline map task is used to create an AGSGenerateOfflineMapJob, provided a few parameters, and a geometry.

ViewController.swift
Expand
Use dark colors for code blocks
Add line.
    private var temporaryDirectoryURL: URL {
        FileManager.default.temporaryDirectory
            .appendingPathComponent(ProcessInfo().globallyUniqueString)
    }

    private var offlineMapTask: AGSOfflineMapTask?
Expand

Create a private, optional AGSGenerateOfflineMapJob property named offlineMapJob. The offline map job handles transactions with the service to download an area of the web map offline.

ViewController.swift
Expand
Use dark colors for code blocks
Add line.
    @objc
    func userSelectedDownloadOfflineMap(_ sender: UIBarButtonItem) {

    }

    private var temporaryDirectoryURL: URL {
        FileManager.default.temporaryDirectory
            .appendingPathComponent(ProcessInfo().globallyUniqueString)
    }

    private var offlineMapTask: AGSOfflineMapTask?

    private var offlineMapJob: AGSGenerateOfflineMapJob?
Expand

Define a private method to perform the download. This method receives two parameters, an AGSGeometry defining the offline area and a URL at which to store the downloaded map.

ViewController.swift
Expand
Use dark colors for code blocks
Add line.Add line.Add line.
    private var offlineMapJob: AGSGenerateOfflineMapJob?

    private func downloadOfflineMap(with offlineArea: AGSGeometry, at downloadDirectory: URL) {

    }
Expand

Create an AGSOfflineMapTask by supplying the web map in the constructor.

ViewController.swift
Expand
Use dark colors for code blocks
Add line.Add line.
    private var offlineMapJob: AGSGenerateOfflineMapJob?

    private func downloadOfflineMap(with offlineArea: AGSGeometry, at downloadDirectory: URL) {

        guard let map = mapView.map else { return }
        offlineMapTask = AGSOfflineMapTask(onlineMap: map)

    }
Expand

Use the offline map task to generate offline map job parameters by supplying the offline area geometry.

ViewController.swift
Expand
Use dark colors for code blocks
Add line.Add line.Add line.Add line.Add line.
    private func downloadOfflineMap(with offlineArea: AGSGeometry, at downloadDirectory: URL) {

        guard let map = mapView.map else { return }
        offlineMapTask = AGSOfflineMapTask(onlineMap: map)

        offlineMapTask?.defaultGenerateOfflineMapParameters(withAreaOfInterest: offlineArea) { [weak self] parameters, error in
            guard let self = self else { return }
            guard let offlineMapTask = self.offlineMapTask else { return }

        }

    }
Expand

Create the generate offline map job by supplying the offline map task with AGSGenerateOfflineMapParameters. Use the offline map parameters to specify your preferences for the offline map. Finally, set the job's progress to the progress view's observedProgress property and start the job.

The offline map job is specified with two parameters.

Set the updateMode to .noUpdates ensures that the offline map remains read-only.
Set the esriVectorTilesDownloadOption to .useReducedFontsService to reduce the download size by stripping unused language characters from fonts.

ViewController.swift
Expand
Use dark colors for code blocks
Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.
    private func downloadOfflineMap(with offlineArea: AGSGeometry, at downloadDirectory: URL) {

        guard let map = mapView.map else { return }
        offlineMapTask = AGSOfflineMapTask(onlineMap: map)

        offlineMapTask?.defaultGenerateOfflineMapParameters(withAreaOfInterest: offlineArea) { [weak self] parameters, error in
            guard let self = self else { return }
            guard let offlineMapTask = self.offlineMapTask else { return }

            if let parameters = parameters {
                parameters.updateMode = .noUpdates
                parameters.esriVectorTilesDownloadOption = .useReducedFontsService
                let job = offlineMapTask.generateOfflineMapJob(with: parameters, downloadDirectory: downloadDirectory)
                (self.navigationItem.titleView as! UIProgressView).observedProgress = job.progress
                var n = 0
                job.start(statusHandler: { _ in
                    while n < job.messages.count {
                        print("Job message \(n): \(job.messages[n].message)")
                        n += 1
                    }
                }, completion: { [weak self] result, error in
                    guard let self = self else { return }
                    if let result = result {
                        self.mapView.map = result.offlineMap
                    } else if let error = error {
                        print("Error downloading the offline map: \(error)")
                        return
                    }
                })
                self.offlineMapJob = job
            } else if let error = error {
                print("Error fetching default parameters for the area of interest: \(error.localizedDescription)")
            }

        }

    }
Expand

In the userSelectedDownloadOfflineMap:() method, use the map view's visible area geometry to download the map.

ViewController.swift
Expand
Use dark colors for code blocks
Add line.
    @objc
    func userSelectedDownloadOfflineMap(_ sender: UIBarButtonItem) {

        guard let offlineArea = mapView.visibleArea else { return }

    }
Expand

Disable the button after the user has selected an area of the map to take offline.

ViewController.swift
Expand
Use dark colors for code blocks
Add line.
    @objc
    func userSelectedDownloadOfflineMap(_ sender: UIBarButtonItem) {

        guard let offlineArea = mapView.visibleArea else { return }

        sender.isEnabled = false

    }
Expand

Create a graphic for the selected offline area.
ViewController.swift
Expand
Use dark colors for code blocks
86 86 86 86 86 86 86 86 86 86 86 86 86 86 86 86 86 86 86 86 86 86 86 86 86 86 86 86 86 86 86 86 86 86 86 86 86 86 86 86 86 86 86 86 86 86 86 86 86 86 86 86 86 86 86 86 86 86 86 86 86 86 86 86 86 86 86 86 86 86 86 86 86 86 86 86 86 86 86 86 86