iOS Device Provisioningthe Big Nerd Ranch Guide

Introduction

When students are preparing to attend one of our iOS Bootcamps, we typically recommendthat they sign up in advance for the Apple Developer Program, and bring a provisioned devicewith them. As this can be a somewhat involved process to troubleshoot, we don’t have time tospend on this at the beginning of our already jam-packed week.

Here’s a guide, then, to how you can complete the process at home.

This is a “living document” like Apple’s App Store Review Guidelines. I will periodically comeback and update it whenever Apple updates the developer tools or portal.

Table of ContentsRecommended SoftwareSigning up for the Developer ProgramProvisioning, The Easy WayProvisioning, The Hard Way

Getting Your CertificateAdding Your DeviceGenerating Your Profile

Testing Your SetupTroubleshootingChangelog

Recommended SoftwareThis guide and our course materials are based on the following software versions:

Xcode: 4.6.3iOS: 6.1.3 / 6.1.4 depending on deviceOS X: 10.8.4

At any given time, especially during the Summer, it is likely that there is a more recent (beta)version of Xcode available from the iOS Developer Portal.

We strongly recommend to our students that they come to class using the most up to datesoftware versions listed above. Running outdated or beta software can slow your progresssignificantly during class.

If you need to update your system software either on your Mac or on your iOS device, westrongly recommend that you do so before arriving.

Apple has guides for updating your iOS and OS X versions, and you can download the mostrecent version of Xcode from the Mac App Store.

Signing up for the Developer ProgramAnyone can test iOS apps in the iOS Simulator that ships as a part of Xcode.

If you want to test your apps on your device, however, you must be a paid member of the iOSDeveloper Program.

If your company has an app on the App Store, it is possible that you might be able to use thecompany iOS Developer Program membership rather than paying for your own. Even in suchcases, I typically recommend that folks have their own personal memberships; life is so mucheasier with one, and it’s only $99.

You can enroll in the Standard iOS Developer Program on Apple’s website.

Except where explicitly stated otherwise, the rest of these instructions will assume that youhave an individual iOS Developer Program membership.

Provisioning, the Easy WayRecent versions of Xcode have built in functionality to make the process of setting up a devicevery easy. This works just fine most of the time.

Here’s how:

Connect your iOS device to your Mac via the USB cableLaunch Xcode and show the Organizer window (select Organizer from the Windowmenu)Switch to the Devices tab of the Organizer, and select your device from the list on theleft.Click “Use for Development”.

Xcode will begin the process of chatting with Apple’s servers and may ask some questionsabout requesting certificates, adding your device to the portal, and finally generating anddownloading your provisioning profiles. Answer any of these in the affirmative.

If the little gem next to your device in the Organizer device list turns green, you’re done! Skipdown to the Testing Your Setup section. Yeehaw!

If the gem didn’t turn green, then there was a hiccup in the automatic process, and you’ll needto do it manually. Continue to Provisioning, The Hard Way.

Provisioning, the Hard Way

Getting Your Certificate

The first ingredient you’ll need is a secure certificate that you can use to digitally sign yourapps before they’ll run on the device.

Launch the Keychain Access application on your Mac. It lives in the Utilities subfolder of theApplications folder. You can also find it with Spotlight.

Select My Certificates from the left-hand sidebar. You should see a list of certificates youhave on your system.

There is one certificate in particular that you’re looking for. It’s named iPhone Developer:Your Name (XXXXXXXXXX):

Don’t worry if you don’t have an entry like this, or even if the entire list is empty. That’s whatyou’re here to find out.

If you see an item like the one above, click on the little gray disclosure triangle to its left, toexpand it. You should see a sub-item with an icon that looks like a key, and has “private key”in the “kind” column, as illustrated above.

If you see an “iPhone (or iOS) Developer” certificate and it’s got a private key attached to it,then you’re done with this step! Continue to Adding Your Device.

If you don’t have a certificate, or you have a certificate without a private key, then you’ll needto go through the certificate generation process. Let’s get started.

Select Request a Certificate From a Certificate Authority… from the Certificate Assistantsub-menu of the Keychain Access menu at the top of the screen. This will launch theCertificate Assistant.

For the User Email Address, enter your Apple ID email address. Enter your name for theCommon Name, select Saved to Disk from the options at the bottom, and then clickContinue.

When asked, let the Certificate Assistant save the file (named“CertificateSigningRequest.certSigningRequest” by default - that’s fine) to your Desktop. You’llneed that file shortly. Click Done.

