Iphone development

Contents

About the Tools Workflow for iOS 6
At a Glance 6
Obtain and Manage Essential Development Assets 7
Learn iOS Coding Techniques by Examining Example Projects 7
Configure iCloud-Storage Access in Your App 7
Simulate iOS on Your Mac 7
Run Your App on Your New iOS Device 7
Ensure Your App Keeps Running as Designed 7
Perform Realistic User Testing of Your App 8
Prerequisites 8
See Also 8

Configuring Development and Distribution Assets 9
Becoming a Member of a Development Team 9
Setting Up Your Development Devices 10
Provisioning a Device for Development 10
Installing iOS on a Device 13
Capturing Screenshots 14
Setting Up Your Distribution-Only Assets 15
Managing Your Signing and Provisioning Assets 15
Replacing an Expired Certificate 15
Renewing Expiring or Expired Provisioning Profiles 15
Safeguarding and Transferring Your Signing and Provisioning Assets 16

Configuring Apps 17
Configuring iCloud Entitlements 17
Specifying the Targeted iOS Version 17
Specifying the Targeted Devices 18
Specifying the Targeted Architecture 19
Compiling and Linking Code Conditionally 20
Compiling Source Code Conditionally for iOS App 20
Linking Frameworks Conditionally for iOS Apps 21
Adding the iTunes Artwork to Your App for User Testing 21
Configuring Your Project for App Store Submission 21

2012-09-19 | © 2012 Apple Inc. All Rights Reserved.

2

Contents

Building and Running Apps 23
Running Sample Apps 23
The Build-and-Run Workflow 25
Specifying the Buildtime Environment 25
Specifying the Runtime Environment 28
Building Your App 29
Running Your App 30
Managing App Data 30
Further Exploration 31

Using iOS Simulator 32
Setting the Device and iOS Version 32
Manipulating the Hardware 32
Performing Gestures 33
Installing Apps 34
Uninstalling Apps 34
Resetting Content and Settings 34
Viewing iOS Simulator Console and Crash Logs 35
Simulation Environment File System Location 35
Hardware Simulation Support 35

Ensuring High Quality and Optimal Performance 36
Ensuring Your Code Is Correct 36
Fixing Bugs in Your App 36
Debugging Facilities Overview 37
Viewing Console Output and Device Logs 38
Tuning the Performance of Your App 38
The Instruments App 39

Distributing Apps 41
Publishing Your App for User Testing 41
Adding User Testing Devices to Your Team 42
Configuring the User Testing Provisioning Profile 43
Sending Your App to Testers 43
Importing Crash Logs from Testers 43
Instructions for App Testers 44
Publishing Your App on the App Store 46
Creating a Distribution Provisioning Profile for Your App 46
Submitting Your App for Publication on the App Store 46


3

Contents

iOS Development: Troubleshooting 48
Issues 48
Certificate Issues 48
Provisioning Issues 49
Building Issues 50
Debugging Information Issues 52
Fixing Issues 53
Ensure That Your Development Signing Identity Is in Your Keychain 53
Fix the Trust Level of Your Certificates 53
Reset Your Signing and Provisioning Assets on Your Mac and in Your Team 54

iOS Development: FAQ 58
Developing a Static Library and Incorporating It in Your App 59
Glossary 61
Document Revision History 63


4

Figures, Tables, and Listings

Configuring Development and Distribution Assets 9
Figure 1-1

Digital assets required for iOS development 11

Configuring Apps 17
Listing 2-1
Listing 2-2

Determining whether you’re compiling for a simulator 20
Determining whether you’re compiling for a device 20

Building and Running Apps 23
Figure 3-1
Figure 3-2

Project with a Missing SDK issue 26
Code Signing Identity options with a specialized provisioning profile selected 27

Using iOS Simulator 32
Table 4-1

Performing gestures in iOS Simulator 33

Distributing Apps 41
Figure 6-1

Items required for sharing apps with testers 42


5

About the Tools Workflow for iOS

To develop iOS apps, you use Xcode, Apple’s first-class integrated development environment (IDE). Xcode
provides all the tools needed to design your app’s user interface and write the code that brings it to life.

At a Glance
This document describes how to perform the workflows required to develop and publish your iOS apps,
including running your app on development devices and sharing it with users for testing before publishing it
on the App Store.
The content in this document is written for Xcode 4.3 and iOS SDK 5.0.


6

At a Glance

Obtain and Manage Essential Development Assets
Before you can run iOS apps on your iOS devices, you must obtain essential development assets, including
code signing certificates, that authenticate you as an iOS app developer.
Chapter: “Configuring Development and Distribution Assets” (page 9)

Learn iOS Coding Techniques by Examining Example Projects
Viewing and analyzing iOS sample-code projects is a great way to learn how to use particular technologies
and APIs. You can incorporate the code in sample projects in your own projects to get going quickly.
Section: “Running Sample Apps” (page 23)

Configure iCloud-Storage Access in Your App
To use iCloud storage in your app you need to specify the app’s iCloud entitlements.
Section: “Configuring iCloud Entitlements” (page 17)

Simulate iOS on Your Mac
When you’re designing your app’s user experience, you can simulate its operation in your Mac using iOS
Simulator. With iOS Simulator you can get an idea of how your app will work on a device.
Chapter: “Using iOS Simulator” (page 32)

Run Your App on Your New iOS Device
After obtaining an iOS device to use in your development efforts, set it up so that you can install and run your
app on it.
Section: “Setting Up Your Development Devices” (page 10)

Ensure Your App Keeps Running as Designed
As you make changes to your app, you might introduce bugs in your code. Prevent your current work from
undoing your past efforts by incorporating unit testing in your development strategy.


7

Prerequisites

Chapter: “Ensuring High Quality and Optimal Performance” (page 36)

Perform Realistic User Testing of Your App
You cannot test your app the same way the users of your app will use it. They have different data and different
usage patterns. Before publishing your app on the App Store, put it through real-world testing to find and
solve as many problems as possible.
Section: “Publishing Your App for User Testing” (page 41)

Prerequisites
You should be familiar with basic programming concepts. You should also understand the concepts and
technologies described in:
●

Developing for the App Store

●

iOS App Programming Guide

See Also
To learn more about the iOS SDK, visit http://developer.apple.com/devcenter/ios.
To learn more about Xcode, visit http://developer.apple.com/xcode.
Note: Xcode requires a Mac.

If you’re interested in developing iOS web applications, visit http://developer.apple.com/devcenter/safari/library.


8

Configuring Development and Distribution Assets

