Packaging Native iOS Applications

This guide walks through the steps required to create and install a native application on a device running iOS for development and testing. This guide does not discuss how to submit your finished app to the iTunes store. For more information, see the Apple Development Portal.

These steps are required within the Apple Developer Portal to run an application on an iOS device:

1. Create, download, and convert an iOS Certificate.
2. Create an Application ID.
3. Register a device.
4. Create and download a Provisioning Profile.

After you complete the Apple Developer Portal steps, then:

1. Configure the application package Configuration.
2. Generate your app.
3. Copy and run the packaged application.

iOS Certificate Creation, Download and Conversion

Important: Because an iOS Certificate contains signed information about an author (person and company) who creates the application, perform this step normally once. You can use one certificate for multiple applications.

All iOS native applications need to be bundled with iOS Certificates that contain information about the author of the application. These certificates are issued and digitally signed by Apple Inc. through the Apple Developer Portal.

To generate an iOS Certificate:

1. Generate a Certificate Signing Request (CSR).
2. Navigate to the Apple Development Portal, Certificates section, and Click Add.
3. Upload the CSR to the Development Portal and generate an iOS Certificate
4. Download the iOS Certificate.
5. Convert to iOS Certificate to P12 format.

When developing under Windows, the steps are the same, but the methods and commands differ slightly.

Mac OS Environment

All of the tools required for your iOS Certificate are included with Mac OS, so creating your certificate is relatively simple and facilated using the Keychain Access utility. This is located in your Applications/Utility folder.

Generate Certificate Signing Request

Launch the KeyChain Access utility. From the application menu, choose:

Keychain access > Certificate Assistant > Request a Certificate from a Certificate Authority.

In the Certificate Information window, enter or select the following information:

• User Email Address field: Your email address
• Common Name field: Your name
• Request is group: Select the Save to disk option
• Click Continue

The Certificate Assistant saves a Certificate Signing Request (CSR) file to your desktop. The public and private key pair generates when you create the Certificate Signing Request (CSR) if you use the Key Chain Assistant to create the CSR.

Upload CSR and Generate iOS Certificate

After you create your CSR file, navigate to the Apple Development Portal, Certificates section. To create a Certificate, click the Add button and select a certificate type of iOS App Development. The portal then requests you to upload your CSR file. After the upload completes, you can generate and download your iOS Certificate.

Convert Certificate to P12 Format

After you download your certificate (the default name is ios_development.cer), convert the certificate to P12 format before you can bundle it into your application. For information on what a P12 certificate is, see the Wikipedia PKCS #12 article.

To convert the certificate to P12 format:

1. In the Mac Keychain Access utility, click File > Importand navigate to the location of the downloaded ios_development.cer file.
2. After importing the certificate file, click Keys Category.
3. Click the private key associated with your Apple iOS Certificate. The private key has the following name pattern: iPhone Developer:<First Name> <Last Name> public key reference.
4. Click File > Export Items and save the key in P12 format.
5. Specify this file in the Sencha packager config file in the certificatePath variable.

Windows Environment

OpenSSL is required for you to generate a self-signed certificate for your application. OpenSSL for Windows is available at Shining Light Productions where you can download and install:

• Visual C++ 2008 Redistributables (required for OpenSSL)
• Open SSL Light (32 or 64 bit version)

By default, OpenSSL installs in the directory \OpenSSL-Win_XX_ where XX is 32 or 64 depending on the version you installed. Set environment variables first for OpenSSL to run properly before you proceed to generate your private key required for creating your digital certificate.

Create Private Key

The following example generates a private key, which is required for signing a digital certificate:

> cd \OpenSSL_Win64
> set OPENSSL_CONF=\OpenSSL-Win64\bin\openssl.cfg
> set RANDFILE=\OpenSSL-Win64\.rnd
> openssl genrsa -out myprivatekey.key 2048
Loading 'screen' into random state - done
Generating RSA private key, 2048 bit long modulus
................................................................+++
................................................................+++
e is 65537 (0x10001)
>

