Skip To Content ArcGIS for Developers Sign In Dashboard


You will learn: how to build a simple app that displays a 2D map.

With the ArcGIS Runtime SDK for iOS, it is easy to create a native mapping app that displays a basemap. In this tutorial, you will use the iOS SDK to build a simple mapping app that we will use as a starting point for the other iOS tutorials. This tutorial demonstrates the basic SDK setup for iOS Xcode projects.

These tutorials assume you're developing with Xcode and have downloaded and installed the ArcGIS Runtime SDK for iOS to the default location. For a more detailed walk-through of these steps (and to see how to use Cocoapods instead), see Install and set up.

Before you begin

Make sure you have installed the latest version of Xcode.

Download and install the ArcGIS Runtime SDK for iOS by following the instructions at Install and set up.

You will need an ArcGIS account to download the SDK. If you haven't already, sign up for free.


Create a starter app

  1. Open Xcode and create a new iOS Swift Single View App named ArcGIS Starter App.

Hook up the ArcGIS Runtime SDK

  1. With the project selected, under the General tab scroll down to the 'Frameworks, Libraries, and Embedded Content' section. Click the '+' button located in the bottom left corner of the section.

  2. Click 'Add Other...' > 'Add Files...'

  3. Select framework following the path: /Users/<your-username>/Library/SDKs/ArcGIS/iOS/Frameworks/Dynamic/ArcGIS.framework

  4. Click 'Open'.

Add a map to your app

Now that you've created an app and included the ArcGIS Runtime SDK for iOS, the next step is to add a AGSMapView to the storyboard.

  1. Open Main.storyboard in the project navigator and add a new View to the parent view. Add constraints so the new view fills the parent view.

  2. With the new view selected, in Xcode's app menu, select View > Inspectors > Show Identity Inspector and in the Identity Inspector (top-right), set the Class attribute to AGSMapView.

  3. Import the ArcGIS SDK module into ViewController.swift and add an @IBOutlet named mapView to the ViewController class.

    import UIKit
    /*** ADD ***/
    import ArcGIS
    class ViewController: UIViewController {
        /*** ADD ***/
        @IBOutlet weak var mapView: AGSMapView!
  4. Create a new private method to configure your map and assign it to the map view.

        private func setupMap() {
   = AGSMap(
                basemapType: .navigationVector,
                latitude: 34.09042,
                longitude: -118.71511,
                levelOfDetail: 10
  5. Call the newly introduced method once the view loads.

        override func viewDidLoad() {
            /*** ADD ***/
  6. Open the Main.storyboard and right click on the yellow View Controller icon. Drag the mapView outlet connector to the AGSMapView.

  7. Press Command-R to run the app in the iOS Simulator.

    (Note, as of 100.8 Runtime supports Metal. In order to run your app in a simulator you must meet some minimum requirements. You must be developing on macOS Catalina, using Xcode 11, and simulating iOS 13.)

Congratulations, you're done!

Your app should run and display the basemap. Compare your solution with our completed solution project. We will refer back to this project as the starting template for many of the iOS tutorials.


License your Runtime app

During development you will see a watermark on your map. Before you deploy your ArcGIS Runtime app into production, you're required to license it.

  1. Log into your ArcGIS Developer Account and go to your dashboard.

  2. Find your Runtime Lite license key and copy it.

  3. Add a new swift file to your Xcode project named AppPrivate.swift. Use this to define a structure to hold sensitive configuration constants required by your app.

  4. Add the following extension to AppPrivate.swift. When you type this code, change "YOUR-RUNTIME-LICENSE-KEY" to the Runtime Lite license key you copied from the prior step.

     /*** ADD ***/
     extension String {
         static let licenseKey = "YOUR-RUNTIME-LICENSE-KEY"
  5. Open AppDelegate.swift. At the very bottom of the file add a new extension helper function to license the app. Add a call to ArcGISRuntimeEnvironment.setLicenseKey with a reference to the license string set in the prior step.

     /*** ADD ***/
     extension AppDelegate {
         func licenseApplication() {
             do {
                 try AGSArcGISRuntimeEnvironment.setLicenseKey(.licenseKey)
             } catch {
                 print("[Error: AGSArcGISRuntimeEnvironment] Error licensing app: \(error.localizedDescription)")
  6. Open the file named AppDelegate.swift and, near the top of the file, include an import statement for the ArcGIS module.

     import UIKit
     /*** ADD ***/
     import ArcGIS
  7. In the didFinishLaunchingWithOptions method, add a call to the extension to license your app.

     func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
         /*** ADD ***/
  8. Run your app and test the code to see the map rendered without the developer watermark. This app is licensed and can be deployed to your users.

Explore basemaps

Visit the iOS SDK documentation to learn more about the different types of basemaps available. Try some different basemap types such as .lightGrayCanvasVector, .topographicVector or .streetsWithReliefVector and pick your favorite basemap.

Change view

Try different settings for the initial view by changing the latitude, longitude, and level of detail.

Run on a device

If you have an Apple Developer account, try opening the app on a device rather than in the simulator. The Runtime SDK makes extensive use of Metal and the iOS simulator performs poorly for tasks that make use of the iOS device's graphics hardware.