Using Flash Builder 4.5 to package applications for Apple iOS devices

Note: This is an updated and expanded version of an article originally written by Andrew Shorten.

Flash Builder 4.5 includes support for packaging Flex and ActionScript applications for Google Android, Apple iOS, and BlackBerry Tablet OS devices. The process for acquiring signing certificates and provisioning application packages for the various platforms differs significantly.

This article and video aim to help ActionScript and Flex developers complete the necessary steps so that applications built in Flash Builder can be deployed to iOS devices during the development, testing and deployment phases of the project.

For more information on packaging applications for other platforms please read the following articles:

• Using Flash Builder 4.5 to package applications for Google Android
• Using Flash Builder 4.5 to package applications for BlackBerry Tablet OS

Get required certificates

In order to package applications for testing/debugging on iOS devices and for deployment to the Apple App Store you need an Apple iOS development certificate (in P12 format) and a provisioning profile. There are both development and distribution versions of each.

The development provisioning profile is a collection of data that ties developers and devices to an authorized iOS development team and enables a device to be used for testing. It contains a set of iOS development certificates, device IDs, and an application ID and must be installed on each device on which you wish to run your application.

A distribution provisioning profile, on the other hand, may or may not contain device data depending upon if you are creating the application package for ad hoc distribution directly to specific devices or through the Apple App Store. Apple will only accept applications if they are built with an App Store distribution provisioning profile, but applications built with App Store provisioning files cannot be directly installed on a device.

Step 1: Enroll in the iOS Developer Program.

The first step in acquiring the necessary certificates is to become an Apple Developer and enroll in the iOS Developer Program (fee required).

Browse to http://developer.apple.com and click the link to join the iOS Developer Program. Follow the steps to enroll in the iOS Developer Program. You will need to register as an Apple Developer (if you are not already) as an individual or as part of a company development team and then wait until you receive a verification code via email. You can then join the iOS Developer Program. In June 2011, the fee for the program was $99 per year. The entire process can take from several hours up to several days.

Step 2: Log in to the iOS Provisioning Portal.

The iOS Provisioning Portal is where you create application IDs, register iOS devices that you wish to deploy applications to during development, upload certificate signing requests, approve and download developer certificates, and create and download provisioning profiles.

1. Browse to the Apple Developer website and click the Member Center link.
2. Log in to the Member Center and click the link beneath iOS Provisioning Portal.

Step 3: Create an App ID on the iOS Provisioning Portal.

Each application (or group of applications) that you want to deploy on an iOS device must have an App ID; this is made up from a Bundle Seed ID (also called the App ID prefix) and a Bundle Identifier (also called the App ID suffix).

1. Go to the App IDs page in the iOS Provisioning Portal and click New App ID.
2. On the Manage tab, enter a description for your application (or group of applications), generate a new Bundle Seed ID (select Generate New from the pop-up menu), and enter a Bundle Identifier (for example, com.adobe.samples.*).

An App ID is the combination of a the Bundle Seed ID, a generated unique ten character string, and a Bundle Identifier. The recommended practice is to use a reverse-domain name style string for the Bundle Identifier portion of the App ID.

The Bundle Identifier you specify must match the application ID set in the AIR application descriptor file. For example, if you specify a Bundle Identifier of com.adobe.samples.FlexMobileTestDrive, the app.xml file must contain that ID (see Figure 1).

Figure 1. Make sure the AIR application's ID and the Apple App ID match.

For more flexibility, you can use a wildcard in the Bundle Identifier so that it can be used for a group of applications. For example, a Bundle Indentifier of com.adobe.samples.* can be used to build and install applications with IDs of com.adobe.sample.FlexMobileTestDrive , com.adobe.samples.myOtherApp , and so on.

Step 4: Use iTunes to get iOS device IDs.

The devices that you want to run or debug the application on must be specified in the provisioning profile used to package the application; as such, you must register the devices on the iOS Provisioning Portal. To register a device you need its unique device ID.