Next, sign into the Certificates, Identifiers & Profiles page of the iOS Dev Center.

Click Certificates.

You should be looking at the certificate, device, app, and provisioning profile managementresource, with your Certificates list (which is probably empty) currently selected. I recommendbookmarking this page; it’ll come in handy.

Click on the + button to launch the “Add iOS Certificate” assistant.

The first question is, “What type of certificate do you need?”, and the answer is iOS AppDevelopment. Select this option and scroll down, then click Continue.

This next page walks you through steps you’ve already taken. Click Continue again.

On this page, titled “Generate your cerficate”, click Choose File… and select theCertificateSigningRequest.certSigningRequest file that you created earlier in KeychainAccess and saved to your Desktop.

Click Generate. The page will take a brief coffee break while it crunches some numbers andgenerates the certificate you’ve requested.

When the page resumes, you’ll have a Download button. Click it to download your freshly-minted certificate.

Click Done, and you’ll be returned to the Certificates list. You should now see a line item herewith your name, “iOS Development” as its type, and an expiration date one year from now.

Go find the “ios_development” file you’ve downloaded (it’s probably in your Downloads folder),and double-click it. Keychain Access will pop back up, asking where you’d like to import thiskey. Make sure your login keychain is selected, and click Add.

Return to Keychain Access once more, and verify that you now see a certificate under MyCertificates with a private key associated with it:

If you do, you’re clear to go on to the next step, Adding Your Device. Otherwise, somethingwent wrong, and you may want to retry this step or have a look at some of the advice in theTroubleshooting section below.

Adding Your Device

You made it! Things get easier from here, I promise.

Next, it’s time to identify your device to Apple so that Xcode can sign each of your apps to runon your device.

Back in the Xcode Organizer, have a look at your device. The number named “identifier” (alsocalled Universal Device Identifier, or UDID) is a 40-character alphanumeric string.

Copy it to the clipboard, like you would any text.

Back in the Certificates, Identifiers & Profiles page of the iOS Dev Center, click Devices in theleft-hand sidebar. Here’s a link in case you’ve closed the page already.

If you already see your device in this list, excellent! Continue to the next section, GeneratingYour Profile.

If you don’t see it, click on the + button in the upper-right corner to add a new registereddevice.

On the next page, enter a name for your device, and paste the UDID that you copied from theXcode Organizer.

Click Continue.

You’ll be asked to double-check the submission, for a good reason. Do it, then click Register.

You’ll be dropped back at the list of your devices, but there is now an item for the deviceyou’ve just added.

Move on to the next section, Generating Your Profile.

Generating Your Profile

The final piece of the puzzle that you need is a provisioning profile. A provisioning profilecontains information about one or more developers (using your certificate), one or moredevices, and either an App ID or a Team ID. You already have a Team ID (it was automaticallygenerated for you), so all of the bits should be in place to create the provisioning profile.

Xcode is responsible for creating one for you, and keeping it in sync with the iOS Dev Center.

Open the Xcode Organizer again, and visit the Library’s Provisioning Profile’s list.

Click Refresh. Xcode will begin chattering with Apple’s servers again, like it did if youattempted Provisioning, The Easy Way. This should generate your iOS Team ProvisioningProfile.

When it’s done, look at the list again. You should see an item that looks like this:

The important bit here is that green checkbox, and the words “Valid profile.”

If yours is missing, or says anything other than “Valid profile,” you’ll need to do sometroubleshooting.

Testing Your SetupIt’s time to test an app! Woohoo!

First, connect your device and leave it connected for the rest of this test.

In Xcode (not the Organizer), select New > Project… from the File menu at the top of thescreen. This will begin the New Project assistant.

In the left-hand sidebar, select Application from the iOS group, and choose the UtilityApplication template and click Next.

Fill out the short questionnaire about your new project and then click Next:

The values that you enter aren’t terribly important; you’re just going to delete this projectanyway.

The last step of the New Project assistant is choosing a save location for your project. Chooseyour Desktop and click Create.

Welcome to Xcode! There’s an awful lot going on here, but we’re only interested in a verysmall piece of what Xcode can do.

If your device has a passcode, wake the device now and key it in so that you’re looking at thedevice’s Home Screen.

Have a look at the Scheme dropdown near the top-left of the window:

Select your device in the Scheme dropdown, and then click Run.

It’ll take a few moments (I’ve had it take upward of 10 seconds on a slow computer) yourdevice’s screen should turn black, and then launch the utility template app!