As a registered Apple developer, you have access to iOS developer documentation and can build iOS apps
that run in simulators. (To become a registered Apple developer, visit http://developer.apple.com/programs/register.) Being a registered Apple developer, however, doesn’t allow you to run apps on iOS devices. To do so
you must also be a member of a development team. See “Becoming a Member of a Development Team” (page
9) for more information.
This chapter shows how to configure your Mac and iOS devices for iOS development. The chapter also describes
how to safeguard the digital identifications required to install apps on devices for development and distribute
them to app testers and App Store customers.
Content specifications: This content is written for Xcode 4.3 and iOS SDK 5.0.

Becoming a Member of a Development Team
To install apps that are under development on iOS devices, you must be part of a development team . A
development team associates a legal entity (a person, company, or organization), people (one or more persons
involved in developing and distributing the team’s apps), and online development resources (the iOS and Mac
provisioning portals). The people on the team can then build and run apps on development devices and
distribute them to customers. If you are authorized to distribute apps, you can send them to testers to get
feedback on real-world performance. As a distributor, you can also publish apps on the App Store.
You become a member of a development team in one of two ways:
●

You are invited to join a team by an authorized person.

●

You create your own team by enrolling in the iOS Developer Program.
To enroll in the program, visit http://developer.apple.com/programs/ios.


9

Setting Up Your Development Devices

With iOS Simulator you can start developing iOS apps without using iOS-based devices. Use simulators to
familiarize yourself with the API and development workflows used to develop applications. However, you must
always test your apps on actual devices before publishing them to ensure that they run as intended and to
tune them for performance on actual hardware.
Note: If your team duties are only to distribute apps and you don’t handle development devices,
skip this section and go to “Setting Up Your Distribution-Only Assets” (page 15).

This section shows how to configure your iOS devices for development. It also shows how to take screenshots
of your application as it runs.

Provisioning a Device for Development
To run apps you’re developing on a device, you must set up the device for development. This process involves
these main tasks, which you do in Xcode:
1.

Obtaining a developer certificate that allows you to sign apps.

2.

Obtaining a provisioning profile that identifies your developer certificate, your device, and the applications
you can run on the device.

To run apps on a device, you must configure your Mac and your device for iOS development. This section
presents an overview of the items you need to develop an iOS application on your Mac and run the application
on a device.
Note: Configuring an iOS-based device for development does not affect its normal operation.

In preparing your device for development, Xcode creates or obtains the following digital assets:
●

●

Certificate request. A certificate request (also known as a certificate signing request, or CSR) contains
personal information used to generate your development certificate .
Development certificate. A development certificate identifies you as an app developer. When it’s stored
in your keychain, it includes your private key. In your development team’s signing assets and in your
provisioning profile , it includes only your public key.
When Xcode builds your app for installation on a device, it looks for your developer certificate in your
keychain. If it finds the certificate, Xcode signs your app. Otherwise, it reports a build error.


10


●

Provisioning profile. A provisioning profile associates one or more developer certificates and one or more
devices with an app ID.
To install applications signed with your developer certificate on a device, you must install at least one
provisioning profile on the device. This provisioning profile must identify you (through your developer
certificate) and your device (by listing its device identifier). If you’re part of a multimember iOS development
team, other members of your team, if they have appropriately defined provisioning profiles, can run
applications that you build on their devices.

Figure 1-1 illustrates the relationship between these digital assets.
Figure 1-1

Digital assets required for iOS development
Keychain (login)

Xcode

Portal

Private key

Development certificate
request

request



Public key
Tester device ID

Private key

Provisioning profile

App ID
Provisioning profile
Device identifier
Device identifier
Device identifier
App ID
Device identifier

Device identifier

Important: To provision a device for development, you must be part of an iOS development team. To learn
how become part of a development team, see “Becoming a Member of a Development Team” (page 9).
Before continuing, you must know whether you are registered as the agent, an administrator, or a member of
your iOS-development team. To find your access level in the iOS Provisioning Portal:
1.

Log in to the portal.

2.

Click Member Center.

3.

Click People.


11


Provisioning Your Device for Generic Development
For Administrators or the Team Agent
If you are a team administrator or the team agent, provision your device for generic development. Xcode installs
your development certificate in your keychain (if it’s not there already), and installs the team provisioning
profile on your device.
For Team Members
To provision your device for generic development:
1.

Choose Window > Organizer to open the Organizer window.

2.

Click Devices to display the devices organizer.

3.

Plug in your device, and select it in the devices list.

4.

Click Use for Development.

5.

Copy your device identifier from the identifier text field.

6.

Send a message containing your device identifier to your team agent requesting that of your device be
added to the team’s list of devices.
Wait until the team agent tells you that the device has been added to the team’s devices list before
continuing.

7.

In the devices organizer, select Provisioning Profiles in the Library section, and click Refresh.

8.

If you don’t have a developer certificate, Xcode offers to request one on your behalf:
a.

Have Xcode request the developer certificate for you.

b.

Notify the team agent that Xcode requested a developer certificate for you.

Wait until the team agent tells you that your developer certificate has been issued before continuing.
9.

Ensure that your device is plugged into your Mac, and that it’s listed in the devices organizer.

10. Select Provisioning Profiles in the Library section, and click Refresh.

Xcode installs your developer certificate in your keychain (if the certificate is not there already), and installs
the team provisioning profile on your device.

Provisioning Your Device for Specialized Development
If your app requires special iOS-development features (such as iCloud storage, push notifications, in-app
purchases, and Game Center), you must provision your device for specialized development.
To provision a device for specialized development:


12


1.

If your device is not listed in the team’s devices list in the iOS Provisioning Portal, add the device by
following the steps in “Provisioning Your Device for Generic Development” (page 12).

2.

Ensure that the portal contains a provisioning profile that identifies the special requirements of your
application.
If the portal does not have a specialized provisioning profile for the application, the team agent or an
administrator needs to create one and add your developer certificate and devices to it before you can
continue.

3.

In the devices organizer, select Provisioning Profiles in the Library section, and click Refresh.
The specialized provisioning profile should be listed in the profiles list. If the provisioning profile is not
listed and you belong to more than one iOS development team in your organization, make sure you enter
the credentials for the correct iOS development team after clicking Refresh.

4.

Ensure that your device is plugged into your Mac.

5.

From the provisioning profiles list, drag the specialized provisioning profile to your device.

Important: After installing the specialized provisioning profile on your device, ensure that the target that
builds your app uses that provisioning profile to sign the app. See “Setting Your Code Signing Identity” (page
26) for more information.

Installing iOS on a Device
When you develop iOS apps, you should test those apps on the set of device and iOS-release combinations
you intend your app to run on.


13


Important: After you upgrade a device’s OS, you cannot downgrade it, that is, you cannot install an earlier
release of iOS on your device.

Installing public iOS versions: Use iTunes to download the latest public version of iOS and install
it on your device.

Installing beta iOS versions: You can download beta versions of Xcode and iOS from the iOS Dev
Center from http://developer.apple.com/devcenter/ios.
You must be a member of an iOS development team to be able to download beta versions of iOS.
During beta periods, you should install beta versions of iOS only on devices you dedicate to having
beta versions.
You cannot submit applications to the App Store using beta versions of Xcode.
After you get a beta version of iOS, install it on your device. After installing the software, select the
device in the devices organizer, and click Use for Development.

Capturing Screenshots
Screenshots help to document your application, and you also use them to create your app’s launch image,
which iOS displays when a user taps your app’s icon.
●

Capturing screenshots in Xcode from your connected device.
You can capture screenshots of your app while it’s connected to your Mac in the devices organizer.
After you capture a screenshot, you can make it your application’s launch image.
To get a PNG file of the screenshot, drag it to the desktop.

●

Capturing screenshots on your device.
You can capture screenshots directly on your device and import them into your Mac using the iPhoto
application.
To capture a screenshot on your device, press the Lock and Home buttons simultaneously. Your screenshot
is saved in the Saved Photos album in the Photos app.


14

Setting Up Your Distribution-Only Assets

Note: Although the launch image includes the status bar as it looked when the screenshot was
captured, iOS replaces it with the current status bar when your application launches.

Setting Up Your Distribution-Only Assets
To distribute apps you need a distribution certificate and an distribution provisioning profile:
●

●

Distribution certificate. A distribution certificate identifies your development team. When it’s stored in
your keychain, it includes the team’s private key. In your team’s signing assets and in a distribution
provisioning profile the distribution certificate includes only the team’s public key.
Distribution provisioning profile. A distribution provisioning profile includes your team’s distribution
certificate and an app ID. If the provisioning profile is for user-testing (also known as an ad hoc hoc
distribution profile ), it identifies the devices on which testers can run the app identified by the app ID.

To obtain your distribution assets:
1.

Obtain your distribution certificate.

2.

If your team doesn’t have a distribution profile for the app you want to distribute, create it.

3.

Download the distribution profile for the app you want to distribute.

Next steps:
●
“Configuring Your Project for App Store Submission” (page 21)
●

“Distributing Apps” (page 41)

Managing Your Signing and Provisioning Assets
This section describes how to update expiring or expired provisioning profiles and how to safeguard your
digital identities and share them between Macs.

Replacing an Expired Certificate
When your development or distribution certificates expire, you have to request a new certificate in Xcode.

Renewing Expiring or Expired Provisioning Profiles
When one your provisioning profiles is close to expiring or expires, you should renew it.


15

Managing Your Signing and Provisioning Assets

To renew an expiring or expired provisioning profile:
1.

In the devices organizer, select Provisioning Profiles in the Library section.

2.

In the provisioning profiles list, select the provisioning profile you want to renew.

3.

Click Renew.

Copy the renewed provisioning profile to your connected device:
1.

In the Library section in the devices organizer, select Provisioning Profiles.

2.

From the provisioning profiles list, drag the updated provisioning profile to your device.

3.

Delete the expired or expiring provisioning profile from your device by selecting it and clicking Delete.

Safeguarding and Transferring Your Signing and Provisioning Assets
Your signing and provisioning assets are the private keys, certificates, and provisioning profiles you use to
run iOS apps on your development devices. If you need to use a Mac other than the one containing your
developer assets to develop iOS apps, you must transfer the assets to the other Mac. You can do this in the
Organizer by exporting your signing and provisioning assets from the one Mac and importing them to the other.


16

Configuring Apps

This chapter describes how to configure your app’s entitlements. It also explains how to specify your app’s
targeted iOS release, device family, and architecture.

Configuring iCloud Entitlements
iCloud entitlements allow instances of your app running on a user’s various devices to use iCloud storage to
share data and documents. See “iCloud Storage” to learn more.
To configure your app to use iCloud storage, turn on app entitlements.
Xcode sets the values of the iCloud entitlements to your app’s bundle ID. See "Configuring Your App’s iCloud
Entitlements" in iOS App Programming Guide to find out whether you need to change these values.

Specifying the Targeted iOS Version
Each version of iOS (and its corresponding SDK) includes features and capabilities not present in earlier versions.
As new versions of iOS are published, some users upgrade immediately while other users wait before moving
to the latest version. You can take one of two strategies concerning the iOS version to target in developing
your app:
●

●

Target the latest iOS version. Targeting the latest version allows you to take advantage of all the features
available in the latest version of iOS. However, this approach means a smaller set of users capable of
installing your app on their devices because your apps cannot run on iOS versions that are earlier than
the target version.
Target an earlier iOS version. Targeting an earlier version lets you publish your app to a larger set of users
(because your app runs on the target OS version and later versions). However, targeting an earlier version
may limit the iOS features your app can use.

To specify the earliest iOS version on which you want your app to run:


17

Configuring Apps
Specifying the Targeted Devices

1.

In the project navigator, select the project.

2.

From the target list in the project editor, select the target that builds your app.

3.

Click Summary.

4.

From the Deployment Target pop-up menu, choose the iOS version you want to target.

When you build your app, your deployment target selection is reflected in the MinimumOSVersion entry in
the app’s Info.plist file. When you publish your app to the App Store, the store indicates the iOS version
on which your app can run based on the value of this property.
Note: If the SDK you’re using to build the app is more recent than the app’s target iOS version (for
example, the base SDK is iOS 4.3 and the deployment target is iOS 4.0), Xcode displays build warnings
when it detects that your app is using a feature that’s not available in the targeted iOS version.
You must also ensure that the symbols you use are available in the app’s runtime environment. To
check for their availability, use the techniques described in SDK Compatibility Guide .

Important: When building for a simulator, the generated binary runs only on the iOS Simulator version
that’s part of the Xcode toolset version used to build the binary. It doesn’t run on earlier or later versions
of iOS Simulator.

Specifying the Targeted Devices
The Devices setting identifies the type of devices you want the app to run on. There are two device types:
iPhone and iPad. The iPhone type includes iPhone and iPod touch devices. The iPad type includes iPad devices.
To specify the device families on which you want your app to be able to run:
1.

In the project navigator, select the project.

2.

From the target list in the project editor, select the target that builds your app, and click Summary.


18

Configuring Apps
Specifying the Targeted Architecture

3.

From the Devices pop-up menu, choose iPhone, iPad, or Universal (to target both families).

For more information on configuring your app for iPhone, iPad, or both device families, see “Advanced App
Tricks”.

Specifying the Targeted Architecture
An iOS device uses one of a set of architectures, which include armv6 and armv7. The Architectures build
setting identifies the architectures for which your app is built. You have two options for specifying the value of
this setting:
●

●

Standard. Produces an app binary with a common architecture, compatible with all supported iOS devices.
This option generates the smallest app, but it may not be optimized to run at the best possible speed for
all devices.
Optimized. Produces an app binary optimized for each supported iOS device. However, the build time is
longer than when using the Standard option, and the app is also larger because multiple instruction sets
are bundled into it.

If you need to build your app so that it contains executable code for a different set of architectures than these
predefined values offer, you can choose Other from the Architecture build-setting value list and enter the
custom iOS-device architecture names.


19

Configuring Apps
Compiling and Linking Code Conditionally

Compiling and Linking Code Conditionally
Your iOS app can run in simulators or on devices. You run your app in simulators to simulate the app’s execution
on your Mac, and you run the app on devices to test its actual performance. The simulation and device
environments are fundamentally different; therefore, when using technology that’s implemented differently
in the two environments, you need to tweak your code so that some of it runs in a simulator but not on a
device.
This section shows how to target code to a simulator or a device and which frameworks (or libraries) to link
to, depending on whether you’re building your app for a simulator or for a device.

Compiling Source Code Conditionally for iOS App
There may be times when you need to run code on a simulator but not on a device, and the other way around.
On those occasions, you can use the preprocessor macros TARGET_OS_IPHONE and
TARGET_IPHONE_SIMULATOR to conditionally compile code for all iOS-based devices.
Listing 2-1 shows how to use the TARGET_IPHONE_SIMULATOR macro to determine whether code meant for
iOS is being compiled for a simulator or a device.
Listing 2-1

Determining whether you’re compiling for a simulator

// Set hello to "Hello, <device or simulator>"!
#if TARGET_IPHONE_SIMULATOR
NSString *hello = @"Hello, iOS Simulator!";
#else
NSString *hello = @"Hello, iOS device!";
#endif

Listing 2-2 shows how to use the TARGET_OS_IPHONE macro in a source file to be shared between Mac OS X
and iOS.
Listing 2-2

Determining whether you’re compiling for a device

#if TARGET_OS_IPHONE
#import <UIKit/UIKit.h>
#else
#import <Cocoa/Cocoa.h>
#endif


20

Configuring Apps
Adding the iTunes Artwork to Your App for User Testing

The TARGET_OS_IPHONE and TARGET_IPHONE_SIMULATOR macros are defined in the
TargetConditionals.h header file.

Linking Frameworks Conditionally for iOS Apps
There may be occasions when you need to configure your app target so that it links to one framework to run
on a simulator and a different framework to run on a device.
To link a framework only when using a particular SDK, conditionally set the Other Linker Flags build setting to
-framework <framework_name> in all configurations for the SDK you want the definition to apply to.
If you need to, you can add another condition to the Other Linker Flags build setting to specify a different SDK
and framework.

Adding the iTunes Artwork to Your App for User Testing
Test versions of your app should contain artwork iTunes uses to identify your app. Otherwise, when users add
your app to their iTunes library, iTunes uses generic artwork for it.
The iTunes artwork your testers see should be your app’s icon. This artwork must be a 512 x 512 pixel JPEG or
PNG file named iTunesArtwork. Note that the filename must not have an extension.
To add the file to your project:
1.

Open your project in Xcode.

2.

In the project navigator, select your project.

3.

Choose File > Add Files to “<App_Name>”
.

4.

Navigate to the file in your file system, and select it.

5.

Select the “Copy items into destination group’s folder (if needed)” option, and click Add.

Configuring Your Project for App Store Submission
To submit your app for publication on the App Store, you need to build the app using your team’s distribution
code signing identity.
To configure your project to facilitate the building of distribution-identity–signed archives of your app:
1.

In your project, duplicate the Release build configuration and name the duplicate “AppStore”
.


21

Configuring Apps
Configuring Your Project for App Store Submission

2.

Set the Code Signing Identity build setting to your team’s distribution code signing identity through the

app’s distribution provisioning profile for the AppStore build configuration.

3.

In the target, delete the Validate Build Product build setting specification for the Release build configuration.

4.

Managing Schemes the scheme that builds your app and name the duplicate “<App_Name>-AppStore”
.

5.

In the AppStore scheme, set the build configuration for the Archive action to AppStore.


22

Building and Running Apps

When you want to run your app to test or debug it, you build it using the Xcode build system. If there are no
build errors, you can run it in a simulator or on a device.
Note: To ensure your app functions correctly on the iOS-based device models you expect the app’s
users to use, after simulating your app’s execution in simulators, you must test it on corresponding
devices.
To run your app on a device, you must be a member of a development team; see “Becoming a
Member of a Development Team” (page 9) for details. You must also identify to Xcode the devices
you intend to use for development, as described in “Replacing an Expired Certificate” (page 15).

These are the general steps to build and run an app:
1.

Specify the build-time environment.

2.

Specify the destination for which you want the product to be built: a simulator or a device.

3.

Build the app.

4.

Run the app.

This chapter describes each of the steps required to run your app. Start with “Running Sample Apps” (page
23) if you’re interested in seeing apps that showcase iOS features.

Running Sample Apps
The iOS Developer Library provides several resources that help you learn about the iOS app development
process. One of these resource types is sample code. You can access sample-code projects in the Xcode
documentation organizer or in your web browser by visiting the iOS Dev Center. You can run sample code in
a simulator. If you’re a member of a development team, you can also run sample code on devices. See “Becoming
a Member of a Development Team” (page 9) for details.
To get sample code using Xcode:


23

Running Sample Apps

1.

Choose Window > Organizer to open the Xcode Organizer, and click Documentation to display the
documentation organizer.

2.

Click the Browse button (the one with the eye icon) in the navigator selector bar of the documentation
organizer.

3.

Select the library for which you want to view sample code.

4.

In the text field in the content area, enter “sample code”
.

5.

In the content area, click the name of the project you want to open.

6.

In the sample-code project page, click Open Project.

7.

Choose a location for the project.

To get sample code using your web browser:
1.

In your web browser, go to http://developer.apple.com/devcenter/ios, and click the iOS Developer Library
link.

2.

In the list on the left, click Sample Code under the Resource Types group.

3.

In the Documents list, click the name of the project you want to open.

4.

Click Download Sample Code.
An archive containing the project directory is downloaded to your Mac. The archive may be automatically
expanded for you. If it isn’t, expand the archive by double-clicking it.

5.

Navigate to the sample-code project directory.

6.

Double-click the project package, a file with the .xcodeproj suffix.
For example, for the HelloWorld project, double-click HelloWorld.xcodeproj. This action opens the
project in Xcode.
Another way to open the project is to drag the project package to the Xcode icon in the Dock.
Troubleshooting:
●
Xcode doesn’t launch.
Download Xcode and install it on your computer. To learn how, visit iOS Dev Center.

With the sample-code project open in Xcode, follow the instructions in the following sections to build and run
the app.


24

The Build-and-Run Workflow

This section describes each of the steps in the build-and-run workflow.

Specifying the Buildtime Environment
When you build your app, Xcode uses a build environment made up of frameworks, libraries, apps, command-line
tools, and other resources. Each revision of the iOS SDK makes improvements to this environment to, for
example, add user-interface features or improve compilers and resource-processing tools. In addition to these
resources, you can specify whether you want to build your app to debug it or to distribute it to customers.
This section describes how to set your build-time environment.

Setting the SDK Used to Build Your App
One of the main factors that determine how Xcode builds your app is the SDK used to build it.
To specify the SDK to use to build your app, set the Base SDK build setting to the appropriate SDK.


25


Note: To ensure minimal reconfiguration of your projects as you adopt new SDK releases, instead
of a specific SDK release, set the base SDK for your projects to Latest iOS. This way your project always
uses the latest available SDK in the toolset.

Base SDK Missing
If your project has its Base SDK setting set to a particular iOS SDK release, when you open that project with a
later Xcode toolset distribution in which that SDK release is not available, the Base SDK setting has no valid
value. In this case, the issue navigator lists a Missing SDK issue, as shown in Figure 3-1. To fix the Missing SDK
issue, set the base SDK for the target to an available SDK release or to Latest iOS.
Figure 3-1

Project with a Missing SDK issue

Setting Your Code Signing Identity
When you build your app to run it on a device, Xcode signs it with a development certificate (also known as a
code signing identity) stored on your keychain. To learn how to obtain and install development certificates,
see “Provisioning a Device for Development” (page 10).


26


The Code Signing Identity build setting specifies the provisioning profile and code signing identity Xcode uses
to sign your binary. Xcode looks for code signing identities in your default keychain.

The possible values for the Code Signing Identity build setting are:
●

●

●

Don’t Code Sign. Choose this option to build only for a simulator.
Automatic Profile Selector. Choose an option under this selector to select a provisioning profile whose
name starts with “iPhone Developer” or “iPhone Distribution.”
Specific Profile. Choose the code-signing identity under a specific provisioning profile when your app
requires special entitlements (see “Provisioning Your Device for Specialized Development” (page 12)).
Expired or otherwise invalid provisioning profiles are dimmed and cannot be used.
Figure 3-2 shows a set of options for the Code Signing Identity build setting with a provisioning profile
for specialized development selected.
Figure 3-2

Code Signing Identity options with a specialized provisioning profile selected


27


Project templates are configured to use the automatic selector to set the signing identity. You need to change
the value of the Code Signing Identity build setting only when your app uses a specialized provisioning profile.
See “Replacing an Expired Certificate” (page 15) for details.
Important: If you need to use different code signing identities that have the same name, you must use a
separate Mac OS X user account for each identity.

Specifying the Runtime Environment
Three aspects of your app’s runtime environment are: where your app runs, what app-data is placed in its
sandbox, and what location or track the Core Location framework reports to it.

Specifying the Run Destination
Before building your app, Xcode has to know where you want to run it. You specify this run destination in the
Scheme toolbar menu. Using that menu you can switch from running your app in a simulator to running it on
your device to, for example, test the device performance of your app.
When you plug into your Mac a device with a valid provisioning profile, its name and the iOS version it’s running
appear as an option in the Scheme toolbar menu. Use the menu to switch between running your app on a
device or in a simulator.

Troubleshooting:
●
“Device Not Listed as a Run Destination” (page 52).
●

“Xcode Displays the “Unknown iOS Detected” Dialog When You Plug In a Device” (page 52).

Specifying the App Data
The Run action in a scheme determines the app data Xcode places in your app’s sandbox before running it.
Using a particular app-data archive is particularly useful in application unit tests, which check for the correct
operation of critical units of code in your application. Basing your tests on a known data set allows you perform
detailed unit tests without having to configure the test data in the tests themselves.


28


Note: Each scheme can specify only one app-data archive. If you need to use more than one app-data
archive regularly, define a scheme for each archive.

Important: In Run actions, you can specify only app-data archives that that are part of your project. See
“To copy app data from a development device” (page 31) for details.
To specify the app data to place in the app’s sandbox before the app runs:
1.

From the Scheme toolbar menu, choose the scheme you want to use.

2.

Select the Run action.

3.

From the Application Data pop-up menu, choose the app-data archive you want to use.

Specifying a Location or Track
To test a location-based app, you can specify a location or a track the run destination reports to the app when
it launches and as it runs.
A GPS eXhange Format (GPX) file specifies a single location (a single waypoint) or a track (an ordered collection
of waypoints). When you simulate track, the simulator or the device reports the waypoints in the order they
are specified in the track.
To make a GPX file available for use in your project, add it to the project, or add a new GPX file to the project
and specify the location or track details.

Building Your App
To start the build process, choose Product > Build. If the Build option is dimmed, choose a valid run destination,
as described in “Specifying the Run Destination” (page 28).
The activity viewer, in the middle of the workspace window toolbar, indicates the progress of the build and
whether there are build problems. If the build fails or produces warnings, you can view details about the build
in the log viewer:
1.

Choose View > Navigators > Log to display the log navigator.

2.

In the list on the left, select the build task for which you want to view details.
The log viewer in the editor area lists the operations that are part of the build.

If the build completes successfully, you can run your app as described in “Running Your App” (page 30).


29

Managing App Data

Troubleshooting:
●
“Xcode Cannot Install Your App on Your Development Device” (page 49)
●

●

“Your Provisioning Profile Is Expired” (page 50)
“The Code Signing Identity Build Setting Doesn’t Identity a Valid Code Signing Identity in Your
Keychain” (page 51)

●

“Xcode Doesn’t Trust Your Certificate” (page 50)

●

“Your Keychain Contains Duplicate Code Signing Identities” (page 51)

●

“The App ID of Your Provisioning Profile Doesn’t Match Your App’s Bundle Identifier” (page 52)

Running Your App
To run your app, choose Product > Run.
When you run your app, Xcode places it in a simulation environment or on a device, and launches it.
When your app runs on a device, you can ensure that it performs as you intend, using all the capabilities of
your device. You should especially ensure that your app uses the device’s resources—CPU, memory, battery,
and so on—as efficiently as possible. See “Tuning the Performance of Your App” (page 38) for more information.
Note: To run your app on a device, the device must be connected to your Mac through a USB cable.

Managing App Data
When an app is first installed on a device or in a simulation environment, iOS creates a sandbox (also known
as the app home directory) for it. As described in “File and Data Management” in iOS App Programming Guide ,
an iOS app can access only files that reside in its sandbox.
Xcode doesn’t remove app data as it reinstalls an app. But you may need to erase that information as part of
testing your app the way users will use it. To do so, remove the app from the Home screen. See “Uninstalling
Apps” (page 34) for details.
You may also want to replace the app data in your app’s sandbox with a known configuration to test specific
conditions, such as when performing application unit tests. The first step is to create an archive of the app
data from a development device (you cannot generate app-data archives from simulators). Then you can
change the app data on your Mac and copy it back to the device.


30

Further Exploration

To copy app data from a development device:
1. Plug in the device containing the app whose data you want to copy.
2.

Copy the app’s data from the device.

After copying the app data to the file system, you can modify it to, for example, make changes that
would be tedious to do in the app itself. To access the contents of the app-data archive, Control-click
the archive in the Finder and choose Show Package Contents.
If you want to use a particular configuration of your app’s data when you run the app, add the
appropriate app-data archive to your project, and specify that archive in the Run action of the
appropriate scheme. See “Specifying the App Data” (page 28) for more information.

To copy app data to a development device:
1. Plug in the device containing the app whose data you want to replace.
2.

Copy the app’s data to the device.

To access your app’s simulation-environment sandbox, navigate to the directory ~/Library/Application
Support/iPhone Simulator/<sdk_version>/Applications in the Finder. Then open each directory
in the Applications directory to find your app’s binary file. Alongside the binary file are the directories that
make up your app’s sandbox, including Documents and Library.

Further Exploration
To learn more about using Xcode to build and run apps, see “Configure Your Project”.


31

Using iOS Simulator

You use the iOS Simulator app to run your iOS app on a Mac. By simulating the operation of your app you:
●

Learn about the Xcode development experience and the iOS development environment before becoming
a member of a development team.

●

Find major problems in your app during design and early testing.

●

Test your app’s user interface.

●

Measure your app’s memory usage before carrying out detailed performance analysis on iOS-based devices.

The iOS Simulator app (located in
<Xcode>/Platforms/iPhoneSimulator.platform/Developer/Applications) presents the iPhone

or iPad user interface in a window on your computer. This app provides several ways to interact with it by
using the keyboard and mouse to simulate taps, device rotation, and other user actions.
This chapter describes the ways in which you use your computer’s input devices to simulate the interaction
between users and their devices. The chapter also describes how to uninstall apps from a simulator and how
to reset the contents of a simulation environment.

Setting the Device and iOS Version
iOS Simulator can simulate three devices (iPhone, iPhone with Retina display, and iPad) and several iOS versions.
To specify the device you want to simulate, choose Hardware > Device, and choose the device.
To specify the iOS version to simulate, choose Hardware > Version, and choose the iOS version.

Manipulating the Hardware
With iOS Simulator you can simulate most of the actions a user performs on a device. When your app is running
in a simulator, you can carry out these hardware interactions through the Hardware menu:


32

Using iOS Simulator
Performing Gestures

●

Rotate Left. Rotates the simulator to the left.

●

Rotate Right. Rotates the simulator to the right.

●

Shake Gesture. Shakes the simulator.

●

Home. Takes the simulator to the Home screen.

●

Lock. Locks the simulator.

●

●

●

●

Simulate Memory Warning. Sends the frontmost app low-memory warnings. For information on how to
handle low-memory situations, see “Observing Low-Memory Warnings” in iOS App Programming Guide .
Toggle In-Call Status Bar. Toggles the status bar between its normal state and its state when a phone
call or FaceTime call is in progress. The status bar is taller in its in-call state than in its normal state. This
command shows how your app’s user interface looks when the user launches your app during a call.
Simulate Hardware Keyboard. Toggles the software keyboard on an iPad simulator. Turn off the software
keyboard to simulate using a keyboard dock or wireless keyboard with an iPad device.
TV Out. Opens a window simulating the TV out signal of a device.

Performing Gestures
Table 4-1 lists gestures you can perform on a simulator (see iOS Human Interface Guidelines for more about
gestures).
Table 4-1

Performing gestures in iOS Simulator

Gesture

Desktop action

Tap

Click.

Touch and hold

Hold down the mouse button.

Double-tap

Double-click.

Swipe

1. Place the pointer at the place where you want the swipe to start.
2. Hold down the mouse button.
3. Move the pointer in the direction you want to swipe and release the mouse
button.

Flick

1. Place the pointer at the start position.
3. Move the pointer quickly in the direction you want to flick and release the mouse
button.


33

Using iOS Simulator
Installing Apps

Gesture

Desktop action

Drag

1. Place the pointer at the start position.
3. Move the pointer in the direction you want to drag.

Pinch

1. Place the pointer where you want the pinch to occur.
2. Hold down the Option key.
3. Move the circles that represent finger touches to the start position.
4. Move the center of the pinch target by holding down the Shift key, moving the
circles to the desired center position, and releasing the Shift key.
5. Hold down the mouse button, move the circles to the end position, and release
the Option key.

Installing Apps
Xcode installs apps in simulation environments automatically when you build your app for a simulator. See
“Building and Running Apps” (page 23) for details.
Note: You cannot install apps from the App Store in simulation environments.

Uninstalling Apps
To uninstall apps that you have installed in a simulation environment, use the same method used to uninstall
apps from devices:
1.

Place the pointer over the icon of the app you want to uninstall and hold down the mouse button until
the icon starts to jiggle and a close button appears.

2.

Click the close button.

3.

Click the Home button to stop the icon from jiggling.

Resetting Content and Settings
To set the user content and settings of a simulation environment to their factory state and remove the apps
you have installed, choose iOS Simulator > Reset Content and Settings.


34

Using iOS Simulator
Viewing iOS Simulator Console and Crash Logs

Viewing iOS Simulator Console and Crash Logs
To learn how to view your app’s console logs when it runs in a simulator, see “Viewing Console Output and
Device Logs” (page 38).
If your app crashes while running in a simulator, the CrashReporter facility displays details about the crash.
You configure how CrashReporter deals with such crashes using the CrashReporterPref app, located in
<Xcode>/Applications/Utilities (<Xcode>, which is the directory where the Xcode toolset is installed).

Simulation Environment File System Location
The file systems for the iOS releases the iOS Simulator can simulate are stored in your home directory,
~/Library/Application Support/iPhone Simulator. That directory contains one subdirectory per
iOS release supported by iOS Simulator.
Within each iOS-release directory, iOS Simulator stores system app preferences files in Library/Preferences
and third-party–app preferences files in Applications/<app_UUID>Library/Preferences.

Hardware Simulation Support
iOS Simulator doesn’t simulate accelerometer or camera hardware.


35

Ensuring High Quality and Optimal Performance

This chapter describes practices and facilities that help you ensure that your app’s code behaves as intended,
that your app uses resources appropriately, and that it performs optimally.

Ensuring Your Code Is Correct
Unit tests help you write robust and secure code by testing your application’s functionality. Xcode provides
an easy-to-use and flexible unit-testing environment for ensuring that your code continues to work as designed
as you make changes to it.
You can perform two types of unit tests: logic tests and application tests. With logic tests you can ensure that
your code works at the lowest level, usually methods and single classes. With application tests you make sure
that your app’s classes work as designed within the app.
Xcode makes it easy to create projects and products that include unit-testing support. But you can also add
unit testing to existing projects and products.
To learn how to integrate unit testing in your project, see Xcode Unit Testing Guide .

Fixing Bugs in Your App
This section provides an overview of the Xcode debugging facilities and describes how to view console output.
Part of your debugging workflow may require viewing or manipulating data your app writes in its sandbox.
For example, you may need to edit the data that the app has stored so you can recreate a particular condition
to test it. See “Managing App Data” (page 30) for details about manipulating your app’s data.


36

Fixing Bugs in Your App

Debugging Facilities Overview
Xcode provides several integrated debugging facilities, which provide both a general view of your app’s code
and details when you need them.

●

●

The debug navigator. This navigator (on the left of the workspace window) shows your app’s threads
and stack frames, which you use to navigate your running code. Selecting an item in the debug navigator
opens its file in the source editor.
The source editor. You use the source editor (in the editor area) to debug your code right in your code.
It provides most of the debugging features you need. You can:
●

●

View the value of variables by holding the pointer over them

●

Continue execution up to a particular code line

●

●

Set breakpoints

Step in to, out of, or over function or method calls

The debug area. The debug area (below the source editor) presents a variables list and a console pane
to show your program’s console output. You can also issue debugger commands in the console pane. You
use the debug bar, at the top of the debug area, to control your program’s execution by pausing, continuing,
and stepping through code.


37

Tuning the Performance of Your App

Important: To debug an app successfully on a device, ensure that the version number of the iOS SDK your
project uses is equal to or greater than the version number of the iOS version on your device. Installing the
latest public version of Xcode from the App Store or the latest beta version from http://developer.apple.com/devcenter/ios should suffice.

Viewing Console Output and Device Logs
The iOS frameworks, such as UIKit, send log entries to the console to indicate, among other things, when an
unexpected event occurs. You can emit console messages in your iOS apps, too. One way to emit console
messages is to use the NSLog function. Console logs can help you analyze your app’s logic and track down
bugs.
When running your app in a simulator, you can access the app’s console logs in the Console app (located in
/Applications/Utilities). When you run the app on a device, log entries from your app appear in the
Xcode Organizer.
To view a device’s console output:
1.

Choose Window > Organizer to open the Organizer window.

2.

Click Devices to display the devices organizer.

3.

In the section for the device whose logs you want to view, select Device Logs.

The Device Logs pane in the Organizer contains information about app crashes. You may have to unplug your
device and plug it in again to refresh the crash list.
For more information about crash logs, see Understanding and Analyzing iPhone OS Application Crash Reports.

Optimizing your app’s performance is an important part of the development process. This optimization is
especially important in iOS-based devices, which, although powerful computing devices, do not have the
memory or CPU power that desktop or portable computers possess. You also have to pay attention to your
app’s battery use because it directly impacts the user’s battery-life experience.
This section introduces Instruments, the Xcode graphical tool that you use to measure and tune your app’s
performance.
For general performance guidelines, see “Performance Tuning”.


38


The Instruments App
With the Instruments app, you gather a variety of app performance metrics, such as memory and network use.
You can gather data from iOS apps running in a simulator or a development device.
It is important that your iOS apps use device resources as efficiently as possible to provide a satisfactory
experience for your customers. For example, your app should not use resources in a way that makes the app
feel sluggish to users or that drains their batteries too quickly. Apps that use too much memory run slowly.
Apps that rely on network access for their operation must use it as sparingly as possible because powering up
the radios for network communications is a significant drag on the battery.
The Instruments app provides an advanced data gathering interface that lets you know exactly how your app
uses resources, such as the CPU, memory, the file system, and so on.
Instruments uses software-based data-gathering tools, known as instruments , to collect performance data. An
instrument collects a specific type of data, such as network activity or memory usage. A trace document
contains one or more instruments that collect data about an app.
Although most iOS apps can run in a simulator and you can test most design decisions there, a simulator
cannot completely match the behavior of a device. For example, it doesn’t replicate a device’s performance
characteristics such as CPU speed or memory throughput. To effectively measure your app’s performance on
user devices, you must use an actual device. Only on a device can you get an accurate representation of the
runtime environment (in terms of processor speed, memory limitations, specialized hardware requirements,
and the like).
Behavior you cannot test in a simulator and therefore must test on devices:
●

●

●

Events involving more than two fingers.
Actual accelerometer readings. Although you can access your computer’s accelerometer (if it has one)
through the UIKit framework, its readings differ from the accelerometer readings on a device. This
discrepancy stems largely from the difference in the positioning of the screen in relation to the rest of the
hardware between computers and iOS-based devices.
Rendering by OpenGL ES. OpenGL ES uses renderers on devices that are slightly different from those it
uses in a simulator. Therefore, a scene in the simulator and the same scene on a device may not be identical
at the pixel level. See “Drawing with OpenGL ES” in iOS App Programming Guide for details.

To measure your app’s performance on a device:
1.

Build and run your app on the device as described in “Building and Running Apps” (page 23).

2.

Stop the app.

3.

Launch Instruments.


39


The Instruments app is located at <Xcode>/Applications. (<Xcode> refers to the installation location
of the Xcode toolset.)
4.

Choose a template, such as Activity Monitor, to create the trace document.

5.

From the Target toolbar menu, choose the device containing the app from which you want to collect
performance data.

6.

Add or remove instruments from the trace document to collect the data you want.

7.

From the Target toolbar menu, choose the app to launch (the same app you ran in step 1).

8.

Click Record to start collecting data.

9.

Use your app, exercising the areas you want to examine.

To learn more about measuring and analyzing app performance, see Instruments User Guide .


40

Distributing Apps

When you’re ready to share your app for user testing or for general distribution through the App Store, you
need to create an archive of the app using a distribution provisioning profile and send it to app testers or
submit it to iTunes Connect. This chapter shows how to perform these tasks.
To distribute apps, you must meet the requirements described in “Provisioning a Device for Development” (page
10).

Publishing Your App for User Testing
After testing and tuning your app yourself or with the assistance of your teammates, it’s always a good idea
to perform wider testing with a representative sample of your app’s potential users. Such testing may reveal
issues that surface only with particular usage patterns. An app tester is a potential user of your app who is not
part of your development team but is willing to test it before it’s released through the App Store.) Adding app
testers to your group of testers exposes your app to a variety of usage styles. You can collect and analyze crash
reports (also known as crash logs) from these testers to resolve execution problems.
Important: Only one authorized person in a team can publish apps for user testing.
During development, you can run an iOS app only on a device on which you have installed a provisioning
profile that identifies you, the device, and the app. You and your fellow teammates install these files on devices
when you provision a device for development (as described in “Configuring Development and Distribution
Assets” (page 9)). To include users that are not part of your development team in your testing, you must add
their devices to your team and issue them user testing provisioning profiles (also known as ad-hoc provisioning
profiles), which allow them to install your apps on their devices.


