Running the app on your device

Get with the program

You cannot run apps on your iPhone unless you have a paid iOS DeveloperProgram account. Without this account, your apps will never leave theSimulator.

While it is possible to do a lot of development work on the Simulator, somethings it simply cannot do. If your app needs the iPhone’s accelerometer, forexample, you have no choice but to test that functionality on an actual device.Don’t sit there and shake your Mac!

You also need to be a member of the paid Developer Program if you want toput your apps on the iTunes App Store.

Go to developer.apple.com/programs/ios to sign up. 

In order to allow Xcode to put an app on your iPhone, the app must be digitallysigned with your Development Certificate. Apps that you want to submit to theApp Store must be signed with another certificate, the Distribution Certificate.

A certificate is an electronic document that identifies you as an iOS applicationdeveloper and is valid only for a limited amount of time. These certificates are partof your Developer Program account.

In addition to a valid certificate, you also need a so-called Provisioning Profile foreach app you make. Xcode uses this profile to sign the app for use on your device.The specifics don’t really matter, just know that you need a provisioning profile orthe app won’t go on your device.

Any devices you want to use with Xcode on must be registered with your DeveloperProgram account. There is a limit to how many devices you can register, currentlyup to 100. This may sound like plenty – you probably don’t have a hundred iPhoneslying around – but this includes devices of beta testers and anyone else you want todistribute your app to outside of the App Store. Use them sparingly!

(Note: New in iOS 8 is support for the TestFlight beta testing service, which doesnot require you to register the devices of beta testers with your account.)

Making the certificates and provisioning profiles used to be frustrating and error-prone. Fortunately, those days are over: Xcode 6 makes it really easy.

! Connect your iPhone, iPod touch, or iPad to your Mac using the USB cable.
! From the Xcode menu bar select Window → Devices to open Xcode’s Devices

window.
Mine looks like this (I’m using an iPad mini): 

On the left is a list of devices that can be used for development.

! Click on your device name to select it.

If this is the first time you’re using the device with Xcode, the Devices window willsay something like, “Matthijs’s iPad is not paired with your computer.” To pair thedevice with Xcode, you need to unlock the device first (slide to unlock).

After unlocking, an alert will pop up on the device asking you to trust the computeryou’re trying to pair with. Tap on Trust to continue.

Xcode will now refresh the page and let you use the device for development. Youmay need to unplug the device and plug it back in first.

At this point it’s possible to get the error message, “An error was encountered whileenabling development on this device.” You’ll need to unplug the device and rebootit. Make sure to restart Xcode before you reconnect the device. (General tip: If yourun into weird problems, restarting Xcode usually fixes it.)

Cool, that is the device sorted.

The next step is setting up the Developer Program account with Xcode. At this pointI assume you’ve already registered and paid for the account and you have yourApple ID and password handy.

! Open the Accounts pane in the Xcode Preferences window: 

! Click the + button at the bottom and choose Add Apple ID.Xcode will ask for your Apple ID: 

! Type the username and password for your Developer Program. This is the samelogin that you use for the iOS Dev Center website.

Xcode verifies your account details and adds them to the accounts window.! Click the View Details... button in the bottom-right corner.

This brings up another panel, listing your signing identities (the certificates) and theprovisioning profiles. Currently this panel will be empty: 

! Click the arrow in the bottom-left corner. Xcode now contacts the iOS Dev Center

to fetch any certificates and provisioning profiles that you already have.

If this is your first time, you’ll get the following message because you do not have aDevelopment Certificate yet: 

! Click Request and wait a few seconds. Great! That wasn’t so hard, was it? !

While you’re waiting, Xcode automatically registers your device with your DeveloperProgram account, creates a new Development Certificate, and downloads andinstalls the so-called Team Provisioning Profile on your device. (They call it the“team” profile because it will work on all the devices that you have registered withthe Developer Program.)

When you’re done, close the Accounts window and return to the Devices window.You can see the profiles that are installed on your device by right-clicking the

device name and choosing Show Provisioning Profiles: 