Note: Safely store the myprivatekey.key file. You need this to generate your P12 certificate.

Generate Certificate Signing Request

A CSR is a message sent to a certificate authority to request an identity certificate. For more information, see Certificate signing request.

To create your CSR, type the following openssl command at a command line:

> openssl req -new -key myprivatekey.key -out mycert.csr 
Loading 'screen' into random state - done
You are about to be asked to enter information that will be incorporated 
into your certificate request.
What you are about to enter is called a Distinguished Name or a DN.
There are quite a few fields, but you can leave some blank.
For some fields there will be a default value,
If you enter '.', the field will be left blank.
-----
Country Name <2 letter code> [AU]: US
State or Province Name <full name> [Some-State]: My State
Locality Name <eg, city> []: My City
Organizational Name <eg, company [Internet Widgits Pty Ltd]: MyCompany, Inc
Organizational Unit Name <eg, section> []:
Common Name <eg server FQDN or Your name> []: com.mydomain
Email Address [] [email protected]

Please enter the following 'extra' attributes
to be sent with your certificate request
A challenge password []:
An optional company name []:

>

Upload CSR and Generate iOS Certificate

After you create your CSR file, navigate to the Apple Development Portal, Certificates section. To create a Certificate, click the Add button and select the certificate type of iOS App Development. You are requested to upload your CSR file. After the upload completes, you can generate and then download your iOS Certificate.

Convert Certificate to P12 Format

After you download your certificate (default name is ios_development.cer), convert the certificate to P12 format so that you can bundle it into your application. Assuming you are in the directory where you downloaded your iOS Certificate, convert the certificate to P12 by executing the following openssl commands:

> openssl x509 -in ios_development.cer -inform DER -out ios_development.pem -outform PEM
> openssl pkcs12 -export -inkey _myprivatekey.key_ -in ios_development.pem -out ios_development.p12

Loading 'screen' into random state - done
Enter Export Password:
Verifying - Enter Export Password:

Where myprivatekey.key is the keyfile you specified when you generated your CSR.

Note: If you didn’t enter a challenge password in your CSR, press the Enter key to leave this request empty.

The resulting .P12 file is the name you specified in your packager configuration file for the certificatePath setting.

App ID Creation

The App ID, also known as the Bundle ID, is a unique string used to identify your application. Obtain the App ID from the Apple Development Portal.

For development purposes, all your apps may use the same ID, however for production, this ID must be unique for each application you submit to the iTunes store. Normally the format of the ID follows reverse domain name convention of tld.domain (for example, com.mydomain.appname).

The App ID is used during the provisioning process to create a relationship between the application you’re developing, and iOS certificates and devices permitted to run the application during testing.

Device Registration

(Required once for each device) - Register your device in the Apple Developer portal if you have not already done so. You will need your device’s unique ID (UDID), which you can get with iTunes from your device.

To view the UDID:

1. Open iTunes on your computer (Mac or PC).
2. Plug in your iOS device (iPhone, iPod, etc).
3. Click its name under the devices list.
4. Ensure you’re on the Summary tab.
5. Click the serial number - This changes to your device’s UDID.
6. Click Copy from the Edit menu.

With your UDID in the clipboard ready for use, go to the Developer Portal and open up the Devices section.

To add your device:

1. Select the Devices menu option.
2. Click the [+] in the upper right hand corner to open up theAdd iOS Devices page.
3. Enter a name for your device and its UDID (paste from clipboard).
4. Click Continue.

Provisioning Profile Creation and Download

At this point, you’ve created an iOS Certificate with your credentials (Step 1), defined an App ID (Step 2) and registered your iOS device (Step 3).

You only have one step left and that is to put all these together so that your iOS device knows that it can trust your application. That’s what provisioning accomplishes.

