Display an offline map (on-demand) | ArcGIS Maps SDK for Swift

Learn how to download and display an offline map An offline map is a map area and its data content downloaded from an offline-enabled web map for use in offline applications built with ArcGIS Maps SDKs for Native Apps. Learn more for a user-defined geographical area of a web map A web map is a map stored as a JSON object that defines properties such as the basemap layer, data layers, layer styles, and pop-up styles. Its JSON structure is defined by the web map specification. Learn more .

display offline map on demand

Offline maps An offline map is a map area and its data content downloaded from an offline-enabled web map for use in offline applications built with ArcGIS Maps SDKs for Native Apps. Learn more allow users to continue working when network connectivity is poor or lost. If a web map A web map is a map stored as a JSON object that defines properties such as the basemap layer, data layers, layer styles, and pop-up styles. Its JSON structure is defined by the web map specification. Learn more 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 An offline map is a map area and its data content downloaded from an offline-enabled web map for use in offline applications built with ArcGIS Maps SDKs for Native Apps. Learn more for an area of interest from the web map A web map is a map stored as a JSON object that defines properties such as the basemap layer, data layers, layer styles, and pop-up styles. Its JSON structure is defined by the web map specification. Learn more of the stormwater network within Naperville, IL, USA . You can then use this offline map without a network connection.

Prerequisites

Before starting this tutorial:

You need an ArcGIS Location Platform or ArcGIS Online account.
Your system meets the system requirements.

Develop or Download

You have two options for completing this tutorial:

Option 1: Develop the code or
Option 2: Download the completed solution

Option 1: Develop the code

To start the tutorial, complete the Display a map tutorial. This creates a map to display the Santa Monica Mountains in California using the topographic basemap from the ArcGIS Basemap Styles service The ArcGIS Basemap Styles service, also referred to as the Basemap Styles service, is a location service that provides basemap styles and data for the world. It returns styles as Mapbox styles and web maps, and data as vector tiles and/or map tiles. It supports all of the styles in the ArcGIS Basemap style and Open Basemap style family. An ArcGIS Location Platform or ArcGIS Online account is required to use the service. Learn more .

Open an Xcode project

Open the .xcodeproj project you created by completing the Display a map tutorial.
Continue with the following instructions to download and display an offline map for a user-defined geographical area of a web map.

Get the web map item ID

You can use ArcGIS tools Tools, also known as developer tools, are ArcGIS software applications such as portal and ArcGIS Pro that developers can use to prepare content and data for custom applications they are building. Learn more to create and view web maps A web map is a map stored as a JSON object that defines properties such as the basemap layer, data layers, layer styles, and pop-up styles. Its JSON structure is defined by the web map specification. Learn more . Use the Map Viewer Map Viewer is a browser-based mapping tool that can view, create, and save web maps. It can also perform mapping, visualization, and spatial analysis operations. Learn more to identify the web map item ID An item ID is a unique identifier representing a single item stored, managed, and accessed in a portal, such as a web map, hosted layer, or file. Learn more . This item ID will be used later in the tutorial.

Go to the Naperville water network in the Map Viewer Map Viewer is a browser-based mapping tool that can view, create, and save web maps. It can also perform mapping, visualization, and spatial analysis operations. Learn more in ArcGIS Online ArcGIS Online is a GIS mapping, analytics, data hosting, and content management software as a service (SaaS) product. It includes applications, tools, APIs, and location services for users and developers. It is subscription-based and requires an ArcGIS Online account. Learn more . This web map A web map is a map stored as a JSON object that defines properties such as the basemap layer, data layers, layer styles, and pop-up styles. Its JSON structure is defined by the web map specification. Learn more displays a stormwater network within Naperville, Illinois, USA.
Make a note of the item ID An item ID is a unique identifier representing a single item stored, managed, and accessed in a portal, such as a web map, hosted layer, or file. Learn more at the end of the browser’s URL.

The item ID should be 5a030a31e42841a89914bd7c5ecf4d8f.

Display the web map

You can display a web map A web map is a map stored as a JSON object that defines properties such as the basemap layer, data layers, layer styles, and pop-up styles. Its JSON structure is defined by the web map specification. Learn more using the web map’s item ID An item ID is a unique identifier representing a single item stored, managed, and accessed in a portal, such as a web map, hosted layer, or file. Learn more . Create an Map from the web map’s PortalItem, and display it in your app’s MapView.

In Xcode, in the Project Navigator, click ContentView.swift.
In the editor, modify the map variable. Provide the web map’s item ID.

The code creates an PortalItem using the Portal that references ArcGIS Online ArcGIS Online is a GIS mapping, analytics, data hosting, and content management software as a service (SaaS) product. It includes applications, tools, APIs, and location services for users and developers. It is subscription-based and requires an ArcGIS Online account. Learn more , and the web map’s itemID. The portalItem is used to create an Map that is displayed in the app’s MapView.
ContentView.swift
1 @State private var map = Map( 2 item: PortalItem( 3 portal: .arcGISOnline(connection: .anonymous), 4 5 id: PortalItem.ID("5a030a31e42841a89914bd7c5ecf4d8f")! 6 7 ) 8 )

Create a private class named Model of type ObservableObject and add a @StateObject variable of the Model to the ContentView. Make the Model the @MainActor. See the programming patterns page for more information on how to manage states.

ContentView.swift

1
import SwiftUI
2
import ArcGIS
3

4
@MainActor
5
private class Model: ObservableObject {
6

7
}
8