41

Distributing Apps

Figure 6-1 shows the items involved in publishing apps for user testing.
Figure 6-1

Items required for sharing apps with testers
Tester

Team Agent

Portal

Tester device ID

Tester device ID

Tester device ID
Tester Device

User testing
provisioning profile

User testing

User testing
Tester device ID

Application archive

Application IPA

Application binary

App ID
Distribution certificate

Development
certificate

To help users obtain the information you need to add them to your testing group and to show them how to
send you crash logs, you can send them the information in “Instructions for App Testers” (page 44).
Requirements for user testing: To publish an app for user testing, the app must have iTunes artwork.
See “Adding the iTunes Artwork to Your App for User Testing” (page 21).

The remainder of this section describes the steps you need to perform to add testers to your team, and shows
how to import the crash logs they send you into the Organizer.

Adding User Testing Devices to Your Team
To add a user’s device to your team for user testing:
1.

Obtain the identifier of the user’s device.
The easiest way to obtain this information is through email. Have your tester follow the instructions for
sending their device identifier to you in “Sending Your Device Identifier to a Developer” (page 44).


42

Distributing Apps

2.

Add the user’s device identifier to your team.

Tip: Use the tester’s email address as the device name.

Configuring the User Testing Provisioning Profile
If you already have a user testing provisioning profile for your app in the iOS Provisioning Portal, add the
tester’s device identifier to it. Otherwise, create a distribution profile with these characteristics:
Distribution method