A Provisioning Profile simply links an App ID with iOS Certificates and devices authorized to run the application.

To create or update a Provisioning profile:

1. Give your profile a name.
2. Specify the App ID for this profile along with authorized iOS Certificates and devices.
3. Generate and download the provisioning file which defaults to the name _profileName_.mobile provision (where profileName is the name you specified for the profile).

4. Specify the downloaded provisioning file path and location in your packager configuration file with the provisionProfile setting:

   “provisionProfile”: “profileName.mobileprovision”

When an application loads on an iOS device, iOS compares the iOS Certificate that is bundled into the application and the device’s UDID against the authorized certificates and device UDIDs found in the provisioning file. If either the bundled iOS Certificate or device UDID are not found, the application is not permitted to load onto the device.

You can have mulitple provision files, one for each project you work on, or use just one provision file for all your apps. If you have just started a new app, or still are in the early stages of development, the simple thing to do is to use one provision file for all development. Eventually, though, you may find it prudent to create specific provision files for each app as the AppId added in the provisioning portal is compared to what is configured in the app, and only one AppId is permitted per app in the App Store.

For more information about provisioning files, see the Apple iOS provisioning portal (requires an Apple ID and password).

Package Configuration

The next step is to edit the Sencha packager file with appropriate settings for your environment and application testing.

Note If you are using the Touch Cordova or PhoneGap features, the packager file is not used. Refer to Cordova and PhoneGap app for more information.

In the root directory of your application there should be a packager configuration file - `packager.json’. If this file does not exist, you may easily generate one with this command:

sencha app package generate packager.json

You may now edit the packager file. The following configuration properties pertain to iOS development and are required for both debug and release configurations unless otherwise specified:

• applicationName

The name you give your application. This name appears under your application’s icon on the device’s home screen.

• applicationId

Also known as the Bundle ID, this is a unique identifier for your application. For development, all your apps may share the same App ID; however for production, the App ID must be unique for each application you submit to the iTunes store. Normally the format of the ID follows reverse domain name convention of “tld.domain” (for example, com.mydomain.appname).

The applicationId must match the application ID you enter when creating your App ID.

• bundleSeedId

This value is the Prefix value found when viewing the App ID in the developer portal. It is a 10-character string and is the same for all your applications in your account.

• configuration

The type of configuration for your native app build: specify Debug for development and testing, Release for publishing to the iTunes store.

• platform

The target platform for your application: specify iOS to test on a real device or iOSSimulator to view your application in the iOS Emulator.

• deviceType

The target device for the application. Specify iPhone or iPad.

• certificatePath

The path to the location of your certificate file (P12 file).

• provisionFile

The path to the location of your Provisioning file for this application.

• permissions

It is safe to leave the permissions set to the default.

Save your packager file settings.

Creating the Packaged Application

Build your native application in the root directory of your application:

sencha app build native

This command reads your packager.json configuration file (if you are not using Cordova or PhoneGap), builds your application, and places it in the build directory. You can locate the resulting app compressed file in the native build target directory by doing a directory listing:

$ cd build/<appname>/native/
$ ls
<applicationName>.app
$

Where <appname> is the application name you specified when you ran your sencha generate app command and <applicationName> is the value you specified for the applicationName property in your packager.json file.

Copy and Run your Application

Now the moment you’ve been waiting for to test your application on an iOS device!

To load your application onto your device:

1. Launch iTunes and select the Apps screen in your Library.
2. Bring up a file browser window and locate the .app directory where your native application was built.
3. Drag the .app directory the the Apps screen in iTunes.
4. Select your iOS device under the Devices section of iTunes.
5. Click the Apps tab on your device.
6. Locate the app you just copied over to your Apps Library.
7. Click Install.
8. Click the Applybutton to copy the app from your Library to your iOS device.

Now switch to your device, find your application and press the icon. You should have your basic application all up and running.