Device deployment

This topic describes the steps to deploy your iOS apps onto iOS devices for testing.

Note that Apple constantly changes these steps so although some of the specifics might be a little different, the overall process should be similar.

Getting started

You should be using the most recent Xcode and Xojo versions to ensure that your apps will build properly for devices. At the time of this writing that is Xcode 12 and Xojo 2020 Release 1.2.

In order to deploy your app to an iOS device for testing, you need to be a member of the Apple Developer Program. There are two main steps to this. First, you need to create your certificates and provisioning profiles which are required to deploy onto a device. Then you need to install the profile onto the device. For these steps you will need to use Xcode. Some steps can also be done using the Apple Configurator tool. Generally speaking, you only need to do these steps once. But you may have to revisit them if you add devices or are setting up another Mac for deployment testing. If you run into trouble, refer to the Troubleshooting section.

  1. Start Xcode and open Preferences.

  2. Select Accounts.

  3. Add the Apple ID you used for your iOS developer account.

  4. Select the account for the Apple ID.

  5. Click "Manage Certificates".

  6. Click the "+" button in the lower right and select "Apple Development" to create the necessary certificates.

  7. Click "Done" to close the window.

Keep Xcode running as you will later use it to transfer the built app to the device.

Configuring provisioning profile

Now you need to add any devices on which you will do testing.

  1. Log into the Apple Developer Portal at https://developer.apple.com/account and select "Certificates, Identifiers & Profiles".

  2. Select the Devices section and click the appropriate device to add (iPhone, iPad or iPod Touch). Click on the "+" button to add a new device. You'll need to supply a name and the UDID (Universal Device Identifier) for any devices you want to add (and thus deploy to). You can get the UDID by using the Xcode Devices window (Windows > Devices). This UDID is displayed in the "Identifier" field when you select your device in the list. From this window you can copy the value to paste it on the Add Device screen.

  3. You only need to add a device once.

If you don't already have one, you will also need to create an App ID. For the purposes of the steps below, your app name is represented by "MyApp" and your company/organization name is represented by "MyCompany" : 1. Select the Identifiers section.

  1. Click "+" to add an ID.

  2. Choose "App IDs" and Continue.

  3. Select "App" and Continue.

  4. Enter a description such as "MyApp".

  5. Specify the Bundle ID. You should choose an Explicit Bundle ID, such as "com.mycompany.myapp".

  6. Choose Capabilities as necessary.

  7. Click Continue and then Register.

This ID must match what you use as the Bundle Identifier for your Xojo iOS app (located in iOS Build Settings). For example, if you use "com.mycompany.myapp" as an App ID, then the Bundle Identifier for your Xojo iOS app should be "com.mycompany.myapp". If you forget this step you may get a Xojo build error that says "A development profile is required when building an iOS application.". In addition, your iOS App Name should match the description or last part of the bundle ID (MyApp in this case).

