Exporting Your App for Testing (iOS, watchOS)
Before uploading your app to iTunes Connect, optionally distribute it for testing on registered devices using an ad hoc provisioning profile or team provisioning profile. These distribution methods allow you to test variants of your app that are built locally by Xcode. Testers don’t need to be team members or iTunes Connect users to run the app, but their devices need to be registered in Member Center. You can register up to 100 devices per product family per year that your team uses for development and testing. Choose one of these methods if you can afford to use a portion of these devices for testing and can collect device IDs from your testers.
These are the steps to export your app for testing:
Register all test devices.
Archive your app.
Export the archive as an iOS App using either an ad hoc provisioning profile or team provisioning profile to code sign your app.
Install the app on test devices.
Solicit crash reports from testers.
An iOS App is a file with a
.ipa filename extension.
About Ad Hoc Provisioning Profiles
An ad hoc provisioning profile is a distribution provisioning profile that allows your app to be installed on designated devices and to use app services without the assistance of Xcode. It’s one of the two types of distribution provisioning profiles that you can create for iOS apps. (You use the other type of distribution provisioning profile later to submit your app to the store.) An ad hoc provisioning profile ensures that test versions of your app aren’t copied and distributed without your knowledge.
When you’re ready to distribute your app to testers, you create an ad hoc provisioning profile specifying an App ID that matches one or more of your apps, a set of test devices, and a single distribution certificate.
Each device in an ad hoc provisioning profile is identified by its unique device ID (UDID). The devices you register and add to a provisioning profile are stored by Member Center. Each individual or organization can register up to 100 devices per product family per membership year for development and testing. For example, you can register 100 Apple Watch, 100 iPad, 100 iPhone, and 100 iPod Touch devices per year.
Sign the iOS App file using the distribution certificate specified in the ad hoc provisioning profile, and distribute it to testers.
Registering Test Devices
Register one or more test devices before you create an ad hoc or team provisioning profile. To register test devices, collect device IDs from testers and add them to Member Center.
Testers can get their device ID using iTunes. (They don’t need to install Xcode to do this.) Send the instructions in Locating iOS Device IDs Using iTunes to testers and ask them to send their device IDs to you, or follow these steps to collect your own device IDs.
In Member Center, register one or more devices, as described in Registering Devices Using Member Center.
Archiving Your App
Next, create an archive of your app. Xcode stores this archive in the Archives organizer.
To create an archive
In the Xcode project editor, choose a generic device—iOS Device, or watchOS Device—or your device name from the Scheme toolbar menu.
You can’t create an archive of a simulator build. If a device is connected to your Mac, the device name appears in the Scheme toolbar menu. When you disconnect the device, the menu item changes to the generic device name.
Choose Product > Archive.
The Archives organizer appears and displays the new archive.
Xcode runs preliminary validation tests on the archive and may display a validate warning in the project editor. For example, if you are not using asset catalogs and don’t set required app icons, as described in Setting Individual App Icon and Launch Image Files, an
Info.plist warning message appears. If you see this warning, fix the issue and create the archive again.
Exporting Your App for Testing Outside the App Store
Because testers don’t have Xcode to run your app, you create an iOS App file that they can then use to install your app on their device. Use this method to test a universal app that runs on all supported devices or test device variants that the App Store distributes later to users.
To create an iOS App file for testing
In the Archives organizer, select the archive.
Click the Export button, select an export option, and click Next.
To distribute your app to users with designated devices, select “Save for Ad Hoc Deployment.” The app will be code signed with the distribution certificate.
To distribute your app for internal testing, select “Save for Development Deployment.” The app will be code signed with your development certificate.
In the dialog that appears, choose a team from the pop-up menu and click Choose.
If necessary, Xcode creates the needed signing identity and provisioning profile for you.
In the Device Support dialog, choose whether to export the universal app or a variant for a specific device, and click Next.
If you want to run the app on any supported device, select “Export one app for all compatible devices.”
If you want to test all device variances, select “Export for specific devices” and choose “All compatible device variants” from the pop-up menu.
If you want to test a specific device variant, select “Export a thinned app for a specific device” and choose the device family from the pop-up menu.
In the dialog that appears, review the app, its entitlements, and the provisioning profile.
The ad hoc provisioning profile should begin with the text
XC Ad Hoc:. The team provisioning profile should begin with the text
iOS Team Provisioning Profile:.
Review the build options, and click Next.
If you use on-demand resources, check “Include manifest for over-the-air installation.”
If you distribute your app outside of the App Store, you need to host the on-demand resources yourself. The manifest file is an XML plist used by a device to find, download, and install apps from your web server.
If you want to test a build created from bitcode, check “Export from bitcode.”
Bitcode is an intermediate representation of your compiled app that allows the App Store to build your binaries, described in Bitcode (iOS, watchOS). You can test builds created from bitcode using Xcode, but should also test the builds created by the App Store using TestFlight, described in Distributing Your App Using TestFlight (iOS, watchOS).
If you request a manifest file, enter details about your web server in the “Distribution manifest information” dialog that appears.
Enter the following information:
Name. The name of the app displayed during download and installation.
App URL. A fully qualified HTTPS URL for the iOS App file.
Display Image URL. A fully qualified HTTPS URL for an app icon that is displayed during download and installation. The image file must be 57 x 57 pixels and in PNG format.
Full Size Image URL. A fully qualified HTTPS URL for a larger image that is displayed in iTunes. The image file must be 512 x 512 pixels and in PNG format.
The Finder shows the exported files.
Xcode creates a folder containing the iOS App files (files with an
.ipa extension) you specified. If you request a manifest file, a
manifest.plist file appears in the same location as the
.ipa file. If you request variances, app thinning metrics are also included in the folder.
Installing Your App on Test Devices
Before you distribute your app to testers, follow the same steps that testers use to install and run the app on their devices. Use iTunes to install the app on a nondevelopment device. The operating system extracts the embedded provisioning profile in your app and installs it on the device for you. Then test your app on the device.
To install the app on a device
Connect the testing device to a Mac running iTunes.
If possible, don’t use a Mac that you use for development.
Double-click the iOS App file that you created earlier (the file with the
In iTunes, click the device in the upper-left corner of the window.
Click the Apps button.
The app appears in the iTunes Apps list.
Under Apps, choose “Sort by Name” or “Sort by Kind” from the pop-up menu.
An Install or Remove button appears adjacent to the app.
If an Install button appears, click it.
The button text changes to Will Install.
Click the Apply button or the Sync button in the lower-right corner to sync the device.
The app is uploaded to the device so that the user can start testing.
Finally, send the iOS App file to testers, along with the app installation instructions and the crash report instructions, as described in Soliciting Crash Reports from Testers.
Distributing Your App Using Xcode Server
After you perform the steps in this chapter to export your app for beta testing, you can optionally set up an Xcode service to distribute your app. Xcode Server automates the integration process of building, analyzing, testing, and archiving your app. Xcode Server hosts a website that facilitates the distribution of product builds and archives to testers and other team members. See Xcode Server and Continuous Integration Guide for more information about using Xcode Server to distribute versions of your app to testers.
Copying App Sandbox Data
To further diagnose an issue with your app, you can view, download, and replace the contents of an app container on a device, as described in Viewing, Downloading, and Replacing App Containers on iOS Devices.
Soliciting Crash Reports from Testers
When an app crashes on a device, the operating system creates a report of that event. The next time the tester connects the device to iTunes, iTunes downloads those records (known as crash logs) to the tester’s Mac. Testers should send these crash logs to you along with any bug reports. Later, after your app is released, you can also retrieve crash reports of your live app from iTunes Connect.
Tell testers how to retrieve crash reports from their devices and send them to you.
To send crash reports from a Mac
Connect the testing device to a Mac running iTunes.
iTunes downloads the crash reports to your Mac.
In the Finder, choose Go > Go to Folder.
Open the folder identified by your device’s name.
Select the crash logs named after the app you’re testing.
Choose Finder > Services > Mail > Send File.
In the New Message window, enter the developer’s address in the To field and appropriate text in the Subject field.
Choose Message > Send.
To avoid sending duplicate reports later, delete the crash reports you’ve sent.
To send crash reports from Windows
In the Windows search field, enter the crash log directory for your operating system, replacing
<user_name>with your Windows user name.
For crash log storage on Windows, type:
For crash log storage on Windows XP, type:
C:\Documents and Settings\<user_name>\Application Data\Apple computer\Logs\CrashReporter
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.
To learn how to interpret the reports that you receive from testers, read Viewing and Importing Crashes in the Devices Window.
Ad Hoc Provisioning Profiles in Depth
You signed the iOS App file using the distribution certificate specified in the ad hoc provisioning profile. The ad hoc provisioning profile was included in the app bundle when you built and archived the app. Then you installed the app on a test device. The app successfully launches if the app’s bundle ID matches the App ID, the signature matches the distribution certificate, and the device is in the device list of the ad hoc provisioning profile.
In this chapter, you learned how to distribute your app on designated test devices using ad hoc provisioning profiles. You also received instructions to send to ad hoc testers to install the beta version of your app and send crash reports to you.