Ad Hoc

Profile name

<App_Name> User Testing Profile

App ID

Appropriate app ID for the app being tested

Devices

Tester’s device identifier

The app name in the name of the provisioning profile is optional.
The app ID can identify a specific app or an app domain.

Sending Your App to Testers
To send your app to testers:
1.

If you don’t have access to the project that generates the app, obtain an iOS App Store Package (IPA) file
for your app from the appropriate teammate. Otherwise, generate the IPA file yourself:
a.

Open the project in Xcode.

b.

Archive your app.

c.

Generate an IPA file for your app.

2.

Download the user testing provisioning profile for your app from the iOS Provisioning Portal to your file
system. (You don’t have to install this profile in Xcode.)

3.

Email the user testing provisioning profile and the IPA file to your testers.

Importing Crash Logs from Testers
To add tester crash logs to the devices organizer, drag the crash logs to the Device Logs group in the Library
section. You can then view information about the symbols involved.


43

Distributing Apps

Important: For Xcode to symbolicate crash logs (to add to the crash log information about the API used),
the volume containing your archived apps and their corresponding dSYM files must be indexed by Spotlight.

Instructions for App Testers
This section provides instructions for app testers to follow when they test your iOS apps on their devices. You
may send these instructions, along with instructions for any special tasks needed to test your app, to customers
interested in testing your app.