1. Connect your iOS device to your computer and open iTunes.
2. In iTunes, select your device in the Devices section and navigate to the Summary tab.
3. Click the Serial Number label to reveal the Identifier field and the 40 character UDID (see Figure 2).
4. Press Command/Ctrl+C to copy the UDID to your clipboard.

Figure 2. Get iOS device IDs.

Step 5: Register iOS devices on the iOS Provisioning Portal.

Once you have the iOS device IDs, you can register them on the iOS Provisioning Portal.

1. Return to the iOS Provisioning Portal and navigate to the Devices page.
2. Click Add Device, enter a device name and the device ID you got from iTunes, and click Submit.

Step 6: Create a certificate signing request (CSR) file.

Next you need to create a development developer certificate and a development provisioning profile for a specific developer certificate, App ID, and device(s). To get a developer certificate, you generate a certificate signing request (CSR) file on your computer, upload it to the iOS Provisioning Portal, and then you or a team leader approve it. Although you can create a CSR on both Mac and Windows computers, it is much simpler on Macs.

Generate a CSR on Mac OS

On a Mac, you use the Keychain Access program to generate a CSR.

1. Open Keychain Access located in Applications > Utilities.
2. Select Keychain Access > Certificate Assistant > Request a Certificate from a Certificate Authority.
3. In the Certificate Assistant, enter your name, email, save the request to disk, check Let me specify key pair information (see Figure 3), and click Continue.

Figure 3. Create a certificate request.

4. Specify where to save the file and what to name it and click Save.
5. On the Key Pair Information page, select RSA algorithm with 2048 bits key size. If you do not set the key size to 2048 bits, the iOS Provisioning Portal will reject the CSR.
6. Locate the certificate request file saved to your computer.

Generate a CSR on Windows

On Windows, you can use OpenSSL to generate a CSR.

1. Browse to the OpenSSL website and download and install OpenSSL on your computer.

   Note: You may also need to install the Visual C++ 2008 Redistributable files listed on the Open SSL download page, though you do not need to install Visual C++.

2. Open a Windows command session and navigate to the CD to the OpenSSL bin directory.
3. Create a private key by entering the following in the command line:

openssl genrsa -out mykey.key 2048.

4. Save this private key file. You will use it later.

   Note: When using OpenSSL, do not ignore error messages. If OpenSSL generates an error message, it may still output files but those files may not be usable. If you see errors, check your syntax and run the command again.

5. Create the CSR file by entering the following in the command line:

openssl req -new -key mykey.key -out CertificateSigningRequest.certSigningRequest -subj "/emailAddress=yourAddress@example.com, CN=John Doe, C=US"

6. Replace the e-mail address, CN (certificate name), and C (country) values with your own.

7. Locate the certificate request file saved to your computer.

Step 7: Use the iOS Provisioning Portal to create a developer certificate (CER) file.

Now you upload the certificate request file to the iOS Provisioning Portal to create a development developer certificate.

1. Return to the iOS Provisioning Portal and navigate to Certificate > Development.
2. Click Request Certificate and then click the Browse button.
3. Select the CSR file you just created and saved on your computer and click Submit. The certificate will appear on the Certificates page with a status of pending issuance.

4. Note: If you are an individual developer or a team leader, wait until the certificate status changes from pending issuance to an Approve button (you will have to refresh the page) or until you receive an email notification that you have a certificate request requiring your approval and then click the Approve button. This usually only takes a few minutes.

   If you are not an individual developer or a team leader, wait until you receive an email notifying you that a team leader has approved your certificate.

5. On the Certificates page in the iOS Provisioning Portal, click the Download button next to your certificate.
6. Save the file. It will be saved as developer_identity.cer.
7. Click the link to also download the WWDR intermediate certificate.

Step 8: Convert the iOS developer certificate into P12 format.

In order to use the certificate with Flash Builder, you must convert it to P12 format. The P12 file combines your Apple developer certificate and the associated private key in a single file.

Create a P12 file on Mac OS

On a Mac, you use the Keychain Access program to generate a P12 version.

