Install and set up

There are a number of ways to install and use the API in your Xcode project. You can use Swift Package Manager, Cocoapods, or the manual download and install process.

Swift Package Manager

The ArcGIS Runtime API for iOS can be easily integrated into your Xcode project using Swift Package Manager.

Xcode 13
  1. Open your Xcode project. In the menu bar, select File > Add Packages...
  2. In the search bar, enter https://github.com/esri/arcgis-runtime-ios as the package repository URL.
  3. Optionally, select an option for the Dependency Rule if you want to specify an exact version or a range of versions to use.
  4. Click Add Package.
Swift Package Manager

To use the ArcGIS Runtime API, add the following import statement to any of your swift code (.swift) files:

Use dark colors for code blocksCopy
1
import ArcGIS

CocoaPods

The ArcGIS Runtime API for iOS is available as a registered CocoaPod. If you are new to CocoaPods, review learn how to get started with CocoaPods, and then follow these instructions to use this pod within your iOS project:

  1. Add pod 'ArcGIS-Runtime-SDK-iOS' to your project's Podfile. This will default to using the latest version available.
  2. Optionally, you can specify an exact version or a range of versions to use. Refer to the pod syntax
  3. Run the command pod install on the Podfile using the Terminal application. This will download the ArcGIS framework to your machine and place it inside your project's Pod directory. It will also make the necessary changes to your project's build settings to correctly reference the ArcGIS framework and create a new Xcode workspace (.xcworkspace file).

To use the ArcGIS Runtime API, open the newly created Xcode workspace and add the following import statement to any of your swift code (.swift) files:

Use dark colors for code blocksCopy
1
import ArcGIS

Manual download

The manual download installs the API once for all iOS projects.

  1. Download the SDK package installer.
  2. Make sure you have write permissions to the ${HOME}/Library folder.
  3. If you have installed a previous version of ArcGIS Runtime API for iOS on this machine, uninstall it. Otherwise, the previous installation will be overwritten. To uninstall, run the ${HOME}/Library/Application Support/AGSiOSRuntimeSDK/uninstallAGSiOSSDK script in the Terminal application.
  4. After you've downloaded the SDK, double-click the downloaded .pkg file. Follow the install wizard instructions to complete the installation procedure.
  5. Complete the additional steps for configure a project.
  6. By default, the API is installed in ${HOME}/Library/SDKs/ArcGIS. This folder contains the following subfolders: Frameworks, Legal, and Samples.

You can go to the Samples folder and run either the Objective-C or Swift sample to ensure that everything was installed correctly on your machine.

If you encounter installation errors, see the install.log file at /var/log/install.log for more information. A common reason for failure is the installation package was corrupted during download. Try downloading the package again. On rare occasions, the installer may ask you for your username/password during installation. When this happens, the installer finishes successfully but the SDK gets installed in the root directory instead of in your home directory. To resolve this issue, you can manually copy the SDKs folder from the root /Library directory into your user profile's $HOME/Library directory.

Configure a project

After manually installing the API as described above, configure each Xcode project to use the API.

Add ArcGIS framework to the project

  1. Open an Xcode project or create a new one.
  2. Select the project node in the left Navigator pane, select a target node, and choose the General tab.
  3. In the Frameworks, Libraries, and Embedded Content section, drag and drop the ArcGIS.xcframework and Runtimecore.xcframework files from the $(HOME)/Library/SDKs/ArcGIS/Frameworks directory as shown below :
Xcode choose framework

That's it. To use the ArcGIS API, add the following import statement to any of your swift code (.swift) files:

Use dark colors for code blocksCopy
1
import ArcGIS

Additional downloads

Additional sources of sample code, data, and tools are available to enhance your ArcGIS Runtime development projects. You can even download this guide as stand-alone developer documentation.

Sample code

Get hands-on sample code that illustrates a variety of powerful ArcGIS Runtime capabilities that you can add to your own applications. Search for samples and browse the relevant code in the samples documentation or download the code from the samples repository and run them locally. You can also download the sample viewer app from the App Store on your iOS device.

ArcGIS Runtime SDK for iOS Toolkit

The ArcGIS Runtime SDK for iOS Toolkit, an open source project maintained by the ArcGIS Runtime API for iOS team, contains controls and utilities to simplify your app development. Check out the Examples project to see these components in action or read through the Documentation to learn more about them.

Stand-alone developer documentation

You can download the developer documentation (for any ArcGIS Runtime API) as an archive from the downloads. The archive contains instructions to serve the documentation from a local web server so you can access it without a connection to the internet. The stand-alone documentation includes the developer guide, API reference, tutorials, and samples documentation. This documentation is designed to run on a local stand-alone computer or on an internal network and not on the public internet.

To serve the documentation locally:

  • Download the documentation for the ArcGIS Runtime API(s) you want to use. The downloaded files are in a .zip archive format.
  • Extract the archive to a local folder. The extracted archive has two subfolders: public and install.
  • Open the README.md file in the install folder and follow the instructions for your chosen web server.

Supplemental data

StreetMap Premium

StreetMap Premium for ArcGIS Runtime provides enriched street data, which powers a high-quality cartographic maps and high-quality search, geocoding, and route analysis. StreetMap Premium maps are consistent across all regions of the world and can be taken offline for disconnected use; they can simultaneously fulfill the need for an address locator, street network dataset, and basemap in your app.

If you want to use StreetMap Premium data (the StreetMap Premium extension), download the demonstration data from the downloads page for development and testing. Please contact Esri Customer Service for access to a region of your choice for development and testing or to license StreetMap Premium data for deployment.

Projection Engine data

Datum transformations are used when geometries must be projected from one spatial reference to another when there is a difference in the datum that underlies the two spatial references. Datum transformations can be mathematically defined (equation-based transformations), or may rely on external supporting files (grid-based transformations). Certain Projection Engine data files must be present when you use a grid-based transformation in your app; attempting to use a transformation with missing Projection Engine files will cause an error. The API can detect whether the necessary files are available on the local file system.

If your app requires grid-based transformations, you can download supporting Projection Engine files from the downloads page. See the Spatial references topic for more information about working with coordinate systems, projections, and datum transformations.

Electronic Navigational Charts (ENC)

Electronic navigational charts (ENCs) are georeferenced vector datasets for the visualization and analysis of hydrographic and maritime information. ArcGIS Runtime supports ENCs that conform to the International Hydrographic Organization (IHO) S-57 standard.

If you want to work with Electronic Navigational Charts (ENC) download the hydrography directory from the downloads page.

See the Display electronic navigational charts topic for more information about working with ENC data.

Next steps

Your browser is no longer supported. Please upgrade your browser for the best experience. See our browser deprecation post for more details.