Skip To Content

Add a map to your app

In this topic

This topic describes how to display a map in your application. It's assumed that:

  • You've created a project named MyFirstMapApp using Apple's Single View Application Xcode project template
  • Your project uses storyboards and auto reference counting (ARC)
  • You've configured your project as described in Set up (configure your Xcode project) to ensure your project can properly reference ArcGIS Runtime SDK for iOS

The primary way to display geographic information in your application is through a map. The API provides a user interface (UI) component called a map view (AGSMapViewclass). The map view lets you display content by mashing up maps from different web services such as Bing Maps, Open Street Map, ArcGIS Server map and image services, OGC WMS, and so on; or by opening preconfigured web maps from ArcGIS Online (Esri's cloud) or your on-premises ArcGIS portals.

1. Add a map view to the UI

The first step in displaying a map in your application is to add a map view to your application's UI. This map view acts as an empty canvas to which you'll later add map content.

The user inteface (UI) of iOS applications is typically contained in one or more storyboard files (.storyboard extension). These files contain various scenes that comprise your application. Each scene defines the styling, positioning, and layout of UI Components as well as the relationship and transitions to other scenes. Each scene is typically associated with a view controller that contains code to respond to user interaction and to optionally perform some setup and teardown tasks. This separation of view and controller objects is based on the Model-View-Controller design pattern.

To make things simple, assume you're only building an iPhone application at this time. You'll add a map view to the UI contained in the Main_iPhone storyboard. You can later repeat these steps to build an iPad application.

When you select the storyboard file in the Project Navigator pane on the left, its contents are displayed in the Canvas section on the right where you can compose the UI visually. Between the Project Navigator and the Canvas lies the Dock, which provides a convenient list of all the view controller scenes & UI components currently in the storyboard. At this point, you'll probably have just one view controller scene in your storyboard. We'll be adding a map to this scene.

The right most section in Xcode is the Utility area, which contains the Inspector pane (top) and Library pane (bottom). The Inspector allows you to inspect and change properties of UI components in the storyboard, and the Library allows you to pick UI components, media, code snippets, and so on, to add to your project.

To add a map view, select a generic UIView object from the Library pane and drag and drop it onto the view shown in the Canvas.

Adding a view using interface builder

This UIView object acts as a place holder for the map that needs to be displayed in the application. For the purpose of this project, resize the UIView, if necessary, so that it totally covers the view beneath. This will ensure that your map is displayed full screen.

Before this UIView can display your map, you need to change it to a map view. You do this by specifying AGSMapView as the class for this object in the Inspector.

Changing view to map view

When adding UI components, you typically also need to specify Auto Layout constraints for the components so that they can be properly sized and positioned when the layout of your application changes, for example, when the device is rotated. For the sake of simplicity, we will skip setting layout constraints in this tutorial, but you can look at the accompanying tutorial app to see these constraints in action.

2. Connect the map view to the view controller

Now that you've added a map view to the UI, you need to connect it to the view controller so that you can programmatically access it. This will allow you to add content to it and respond to user interaction.

To do this, first you need to enable the Assistant Editor so that the view controller's header file (ViewController.h) is displayed along side the Canvas. You can then right-click the map view in the Dock and drag and drop it in the header file shown in the Assistant Editor.

Adding outlet to map view

Upon doing so, Xcode will automatically prompt you for a name so that it can create an outlet connection from the view controller to the map view in the UI. Call this outlet mapView.

Naming the outlet

If you attempt to build your application at this stage, you'll get compile errors because the view controller contains reference to the AGSMapView class, which hasn't been defined. To fix these errors, you need to import the main ArcGIS.h header file into the view controller's header file. This will allow you to reference any class in the ArcGIS Runtime SDK for iOS.

#import <UIKit/UIKit.h>

//Import the header file for ArcGIS framework
#import <ArcGIS/ArcGIS.h>

@interface ViewController: UIViewController 



3. Add content to the map view

Now that you've added a map view to the UI and connected it to the view controller, you can choose the content to be displayed in the map. In this tutorial, we will add individual map layers to the map view. However, you can also display content by opening a preconfigured web map.

Select the ViewController.m implementation file in the Navigator to open it in the source editor. Locate the viewDidLoadmethod. This method is executed when the view controller's UI is displayed, giving the view controller a chance to add some behavior or adjust the display. You'll create a Tiled layer that uses an ArcGIS Online map service, and add it to the map:

- (void)viewDidLoad {
   [super viewDidLoad];

   //Add a basemap tiled layer
   NSURL* url = [NSURL URLWithString:@""];
   AGSTiledMapServiceLayer *tiledLayer = [AGSTiledMapServiceLayer tiledMapServiceLayerWithURL:url];
   [self.mapView addMapLayer:tiledLayer withName:@"Basemap Tiled Layer"];

If you run the application now, the map displays contents from the ArcGIS Online map service.

Learn more about displaying content using layers

Learn more about displaying content using web maps

4. Respond to map actions

A map view informs its delegates when certain actions take place on the map, for example, when a user taps on the map. The map's delegates are responsible for responding to these actions. In addition, a map view also consults its delegates before performing certain actions, for example, displaying a callout. The delegate is responsible for instructing the map on what to do. This separation of responsibility between the map and its delegates is based on the Delegation design pattern.

Depending on the actions you're interested in handling, you need to set one of your classes as the map view's delegate. A map view has three types of delegates: map view layer, map view touch, and map view callout.

Map view layer delegate

The layer delegate is informed about layer related actions, such as when the map loads. See the API reference documentation for the AGSMapViewLayerDelegate protocol to learn about the information conveyed to the layer delegate.

Any class serving as the layer delegate must adopt the AGSMapViewLayerDelegate protocol and implement the methods related to the actions in which it's interested. For example, the following code snippet shows how the ViewController class adopts the delegate protocol,sets itself as the map view's layerDelegate, and implements the mapViewDidLoad: delegate method that is invoked when the map finishes loading:

//1. Adopt the delegate protocol
@interface ViewController: UIViewController <AGSMapViewLayerDelegate>

@implementation ViewController 

 - (void)viewDidLoad {
  [super viewDidLoad];

  //Add a basemap tiled layer
  NSURL* url = [NSURL URLWithString:@""];
  AGSTiledMapServiceLayer *tiledLayer = [AGSTiledMapServiceLayer tiledMapServiceLayerWithURL:url];
  [self.mapView addMapLayer:tiledLayer withName:@"Basemap Tiled Layer"];

  //2. Set the map view's layerDelegate
  self.mapView.layerDelegate = self;

 //3. Implement the layer delegate method
 - (void)mapViewDidLoad:(AGSMapView *) mapView {
		//do something now that the map is loaded
  //for example, show the current location on the map
	 [mapView.locationDisplay startDataSource]; 


Beginning with iOS 8, in addition to calling startDataSource on the map's location display to show the device's location, you also need to add the NSLocationWhenInUseUsageDescription key to your app's Info.plist file along with the text to be displayed to the user when asking for authorization to access the device's location service.

Map view touch delegate

The touch delegate is informed about user interaction with the map, such as when a user taps, or taps and holds the map. See the API reference documentation for the AGSMapViewTouchDelegate protocol to learn about the different actions conveyed to the touch delegate.

The procedure for assigning a touch delegate is similar to the procedure for a layer delegate: adopt the delegate protocol (AGSMapViewTouchDelegate) in your class, implement the relevant methods of the protocol, and set your class as the map view's touchDelegate.

Map view callout delegate

The callout delegate is informed when the map performs or is about to perform callout related actions, such as displaying or dismissing a callout. See the API reference documentation for the AGSMapViewCalloutDelegate protocol to learn about the different actions conveyed to the callout delegate.

The procedure for assigning a callout delegate is similar to those for the layer delegate and touch delegate.