Congratulations! Your device is provisioned and ready for running your apps!

TroubleshootingHere are some common problems and things to try if you get stuck.

If you’re here because you’re preparing to take one of our Bootcamps and these steps aren’tworking for you, be sure to let us know and we’ll help!

I don’t have an iOS Team Provisioning Profile

Back in your web browser, on the Certificates, Identifiers & Profiles page, select ProvisioningProfiles from the left-hand sidebar.

You should see an iOS Team Provisioning Profile. Click on it.

You’ll see that your profile has at least one Certificate and at least one Device associated withit. Or maybe not.

The root problem may be:

If you have a team profile, but the number of Certificates listed is zero, then somethingwent wrong during the Getting Your Certificate step. I’d give it another go.

If you have a team profile, but the number of Devices listed is zero, then the problemmost likely happened while adding your device. Use the Adding Your Device instructionsto verify that your device has actually been added. Double, even triple check that theidentifier that you see in Xcode matches the one in the iOS Dev Center’s devices list.

If your iOS Provisioning Profiles list on this page simply has zero items in it, then thenXcode failed to create the team profile for you. The following instructions will walk youthrough creating a wildcard profile that you can use instead.

Creating a Wildcard Provisioning Profile

Start by visiting the Certificates, Identifiers & Profiles page, and select App IDs from the left-hand sidebar.

If there are no items in the list here, go create an App ID first, and then come back.

Next, verify that you have a valid certificate. Select Certificates in the left-hand sidebar. If thislist is empty, read back through Getting Your Certificate to make sure you’ve done everythingright. You may need to re-do that step from scratch, and then come back.

Provided at this point that you’ve got both a wildcard App ID (either one that was created foryou, or that you created yourself), select Provisioning Profiles from the left-hand sidebar ofthe Certificates, Identifiers & Profiles page.

Click the + button toward the upper-right corner. This begins the Add iOS Provisioning Profileassistant.

On the first page, select iOS App Development from the list, and click Continue.

On the second page, select your wildcard App ID from the list, and click Continue.

On the third page, check the box next to your Certificate name, and click Continue.

On the fourth page, check the box next to your Device name, or Select All, and click (youguessed it) Continue.

On the fifth page, name the profile “Your Name Wildcard Provisioning Profile”, and click Conti-, I mean Generate.

On the final page, click the Download button, which will download a file to your computer withthe extension .mobileprovision . Find this file (probably in your Downloads folder) anddouble-click it. This will open Xcode, which will then ingest and process the file.

You should be done now. You can read through Generating Your Profile to see how to double-check that the provisioning profile was installed.

I don’t have an App ID

Double-check by visiting the Certificates, Identifiers & Profiles page, and selecting App IDsfrom the left-hand sidebar.

If the list has zero items in it, you’ll need to make one yourself.

Click on the + button in the upper-right. This begins the Register iOS App ID questionnaire.

Here are the values to provide: - App ID Description: “Your Name Wildcard App ID” - App IDPrefix: (leave the default value) - App ID Suffix: (select Wildcard App ID) and just type “*” (anasterisk) in the box. - App Services: (leave the default options)

Click Continue.

On the “Confirm Your App ID” page, click Submit. And then click Done. Because clearly,Submit wasn’t enough. I don’t get it either.

You should now see your new App ID in the list. Woohoo!

My profile says “Valid signing identity not found” in the XcodeOrganizer

This is most commonly caused by a missing or expired signing certificate.

Read carefully through Getting Your Certificate to ensure that all of these steps were followedcorrectly, and that you have a certificate/private key pair in Keychain Access.

A common missstep is to forget to actually open the certificate file that was downloaded fromthe iOS Dev Center after you finished generating it.

My device isn’t listed in the Scheme dropdown in Xcode

In some cases, the Scheme dropdown in Xcode only has an entry called “iOS Device”, and ahandful of entries with “Simulator” in the name.

Unfortunately, the problem could be just about anywhere in the line. When this happens to me,I revisit each step of Provisioning, The Hard Way and make sure that I see what is expected.

More often than not, I’ll discover that a step was missed, for example, I may have forgotten toactually open a provisioning profile or certificate file after downloading it.

Also, it’s worth clicking the Refresh button in the Xcode Organizer’s Provisioning Profilespane. Sometimes this kicks Xcode and Apple’s server back into agreement.

Changelog2013–08–12 Created initial version of the Guide.