1. Open the Keychain Access application (in the Applications/Utilities folder).
2. Double-click the WWDR certificate file (AppleWWDRCA.cer) in Finder or in Keychain Acces select File > Import and import the AppleWWDRCA.cer.
3. Double-click the develop_identity.cer file in Finder or in Keychain Access, select File > Import and import it.
4. Navigate to Certificates. You should see the two certificates listed (see Figure 4).
5. Expand the developer certificate. You should see a private key (see Figure 4).

Figure 4. Import the developer certificate.

6. Right-click on the private key and select Export.
7. Select a file format of Personal Informatin Exchange (.p12) and assign a file name and save location (see Figure 5). Assign a name and where to save the file, select a file format of Personal Information Exchange (.p12), and click Save.

Figure 5. Create a P12 version of the certificate.

8. In the dialog box that appears, create a password for the P12 file. You will have to enter this password when you use this certificate to sign applications.

Create a P12 file on Windows

On Windows, you use OpenSSL to convert the iOS developer certificate file into a PEM certificate file and then generate a P12 file based on the PEM certificate and the certificate key you generated earlier with the request.

1. Create a PEM file by entering the following command-line statement from the OpenSSL bin directory:openssl x509 -in developer_identity.cer -inform DER -out developer_identity.pem -outform PEM
2. Generate a valid P12 file by entering the following command-line statement from the OpenSSL bin directory. Use the PEM version you just created and the private key you generated earlier when creating the certificate signing request (CSR) file.openssl pkcs12 -export -inkey mykey.key -in developer_identity.pem -out iOS_dev.p12

Step 9: Create an iOS development provisioning profile.

The final step you need to complete using the iOS Provisioning Portal before packaging your application is to create an iOS development provisioning profile.

1. Return to the iOS Provisioning Portal, navigate to Certificate > Provisioning, and click New Profile.
2. Enter a profile name, select your certificate, select the App ID and devices, and click Submit.

3. Wait until the status of the provisioning profile changes from Pending to Active (you will have to refresh the page). This usually only takes a few seconds.
4. Download the provisioning file.

Run and debug on a device

Now that you have a development P12 developer certifcate and a development provisioning profile, you are ready to use Flash Builder to package your AIR application as a native iOS application that can be installed on one of the devices specified in the provisioning profile. You specify these files in the project's packaging info and then create a run configuration for iOS devices. Flash Builder creates an IPA application package that you add to iTunes and then sync to your device.

Step 1: In Flash Builder, set the application ID.

Recall that the application ID in the application descriptor file must match the Apple App ID associated with the provisioning file you are going to use to package the application.

Open the application descriptor file and make sure its ID is set to the same name (like com.adobe.samples.FlexMobileTestDrive) or if a wildcard bundle identifier was used (like com.adobe.samples.*), make sure the ID starts with this string.

Step 2: In Flash Builder, specify project iOS packaging information.

This information will be used when debug application packages are created.

1. In Flash Builder, right-click your project in the Package Explorer and select Properties.
2. In the Properties dialog box, select Flex Build Packaging > Apple iOS (for a Flex project) or ActionScript Build Packaging > Apple iOS (for an ActionScript project).
3. Specify the P12 development developer certificate file and the development provisioning file you created (see Figure 6).

Figure 6. Specify Apple iOS packaging properties.

Step 3: Use Flash Builder to package the application as a debug IPA file.

To create an application package, you create a run configuration to run on an iOS device.

1. In Flash Builder, select Run Configurations from the Run menu or from the dropdown list for the Run button and click the new or duplicate button to create a new run configuration.
2. Name the new configuration, set the target platform to Apple iOS, set the launch method to On device, and select either standard or fast packaging (see Figure 7). Standard packaging takes several minutes, but application performance is similar to a release build. Fast packaging takes several seconds, but the application runs significantly slower than a release build.

Figure 7. Create a run configuration for running on an Apple iOS device.

3. Click the Run button and then enter your certificate password in the Certificate Password dialog box. Flash Builder will convert your application to a native iOS application. When the process is complete, you will get a Packaging Completed dialog box (see Figure 8).

