nevan.net

In this post I will show you how to implement a table in watchOS. I’ll highlight some of the differences with tables compared to iOS, like setting up row contents in advance and the use of row controllers.

To create a list of items in watchOS you use the WKInterfaceTable class. This class is roughly equivalent to UITableView in UIKit but has some important differences. If you’ve used UITableView for a while, the differences will be surprising, but for new developers the API is far simpler.

The steps required to implement a WKInterfaceTable are:

• Set up a table in Interface Builder
• Create a subclass for the table’s rows
• Tell the table how many rows it has
• Tell the table the name of its row identifier
• Set the row contents

Differences between WKInterfaceTable and UITableView

To configure the contents of a UITableView, you set a delegate and data source and give the table information when it requests the number of rows and the row contents. You can create the table in Interface Builder or instantiate it in code.

To create a WKInterfaceTable, you only have the option to use Interface Builder. This is the same as all of watchOS’s interface objects. You have to tell the table in advance how many rows it has and what their contents will be. In watchOS they are part of the table’s setup while in iOS they are queried lazily after the table has been created.

The other change is that there’s no WKInterfaceTableController as an equivalent to UITableViewController. All of the controller methods have been subsumed into the general WKInterfaceController class, which handles cell selection callbacks.

Because you set up all table cells before the interface appears, Apple recommends only using a small number of cells. While you can have a table with thousands of rows in iOS, Apple suggests that you limit the number to around 20 in watchOS. Contrary to this recommendation is the Music app on Apple Watch, which can contain many hundreds of items in the Album list. When scrolling through this list you will see a way that Apple reduces the burden of navigating a long list: A box with the index letter of the current region appears after scrolling for a few seconds and further scrolls advance the list to the following letter. There are no explicit sections in WKInterfaceTable but the table in Music is acting like there are.

Tables on watchOS lack many of the more advanced (and space-consuming) features of iOS tables, like headers, sections, accessory views and Core Data integration.

In this tutorial, you will set up a table-based interface, first with just a single row with one label, then using a row controller and model object to supply data.

Basic WKInterfaceTable

You’re going to create a watchOS app which contains a table with just one item. This will demonstrate how to instantiate a WKInterfaceTable on Apple Watch.

Create an empty project with a Watch app

In Xcode, create a new project (⇧⌘-N) using the iOS Application template for a Single View Application. Call it “Names” and set it to use Swift and target iPhone. You’re not going to use any of the iPhone files created, but will be working exclusively in an Apple Watch target. To create that target, select File->New->Target and under watchOS->Application, select WatchKit App. Call the target “Watch Names” and uncheck the checkboxes to add a Notification, Glance or Complication. This will give you two extra groups (folders) in Xcode, “Watch Names” and “Watch Names Extension”. The extension contains the classes (the brains) and “Watch Names” contains the interface (the looks) in a single Storyboard file. The part with the interface is generally called the “WatchKit App” and the extension is called the “WatchKit Extension”. Open the Interface.storyboard file and you should see one scene, currently empty.

Add a WKInterfaceTable and configure it

You’re going to add a table to the Storyboard, add a label to the table’s single row and configure the label to display the word “Hello”.

With the Interface.storyboard file open, find the objects library (⌃-⌥-⌘-3) and search for table. Click once on the table to see its description:

A table displays one or more rows of data. The table’s row templates define the types of rows that can appear in the table. Your app extension provides the row data dynamically using the WKInterfaceTable API.

Drag the table onto the Storyboard scene and position it at the top of the interface (it will probably default to this position anyway). Expand the hierarchy in the Document Outline and you will see the following:

- Interface Controller
    - Table
        - Table Row Controller
            - Group

The surprising object here is the Table Row Controller. The color in Interface Builder suggests that it’s a WKInterfaceController subclass (similar to a view controller) but in reality it’s a simple NSObject subclass which you create yourself. The row controller is responsible for defining the interface objects for a row. You will use a custom row controller to allow customisation of both the interface objects in the row and their contents. Before you do that, you’ll set up one row without using a custom row controller.