Sending Your Device Identifier to a Developer
Before a developer can send you an app for testing, they must register your device with Apple under their
app-testing program.
To send your device identifier to a developer:
1.

Launch iTunes.

2.

Connect your device to your computer.

3.

Select the device in the Devices list.

4.

In the Summary pane, click the Serial Number label.
It changes to Identifier.

5.

Choose Edit > Copy.

6.

Email your device identifier to the developer.
Be sure to include your name in the email.

Installing an App for Testing
When a developer sends an app for you to test, you use iTunes to install the app on your device.
To install the test app on your device:
1.

In the Finder, drag the provisioning profile (the file with the .mobileprovision extension) to the iTunes
icon in the Dock.

2.

Double-click the app archive <App_Name>.ipa.
The app appears in the iTunes Applications list.

3.

Sync your device.
If the version of iOS on your device is earlier than the test app can run on, you need to update your device
with the current version of iOS.


44

Distributing Apps

Sending Crash Reports to a Developer
When the app you’re testing crashes, iOS creates a record of that event. The next time you connect your device
to iTunes, iTunes downloads those records (known as crash logs) to your computer. To help get the problem
fixed, you should send crash logs of the app you’re testing to its developer.
Sending Crash Reports from Macs
To send crash logs to developers:
1.

In the Finder, open a new window.

