Skip To Content

Install and set up

In this topic

Follow this guide to install the SDK on your Mac. You can either

  • use CocoaPods to install the SDK into your Xcode workspace
  • or install the SDK to a central location on your Mac and link your Xcode projects to that SDK.
Both methods are described here:

Install the SDK using CocoaPods

Read this guide to learn how to get started with CocoaPods. If you are ready to use CocoaPods then follow these instructions to install and set up the pod in your project.

  1. Add pod 'ArcGIS-Runtime-SDK-iOS' to your project's Podfile
  2. 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.
  3. Import ArcGIS file
  4. Add ArcGIS resource bundle
  5. Disable bitcode
  6. Handle App Transport Security

Install the SDK manually

Alternatively, you can install the SDK on your Mac in a location available to all of your projects:

  1. Make sure your system meets the system requirements.
  2. Download and extract the SDK. Download the SDK for your operating system from the Downloads page.
  3. Make sure you have write permissions to the ${HOME}/Library folder.
  4. Uninstall any previous version of ArcGIS Runtime SDK for iOS on this machine. To uninstall, run the ${HOME}/Library/Application Support/AGSiOSRuntimeSDK/uninstallAGSiOSSDK script in the Terminal application.
  5. Double-click the downloaded .pkg file. In the installation wizard that displays, follow the on-screen instructions to step through the panels.
  6. The SDK is installed to the ${HOME}/Library/SDKs/ArcGIS/iOS. This folder contains two subfolders, one called Samples that contains a single sample and one called ArcGIS.framework that contains the API library, header files, images, localized strings, and more.

The ${HOME}/Library folder is hidden by default. Unhide it using the command chflags nohidden ~/Library/ in the Terminal application.

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 getting corrupted during download. Try downloading the package again.

Set up your Xcode project manually

You can configure your XCode project as described below to begin development with ArcGIS Runtime SDK for iOS.

Add ArcGIS to the framework search paths

Select the project node in the left Navigator pane, select a target node, and choose the Build Settings tab. Under the tab, type Framework Search Paths in the Search bar to quickly find the Framework Search Paths setting. Double-click the empty space under the target column, and use the + button to add the following entry: $(HOME)/Library/SDKs/ArcGIS/iOS/

Add build flags

Under the Build Settings tab, type Other Linker Flags in the Search bar to quickly find the Other Linker Flags setting. Click the empty space under the target column. The empty space becomes a text box. Type the following text: -ObjC -framework ArcGIS -l c++. Click anywhere outside the text box to finish.

Add dependencies

The ArcGIS framework in-turn depends upon a number of other iOS frameworks. The easiest way to ensure these dependencies are linked in during build time is set theEnable Modules (C and Objective-C) setting to Yes. This will allow your project to automatically reference any needed system frameworks and libraries required by ArcGIS.

Alternatively, you can manually add the following frameworks to your project's settings -

  • AssetsLibrary.framework
  • CoreGraphics.framework
  • CoreLocation.framework
  • CoreText.framework
  • Foundation.framework
  • QuartzCore.framework
  • MediaPlayer.framework
  • MobileCoreServices.framework
  • OpenGLES.framework
  • Security.framework
  • UIKit.framework

To do so, select the Build Phases tab. Under the Link Binary with Libraries section, click the + button, and select and add each dependency.

Configure your Xcode project

Import ArcGIS file

Add the following import statement to any swift file in which you wish to use the API -

import ArcGIS


It is necessary to add the import statement if you are using the Enable Modules approach otherwise, your project may not compile properly. This will happen because Xcode does not know which system libraries and frameworks ArcGIS depends upon and so cannot reference them at build time.

Add ArcGIS resource bundle

API resources, such as Esri and Bing logo images, GPS location symbol, localized strings, etc. are consolidated into an ArcGIS.bundle file. This bundle is typically installed under ${HOME}/Library/SDKs/ArcGIS/iOS/ArcGIS.framework/Versions/Current/Resources if you selected the default location during installation. You need to manually add this bundle to your project.

Go to the Xcode application File menu, select the Add Files to <project> item, browse to the ${HOME}/Library/SDKs/ArcGIS/iOS/ArcGIS.framework/Versions/Current/Resources location, select the ArcGIS.bundle file, and click Add.


The ${HOME}/Library folder is hidden by default in Mac OS X. You can issue the command chflags nohidden ~/Library/ in the Terminal application to show it. This enables you to browse to it using the Add Files to <project> dialog window.

Disable bitcode

Apple has introduced a new compilation option at Xcode 7 called Bitcode. This technology will allow Apple to optimize (re-compile) your binary in the future without you having to submit a new version. For more information please see Apple's App Thinning topic.

Xcode 7 has Bitcode enabled by default but this technology is not supported in the ArcGIS Runtime SDKs for iOS versions 10.2.x (and Quartz Beta 1). With these versions of the SDK you can build and test apps with the Simulator, with Bitcode enabled, but you will not be able to deploy these apps to a device or through Apple’s App Store.

To disable Bitcode go to the project's Build Settings tab and type bitcode into the Search bar to find the Enable Bitcode setting. Change this value to No to disable bitcode compilation.


Future versions of this SDK will support bitcode.

Handling App Transport Security

Starting in iOS 9.0 Apple has enforced a new security feature called App Transport Security (ATS). These more stringent policies block plain HTTP connections and require that you exclusively use secure HTTPS connections that support forward secrecy. Details can be found in Apple's technology note. These new policies are enabled by default and any attempts to use insecure HTTP will fail.

This poses a problem when third-party services you rely upon don't meet all of Apple's guidelines. On occasion, you may deliberately want to use plain HTTP connections to avoid unnecessary overhead for information that isn't sensitive and doesn't need to be protected. Fortunately, Apple provides a way to ease these policy restrictions in your app.

To relax these security restrictions you can add the following declaration to the info.plist file.


This change allows your app to make HTTPS connections without requiring forward secrecy. In this case it permits plain HTTP connections to ArcGIS Online so that apps can quickly load basemap layers without needing the data to be encrypted. ArcGIS Online already supports HTTPS connections using industry leading TLS 1.2 so you can choose to use HTTPS exclusively in your app if you so desire.