Figure 8. Wait until the debug IPA package is created.

4. Locate the IPA file in your project's bin-debug folder (see Figure 9). This is a debug version of the application for development. You learn to create a release version of the IPA for distribution in the next section.

Figure 9. Locate the debug Apple iOS package created.

Step 4: Use iTunes to install the application on an iOS device.

You are now ready to deploy or debug the application on an iOS device. Unlike with other platforms, it is not possible for Flash Builder to automatically deploy the application to a device; you need to use Apple iTunes to complete this task.

1. Open iTunes, select File > Add to Library, and add the application's provisioning file. You can also add the file by dragging and dropping it on the iTunes dock icon.
2. Select File > Add to Library and add the application IPA file to iTunes (or drag and drop it onto the iTunes dock icon).
3. Locate your new application in Apps (see Figure 10). Currently, a default name and icon are used for the application. You will learn to customize these in the next section.

Figure 10. Locate the application in iTunes.

4. Connect your iOS device to your computer's USB port.
5. In iTunes, select the attached device and make sure your application is selected to be synced on the device and then sync the device (see Figure 11).

Figure 11. Add the application to the Apple iOS device.

6. Locate the application on the device (Figure 12) and run it (see Figure 13).

Figure 12. Locate the application on the device.

Figure 13. Run the application on the device.

Step 5: Debug the application on the device.

To debug an application on a device, you use Flash Builder to create a debug IPA package and then use iTunes to install it on the device just as you did for running the application on a device. For debugging, though, your computer and the device must be on the same Wi-Fi network. The USB cable is used to install the application on the device initially with iTunes; the Wi-Fi network is used for all communication between the device and Flash Builder when the application is running and being debugged.

1. In Flash Builder, select your iOS device configuration profile from the drop-down menu for the Debug button and click Debug.
2. After the IPA package is created, you will get a Waiting for Debugger Connection dialog box in Flash Builder (see Figure 14). The debugger will connect after you install and run the application on the device.

Figure 14. In Flash Builder, wait for a debugger connection.

3. Locate the IPA file in your project's bin-debug folder again, add it to iTunes, and sync it to your device exactly as you did in the previous step to install it on the device.

   Note: You should uninstall the application from the device before installing a new version.

4. Run the application on the device. When a breakpoint in the code is reached, the application will freeze and you can use Flash Builder to step through code exactly as when using the device emulator.

If the Flash Builder debugger times out before you finish installing and running the application on the device, just choose to debug on the iOS device again from Flash Builder and then launch the application on the device.

If you have trouble debugging on the device, check to see if you computer is on a VPN or using a firewall. If the computer is on a VPN and the device is not, you may need to take the computer off the VPN for debugging to work. If you have a firewall turned on, try disabling it. If you cannot or do not want to disable it, try opening port 7935, the port used by the Flash Builder debugger to communicate with the device.

Package for distribution

To create a release build of your application for distribution, you must first use the iOS Provisioning Portal to create a distribution developer certificate and a distribution provisioning profile. You then use Flash Builder to create release builds using those distribution files.

Step 1: Create a P12 distribution developer certificate.

You use the same process to create a distribution developer certificate as you did to create a development developer certificate in the previous Get required certificates section. The only difference is that you create it in the Distribution instead of Development tab of the iOS Provisioning Portal pages.

1. Using Keychain Access (on a Mac) or OpenSSL (on Windows), generate a new certificate signing request just as you did in step 6 in the "Get required certificates" section and save it to your computer.
2. In the iOS Provisioning Portal, navigate to Certificates > Distribution, and click Request Certificate.
3. Browse to this new CSR file on your computer and submit the request.
4. Wait until the certificate is issued and then download it. The file will be saved as distribution_identity.cer.

5. Using Keychain Access (on a Mac) or OpenSSL (on Windows), import the distribution certificate (see Figure 15) and create a P12 version of the certificate just as you did in step 8 in the Get required certificates section and save it to your computer.

Figure 15. Import the distribution certificate.

Step 2: Create distribution provisioning profiles.