9
struct ContentView: View {
10

11
    @StateObject private var model = Model()
12

13
    @State private var map = Map(
14
        item: PortalItem(
15
            portal: .arcGISOnline(connection: .anonymous),
16

17
            id: PortalItem.ID("5a030a31e42841a89914bd7c5ecf4d8f")!
18

19
        )
20
    )

In the Model, create a @Published variable named offlineMap of type Map to store the output of the downloaded map.
ContentView.swift
1 @MainActor 2 private class Model: ObservableObject { 3 4 @Published private(set) var offlineMap: Map! 5 6 }

In the ContentView, modify the map view to display the model’s offline map or the online map. If offlineMap has no value, then the map view should display the online map.

ContentView.swift

1
struct ContentView: View {
2

3
    @StateObject private var model = Model()
4

5
    @State private var map = Map(
6
        item: PortalItem(
7
            portal: .arcGISOnline(connection: .anonymous),
8

9
            id: PortalItem.ID("5a030a31e42841a89914bd7c5ecf4d8f")!
10

11
        )
12
    )
13

14
    var body: some View {
15

16
                MapView(map: model.offlineMap ?? map)
17

18
    }
19

20
}

Specify an area of the web map to take offline

Specify an area of the web map A web map is a map stored as a JSON object that defines properties such as the basemap layer, data layers, layer styles, and pop-up styles. Its JSON structure is defined by the web map specification. Learn more to take offline using either an Envelope or a Polygon. Use views to obtain data about the map view and an overlay to indicate the area on the map to be downloaded.

In the ContentView, wrap the map view inside a MapViewReader and expose the MapViewProxy in its closure. Name it mapView. MapViewProxy provides operations that can be performed on the map view, such as envelope(fromViewRect:). For more information see Perform GeoView operations.

ContentView.swift

1
struct ContentView: View {
2

3
    @StateObject private var model = Model()
4

5
    @State private var map = Map(
6
        item: PortalItem(
7
            portal: .arcGISOnline(connection: .anonymous),
8

9
            id: PortalItem.ID("5a030a31e42841a89914bd7c5ecf4d8f")!
10

11
        )
12
    )
13

14
    var body: some View {
15

16
            MapViewReader { mapView in
17

18
                MapView(map: model.offlineMap ?? map)
19

20
            }
21

22
    }
23

24
}

Wrap the map view reader inside a GeometryReader and expose the GeometryProxy in its closure. Name it geometry. GeometryProxy provides access to the size and coordinate space (for anchor resolution) of the views enclosed in the geometry reader.

ContentView.swift

1
struct ContentView: View {
2

3
    @StateObject private var model = Model()
4

5
    @State private var map = Map(
6
        item: PortalItem(
7
            portal: .arcGISOnline(connection: .anonymous),
8

9
            id: PortalItem.ID("5a030a31e42841a89914bd7c5ecf4d8f")!
10

11
        )
12
    )
13

14
    var body: some View {
15

16
        GeometryReader { geometry in
17

18
            MapViewReader { mapView in
19

20
                MapView(map: model.offlineMap ?? map)
21

22
            }
23

24
        }
25

26
    }
27

28
}

Add an .overlay modifier to the map view. The overlay contains a red rectangle that encompasses an area to be downloaded.

ContentView.swift

1
    var body: some View {
2

3
        GeometryReader { geometry in
4

5
            MapViewReader { mapView in
6

7
                MapView(map: model.offlineMap ?? map)
8

9
                    .overlay {
10
                        Rectangle()
11
                            .stroke(.red, lineWidth: 2)
12
                            .padding(EdgeInsets(top: 60, leading: 20, bottom: 100, trailing: 20))
13
                            .opacity(model.offlineMap == nil ? 1 : 0)
14
                    }
15

16
            }
17

18
        }
19

20
    }

Download and display the offline map

Generate and download an offline map An offline map is a map area and its data content downloaded from an offline-enabled web map for use in offline applications built with ArcGIS Maps SDKs for Native Apps. Learn more for a specified area of interest using an asynchronous task. When complete, it will provide the offline map that can be displayed in a map view A map view is a user interface that displays map layers and graphics in 2D. It controls the area (extent) of the map that is visible and supports user interactions such as pan and zoom. Learn more .

In the Model, create a @Published GenerateOfflineMapJob variable called generateOfflineMapJob and a OfflineMapTask variable called offlineMapTask. These objects will contain the job and task needed to perform the download function. Learn more about Tasks and jobs.
ContentView.swift
1 @MainActor 2 private class Model: ObservableObject { 3 4 @Published private(set) var offlineMap: Map! 5 6 @Published private(set) var generateOfflineMapJob: GenerateOfflineMapJob! 7 private var offlineMapTask: OfflineMapTask! 8 9 }

Create a @Published Boolean variable called isGenerateDisabled and set it to true. Create a variable called isShowingAlert and set it to false. These variables will be used to determine if the download button is enabled and if the completion alert is present.

ContentView.swift

1
@MainActor
2
private class Model: ObservableObject {
3

4
    @Published private(set) var offlineMap: Map!
5

6
    @Published private(set) var generateOfflineMapJob: GenerateOfflineMapJob!
7
    private var offlineMapTask: OfflineMapTask!
8

9
    @Published private(set) var isGenerateDisabled = true
10
    @Published var isShowingAlert = false
11

12
}

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

ContentView.swift

1
@MainActor
2
private class Model: ObservableObject {
3

4
    @Published private(set) var offlineMap: Map!
5

6
    @Published private(set) var generateOfflineMapJob: GenerateOfflineMapJob!
7
    private var offlineMapTask: OfflineMapTask!
8

9
    @Published private(set) var isGenerateDisabled = true
10
    @Published var isShowingAlert = false
11

12
    private let temporaryDirectory: URL = {
13
        // swiftlint:disable:next force_try
14
        return try! FileManager.default.url(
15
            for: .itemReplacementDirectory,
16
            in: .userDomainMask,
17
            appropriateFor: FileManager.default.temporaryDirectory,
18
            create: true
19
        )
20
    }()
21

22
}

Create a deinit function to remove the temporary directory after the app closes.

ContentView.swift

1
@MainActor
2
private class Model: ObservableObject {
3

4
    @Published private(set) var offlineMap: Map!
5

6
    @Published private(set) var generateOfflineMapJob: GenerateOfflineMapJob!
7
    private var offlineMapTask: OfflineMapTask!
8

9
    @Published private(set) var isGenerateDisabled = true
10
    @Published var isShowingAlert = false
11

12
    private let temporaryDirectory: URL = {
13
        // swiftlint:disable:next force_try
14
        return try! FileManager.default.url(
15
            for: .itemReplacementDirectory,
16
            in: .userDomainMask,
17
            appropriateFor: FileManager.default.temporaryDirectory,
18
            create: true
19
        )
20
    }()
21

22
    deinit {
23
        try? FileManager.default.removeItem(at: temporaryDirectory)
24
    }
25

26
}

Create an asynchronous function called initializeOfflineMapTask(onlineMap:). This function loads the online map and creates a OfflineMapTask from it. Set the isGenerateDisabled Boolean to false.

ContentView.swift

1
@MainActor
2
private class Model: ObservableObject {
3

4
    @Published private(set) var offlineMap: Map!
5

6
    @Published private(set) var generateOfflineMapJob: GenerateOfflineMapJob!
7
    private var offlineMapTask: OfflineMapTask!
8

9
    @Published private(set) var isGenerateDisabled = true
10
    @Published var isShowingAlert = false
11

12
    private let temporaryDirectory: URL = {
13
        // swiftlint:disable:next force_try
14
        return try! FileManager.default.url(
15
            for: .itemReplacementDirectory,
16
            in: .userDomainMask,
17
            appropriateFor: FileManager.default.temporaryDirectory,
18
            create: true
19
        )
20
    }()
21

22
    deinit {
23
        try? FileManager.default.removeItem(at: temporaryDirectory)
24
    }
25

26
    func initializeOfflineMapTask(onlineMap: Map) async {
27
        do {
28
            try await onlineMap.load()
29
            offlineMapTask = OfflineMapTask(onlineMap: onlineMap)
30
            isGenerateDisabled = false
31
        } catch {
32
            print(error)
33
        }
34
    }
35

36
}

In the ContentView, call the initializeOfflineMapTask(onlineMap:) function in a .task modifier, passing in the online map. The task’s function is called as the map view appears.

ContentView.swift

1
struct ContentView: View {
2

3
    @StateObject private var model = Model()
4

5
    @State private var map = Map(
6
        item: PortalItem(
7
            portal: .arcGISOnline(connection: .anonymous),
8

9
            id: PortalItem.ID("5a030a31e42841a89914bd7c5ecf4d8f")!
10

11
        )
12
    )
13

14
    var body: some View {
15

16
        GeometryReader { geometry in
17

18
            MapViewReader { mapView in
19

20
                MapView(map: model.offlineMap ?? map)
21

22
                    .task {
23
                        await model.initializeOfflineMapTask(onlineMap: map)
24
                    }
25

26
                    .overlay {
27
                        Rectangle()
28
                            .stroke(.red, lineWidth: 2)
29
                            .padding(EdgeInsets(top: 60, leading: 20, bottom: 100, trailing: 20))
30
                            .opacity(model.offlineMap == nil ? 1 : 0)
31
                    }
32

33
            }
34

35
        }
36

37
    }
38

39
}

In the Model, create an asynchronous function called makeGenerateOfflineMapParameters(areaOfInterest:). The function returns GenerateOfflineMapParameters, created using offlineMapTask and the area of interest.

ContentView.swift

1
@MainActor
2
private class Model: ObservableObject {
3

4
    @Published private(set) var offlineMap: Map!
5

6
    @Published private(set) var generateOfflineMapJob: GenerateOfflineMapJob!
7
    private var offlineMapTask: OfflineMapTask!
8

9
    @Published private(set) var isGenerateDisabled = true
10
    @Published var isShowingAlert = false
11

12
    private let temporaryDirectory: URL = {
13
        // swiftlint:disable:next force_try
14
        return try! FileManager.default.url(
15
            for: .itemReplacementDirectory,
16
            in: .userDomainMask,
17
            appropriateFor: FileManager.default.temporaryDirectory,
18
            create: true
19
        )
20
    }()
21

22
    deinit {
23
        try? FileManager.default.removeItem(at: temporaryDirectory)
24
    }
25

26
    func initializeOfflineMapTask(onlineMap: Map) async {
27
        do {
28
            try await onlineMap.load()
29
            offlineMapTask = OfflineMapTask(onlineMap: onlineMap)
30
            isGenerateDisabled = false
31
        } catch {
32
            print(error)
33
        }
34
    }
35

36
    private func makeGenerateOfflineMapParameters(areaOfInterest: Envelope) async -> GenerateOfflineMapParameters? {
37
        do {
38
            return try await offlineMapTask.makeDefaultGenerateOfflineMapParameters(areaOfInterest: areaOfInterest)
39
        } catch {
40
            print(error)
41
            return nil
42
        }
43
    }
44

45
}

Create an asynchronous function called generateOfflineMap(extent:). This function is called when the user initiates the download. Set the isGenerateDisabled Boolean to true and create default parameters for the given extent. If the parameters fail to create, set the isGenerateDisabled Boolean to false.

ContentView.swift

1
@MainActor
2
private class Model: ObservableObject {
3

4
    @Published private(set) var offlineMap: Map!
5

6
    @Published private(set) var generateOfflineMapJob: GenerateOfflineMapJob!
7
    private var offlineMapTask: OfflineMapTask!
8

9
    @Published private(set) var isGenerateDisabled = true
10
    @Published var isShowingAlert = false
11

12
    private let temporaryDirectory: URL = {
13
        // swiftlint:disable:next force_try
14
        return try! FileManager.default.url(
15
            for: .itemReplacementDirectory,
16
            in: .userDomainMask,
17
            appropriateFor: FileManager.default.temporaryDirectory,
18
            create: true
19
        )
20
    }()
21

22
    deinit {
23
        try? FileManager.default.removeItem(at: temporaryDirectory)
24
    }
25

26
    func initializeOfflineMapTask(onlineMap: Map) async {
27
        do {
28
            try await onlineMap.load()
29
            offlineMapTask = OfflineMapTask(onlineMap: onlineMap)
30
            isGenerateDisabled = false
31
        } catch {
32
            print(error)
33
        }
34
    }
35

36
    private func makeGenerateOfflineMapParameters(areaOfInterest: Envelope) async -> GenerateOfflineMapParameters? {
37
        do {
38
            return try await offlineMapTask.makeDefaultGenerateOfflineMapParameters(areaOfInterest: areaOfInterest)
39
        } catch {
40
            print(error)
41
            return nil
42
        }
43
    }
44

45
    func generateOfflineMap(extent: Envelope) async {
46
        isGenerateDisabled = true
47
        guard let parameters = await makeGenerateOfflineMapParameters(areaOfInterest: extent) else {
48
            isGenerateDisabled = false
49
            return
50
        }
51

52
    }
53

54
}

Create an offline map job using makeGenerateOfflineMapJob(parameters:downloadDirectory:overrides:) and start the job.

ContentView.swift

1
    func generateOfflineMap(extent: Envelope) async {
2
        isGenerateDisabled = true
3
        guard let parameters = await makeGenerateOfflineMapParameters(areaOfInterest: extent) else {
4
            isGenerateDisabled = false
5
            return
6
        }
7

8
        generateOfflineMapJob = offlineMapTask.makeGenerateOfflineMapJob(
9
            parameters: parameters,
10
            downloadDirectory: temporaryDirectory
11
        )
12
        generateOfflineMapJob.start()
13

14
    }

In a defer closure, ensure the job does not continue running by setting it to nil and set the isGenerateDisabled value according to whether or not offlineMap is instantiated.

ContentView.swift

1
    func generateOfflineMap(extent: Envelope) async {
2
        isGenerateDisabled = true
3
        guard let parameters = await makeGenerateOfflineMapParameters(areaOfInterest: extent) else {
4
            isGenerateDisabled = false
5
            return
6
        }
7

8
        generateOfflineMapJob = offlineMapTask.makeGenerateOfflineMapJob(
9
            parameters: parameters,
10
            downloadDirectory: temporaryDirectory
11
        )
12
        generateOfflineMapJob.start()
13

14
        defer {
15
            generateOfflineMapJob = nil
16
            isGenerateDisabled = offlineMap != nil
17
        }
18
        do {
19

20
        } catch {
21
            print(error)
22
        }
23

24
    }

In the do closure, wait for the GenerateOfflineMapJob to produce an output that contains the downloaded offline map. Assign the output to the offlineMap property. Use EnvelopeBuilder to expand the extent by 0.8. Set the offline map’s initial viewpoint to this new envelope. Indicate that an alert is shown to the user.

ContentView.swift

1
    func generateOfflineMap(extent: Envelope) async {
2
        isGenerateDisabled = true
3
        guard let parameters = await makeGenerateOfflineMapParameters(areaOfInterest: extent) else {
4
            isGenerateDisabled = false
5
            return
6
        }
7

8
        generateOfflineMapJob = offlineMapTask.makeGenerateOfflineMapJob(
9
            parameters: parameters,
10
            downloadDirectory: temporaryDirectory
11
        )
12
        generateOfflineMapJob.start()
13

14
        defer {
15
            generateOfflineMapJob = nil
16
            isGenerateDisabled = offlineMap != nil
17
        }
18
        do {
19

20
            let output = try await generateOfflineMapJob.output
21
            offlineMap = output.offlineMap
22
            let builder = EnvelopeBuilder(envelope: extent)
23
            builder.expand(by: 0.8)
24
            offlineMap.initialViewpoint = Viewpoint(boundingGeometry: builder.toGeometry())
25
            isShowingAlert = true
26

27
        } catch {
28
            print(error)
29
        }
30

31
    }

Setup the UI

Add a button to initiate the download, a ProgressView to display the download progress, and use alert(_:isPresented:presenting:actions:message:) to indicate when the download is complete.

In the ContentView, add a @State variable called isGeneratingOfflineMap and set it to false. This Boolean indicates whether an offline map is currently being generated.

ContentView.swift

1
struct ContentView: View {
2

3
    @StateObject private var model = Model()
4

5
    @State private var isGeneratingOfflineMap = false
6

7
    @State private var map = Map(
8
        item: PortalItem(
9
            portal: .arcGISOnline(connection: .anonymous),
10

11
            id: PortalItem.ID("5a030a31e42841a89914bd7c5ecf4d8f")!
12

13
        )
14
    )

Add an .interactionModes modifier to the map view. When isGeneratingOfflineMap is true, the user should not be able to interact. Otherwise, allow the user to pan and zoom.

ContentView.swift

1
    var body: some View {
2

3
        GeometryReader { geometry in
4

5
            MapViewReader { mapView in
6

7
                MapView(map: model.offlineMap ?? map)
8

9
                    .interactionModes(isGeneratingOfflineMap ? [] : [.pan, .zoom])
10

11
                    .task {
12
                        await model.initializeOfflineMapTask(onlineMap: map)
13
                    }
14

15
                    .overlay {
16
                        Rectangle()
17
                            .stroke(.red, lineWidth: 2)
18
                            .padding(EdgeInsets(top: 60, leading: 20, bottom: 100, trailing: 20))
19
                            .opacity(model.offlineMap == nil ? 1 : 0)
20
                    }
21

22
            }
23

24
        }
25

26
    }

Add an .overlay modifier to the map view. If isGeneratingOfflineMap is true, create a ProgressView to track model.generateOfflineMapJob?.progress. Customize the progress view style, frame, and other attributes as required.

ContentView.swift

1
    var body: some View {
2

3
        GeometryReader { geometry in
4

5
            MapViewReader { mapView in
6

7
                MapView(map: model.offlineMap ?? map)
8

9
                    .interactionModes(isGeneratingOfflineMap ? [] : [.pan, .zoom])
10

11
                    .task {
12
                        await model.initializeOfflineMapTask(onlineMap: map)
13
                    }
14

15
                    .overlay {
16
                        Rectangle()
17
                            .stroke(.red, lineWidth: 2)
18
                            .padding(EdgeInsets(top: 60, leading: 20, bottom: 100, trailing: 20))
19
                            .opacity(model.offlineMap == nil ? 1 : 0)
20
                    }
21

22
                    .overlay {
23
                        if isGeneratingOfflineMap,
24
                           let progress = model.generateOfflineMapJob?.progress {
25
                            VStack(spacing: 16) {
26
                                ProgressView(progress)
27
                                    .progressViewStyle(.linear)
28
                                    .frame(maxWidth: 200)
29
                            }
30
                            .padding()
31
                            .background(.regularMaterial)
32
                            .clipShape(RoundedRectangle(cornerRadius: 15))
33
                            .shadow(radius: 3)
34
                        }
35
                    }
36

37
            }
38

39
        }
40

41
    }

Add an .alert(_:isPresented:presenting:actions:message:) modifier to the map view. Present an alert to indicate that the offline map has finished generating. Use the model’s isShowingAlert property to determine when to present the alert.

ContentView.swift

1
    var body: some View {
2

3
        GeometryReader { geometry in
4

5
            MapViewReader { mapView in
6

7
                MapView(map: model.offlineMap ?? map)
8

9
                    .interactionModes(isGeneratingOfflineMap ? [] : [.pan, .zoom])
10

11
                    .task {
12
                        await model.initializeOfflineMapTask(onlineMap: map)
13
                    }
14

15
                    .overlay {
16
                        Rectangle()
17
                            .stroke(.red, lineWidth: 2)
18
                            .padding(EdgeInsets(top: 60, leading: 20, bottom: 100, trailing: 20))
19
                            .opacity(model.offlineMap == nil ? 1 : 0)
20
                    }
21

22
                    .overlay {
23
                        if isGeneratingOfflineMap,
24
                           let progress = model.generateOfflineMapJob?.progress {
25
                            VStack(spacing: 16) {
26
                                ProgressView(progress)
27
                                    .progressViewStyle(.linear)
28
                                    .frame(maxWidth: 200)
29
                            }
30
                            .padding()
31
                            .background(.regularMaterial)
32
                            .clipShape(RoundedRectangle(cornerRadius: 15))
33
                            .shadow(radius: 3)
34
                        }
35
                    }
36

37
                    .alert("Offline map generated", isPresented: $model.isShowingAlert) {
38
                        Button("Done") {
39
                            model.isShowingAlert = false
40
                        }
41
                    }
42

43
            }
44

45
        }
46

47
    }

Add a Button labeled “Download Map Area” to a toolbar at the bottom of the map view. When you click on the button, the isGeneratingOfflineMap property is set to true. The button is disabled if the offline map has been generated (model.isGeneratedDisabled == true) or if the offline map is being generated (isGeneratingOfflineMap == true).

ContentView.swift

1
    var body: some View {
2

3
        GeometryReader { geometry in
4

5
            MapViewReader { mapView in
6

7
                MapView(map: model.offlineMap ?? map)
8

9
                    .interactionModes(isGeneratingOfflineMap ? [] : [.pan, .zoom])
10

11
                    .task {
12
                        await model.initializeOfflineMapTask(onlineMap: map)
13
                    }
14

15
                    .overlay {
16
                        Rectangle()
17
                            .stroke(.red, lineWidth: 2)
18
                            .padding(EdgeInsets(top: 60, leading: 20, bottom: 100, trailing: 20))
19
                            .opacity(model.offlineMap == nil ? 1 : 0)
20
                    }
21

22
                    .overlay {
23
                        if isGeneratingOfflineMap,
24
                           let progress = model.generateOfflineMapJob?.progress {
25
                            VStack(spacing: 16) {
26
                                ProgressView(progress)
27
                                    .progressViewStyle(.linear)
28
                                    .frame(maxWidth: 200)
29
                            }
30
                            .padding()
31
                            .background(.regularMaterial)
32
                            .clipShape(RoundedRectangle(cornerRadius: 15))
33
                            .shadow(radius: 3)
34
                        }
35
                    }
36

37
                    .alert("Offline map generated", isPresented: $model.isShowingAlert) {
38
                        Button("Done") {
39
                            model.isShowingAlert = false
40
                        }
41
                    }
42

43
                    .toolbar {
44
                        ToolbarItem(placement: .bottomBar) {
45

46
                            Button("Download Map Area") {
47
                                isGeneratingOfflineMap = true
48
                            }
49

50
                            .disabled(model.isGenerateDisabled || isGeneratingOfflineMap)
51

52
                        }
53
                    }
54

55
            }
56

57
        }
58

59
    }

Add a .task modifier to the button using isGeneratingOfflineMap as its identifier. When isGeneratingOfflineMap is true, create a frame from the geometry using frame(in coordinateSpace:). Use the frame to create an envelope in the map view using envelope(viewRect:). Pass the resulting envelope into the model’s generateOfflineMap(extent:) function and set isGeneratingOfflineMap to false.

ContentView.swift


153 collapsed lines
1
// Copyright 2024 Esri
2
//
3
// Licensed under the Apache License, Version 2.0 (the "License");
4
// you may not use this file except in compliance with the License.
5
// You may obtain a copy of the License at
6
//
7
//   https://www.apache.org/licenses/LICENSE-2.0
8
//
9
// Unless required by applicable law or agreed to in writing, software
10
// distributed under the License is distributed on an "AS IS" BASIS,
11
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12
// See the License for the specific language governing permissions and
13
// limitations under the License.
14

15

16
import SwiftUI
17
import ArcGIS
18

19
@MainActor
20
private class Model: ObservableObject {
21

22
    @Published private(set) var offlineMap: Map!
23

24
    @Published private(set) var generateOfflineMapJob: GenerateOfflineMapJob!
25
    private var offlineMapTask: OfflineMapTask!
26

27
    @Published private(set) var isGenerateDisabled = true
28
    @Published var isShowingAlert = false
29

30
    private let temporaryDirectory: URL = {
31
        // swiftlint:disable:next force_try
32
        return try! FileManager.default.url(
33
            for: .itemReplacementDirectory,
34
            in: .userDomainMask,
35
            appropriateFor: FileManager.default.temporaryDirectory,
36
            create: true
37
        )
38
    }()
39

40
    deinit {
41
        try? FileManager.default.removeItem(at: temporaryDirectory)
42
    }
43

44
    func initializeOfflineMapTask(onlineMap: Map) async {
45
        do {
46
            try await onlineMap.load()
47
            offlineMapTask = OfflineMapTask(onlineMap: onlineMap)
48
            isGenerateDisabled = false
49
        } catch {
50
            print(error)
51
        }
52
    }
53

54
    private func makeGenerateOfflineMapParameters(areaOfInterest: Envelope) async -> GenerateOfflineMapParameters? {
55
        do {
56
            return try await offlineMapTask.makeDefaultGenerateOfflineMapParameters(areaOfInterest: areaOfInterest)
57
        } catch {
58
            print(error)
59
            return nil
60
        }
61
    }
62

63
    func generateOfflineMap(extent: Envelope) async {
64
        isGenerateDisabled = true
65
        guard let parameters = await makeGenerateOfflineMapParameters(areaOfInterest: extent) else {
66
            isGenerateDisabled = false
67
            return
68
        }
69

70
        generateOfflineMapJob = offlineMapTask.makeGenerateOfflineMapJob(
71
            parameters: parameters,
72
            downloadDirectory: temporaryDirectory
73
        )
74
        generateOfflineMapJob.start()
75

76
        defer {
77
            generateOfflineMapJob = nil
78
            isGenerateDisabled = offlineMap != nil
79
        }
80
        do {
81

82
            let output = try await generateOfflineMapJob.output
83
            offlineMap = output.offlineMap
84
            let builder = EnvelopeBuilder(envelope: extent)
85
            builder.expand(by: 0.8)
86
            offlineMap.initialViewpoint = Viewpoint(boundingGeometry: builder.toGeometry())
87
            isShowingAlert = true
88

89
        } catch {
90
            print(error)
91
        }
92

93
    }
94

95
}
96

97
struct ContentView: View {
98

99
    @StateObject private var model = Model()
100

101
    @State private var isGeneratingOfflineMap = false
102

103
    @State private var map = Map(
104
        item: PortalItem(
105
            portal: .arcGISOnline(connection: .anonymous),
106

107
            id: PortalItem.ID("5a030a31e42841a89914bd7c5ecf4d8f")!
108

109
        )
110
    )
111

112
    var body: some View {
113

114
        GeometryReader { geometry in
115

116
            MapViewReader { mapView in
117

118
                MapView(map: model.offlineMap ?? map)
119

120
                    .interactionModes(isGeneratingOfflineMap ? [] : [.pan, .zoom])
121

122
                    .task {
123
                        await model.initializeOfflineMapTask(onlineMap: map)
124
                    }
125

126
                    .overlay {
127
                        Rectangle()
128
                            .stroke(.red, lineWidth: 2)
129
                            .padding(EdgeInsets(top: 60, leading: 20, bottom: 100, trailing: 20))
130
                            .opacity(model.offlineMap == nil ? 1 : 0)
131
                    }
132

133
                    .overlay {
134
                        if isGeneratingOfflineMap,
135
                           let progress = model.generateOfflineMapJob?.progress {
136
                            VStack(spacing: 16) {
137
                                ProgressView(progress)
138
                                    .progressViewStyle(.linear)
139
                                    .frame(maxWidth: 200)
140
                            }
141
                            .padding()
142
                            .background(.regularMaterial)
143
                            .clipShape(RoundedRectangle(cornerRadius: 15))
144
                            .shadow(radius: 3)
145
                        }
146
                    }
147

148
                    .alert("Offline map generated", isPresented: $model.isShowingAlert) {
149
                        Button("Done") {
150
                            model.isShowingAlert = false
151
                        }
152
                    }
153

154
                    .toolbar {
155
                        ToolbarItem(placement: .bottomBar) {
156

157
                            Button("Download Map Area") {
158
                                isGeneratingOfflineMap = true
159
                            }
160

161
                            .disabled(model.isGenerateDisabled || isGeneratingOfflineMap)
162

163
                            .task(id: isGeneratingOfflineMap) {
164
                                guard isGeneratingOfflineMap else { return }
165
                                let viewRect = geometry.frame(in: .local).inset(
166
                                    by: UIEdgeInsets(
167
                                        top: 60,
168
                                        left: geometry.safeAreaInsets.leading + 20,
169
                                        bottom: 100,
170
                                        right: -geometry.safeAreaInsets.trailing + 20
171
                                    )
172
                                )
173
                                guard let extent = mapView.envelope(fromViewRect: viewRect) else { return }
174
                                await model.generateOfflineMap(extent: extent)
175
                                isGeneratingOfflineMap = false
176
                            }
177

178
                        }
179
                    }
8 collapsed lines
180

181
            }
182

183
        }
184

185
    }
186

187
}

Run the solution

Press Command + R to run the app.

If you are using the Xcode simulator your system must meet these minimum requirements: macOS 14 (Sonoma), Xcode 16, iOS 18. If you are using a physical device, then refer to the system requirements.

You should see a web map A web map is a map stored as a JSON object that defines properties such as the basemap layer, data layers, layer styles, and pop-up styles. Its JSON structure is defined by the web map specification. Learn more of the Naperville water network in the map view and a Download Map Area button embedded within the bottom toolbar.

Tap the Download Map Area button to download the visible area of the web map, offline. Once the download is complete, you will be able to pinch, drag, and double-tap the map view to explore this offline map.

Alternatively, you can download the tutorial solution, as follows.

Option 2: Download the solution

Click the Download solution link under Solution and unzip the file to a location on your machine.
Open the .xcodeproj file in Xcode.

Since the downloaded solution does not contain authentication credentials, you must first set up authentication to create credentials, and then add the developer credentials to the solution.

Set up authentication

To access the secure ArcGIS location services ArcGIS Location Services, also referred to as Location Services, are services hosted by Esri that provide geospatial functionality for developing mapping applications. They include the ArcGIS Basemap Styles service, ArcGIS Static Basemap Tiles service, ArcGIS Places service, ArcGIS Geocoding service, ArcGIS Routing service, ArcGIS GeoEnrichment service, and ArcGIS Elevation service. An ArcGIS Location Platform or ArcGIS Online account is required to use the services. Learn more used in this tutorial, you must implement API key authentication API key authentication is a type of authentication that uses an API key to authenticate requests to ArcGIS services and secure portal items. Learn more or user authentication User authentication is a type of authentication that allows users with an ArcGIS account to sign into an application and allow it to access ArcGIS content, services, and resources on their behalf. The typical authorization protocol used is OAuth2.0. Learn more using an ArcGIS Location Platform An ArcGIS Location Platform account, formerly known as an ArcGIS Developer account, is an identity associated with an ArcGIS Location Platform subscription. Learn more or an ArcGIS Online An ArcGIS Online account, also known as an ArcGIS Organization account, is an identity associated with an ArcGIS Online subscription. It can be used to access ArcGIS tools and develop applications with ArcGIS location services for an organization. Learn more account.

You can implement API key authentication or user authentication in this tutorial. Compare the differences below:

API key authentication API key authentication is a type of authentication that uses an API key to authenticate requests to ArcGIS services and secure portal items. Learn more

Users are not required to sign in.
Requires creating an API key credential API key credentials are an item that contains the parameters used to create and manage long-lived access tokens for API key authentication. They are a type of developer credential. Learn more with the correct privileges.
API keys An API key is a long-lived access token created using API key credentials. They are valid for up to one year and are typically embedded directly into client applications. Learn more are long-lived access tokens.
Service usage is billed to the API key owner/developer.
Simplest authentication method to implement.
Recommended approach for new ArcGIS developers.

Learn more in API key authentication.

User authentication User authentication is a type of authentication that allows users with an ArcGIS account to sign into an application and allow it to access ArcGIS content, services, and resources on their behalf. The typical authorization protocol used is OAuth2.0. Learn more

Users are required to sign in with an ArcGIS account An ArcGIS account is an identity with a user type and set of privileges that can access specific ArcGIS products, tools, APIs, services, and resources. The main account types that can be used for development are an ArcGIS Location Platform account, ArcGIS Online account, and ArcGIS Enterprise account. ArcGIS Location Platform and ArcGIS Online accounts are also associated with a subscription. Learn more .
User accounts must have privilege Privileges are a set of permissions assigned to ArcGIS accounts, developer credentials, and applications that grant access to secure resources and functionality in ArcGIS. Learn more to access the ArcGIS services A service, also known as an ArcGIS service, is software that supports an ArcGIS REST API and provides geospatial functionality or data. A service can be hosted by Esri or in ArcGIS Enterprise. Learn more used in application.
Requires creating OAuth credentials OAuth credentials are an item that contains parameters required to implement user authentication or app authentication, including a client_id, client_secret, and redirect URIs. They are a type of developer credential. Learn more .
Application uses a redirect URL and client ID.
Service usage is billed to the organization of the user signed into the application.

Learn more in User authentication.

To complete this tutorial, click on the tab in the switcher below for your authentication type of choice, either API key authentication or User authentication.

Create a new API key access token An access token is an authorization string that provides access to secure ArcGIS content, data, and services. Its capabilities are determined by the privileges it supports. It is obtained by implementing API key authentication, User authentication, or App authentication. Learn more with privileges Privileges are a set of permissions assigned to ArcGIS accounts, developer credentials, and applications that grant access to secure resources and functionality in ArcGIS. Learn more to access the secure resources used in this tutorial.

Complete the Create an API key tutorial and create an API key with the following privilege(s) Privileges are a set of permissions assigned to ArcGIS accounts, developer credentials, and applications that grant access to secure resources and functionality in ArcGIS. Learn more :
- Privileges
  - Location services > Basemaps
Copy and paste the API key access token into a safe location. It will be used in a later step.

Create new OAuth credentials to access the secure resources used in this tutorial.

Complete the Create OAuth credentials for user authentication tutorial to obtain a Client ID and Redirect URL.

A Client ID uniquely identifies your app on the authenticating server. If the server cannot find an app with the provided Client ID, it will not proceed with authentication.
The Redirect URL (also referred to as a callback url) is used to identify a response from the authenticating server when the system returns control back to your app after an OAuth login. Since it does not necessarily represent a valid endpoint that a user could navigate to, the redirect URL can use a custom scheme, such as my-app://auth. It is important to make sure the redirect URL used in your app’s code matches a redirect URL configured on the authenticating server.
Copy and paste the Client ID and Redirect URL into a safe location. They will be used in a later step.

All users that access this application need account privileges Privileges are a set of permissions assigned to ArcGIS accounts, developer credentials, and applications that grant access to secure resources and functionality in ArcGIS. Learn more to access the ArcGIS Basemap Styles service The ArcGIS Basemap Styles service, also referred to as the Basemap Styles service, is a location service that provides basemap styles and data for the world. It returns styles as Mapbox styles and web maps, and data as vector tiles and/or map tiles. It supports all of the styles in the ArcGIS Basemap style and Open Basemap style family. An ArcGIS Location Platform or ArcGIS Online account is required to use the service. Learn more .

Set developer credentials in the solution

To allow your app users to access ArcGIS location services ArcGIS Location Services, also referred to as Location Services, are services hosted by Esri that provide geospatial functionality for developing mapping applications. They include the ArcGIS Basemap Styles service, ArcGIS Static Basemap Tiles service, ArcGIS Places service, ArcGIS Geocoding service, ArcGIS Routing service, ArcGIS GeoEnrichment service, and ArcGIS Elevation service. An ArcGIS Location Platform or ArcGIS Online account is required to use the services. Learn more , use the developer credentials that you created in the Set up authentication step to authenticate requests for resources.

Pass your API Key access token to the ArcGISEnvironment.

In the Project Navigator, click MainApp.swift.

Set the AuthenticationMode to .apiKey.

MainApp.swift

