Exporting Your App for Testing (iOS, tvOS, 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.

Note:

These are the steps to export your app for testing:

1. Register all test devices.
2. Archive your app.
3. Export the archive using either an ad hoc provisioning profile or team provisioning profile to code sign your app.
4. Install the app on test devices.
5. Solicit crash reports from testers.

About Ad Hoc Provisioning Profiles

ad hoc provisioning profile

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.

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. You can register 100 devices of each type per year. For iOS apps, you can register 100 iPad, 100 iPhone, and 100 iPod Touch devices.

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.

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. For Apple TV devices, send the instructions in Locating Device IDs Using System Information

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

1. In the Xcode project editor, choose a generic device—Generic iOS Device, Generic tvOS Device, or Generic iOS Device + 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.
2. Choose Product > Archive.
   The Archives organizer appears and displays the new archive.

Setting Individual App Icon and Launch Image Files, an Info.plist

Exporting Your App for Testing Outside the Store

iOS App file (a file with an .ipa

Note: tvOS binaries are also iOS App files with an .ipa

To create an iOS App file for testing

1. In the Archives organizer, select the archive.
2. 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.
3. 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.
4. 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.

5. In the dialog that appears, review the app, its entitlements, and the provisioning profile.

XC Ad Hoc:

1. . The team provisioning profile should begin with the text [platform] Team Provisioning Profile: [App ID] (see Team Provisioning Profiles in Depth).
2. 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 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. You can test binaries created from bitcode using Xcode, but should also test the binaries created by the store using TestFlight, described in Distributing Your App Using TestFlight (iOS, tvOS, watchOS).

3. 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.
• App URL.
• Display Image URL.
• Full Size Image URL.

4. Click Export.
   The Finder shows the exported files.

manifest.plist file appears in the same location as the iOS App file. If you request variances, app thinning metrics are also included in the folder. The App Thinning Size Report file contains a summary of the sizes of all variants and the app-thinning.plist

Installing Your App on Test Devices Using Xcode

You can install iOS App files on devices using Xcode.

To install an app on a device using Xcode

1. Connect the device to your Mac.
2. In Xcode, choose Window > Devices and select the device under Devices.
3. In the Installed Apps table, click the Add button (+) below the table.
4. In the dialog that appears, choose the iOS App file and click Open.

Managing Apps on Devices.

Installing Your App on Test Devices Using iTunes (iOS, watchOS)

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 an iOS device using iTunes

1. Connect the testing device to a Mac running iTunes.
   If possible, don’t use a Mac that you use for development. For watchOS apps, connect an iPhone paired with an Apple Watch.
2. Double-click the iOS App file that you created earlier.
3. In iTunes, click the device in the upper-left corner of the window.
4. Click the Apps button.
   The app appears in the iTunes Apps list.
5. 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.
6. If an Install button appears, click it.
   The button text changes to Will Install.
7. 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.

Soliciting Crash Reports from Testers.

Installing Your App on Test Devices Using Apple Configurator 2 (iOS, watchOS, tvOS)

Apple Configurator 2 is a free app from the Mac App Store that makes it easy to install iOS and tvOS apps on connected test devices. For tvOS apps, this is the only way to install an iOS App file on an Apple TV without using Xcode.

To install the app on a device using Apple Configurator 2

1. Connect the testing device to a Mac running Apple Configurator 2.
   If possible, don’t use a Mac that you use for development. For watchOS apps, connect an iPhone paired with an Apple Watch.
2. Select the device, click the Add button (+), and select Apps from the pop-up menu.
3. In the dialog that appears, click “Choose from my Mac”.
4. Choose the iOS App file that you created earlier and click Add.

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

Copying App Sandbox Data

Viewing, Downloading, and Replacing App Containers on 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.

Note: If you use TestFlight to distribute your prerelease app, described in Distributing Your App Using TestFlight (iOS, tvOS, watchOS), Apple collects and aggregates crash logs into crash reports for you.

Tell testers how to retrieve crash reports from their devices and send them to you.

To send crash reports from a Mac

1. Connect the testing device to a Mac running iTunes.
   iTunes downloads the crash reports to your Mac.
2. In the Finder, choose Go > “Go to Folder.”

~/Library/Logs/CrashReporter/MobileDevice

1. .
2. Open the folder identified by your device’s name.
3. Select the crash logs named after the app you’re testing.
4. Choose Finder > Services > Mail > Send File.
5. In the New Message window, enter the developer’s address in the To field and appropriate text in the Subject field.
6. Choose Message > Send.
7. To avoid sending duplicate reports later, delete the crash reports you’ve sent.

To send crash reports from Windows

<user_name>

• For crash log storage on Windows, type:

C:\Users\<user_name>\AppData\Roaming\Apple computer\Logs\CrashReporter/MobileDevice

• For crash log storage on Windows XP, type:

C:\Documents and Settings\<user_name>\Application Data\Apple computer\Logs\CrashReporter<app_name> crash logs from <your_name>

1.  (for example, 

MyTestApp crash logs from Anna Haro

1. ) to the app’s developer.

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.