You also use the same process to create distribution provisioning files as you did to create a development provisioning file, but you use the Distribution tab in the Provisioning page of the in the iOS Provisioning Portal instead of Development and you use the distribution developer certificate.

1. In the iOS Provisioning Portal, navigate to Provisioning > Distribution and click New Profile.
2. Set the distribution method to Ad Hoc, select the App ID and the devices, and click Submit. The application will only be able to be distributed on the devices you specify here. This allows you to create and test a release build of the application on devices before submitting it to the Apple App Store.

3. Click the New Profile button again and create a provisioning file for the Apple App Store.

4. When the provisioning profile statuses change from Pending to Active (you will have to refresh the page), download the provisioning files.

Step 3: In Flash Builder, modify the application descriptor file.

Before using Flash Builder to create a release build of the application, set application properties and iOS specific settings in the application descriptor file.

1. Return to Flash Builder and open the application descriptor file.
2. Set the application's name and filename to the value you want to appear in iTunes and on the device, set the versionNumber (you should update this for each release build posted to the App Store), and any other info you want to specify (see Figure 16).
3. See Common Settings in the AIR documentation for descriptions of other settings.

Figure 16. Set application info.

3. Locate the icon tag and specify PNG files for the application icons (see Figure 17).

   iOS uses a 29-by-29–pixel icon in Spotlight search results on iPhone/iPod Touch, a 48-by-48–pixel icon in Spotlight search results on the iPad, a 57-by-57–pixel icon on iPhone/iPod Touch home screens, a 72-by-72–pixel icon on the iPad home screen, a 114-by-114–pixel icon on iPhone/iPod Touch home screen icon for the 960-by-640–pixel display, and a 512-by-512–pixel icon in iTunes.

   Note: The 512-pixel PNG file is used only for testing development versions of your application. When you submit the final application to the Apple App Store, you submit the 512 image separately, as a JPG file. It is not included in the IPA.

Figure 17. Specify application icons.

4. Locate the iPhone tag and modify iOS specific settings (see Figure 18). You can set the status bar style, whether the app needs persistent Wi-Fi access, whether it uses a glare effect on the icon, what device models are supported, iOS compatibility filtering, and more.

See iOS Settings in the AIR documentation for descriptions of these settings.

Figure 18. Set iOS specific settings.

Step 4: In Flash Builder, create a release build of the application.

When exporting for the iOS platform, use the distribution developer certificate and distribution provisioning files you created.

1. Select Project > Export Release Build and make sure Apple iOS is selected as a target platform (see Figure 19) and click Next.

Figure 19. Export a release build.

2. Browse to your P12 distribution developer certificate and one of the distribution provisioning profiles (see Figure 20).
3. Select the package type for that particular provisioning profile: ad hoc or App Store (see Figure 20) and click Finish. The application will take several minutes or longer to build.

Figure 20. Specify iOS packaging settings for a release build.

4. Locate the release IPA package (see Figure 21).

Figure 21. Locate the release IPA package.

5. If you created ad hoc release build, add the distribution provisioning and the release IPA files to iTunes as you did for development and then install it on your device. You should see the custom names and icons you specified in the application descriptor file (see Figures 22 and 23).

Note: You should uninstall the application from the device before installing a new version.

Figure 22. View the application in iTunes.

Figure 23. View the application on the iOS device.

6. If you created an Apple App Store release build, follow the instructions in the Apple App Store Resource Center for submitting your application.

Where to go from here

In this article, you learned to use Flash Builder and iTunes to run and debug Flex and ActionScript applications on iOS devices. You also learned how to create a release build of your application for distribution.

For more information, refer to the following resources:

Documentation: Developing Mobile Applications with Flex and Flash Builder

• Run and debug mobile applications
• Package and export a mobile application

Documentation: Building Adobe AIR Applications

• Digitally signing an AIR file

Documentation: Developing AIR applications for mobile devices

• Setting mobile application properties

Websites

• Mobile and Devices Developer Center
• Apple Developer Center
• Apple Developer Member Center
• iOS Provisioning Portal
• Apple App Store Resource Center