Search for and drag a WKInterfaceLabel from the object library into the table row controller’s group. Every row controller has a group object to contain it’s interface objects. Change the title text of the label to say “Hello” and then Build and Run your app. You can ignore any warnings Xcode gives you for the moment. When the watch app installs, you should see a table with a single row containing the word Hello. Note that this may not work in the current beta of Xcode. I’ve files a radar about creating static tables. If the table doesn’t show for you (black screen), keep going and I’ll show you how to create a full table.

Use a custom row controller to create a table

To create a more dynamic table, you need to have a custom row controller. Select the “Watch Names Extension” group and create a new file (⌘-N). Under watchOS->Source, select the WatchKit Class template and call it “NameRowController”, selecting NSObject as the Subclass of and Swift as the language. Ensure that the file’s target is the Watch Names Extension (the target where the Watch App’s class files go). This row controller will be a way to access and update the row’s label.

Open the Storyboard file again and select the Table Row Controller. You need to change the row controller’s class to the one we just created. Open the Identity Inspector (⌘⌥-3) and set the Class to NameRowController. It should auto-complete. Open the Assistant Editor (⌘-⌥-Return) and if Xcode doesn’t open your NameRowController subclass, open it manually there. Create an outlet called “nameLabel” by ⌃-dragging from the label to inside the NameRowController class. Be careful that you are not dragging from the group. If you do, the option to create an outlet won’t appear. Either select the label before dragging or drag from the label in the Document Outline.

Your class should now look like this:

import WatchKit

class NameRowController: NSObject {

    @IBOutlet var nameLabel: WKInterfaceLabel!
}

with a filled circle beside the IBOutlet to indicate that it’s properly connected.

Custom row controller’s aren’t identified in code by their class, instead they use an identifier string which is set in Interface Builder. With the Name Row Controller selected, open the Attributes Inspector (⌘-⌥-4) and set the Identifier field to NameRowControllerIdentifier. Normally you would give the identifier the same name as the class, but it’s important to know that the class name and identifier are different and must both be set for the table to work. If you forget to set the Identifier, you’ll get a warning like this:

Name Row Controller is missing an identifier.

Add data to the table

Once the row controller is in place you need to configure each row’s data. In the InterfaceController class, create an array of strings to serve as a model object:

  let names = [“Matthew”, “Mark”, “Luke”, “John”]

Create an outlet for the table called “table” by ⌃-dragging from Interface Builder into the InterfaceController class.

Now tell the table how many rows it will display and what their type will be. Add this to the awakeWithContext() method:

table.setNumberOfRows(names.count, withRowType: “NameRowControllerIdentifier”)

Note that you have to set the row type here even though you’ve also set it in the Storyboard. After receiving setNumberOfRows(_:withRowType) the table instantiates all the needed instances of your row controller class and stores them internally, ready for you to finish their configuration.

If you Build and Run at this stage, a table will appear with four rows, but the rows will not yet be configured with the names array.

To configure the row contents, request the row controller for each row from the table using rowControllerAtIndex(_:). This returns an instance of your custom row controller class. Use the nameLabel property that you created to directly set the label’s text:

    for (index, name) in names.enumerate() {
        let row = table.rowControllerAtIndex(index) as! NameRowController
        row.nameLabel.setText(name)
    }

This loops through the model array, using the index to reference the correct row. Since rowControllerAtIndex() returns AnyObject, it needs to be cast to your row controller class. There is no other way to get rows from the table. For example, WKInterfaceTable doesn’t provide a rows property as an array of row controllers.

The table is now fully set up. Build and Run to check that it’s working.

Better interface for row controller

Accessing the view object directly in the row controller can be avoided by using a String object to hold the title. Use willSet to update the label and set the label to private to disallow access from outside.

@IBOutlet private var label: WKInterfaceLabel!

var text: String = “” {
    willSet {
        self.nameLabel.setText(newValue)
    }
}

Now you can also access the row’s title using row.text while providing a cleaner interface and ensuring control over the display.

Final Notes

There are no special requirements for what class the row controller should be. You can compile code that uses an NSArray subclass, although most will crash at run time.

Because the table is always created in Interface Builder, if you try to access it in the init method, you will get an unexpected nil crash. It’s available in awakeWithContext(_:) or willActivate().