    // Change the `AuthenticationMode` to `.apiKey` if your application uses API key authentication.

    private var authenticationMode: AuthenticationMode { .apiKey }

Set the apiKey property with your API key access token.

MainApp.swift

31 collapsed lines
// Copyright 2022 Esri
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//   https://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
import SwiftUI
import ArcGIS
import ArcGISToolkit
@main

struct MainApp: App {

    // The authentication mode.
    private enum AuthenticationMode {
        case apiKey
        case user
    }

    // Change the `AuthenticationMode` to `.apiKey` if your application uses API key authentication.

    private var authenticationMode: AuthenticationMode { .apiKey }


    // Please enter an API key access token if your application uses API key authentication.

    private let apiKey = APIKey("<#YOUR-ACCESS-TOKEN#>")

43 collapsed lines

    // Setup an `Authenticator` with OAuth configuration if your application uses OAuth credentials.
    @ObservedObject var authenticator = Authenticator(
        oAuthUserConfigurations: [
            OAuthUserConfiguration(

                // Please enter OAuth credentials for user authentication.

                portalURL: URL(string: "<#YOUR-PORTAL-URL#>")!,
                clientID: "<#YOUR-CLIENT-ID#>",
                redirectURL: URL(string: "<#YOUR-REDIRECT-URL#>")!

            )
        ]
    )