The Team Provisioning Profile has a so-called wildcard App ID (*), which means youcan use it for any application you are developing (as long as they don’t require anyspecial features such as push notifications).

Thanks to the Team Provisioning Profile you won’t have to repeat this procedure forany of the other apps that you will be developing in this series. Xcode knows aboutthe profile now and it will automatically use this profile to sign your apps. 

You can also login to the iOS Dev Center website to see what the provisioningprofile looks like there. Needless to say, you only have access to this portal if you’rein the paid iOS Developer Program.

! Go to developer.apple.com/devcenter/ios and log in. Under iOS DeveloperProgram, choose Certificates, Identifiers & Profiles. 

It’s easiest to simply let Xcode handle all the certificate and provisioning profilestuff but you can also manage these things yourself from the iOS Dev Center. Youcan download the handy App Distribution Guide that explains how all of thisworks in detail.

This concludes the setup. You have added your Developer Program account toXcode, obtained a Development Certificate, registered your device, and installed aprovisioning profile. You’re ready to run the app on your phone!

! Go back to Xcode’s main window and click on the scheme selector in the toolbarto change where you will run the app. The name of your device should be in thatlist somewhere.

On my system it looks like this: 

! Press Run to launch the app.

At this point you may get a popup with the question “codesign wants to sign usingkey ... in your keychain”. If so, answer with Always Allow. This is Xcode trying touse the new Development Certificate you just created but you need to give itpermission first.

Does the app work? Awesome! If not, read on...

There are a few things that can go wrong when you try to put the app on yourdevice, especially if you’ve never done this before, so don’t panic if you run intoproblems.

The device is not connected. Make sure your iPhone, iPod touch, or iPad isconnected to your Mac. The device must be listed in Xcode’s Devices window andthere should not be a yellow warning icon next to the device name.

The device is locked. If your phone locks itself with a passcode after a fewminutes, you might get this warning: 

Or you might get a message in the Xcode Debug output pane:

error: failed to launch ‘BullsEye‘ -- device locked

Simply unlock your phone (type in the 4-digit passcode) and press Run again.

No signing identity found. Your Development Certificate is not found, not valid,or is missing the corresponding private key. When this happens, Xcode will offer to 

request a new certificate. You can also make the certificate yourself on the iOS Dev

Center and add it to Xcode in the Accounts preferences panel.

Code Sign error: a valid provisioning profile matching the application’sIdentifier ‘com.yourname.BullsEye’ could not be found. Xcode does not havea valid provisioning profile for signing the app. The installation of the TeamProvisioning Profile has apparently failed.

No valid provisioning profile on the device. This really shouldn’t happenbecause Xcode will automatically install the profile onto the device before it runsthe app, but you never know.

Xcode could not find a valid private-key/certificate pair for this profile inyour keychain. Your development certificate isn’t properly installed. This canhappen when you moved your certificates to a new computer but forgot to movethe corresponding private keys as well.

The first step in solving such problems is to restart Xcode and try again. That’salways good advice when Xcode does not do what you want.

If that doesn’t help, open the Preferences window and go to the Accounts tab.Select your account and click the View Details button. In the dialog that appears,click the refresh button (the arrow in the bottom-left corner). Xcode will now fetchyour data from the iOS Dev Center again.

Alternatively, open the Dev Center website in your browser (tip: it works best onSafari) and download the Provisioning Profile to your computer, then drag it ontothe Xcode icon. Click on the Show Provisioning Profiles item under the name of thedevice and verify that the profile is installed on that device. If necessary, you canclick the + button to install the profile manually.

If you want to know how Xcode chooses which profile and certificate to sign yourapp with, then click on your project name and switch to the Build Settings tab.There are a lot of settings in this list, so filter them by typing code sign in thesearch box. (Also make sure All is selected, not Basic.)

The screen will look something like this: 

Under Code Signing Identity it says Debug, Any iOS SDK: iPhone Developer.This is the certificate that Xcode uses to sign the app. If you click on that line, youcan choose another certificate. Under Provisioning Profile you can change theactive profile.

Xcode is actually pretty smart about automatically picking the right provisioningprofile for you, but now at least you know where to look.