With the devices added and an App ID created, you can now create the Provisioning Profile: 1. In the Dev Portal, select the Profiles section.

  1. Click "+" to add a provisioning profile.

  2. Select "iOS App Development" and then Continue.

  3. Choose the App ID created above and then Continue.

  4. Select the Certificate and then Continue.

  1. If you don't have a valid certificate, then you'll be prompted with steps to manually create one. You should already have the one you created with Xcode available for use.

  1. Select the Devices and then Continue.

  2. Enter a name for the profile (it's for your reference and can be anything) and then Continue.

  3. Click the Download button to download and note the location of the downloaded file.

  4. Click Done.

Go to the downloaded profile and double-click it to install it into Xcode.

Manual add provisioning profile to xcode and devices

This is usually done automatically by double-clicking to install the downloaded profile. These are the manual steps. 1. In Xcode, go back to the Preferences, select Accounts, and highlight your account.

  1. Click "Download Manual Profiles".

To manually copy the Provisioning Profile file you previously downloaded to the device: 1. Plug in the device via USB.

  1. Back in Xcode, select Windows > Devices and Simulators.

  2. Right-click on the device and select "Show Provisioning Profiles".

../../../_images/device_deployment_xcode_device_provisioning_profiles.png

  1. In the dialog, click "+" and select the profile file that you previously downloaded from the iOS Dev Portal.

  2. Click Done.

Follow the Xcode instructions to unlock the device and click "Trust" in order to allow the provisioning profile to be added to it.

You may need to close and re-open Xcode in order for the Provisioning Profile to appear.

If you would rather use Apple Configurator instead of Xcode, you can click the "Install Profiles" button on the Prepare Settings screen to add the profile you downloaded and then click the Prepare button.

Build the app

Now that your Mac and iOS device are configured with the provisioning profile, you can now build your iOS app using Xojo. If you had Xojo open during this process, you should close and re-launch it so it can correctly identify the newly created Provisioning Profile. 1. Open or create an iOS project using Xojo. Try one of the included examples, such as XojoDoodle (iOS/Apps/XojoDoodle).

  1. Make sure the Bundle Identifier (in iOS Build Settings) matches the App ID you included in your Provisioning Profile.

  2. Click on iOS Build Settings and in the Code Signing section of the Inspector select your Team. This ought to match the team for your Apple ID.

  3. Leave "Build for App Store" OFF.

  4. Click the Build button in Xojo to build the app. This code-signs your apps and compiles it for ARM using LLVM. This may take a little longer than running in the Simulator.

When your app is built you will get the app bundle (this is what gets installed on the device) and a .dSYM file (the debugging symbols).

It is important that you retain both of these files for builds you deploy. The dSYM file is used for analyzing crash reports that you may receive from your users and without it, it will be difficult to determine the cause of the crash. For more information, refer to the Apple document Understanding and Analyzing iOS Application Crash Reports.

If you submit device crash logs in a bug report, you will also need to include the dSYM file in order for us to interpret them.

Install the app on the device

Now you are ready to install the app onto your device. You can do this using the Xcode Devices window or the Apple Configurator app.

Using Xcode devices window

  1. Start Xcode.

  2. Ensure your iOS device is plugged into the Mac via USB.

  3. From the Window menu, select Devices and Simulators.

  4. Click on the iOS device in the sidebar.

  1. There may be a delay as Xcode prepares the device the first time.

  1. Click the "+" button (In the Installed Apps section) and select the app you previously built (or drag the app into the Installed Apps section). This immediately installs it on the iOS device.

  2. On the device, tap on the app to launch it.

Using Apple Configurator

Apple Configurator 2 is a free download from the Mac App Store. This tool is primarily used for enterprise deployment of apps, so it can do much more than just deploy built apps to devices. Some people might prefer using it instead of the Xcode Devices window (you'll still have to set up your device using Xcode as described above, however): 1. Ensure your iOS device is plugged into the Mac via USB.

  1. Run Apple Configurator.

  2. On the "All Devices" view, double-click your iOS device.

  3. Click on Apps in the Navigator on the left. This displays all the apps on the device.

  4. Click the Add button in the toolbar, select "Apps" from the menu and in the dialog, click "Choose from my Mac...".

  5. Select the app you previously built. Click OK to copy the app to the device.

  6. On the device, tap on the app to launch it.

Getting crash logs

You can retrieve crash logs from your iOS device using the Devices and Simulators window in Xcode. Plug your device in via USB and select it in the list of devices. Then click the "View Device Logs" button. You'll see a list of crash logs (it may take a few minutes to download if you have a lot of them). Find your app in the list and click it to see the log. When submitting Feedback cases with crash logs, wait to ensure that the symbols for your log are loaded before you send the log.

This tool is also useful to reading iOS console logs:

Troubleshooting

Unfortunately, some people have run into trouble deploying to their iOS device even after following these steps. This is generally due to certificate expiration or profile installation problems and is something even users of Xcode have to deal with. Here are some suggestions that might help:

  • One of the most common solutions is to revoke and remove all certificates and profiles (including those in the Keychain) and go through the steps again.

  • Profiles are located here: ~/Library/Mobile Device/Provisioning Profiles/

  • Remove all expired certficates using Keychain Access app.

  • Consult StackOverflow or the Xojo forum for any specific error message your are getting. Keep in mind that few of these errors are Xojo-specific, so you may find help in the general iOS development community.

  • For more information about the specifics of certificates, profiles and deployment, be sure to read the Apple docs in the iOS Developer Portal.

  • Creating a blank test app in Xcode using your developer profile and deploying the app to the iPhone (just a blank iOS app) can sometimes fix issues.