There’s no equivalent to UITableView’s reloadData() method. Instead you call setNumberOfRows(_:withRowType:) again, or use `insertRowsAtIndexes(_: withRowType:)

You can have any number of interface elements in your row controller and they can be of any type. For example, you could have a table of date interface objects, or images, or images with labels. Each one will have a corresponding outlet in the row controller to configure it.

Create a table that doesn’t respond to taps (either by highlighting or sending a message to the controller) by de-selecting “Selectable” for the row controller in Interface Builder.

Summary

Set up up a basic table

1. Create a new project
2. Add a watch app target (no notification, complication or glance)
3. Open the watch’s Storyboard
4. Open the object library (⌃-⌥-⌘-3)
5. Search for table in the object library and drag one onto the UI
6. Drag a label onto the table’s group
7. Change the label text to “Hello”
8. Build and run. You should see a table with one row. (Or maybe not. See above).

Make the table display model data

1. Create a new NSObject subclass called “NameRowController.swift”
2. Change the subclass of the row controller in IB to NameRowController
3. Drag out an outlet from the row’s label to the subclass called “name”
4. Change the identifier to “NameRowControllerIdentifier”
5. Create an outlet from the main interface class to the table
6. Create an array of strings to serve as the model
7. In the main interface’s -awakeWithContext(_:) function, set up the table
8. Tell the table how many rows and what type it has using setNumberOfRows(_:withRowType:)
9. Set the content of each row using rowControllerAtIndex(_:)
10. Build and run. A table appears

Respond to taps

1. Implement table(_:, didSelectRowAtIndex:) in the interface controller
2. Print the selected row’s title in the console (using the index and model)

Today extensions or “Widgets” are a new feature of iOS 8 which allow developers to provide an app’s core functionality into the Notification Center. If an app relies on location, the Widget will also need to be able to use location.

Getting the user’s location in a Widget is a common use case. The app might need to check the weather in the current location, or put up a notice about interesting places nearby. Fortunately it’s just as easy to get location in a Widget as it is in a full app.

The minimum steps to use location in a Widget are as follows:

In the main app:

• Add an NSLocationWhenInUseUsageDescription key with a description string in the container app’s Info.plist

In the Widget:

• Import the CoreLocation framework
• Create a location manager (‘CLLocationManager’)
• Request authorization and start the location manager
• React to the delegate methods

Add the reason for using location in the Info.plist along with the key and that text will be shown to the user when they are asked for permission.

Requesting permission

If the container app relies on location, you can request the user’s permission there and the Widget will automatically be granted the same permission. If the user opens the widget before opening the main app, location authorization will be requested there and subsequently available in the main app without prompting.

There’s no need to request background (always) location for the Widget to work, WhenInUse authorization is enough. A Widget only ever works in the foreground and cannot be woken for background tasks. If your app needs Always authorization, request that type in the Widget too.

Caching location

If you want your Widget to acquire a very quick location fix, you can request background location for your main app, use the significant location change service, and share that location in a shared container that the Widget can quickly read from when its first brought up.

Implementation

Here’s an implementation for a Today Extension that will request WhenInUse location authorization. It sets a label’s text to the latitude and longitude of the current location. If there are errors, it repurposes the label to show the error as an alternative to NSLog() debugging.

#import "TodayViewController.h"
#import <NotificationCenter/NotificationCenter.h>
@import CoreLocation;

@interface TodayViewController () <NCWidgetProviding, CLLocationManagerDelegate>

@property (strong, nonatomic) CLLocationManager *locationManager;
@property (weak, nonatomic) IBOutlet UILabel *locationLabel;

@end

@implementation TodayViewController

- (void)viewDidLoad
{
    [super viewDidLoad];

    self.locationManager = [[CLLocationManager alloc] init];
    self.locationManager.delegate = self;
    // iOS 8 and higher
    if ([self.locationManager respondsToSelector:@selector(requestWhenInUseAuthorization)]) {
        // TODO: Remember to add the NSLocationWhenInUseUsageDescription plist key
        [self.locationManager requestWhenInUseAuthorization];
    }

    [self.locationManager startUpdatingLocation];
}

- (void)locationManager:(CLLocationManager *)manager didUpdateLocations:(NSArray *)locations
{
    CLLocation *location = [locations lastObject];

    // Output the time the location update was received
    NSDateFormatter *dateFormatter = [[NSDateFormatter alloc] init];
    dateFormatter.dateStyle = NSDateFormatterNoStyle;
    dateFormatter.timeStyle = NSDateFormatterMediumStyle;
    NSString *timeString = [dateFormatter stringFromDate:[NSDate date]];

    // Create a string from the CLLocation
    NSString *latLonString = [self stringFromCoordinate:location.coordinate];

    // Set the main label of the Widget to the date and coordinate
    self.locationLabel.text = [NSString stringWithFormat:@"%@ %@", timeString, latLonString];
}

- (void)locationManager:(CLLocationManager *)manager didFailWithError:(NSError *)error
{
    self.locationLabel.text = error.localizedDescription;
}

- (NSString *)stringFromCoordinate:(CLLocationCoordinate2D)coordinate
{
    return [NSString stringWithFormat:@"%f %f", coordinate.latitude, coordinate.longitude];
}

- (void)widgetPerformUpdateWithCompletionHandler:(void (^)(NCUpdateResult))completionHandler
{
    completionHandler(NCUpdateResultNewData);
}

@end

Watching the Apple Watch Keynote, the animation that plays when the watch app opens escaped my notice. It’s the kind of thing that most people won’t see at first, but which they will certainly feel and take in subconsciously. The kind of wow! that Apple does so well. It was only when I went back over they Keynote video, pausing to take in the details, that I noticed how complex and fluid it is.

Apple are so proud of this animation that they show it in various forms more than ten times throughout the keynote. The Jony Ive narrated video has a slowed down version which I’ve slowed even further.

Some things to note:

• The dial animation runs clockwise, of course. The close animation runs in reverse, going anti-clockwise.
• Each watch face has its own animation. This one is the most detailed.
• The watch app is the only one to have a complex open animation. Other apps fade in from the icon. It would be great if there was a dedicated API to create these animations, but it would delay the actual app open time for most apps.
• In the live demo, the animation is finished in around a second. It’s very hard to see the detail in real-time (at least in the Keynote video).
• While the design motif of iPhone is rounded rectangles, the design motif of the watch is circles. The circular icons are arranged in a circular pattern, operated by a circular gesture. The watch app opens with a circular animation.
• Open animations for apps composed of a full-screen light-colored rectangle don’t look as good. The Maps and Photos apps are like that. Apps with a dark background look better, having no edges. This is the trade-off of a circular interface in a rectangular screen.
• In the live demo, a touch on the watch app shows a slightly different open animation. The icon reacts to the touch and shrinks slightly before it expands. This makes it feel like the icon is actually being pressed. Lots of the animations on the watch have that “alive” feeling, using more cartoon-style, dynamic animations than on iPhone. Instead of slowing to a stop (as in iOS’s ease-in ease-out animation) they pass their final destination slightly then snap back. On the iPhone interface it feels like you are interacting with physical inanimate objects; paper, pages, buttons. On the watch it feels like the objects have a life of their own. Like a Tamagochi. This is certainly deliberate.

The CLLocationManager, introduced in iPhone OS 2, has always worked the same way: Create, delegate, start, wait.

// Import CoreLocation framework
// Add <CLLocationManagerDelegate> conformance

// Create a location manager
self.locationManager = [[CLLocationManager alloc] init];
// Set a delegate to receive location callbacks
self.locationManager.delegate = self;
// Start the location manager
[self.locationManager startUpdatingLocation];

// Wait for location callbacks
- (void)locationManager:(CLLocationManager *)manager didUpdateLocations:(NSArray *)locations
{
    NSLog(@"%@", [locations lastObject]);
}

The only big change has been a different delegate method to listen for updates, but the old method continues to work. There was always the frustration of it failing silently when you forgot to set its delegate or mistyped the delegate method’s signature, but these mistakes are well known and well documented.

Location Manager fails to start in iOS 8

In iOS 8, this code doesn’t just fail, it fails silently. You will get no error or warning, you won’t ever get a location update and you won’t understand why. Your app will never even ask for permission to use location. I’m experienced with Core Location and it took me 30 minutes to figure out the new behavior. Baby devs are going to be even more frustrated by this change.

iOS 8 requirements

In iOS 8 you need to do two extra things to get location working: Add a key to your Info.plist and request authorization from the location manager asking it to start. There are two Info.plist keys for the new location authorization. One or both of these keys is required. If neither of the keys are there, you can call startUpdatingLocation but the location manager won’t actually start. It won’t send a failure message to the delegate either (since it never started, it can’t fail). It will also fail if you add one or both of the keys but forget to explicitly request authorization.

So the first thing you need to do is to add one or both of the following keys to your Info.plist file:

• NSLocationWhenInUseUsageDescription
• NSLocationAlwaysUsageDescription

Both of these keys take a string which is a description of why you need location services. You can enter a string like “Location is required to find out where you are” which, as in iOS 7, can be localized in the InfoPlist.strings file.

Next you need to request authorization for the corresponding location method, WhenInUse or Background. Use one of these calls:

[self.locationManager requestWhenInUseAuthorization]
[self.locationManager requestAlwaysAuthorization]

Here’s a full implementation of a view controller with a location manager asking for WhenInUse (foreground) authorization. This is a basic example which doesn’t take into account whether the user has already denied or restricted location.

#import "ViewController.h"
@import CoreLocation;

@interface ViewController () <CLLocationManagerDelegate>
@property (strong, nonatomic) CLLocationManager *locationManager;
@end

@implementation ViewController

- (void)viewDidLoad
{
    [super viewDidLoad];

    // ** Don't forget to add NSLocationWhenInUseUsageDescription in MyApp-Info.plist and give it a string

    self.locationManager = [[CLLocationManager alloc] init];
    self.locationManager.delegate = self;
    // Check for iOS 8. Without this guard the code will crash with "unknown selector" on iOS 7.
    if ([self.locationManager respondsToSelector:@selector(requestWhenInUseAuthorization)]) {
        [self.locationManager requestWhenInUseAuthorization];
    }
    [self.locationManager startUpdatingLocation];
}

// Location Manager Delegate Methods    
- (void)locationManager:(CLLocationManager *)manager didUpdateLocations:(NSArray *)locations
{
    NSLog(@"%@", [locations lastObject]);
}

@end

Authorization Types

There are two kinds of authorization that you can request, WhenInUse and Always. WhenInUse allow the app to get location updates only when the app is in the foreground. Always authorization allows the app to receive location updates both when the app is in the foreground and in the background (suspended or terminated). If you want to use any background location updates, you need Always authorization. An app can include plist keys for either one or both authorization types. If an app needs foreground location for it’s main functionality, but has some secondary functionality that needs background location add both keys. If the app needs background functionality as a main requirement, only all Always.

Receiving Always authorization will also give you WhenInUse but not vice-versa. If your app can function with just foreground location but you have some parts that need Always (e.g. optional geofencing functionality) you would add both keys to the plist and start by requesting WhenInUse, then later asking for Always authorization. Unfortunately, this isn’t as simple as just calling [self.locationManager requestAlwaysAuthorization] at some later point (after getting WhenInUse authorization). Unless the user has never been asked for authorization (kCLAuthorizationStatusNotDetermined) you have to ask them to change it manually in the Settings.

Here are the location types that you need Always authorization to use:

• Significant Location Change
• Boundary Crossing (Geofences)
• Background Location Updates (e.g. Fitness, Navigation apps)
• iBeacons
• Visited Locations (iOS 8+)
• Deferred Location Updates

All these location types have the power to wake the app from suspended or terminated when a location event occurs. If you have WhenInUse authorization, these services will work, but only when the app is in the foreground. There is one exception to this rule. In iOS 8, your app can request a local notification for when the user crosses a set location boundary (geofence). When the user crosses the boundary the system sends a local notification from your app but without waking your app. If the user chooses to open the notification your app will then open, receive the boundary information and be able to use foreground location services as normal.

Authorization Statuses

There are two new authorization statuses in iOS 8. Here’s a description of all statuses:

• kCLAuthorizationStatusNotDetermined User hasn’t yet been asked to authorize location updates
• kCLAuthorizationStatusRestricted User has location services turned off in Settings (Parental Restrictions)
• kCLAuthorizationStatusDenied User has been asked for authorization and tapped “No” (or turned off location in Settings)
• kCLAuthorizationStatusAuthorized User has been asked for authorization and tapped “Yes” on iOS 7 and lower.
• kCLAuthorizationStatusAuthorizedAlways = kCLAuthorizationStatusAuthorized User authorized background use.
• kCLAuthorizationStatusAuthorizedWhenInUse User has authorized use only when the app is in the foreground.

Note that the pre-iOS 8 status “Authorized” is the same code as the iOS 8 status “Always”. This means that if an app has received location permission before the user updates to iOS 8, the app will automatically receive Always (background location) authorization. If the app hasn’t been built to work with the iOS 8 APIs, on first run (on iOS 8) it will ask for Always authorization by default with the message:

“Allow YourApp to access your location even when you are not using the app?”

The system may ask a second question at some later stage (saying that it’s been using your location in the background) if the app does use location in the background. This question will pop up as an alert, generally appearing in the Springboard. Obviously it’s sensible to update your code for iOS 8 to prevent the user from denying permissions they regard as too permissive. Paranoid users may go through the location settings changing all permissions to “When In Use”, so you should be prepared to re-request “Always” if it’s necessary for your app.

Adding Always Authorization

If you have WhenInUse but later need Always authorization, you will need to ask the user to go to the settings and change it manually. You can use the new iOS 8 URL String UIApplicationOpenSettingsURLString to open directly in the correct place in the Settings (this code won’t work on iOS 7):

- (void)requestAlwaysAuthorization
{
    CLAuthorizationStatus status = [CLLocationManager authorizationStatus];

    // If the status is denied or only granted for when in use, display an alert
    if (status == kCLAuthorizationStatusAuthorizedWhenInUse || status == kCLAuthorizationStatusDenied) {
        NSString *title;
        title = (status == kCLAuthorizationStatusDenied) ? @"Location services are off" : @"Background location is not enabled";
        NSString *message = @"To use background location you must turn on 'Always' in the Location Services Settings";

        UIAlertView *alertView = [[UIAlertView alloc] initWithTitle:title
                                                            message:message
                                                           delegate:self
                                                  cancelButtonTitle:@"Cancel"
                                                  otherButtonTitles:@"Settings", nil];
        [alertView show];
    }
    // The user has not enabled any location services. Request background authorization.
    else if (status == kCLAuthorizationStatusNotDetermined) {
        [self.locationManager requestAlwaysAuthorization];
    }
}

- (void)alertView:(UIAlertView *)alertView clickedButtonAtIndex:(NSInteger)buttonIndex
{
    if (buttonIndex == 1) {
        // Send the user to the Settings for this app
        NSURL *settingsURL = [NSURL URLWithString:UIApplicationOpenSettingsURLString];
        [[UIApplication sharedApplication] openURL:settingsURL];
    }
}

If the status is kCLAuthorizationStatusRestricted, the user probably can’t do anything to change that setting and should not be alerted. You can tie this method to some user action (such a a button to turn on geofencing) so that the user knows that it is their action that has caused the request for location. Disable the button if the status is Restricted.

Adding Authorization Types

If you upload an app to the store which uses one authorization type but then later decide that you need another, you can add the second plist key. Here are the rules for changing authorization type (these are mostly guesses):

• The system will preserve authorization if the accepted mode is still supported by the new key
• If you support WhenInUse and add Always, WhenInUse will still work. Always will need to be requested via Settings.
• If you support Always and add WhenInUse, both should work
• If you support both and remove Always it will probably depend on which one the user has granted
• If you support both and remove WhenInUse it will probably work as long as Always had been granted
• If you remove Always and add WhenInUse, WhenInUse will work probably automatically
• If you remove WhenInUse and add Always, app will probably prompt for permission again

Authorization and Maps

It doesn’t end with CLLocationManager. If you are using MapKit to show maps you will need to add code to request authorization before the map can show the user’s location. There are two ways to show the user’s location on a map, with the MKMapView property showsUserLocation or by using an MKUserTrackingBarButtonItem. Location will work with either authorization type but only actually needs WhenInUse to function. If you are setting showsUserLocation in code, set the plist key and then request authorization before that call:

self.locationManager = [[CLLocationManager alloc] init];
self.locationManager.delegate = self;

// TODO: Add NSLocationWhenInUseUsageDescription in MyApp-Info.plist and give it a string

// Check for iOS 8
if ([self.locationManager respondsToSelector:@selector(requestAlwaysAuthorization)]) {
    [self.locationManager requestWhenInUseAuthorization];
}
self.mapView.showsUserLocation = YES;

Authorization with MKUserTrackingBarButtonItem

If you are using an MKUserTrackingBarButtonItem, you probably won’t be changing showsUserLocation in code (since that’s what the button does) but you still need an opportune place to call requestWhenInUseAuthorization. If the arrow button is tapped while there is no authorization, it will spin but never activate location. To make sure this doesn’t happen, you have to check the current authorization type and either request authorization or tell the user to go to the settings and turn on location services. The best place to do this is in the MKMapView delegate method mapViewWillStartLocatingUser: which is called when showsUserLocation changes to YES. This code is iOS 8+.

- (void)viewDidLoad
{
    [super viewDidLoad];

    // Add a user tracking button to the toolbar
    MKUserTrackingBarButtonItem *trackingItem = [[MKUserTrackingBarButtonItem alloc] initWithMapView:self.mapView];
    [self.toolbar setItems:@[trackingItem]];
    // Need a delegate to receive -mapViewWillStartLocatingUser:
    self.mapView.delegate = self;

    self.locationManager = [[CLLocationManager alloc] init];
    self.locationManager.delegate = self;
}

// MKMapViewDelegate Methods
- (void)mapViewWillStartLocatingUser:(MKMapView *)mapView
{
    // Check authorization status (with class method)
    CLAuthorizationStatus status = [CLLocationManager authorizationStatus];

    // User has never been asked to decide on location authorization
    if (status == kCLAuthorizationStatusNotDetermined) {
        NSLog(@"Requesting when in use auth");
        [self.locationManager requestWhenInUseAuthorization];
    }
    // User has denied location use (either for this app or for all apps
    else if (status == kCLAuthorizationStatusDenied) {
        NSLog(@"Location services denied");
        // Alert the user and send them to the settings to turn on location
    }
}

Another thing to note is that you can call either request...Authorization, but unless the status is NotDetermined the call will do nothing. If authorization has already been granted there’s no need to call this method, but there’s also no harm in calling it.

If the current authorization status is anything other than kCLAuthorizationStatusNotDetermined, this method does nothing and does not call the locationManager:didChangeAuthorizationStatus: method.

Here’s what request...Authorization does in various cases of kCLAuthorizationStatus:

• kCLAuthorizationStatusNotDetermined Show an alert with your description and buttons to Accept/Cancel
• kCLAuthorizationStatusRestricted Nothing happens and location services don’t start
• kCLAuthorizationStatusDenied Nothing happens and location services don’t start.
• kCLAuthorizationStatusAuthorized Location services start without an alert
• kCLAuthorizationStatusAuthorizedAlways Location services start without an alert
• kCLAuthorizationStatusAuthorizedWhenInUse Location services start (Always included WhenInUse authorization)

Conclusion

This big change in the location manager can be summed up as “the location manager used to automatically ask for permission when it was asked to start (if it needed it) but now you must explicitly ask for that permission at a time of choosing”. This gives more control to the developer over when to request permission, but also makes it more complex. To have a working location manager in iOS 8 you have to add appropriate plist keys and ask the location manager for authorization to receive location updates.

For such a small change to authorization, there are a surprising number of edge cases. Hopefully this post helped you to understand how you can use location services while giving your users a sense of control over how their location is used.

More Information

• WWDC 2014 Session 706 “What’s New in Core Location”
• Location and Maps Programming Guide
• CLLocationManager Class Reference
• Locate Me Sample Code