    func setAuthentication() {
        switch authenticationMode {
        case .apiKey:
            ArcGISEnvironment.apiKey = apiKey
        case .user:
            ArcGISEnvironment.authenticationManager.arcGISAuthenticationChallengeHandler = authenticator
        }
    }

    init() {
        setAuthentication()
    }


    var body: some SwiftUI.Scene {

        WindowGroup {
            ContentView()

                .authenticator(authenticator)

                .ignoresSafeArea()

        }
    }

}

Best Practice: The access token is stored directly in the code as a convenience for this tutorial. Do not store credentials directly in source code in a production environment.

Use the Authenticator toolkit component to manage your OAuth credentials OAuth credentials are an item that contains parameters required to implement user authentication or app authentication, including a client_id, client_secret, and redirect URIs. They are a type of developer credential. Learn more and pass it to the ArcGISEnvironment.

In the Project Navigator, click MainApp.swift.

Set the AuthenticationMode to .user.

MainApp.swift

// Change the `AuthenticationMode` to `.user` if your application uses OAuth credentials.

private var authenticationMode: AuthenticationMode { .user }

Set your portalURL, clientID and redirectURL values.

MainApp.swift

36 collapsed lines
// Copyright 2022 Esri
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//   https://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
import SwiftUI
import ArcGIS
import ArcGISToolkit
@main

struct MainApp: App {