2.

Choose Go > Go to Folder.

3.

Enter ~/Library/Logs/CrashReporter/MobileDevice.

4.

Open the folder identified by your device’s name.

5.

Select the crash logs named after the app you’re testing.

6.

Choose Finder > Services > Mail > Send File.

7.

In the New Message window, enter the developer’s email address in the To field and <app_name> crash
logs from <your_name> (for example, MyTestApp crash logs from Anna Haro) in the Subject
field.

8.

Choose Message > Send.

9.

(Optional) Delete the crash logs you sent, to avoid sending duplicate reports later.

Sending Crash Reports from Windows
To send crash logs to developers:
1.

Enter the crash log directory for your operating system in the Windows search field, replacing <user_name>
with your Windows user name.
●

For crash log storage on Windows Vista
C:Users<user_name>AppDataRoamingApple
computerLogsCrashReporter/MobileDevice

●

For crash log storage on Windows XP
C:Documents and Settings<user_name>Application DataApple
computerLogsCrashReporter


45

Distributing Apps
Publishing Your App on the App Store

2.

Open the folder named after your device’s name and send the crash logs for the app you’re testing in an
email message using the subject-text format <app_name> crash logs from <your_name> (for
example, MyTestApp crash logs from Anna Haro) to the app’s developer.

When you’re ready to publish your app for general distribution through the App Store, you submit it to iTunes
Connect. This section describes how to prepare your app for submission and how to submit it to iTunes Connect.
Important: Only team agents can publish an app on the App Store.

Creating a Distribution Provisioning Profile for Your App
To create a distribution provisioning profile for your app:
Create a distribution profile in the iOS Provisioning Portal with these characteristics:

1.

Distribution method

App Store

Profile name

<App_Name> Distribution Profile

App ID

The appropriate app ID for the app being distributed

The app name in the name of the provisioning profile is optional.
The app ID can identify a specific app or an app domain.
2.

Download the distribution provisioning profile.

3.

Install the distribution provisioning profile in your provisioning profiles library:
Drag the <Profile_Name>.mobileprovision file to the Provisioning Profiles list in the Library section
of the devices organizer.

Submitting Your App for Publication on the App Store
To publish your app on the App Store, you need to enter information about it in iTunes Connect. For more
information about iTunes Connect, visit https://itunesconnect.apple.com.
Important: To validate your app or to submit it for publication, you must be registered in iTunes Connect.
To validate your app or submit it for publication on the App Store:


46

Distributing Apps

1.

Create an archive of your app using the AppStore scheme.

To learn how to configure the AppStore scheme, see “Configuring Your Project for App Store
Submission” (page 21).
2.

Ensure that an app record for the app exists in iTunes Connect. The information in this record must match
the app you want to validate or submit for publication.
These are the main matching criteria:
●

App Name

●

Bundle ID

●

Version

3.

Ensure that the app record status in iTunes Connect is at least Waiting for Upload.

4.

Submit your app for distribution.

Before submitting your app for distribution, you should validate it to ensure that is passes essential iTunes
Connect validation tests.
Troubleshooting: “Unable to find registered user with username <username>”: The “Unable
to find registered user with username <username>” dialog indicates that you are not registered
in iTunes Connect.
●

Have an authorized person in your team register you in iTunes Connect.


47

iOS Development: Troubleshooting

This chapter shows how to address issues you might encounter as you develop your app and prepare to submit
it for publication on the App Store.

Issues
Certificate Issues
Your Development Certificate Is Expired
To renew an expired development certificate:
●

Request a new development certificate from your team:
To learn how, see “Replacing an Expired Certificate” (page 15).

Your Development Certificate Is Invalid
Your certificate might be invalid because the corresponding private key is not in your keychain.
To replace an invalid certificate with a valid one, delete the invalid certificate from your keychain, and do one
of the following:
●

Restore your certificate and its corresponding private key from a backup of your signing assets.
To learn how, see “Safeguarding and Transferring Your Signing and Provisioning Assets” (page 16).

●

Reset your code signing assets.
To learn how, see “Reset Your Signing and Provisioning Assets on Your Mac and in Your Team” (page 54).

Your Development Certificate Is Not in Your Keychain
Your certificate may be missing from your keychain because you’re developing on a Mac on which you haven’t
developed apps before.


48

Issues

Important: To add a development certificate to your keychain, you must be a member of a development
team.
To add your development certificate to your keychain, do one of the following:
●

Transfer your signing assets from your previous development Mac.
To learn how, see “Safeguarding and Transferring Your Signing and Provisioning Assets” (page 16).

●

Reset your code signing assets.

The Apple Worldwide Developer Relations Certification Authority Certificate Is Not in Your
Keychain
Developer and distribution certificates in your keychain are not valid without the Apple Worldwide Developer
Relations Certification Authority certificate.
Important: The Apple Worldwide Developer Relations Certification Authority certificate is part of your
development team’s signing assets. See “Becoming a Member of a Development Team” (page 9) for more
information.
To add this certificate to your keychain:
1.

Log in to the iOS Provisioning Portal using the appropriate credentials for your team.

2.

Download the Apple Worldwide Developer Relations Certification Authority certificate.

3.

Double-click the certificate or drag it to the Keychain Access icon in the Dock.

Provisioning Issues
Xcode Cannot Install Your App on Your Development Device
If Xcode cannot install your app on your development device because of a problem with the provisioning
profile you’re using with the app:
●

Ensure that the provisioning profile is properly configured in your development team’s signing assets.
To learn about configuring provisioning profiles, see “Provisioning a Device for Development” (page 10).


49

Issues

Your Provisioning Profile Is Expired
If the provisioning profile stored on your development device for your app is expired, Xcode cannot install the
app on that device.
To address this problem:
●

Replace the expired provisioning profile with a new copy.
To learn how, see “Renewing Expiring or Expired Provisioning Profiles” (page 15).

Building Issues
Code Signing Errors
This section describes how to address code signing identity problems that result in build errors.
Xcode Cannot Find Your Provisioning Profile
You get this error message after replacing a provisioning profile with a modified version, such as when a
provisioning profile’s app ID is changed:
Code Sign error: Provisioning Profile 'xxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx' can’t
be found

To address this error:
1.

Ensure that the correct provisioning profile and code signing identity are selected for the value of the
Code Signing Identity build setting.
See “Setting Your Code Signing Identity” (page 26).

2.

Ensure that the correct signing identity is in your keychain.
See “Ensure That Your Development Signing Identity Is in Your Keychain” (page 53).

Xcode Doesn’t Trust Your Certificate
You get this error message when Xcode cannot verify the authenticity of your development or distribution
certificate:
Code Sign error: CSSMERR_TP_NOT_TRUSTED



50

Issues

●

Ensure that the trust level of your certificates is set correctly.
To learn how, see “Fix the Trust Level of Your Certificates” (page 53).

The Code Signing Identity Build Setting Doesn’t Identity a Valid Code Signing Identity in Your Keychain
You get this error message when your certificate has expired or is otherwise invalid:
Code Signing Identity 'iPhone Developer' does not match any valid, non-expired,
code-signing certificate in your keychain.

1.

Download the provisioning profiles that contain your certificate.
a.
b.

In the Library section, select Provisioning Profiles.

c.
2.

Choose Window > Organizer, and click Devices.

Click Refresh.

Choose a valid code signing identity, as described in “Setting Your Code Signing Identity” (page 26).

Your Keychain Contains Duplicate Code Signing Identities
You get one of these error messages when there are duplicate code signing identities in your keychain, such
as two development identities or two distribution identities (your keychain must contain at most one code
signing identity of each type):
Build error "iPhone Developer: <your_name> (XYZ123ABC): ambiguous (matches "iPhone
Developer: <your_name> (XYZ123ABC)" in /Library/Keychains/System.keychain and
"iPhone Developer: <your_name> (XYZ123ABC)" in
/Users/../Library/Keychains/login.keychain)"

[BEROR]CodeSign error: Certificate identity 'iPhone Distribution: <your_name>'
appears more than once in the keychain. The codesign tool requires there only be
one.

To address these errors, try the following:
●

Delete the duplicate identities from the My Certificates list in your keychain.

●

Reset your signing assets.


51

Issues

App ID Errors
The App ID of Your Provisioning Profile Doesn’t Match Your App’s Bundle Identifier
When there’s a conflict between theapp ID in the provisioning profile selected in the Code Signing Identity
build setting and your app’s bundle identifier, you get error messages like this one:
Code Sign error: Provisioning profile 'MyApp Profile' specifies the Application
Identifier 'com.mycompany.MyApp.*' which doesn't match the current setting
'com.mycompany.MyApp'

To address these errors, ensure that:
●

Your app’s bundle identifier is set correctly.

●

The provisioning profile specified in the Code Signing Identity build setting is the correct one.

●

The app ID the provisioning profile uses is correct.
To learn how to configure app IDs, see “Creating and Configuring App IDs”.

Device Not Listed as a Run Destination
If you have a project or workspace open and your plugged in device is not listed as a run destination in the
Scheme toolbar menu:
1.

Ensure that the app’s targeted iOS version is equal to or greater than the iOS version installed on your
device. See “Specifying the Targeted iOS Version” (page 17), and “Installing iOS on a Device” (page 13)
for details.

2.

Ensure that your device contains a valid provisioning profile. See “Provisioning a Device for
Development” (page 10).

3.

Ensure that the version number of the iOS SDK your project uses is equal to or greater than the version
number of the iOS version on your device.
For example, if Xcode shows iOS SDK 4.3 but your device has iOS 5.0 installed, you need to install an Xcode
version that includes iOS SDK 5.0 on your Mac.

Debugging Information Issues
Xcode Displays the “Unknown iOS Detected” Dialog When You Plug In a Device
To successfully debug apps on the device, you must have Xcode collect the information it needs from the
device.


52

Fixing Issues

Fixing Issues
Ensure That Your Development Signing Identity Is in Your Keychain
When you try to build or archive your app, or install it on a development device, Xcode might emit code signing
errors, such as when it cannot find the development signing identity (development certificate and private key)
it’s looking for or when the development certificate your project is using is invalid.
To verify that your development signing identity is in your keychain:
1.

Launch Keychain Access.

2.

In the Category list, click My Certificates.

3.

Enter iphone developer in the search field in the top-right corner of the window.

4.

Verify that a certificate named iPhone Developer: <Your_Name> appears in the certificates list.
If the certificate is missing, see “Your Development Certificate Is Not in Your Keychain” (page 48).

5.

Click the disclosure triangle to the left of the certificate to display the private key stored in the certificate.

6.

Select the certificate, and ensure that the certificate information indicates that the certificate is valid.
If the certificate is invalid, see “Your Development Certificate Is Invalid” (page 48).

If you are starting to develop apps on a Mac that you haven’t used for iOS development before, you may need
to transfer your signing assets from your previous Mac. To learn how, see “Safeguarding and Transferring Your
Signing and Provisioning Assets” (page 16).

Fix the Trust Level of Your Certificates
To set the trust level for your certificates to system defaults:
1.

Launch Keychain Access.

2.

In the Category list, select My Certificates, and enter iphone in the search field.

3.

For each of your iPhone certificates in the certificates list:
a.

Double-click the certificate.
If the message “This certificate was signed by an unknown authority” message appears on the certificate,
see “The Apple Worldwide Developer Relations Certification Authority Certificate Is Not in Your
Keychain” (page 49).

b.

In the certificate window, display the Trust section by clicking the corresponding disclosure triangle.

c.

For the option “When using this certificate” choose Use System Defaults.

d.

Close the certificate window.


53

Fixing Issues

e.

Ensure that the certificate information for the certificate indicates that the certificate is valid.

4.

In the Category list, select Certificates, and enter apple worldwide in the search field.
If you don’t see at least one certificate named Apple Worldwide Developer Relations Certificate Authority,
see “The Apple Worldwide Developer Relations Certification Authority Certificate Is Not in Your
Keychain” (page 49).

5.

For each of the Apple Worldwide Developer Authority certificates in the certificates list:
a.

Double-click the certificate.

b.

In the certificate window, display the Trust section by clicking the corresponding disclosure triangle.

c.

For the option “When using this certificate” choose Use System Defaults.

d.

Close the certificate window.

e.

Ensure that the certificate information for the certificate indicates that the certificate is valid.

Reset Your Signing and Provisioning Assets on Your Mac and in Your Team
When you cannot retrieve your signing and provisioning assets assets from a backup (“Safeguarding and
Transferring Your Signing and Provisioning Assets” (page 16)), you have to recreate them on your Mac and in
your development team.
To reset your signing and provisioning assets:
1.

Quit Xcode.

2.

Delete your private and public keys and your certificate from your keychain:
a.

Launch Keychain Access (located in /Applications/Utilities).

b.

In the Category section, select Keys.

c.

For each of the private keys with a disclosure triangle next to them:


54

Fixing Issues

a.

b.
d.
3.

Click the disclosure triangle to reveal the item with which the private key is associated.

If the private key is associated with a developer or distribution certificate, select the private key
and its corresponding public key, and press Delete.

In the Category section, select My Certificates, and delete any remaining developer or distribution
certificates.

Revoke your certificates in your team’s signing assets:
a.
b.

4.

Log in to the iOS Provisioning Portal using the appropriate credentials for your team.
Revoke your development and distribution certificates.

Ensure that the devices organizer doesn’t list any certificates:
a.
b.

Choose Window > Organizer to open the Organizer window, and click Devices to display the devices
organizer.

c.

In the Library section, select Developer Profile.

d.
5.

Launch Xcode.

Ensure that no certificates are listed in the certificates list (the first list in the Developer Profile pane).

Confirm that all the provisioning profiles are invalid:


55

Fixing Issues


If all the provisioning profiles are not invalid, ensure that your certificates are revoked in your team’s
signing assets.
6.

Remove your provisioning profiles from the devices organizer and your development devices:
a.


b.

Select all the provisioning profiles, and press Delete.

c.

For each of your development devices:
a.
b.

Select Provisioning Profiles in your device’s group.

c.
7.

Plug in your device.

Select the invalid profiles in the profiles list, and press Delete.