    // The authentication mode.
    private enum AuthenticationMode {
        case apiKey
        case user
    }

    // Change the `AuthenticationMode` to `.user` if your application uses OAuth credentials.

    private var authenticationMode: AuthenticationMode { .apiKey }


    // Please enter an API key access token if your application uses API key authentication.

    private let apiKey = APIKey("<#YOUR-ACCESS-TOKEN#>")


    // Setup an `Authenticator` with OAuth configuration if your application uses OAuth credentials.
    @ObservedObject var authenticator = Authenticator(
        oAuthUserConfigurations: [
            OAuthUserConfiguration(

                // Please enter OAuth credentials for user authentication.

                portalURL: URL(string: "<#YOUR-PORTAL-URL#>")!,
                clientID: "<#YOUR-CLIENT-ID#>",
                redirectURL: URL(string: "<#YOUR-REDIRECT-URL#>")!

            )
        ]
    )
28 collapsed lines

    func setAuthentication() {
        switch authenticationMode {
        case .apiKey:
            ArcGISEnvironment.apiKey = apiKey
        case .user:
            ArcGISEnvironment.authenticationManager.arcGISAuthenticationChallengeHandler = authenticator
        }
    }

    init() {
        setAuthentication()
    }


    var body: some SwiftUI.Scene {

        WindowGroup {
            ContentView()

                .authenticator(authenticator)

                .ignoresSafeArea()

        }
    }

}

Best Practice: The OAuth credentials are stored directly in the code as a convenience for this tutorial. Do not store credentials directly in source code in a production environment.

Run the solution

Press Command + R to run the app.

What’s next?

Learn how to use additional API features, ArcGIS location services, and ArcGIS tools in these tutorials:

Create a mobile map package

TutorialsCreate a mobile map package TutorialsDisplay a map from a mobile map package