Generate your new certificates:
a.


b.

Click Refresh.
Xcode offers to request a developer certificate for you. Have Xcode request your developer certificate.
If you are the team agent, Xcode also offers to request a distribution certificate for you. Have Xcode
request your distribution certificate.


56

Fixing Issues

After a few moments, the team provisioning profile appears in the provisioning profiles list.
8.

In your team’s signing assets, associate your new certificates with the appropriate provisioning profiles:
If you are a team administrator or the agent, modify each provisioning profile by adding your certificate
to it. Otherwise, have a team administrator or the agent do this for you.

9.

Install the updated provisioning profiles in the devices organizer and on your devices:
a.


b.

Click Refresh.
The provisioning profiles associated with your developer certificate are listed in the provisioning
profiles list.
Important: If you are the team agent, note that Xcode doesn’t download distribution profiles.
You must download them manually to distribute your app. See “Distributing Apps” (page 41) for
more information.


57

iOS Development: FAQ

Here are some common questions developers ask about iOS development.
●

How do I run my application on a device?
See “Specifying the Run Destination” (page 28).

●

How do I add the Core Location framework to my project?
Link to the Core Location framework in the project editor.

●

Does the iOS Simulator app run on network home directories?
No.

●

Do Objective-C properties need to be backed up by instance variables or accessor methods for them to
work?
Yes.

●

Do static libraries need to be code-signed before being used in an iOS app?
No.

●

Why is my app having problems processing PNG files?
The code that is trying to use your PNG files may not understand compressed PNG files.
Turn off the Compress PNG Files build setting.

●

Can I develop iOS apps on Windows?
No. iOS apps can be developed only on Mac OS X.

●

How do I link all the Objective-C classes in a static library?
Set the Other Linker Flags build setting to -ObjC. If that doesn’t bring in all the classes, set it to -all_load.

●

When should I replace deprecated APIs?
Update as soon as you can, considering the iOS versions you want your app to run on. See SDK Compatibility
Guide for details.

●

Can iOS Simulator use my computer’s camera?
No.

●

What are the minimum hardware requirements for iOS development?
A Mac with an Intel processor.


58

Developing a Static Library and Incorporating It in
Your App
When you need to develop a static library to use in an app and you have to have separate projects for each
product, you can use a workspace to contain both the static library project and the app project. If you do, ensure
that you configure the projects in the workspace as described here:
1.

In the target that builds the static library, ensure that:
●

●

2.

The exported headers are in the Project group in the Copy Headers build phase.
The Skip Install build setting is set to Yes.

In the target that builds the app, ensure that:
●

The User Header Search Paths build setting is set to the recursive absolute path of a directory under
which the static library’s header files are stored.
Important: If you move your static library project directory to a different location in your file
system, you must update the value of the User Header Search Paths build setting to reflect the
new location of the static library’s header files.

●

The Always Search User Paths build setting is set to Yes.

●

The Skip Install build setting is set to No.


59

Developing a Static Library and Incorporating It in Your App

3.

In the scheme that builds the app, ensure the scheme also builds the static library for archiving.


60

Glossary

provisioning portals) in order for the people in the
team to build and run apps on development devices
and distribute them to customers.

application ID A string that identifies an iOS
application or a set of iOS applications from one
vendor. They are similar to bundle identifiers. These
are examples application IDs:
GFWOTNXFIY.com.mycompany.MyApp,
GFWOTNXFIY.com.mycompany.*.

device type Type of device in which iOS can run.
There two device types: iPhone (includes iPod touch),
and iPad.

base SDK Project setting that specifies the default
SDK to use when building the project’s targets.
Targets can override this setting.

entitlement A property that allows an application
to access a protected iOS feature or capability.
GPS eXhange Format (GPX) A file format used to
identify a single location or a set of locations, known
as waypoints.

build configuration A named collection of build
settings in a project used to build one or more
products for a specific purpose—for example, for
debugging or for release.

instrument A data-gathering agent developed
using the Instruments application. Instruments
collect performance information about an
application or an entire system.

certificate signing request (CSR) File that contains
personal information used to generate a
development certificate.

Instruments application A graphical performance
analysis tool used to gather and mine
application-performance data.

code completion A shortcut that automatically
suggests likely completions as you type an identifier
or a keyword. The suggestions are based on the text
you type and the surrounding context within the
file.

iOS Dev Center An Apple developer center that
provides all the resources needed to develop iOS
applications. To access this developer center you
must be a registered Apple developer.

developer certificate File that identifies an iOS
application developer. Xcode uses developer
certificates to sign application binaries.

iOS Developer Program A program that allows you
to develop iOS applications, test them on iOS-based
devices, and distribute them to users.

development team A construct that associates a
legal entity (a person, company, or organization),
people (one or more persons involved in developing
and distributing the team’s apps), and online
development resources (the iOS and Mac

iOS Provisioning Portal A restricted-access area of
the iOS Dev Center that allows you to configure
devices to test your iOS applications.


61

Glossary

test suite A set of test cases. See also test case.

iOS Simulator application Xcode application that
simulates the operation of iOS-based devices
through simulators for testing iOS applications in
early stages of development. See simulator.

Xcode A set of tools and resources used to develop
Cocoa applications (for Mac OS X), and Cocoa Touch
applications (for iOS).

provisioning profile A file that allows applications
in development to be installed on iOS-based devices.
It contains one or more development certificates,
an application ID, and one or more device identifiers.

Xcode application The main application of the
Xcode integrated development environment (IDE).
It manages the other applications that are part of
the Xcode IDE and provides the main user interface
used to develop software products.

simulation environment An invisible environment
the iOS Simulator application uses to simulate the
operation of an iOS release. Each simulation
environment has its own set of system files and
installed applications. The iOS Simulator application
provides one simulation environment for each of
the iOS versions it supports.
scheme A plan for running, testing, analyzing, and
archiving one or more products.
simulator A visible software imitation of an iOS
device running a particular iOS release. A simulator
runs in a simulation environment in the iOS
Simulator application. See also iOS Simulator
application, simulation environment.
static library Object code that is incorporated in
an application binary file at link time.
test case A piece of code that executes test-subject
code to verify that it behaves as expected. A test
case is implemented by a test-case method.
test-case method An instance method of a unit-test
class named test... that calls API to test and
reports whether it produced the expected results.
user testing provisioning profile A provisioning
profile issued to users that are not on your
development team. It allows these users to install
and test applications that your team has not
published on the App Store. Also known as ad-hoc
provisioning profile.


62

Document Revision History

This table describes the changes to Tools Workflow Guide for iOS .
Date

Notes

2012-09-19

Made available in PDF.

2012-03-01

Incorporated Xcode 4.3 workflows.

2012-01-09

Added information about location simulation, app-data management,
and obtaining distribution-only assets.
Added information about simulating locations and tracks in simulators
and on devices in “Specifying a Location or Track” (page 29).
Updated “Managing App Data” (page 30) with new workflow and
described how to specify app data at launchtime in “Specifying the App
Data” (page 28).
Added information about obtaining distribution-only assets in “Setting
Up Your Distribution-Only Assets” (page 15).
Moved most of the information about unit-testing to Xcode Unit Testing
Guide .
Changed title from iOS App Development Workflow Guide .

2011-10-12

Added information about iCloud entitlements and a troubleshooting
chapter.
Added “Configuring iCloud Entitlements” (page 17).
Added “Configuring Your Project for App Store Submission” (page 21).
Added “iOS Development: Troubleshooting” (page 48).
Modified “Submitting Your App for Publication on the App Store” (page
46).


63

Document Revision History

Date

Notes

2011-09-09

Incorporated Xcode 4.0 user interface and concepts.
Added “Developing a Static Library and Incorporating It in Your App” (page
59).
Added “Migrating a Project’s Unit Testing Setup from Xcode 3.2.5 to Xcode
4.0.2.”

2010-11-15

Documented changes to Base SDK build setting.
Described Latest iOS value for Base SDK and added instructions for solving
“Missing Base SDK” problem in “Setting the SDK Used to Build Your
App” (page 25).
Added instructions on moving the center of a pinch in iOS Simulator in
“Performing Gestures” (page 33).
Updated content for the workflows and requirements of the iOS SDK 4.2
distribution.

2010-08-26

Made minor corrections.

2010-07-02

Changed the title from iPhone Development Guide. Updated Hello, World!
tutorial to iPhone SDK 4.0.
Updated Hello, World! tutorial and source code (“Tutorial: Hello, World!”
and “Hello, World! Source Code”) for iOS SDK 4.0 toolset.

2010-05-28

Added information about automatic provisioning profile management,
application archiving, and application distribution.
Updated “Building and Running Apps” (page 23) with details about using
the Base SDK and iPhone OS Deployment Target build setting and the
Overview toolbar menu in the Project window.
Updated “Using iOS Simulator” (page 32) with information about how
the Objective-C–runtime change in iOS 4.0 affects existing iOS Simulator
binaries.
Updated “Configuring Development and Distribution Assets” (page 9)
to describe automatic provisioning-profile management and how to
manage developer profiles in the Xcode Organizer.


64

Iphone development

Recommandé

Recommandé

Contenu connexe

Tendances

Tendances (20)

En vedette

En vedette (16)

Similaire à Iphone development

Similaire à Iphone development (20)

Plus de Pragati Singh

Plus de Pragati Singh (20)

Dernier

Dernier (20)

Iphone development