Introduction

This document will discuss the build process and the tools to create a build you can run on your phone, as well as the necessary steps to get an application on the iTunes App Store.

Most of the complexity lies in the Apple developer process for creating and installing signing certificates. This document guides you through that process from the beginning. If you already have your Apple certificates installed on your development machine, you can skip directly to Building your App using Corona.

Important note

Apple sometimes makes changes to these processes. For the latest and most accurate information, please refer to Apple's documentation.

• iOS Developer Library > iOS Development Guide > Managing Devices and Digital Identities
• iOS Developer Library > iOS Development Guide > Distributing Applications
• Technical Note TN2250: Understanding and Resolving Code Signing Issues

What you will need

In order to submit an application to the App store, you must have a version of XCode that is the same or newer than the version of the OS on your phone. For example, if you have version 3.0 of the iPhone OS installed, you will need XCode that is bundled with the iPhone SDK version 3.0 or later.

Overview

Topics

• Developer account and Developer Certificate
• Keychain certificate
• Adding a Device
• App IDs
• Provisioning profiles
• Building your App
• Submitting your app to the app store

Developer account and Developer Certificate

Developer Account

To enroll in the iPhone Developer Program, go to the following Apple web site:

http://developer.apple.com/iphone/program/

Click on the ‘Enroll Now’ button and follow Apple’s instructions on applying for a certificate. Currently there are two programs, ‘Standard’ and ‘Enterprise’. Choose the program that best fits your needs.

Keychain Certificate

Once you have signed up for the developer program, you will need to use the ‘Keychain Access’ tool located in your utilities folder in order to create a certificate request. This will be used to authenticate your computer.

Open Keychain Access and click on the Keychain Access menu bar item:

Select ‘Request Certificate from a Certificate Authority...’. This will bring up the following window:

Type in the email address you used for your apple developer certificate in the ‘user email address’ field. For Common Name, use the name of the Team Leader or yourself if you do not have a team. Click ‘Saved to disk’ and ‘Let me specify key pair information’. Upon clicking ‘Continue’, you will be asked to choose a save location. Pick a location that is easy to find, such as the desktop. You will then be prompted with the following:

Make sure that 2048 is selected for the Key Size and RSA for the Algorithm, then hit ‘Continue’. This will generate the key and save it to the location you specified. Click ‘Done’ in the next window. Now navigate to the following url:

https://developer.apple.com/ios/my/overview/index.action

Click on Certificates in the left hand column:

Now click on the ‘Add Certificate’ button.

Click on the ‘Choose File’ button and locate your certificate file that you saved earlier, and hit the submit button.

Once you hit submit, an email will be sent to the email address you specified in the Certificate Authority (CA) request form from Keychain Access. If you are the team leader, you will get this email and can approve the request yourself by hitting the approve button:

If you are waiting on approval, you will see the following screen:

You will see this until your request has been approved. Once it has been approved, you will be able to download the certificate:

Click on the download button and save the certificate to a location of your choosing.

Once this is done, double click on the file and you will see the following dialog:

Click ‘OK’. This will install your iPhone Development Certificate in your Keychain.

Adding Devices

This iPhone developer program allow you to have up to 100 devices per team. To register a device you will need the Uniques Device Identification (UDID) number. This can be found in two places, iTunes and XCode.

Xcode

Normally when you plug in your device, and then open XCode, the ‘Organizer’ window will be open. If it is not, click on ‘Window’ and select ‘Organizer’:

Once the Organizer window is open, you should see the name of your device in the ‘Devices’ list on the left. Click on it and select the identifier with your mouse, copying it to the clipboard:

Note: if the colored indicator under the “Devices” list is yellow rather than green, turning the iPhone off and on again will usually re-synch it properly.

iTunes

With your device connected, open itunes and click on your device in the device list:

Click on the Summary tab at the top:

Now click on the serial number to reveal the UDID:

Simply hit Command-C to copy it to the clipboard.

Adding/Registering the Device

To add a device to your Teams device list, click on ‘Devices’ in the iPhone Developer Program Portal and click on ‘Add Devices’.

Here you will be able to name your device as well as input the Device ID that you have stored in your clipboard. Once you have done this, click the submit button.

In order to obtain provisioning profiles, you will first need to create an App ID. The App ID allows an application to communicate with the Push Notification service and/or any external hardware you have for your application. It can also be used to share keychain information, such as passwords, between a suite of applications. Regardless of whether or not you make use of such functionality, every application must have an App ID.

An App ID consists of a 10 character “Bundle Seed ID” prefix generated by Apple and a “Bundle Identifier” suffix that is created by the Team Admin in the Program Portal. An App ID could look like the following example: 9F456G1234.com.apple.YourApplication or 9F456G1234.com.YourApplication. To create a new App ID, click on the ‘New App ID’ button in the ‘App ID’ section of the program portal.

Fill in the ‘Description’ field with the name of your application. If you have already created an application and wish to use the Bundle Seed ID, for instance if you have a free version and a paid version of an application, you can select it in the ‘Bundle Seed ID (App ID Prefix) section on this page. If this is the first in the bundle or a standalone application, select ‘Generate New’. In the ‘Bundle Identifier (App ID Suffix)’ section, specify a unique identifier for your app. This can be just about anything you want for it to be, but it is recommended to use the reverse-domain style string, i.e. com.domainname.appname. For Corona Labs it might look like:

com.coronalabs.newapplication.  

Note: it is often easiest to create a “wildcard” App ID that you can share between your various applications. To do this, simply create a single App ID with an asterisk (*) at the end. You would place this in the field for the bundle identifier either by itself or at the end of your string: com.domainname.* The general drawback of this method is that it cannot be used with any application employing Push Notification, since that requires a unique App ID for each application. However, since Corona does not yet support the Apple Push Notification Service, this restriction does not currently affect Corona development.

For more information on this topic, please visit the Apple Developer site.

Provisioning Profiles

There are three types of provisioning profiles for the iPhone program: Ad Hoc, Development, and Distribution. These profiles tie your devices to your development team for testing and distribution.

Note: The Ad Hoc and Distribution provisioning profiles are not available when running the trial version of Corona. If you are running the trial version, you should build with the Developer's provisioning profile.

The Distribution Profile is what you use to build an application with the express purpose of putting it on the app store. It is not intended to be used for testing.

The Ad Hoc and Development Provisioning Profiles are used similarly, but you will only need to use the Ad Hoc profile with Corona. The Development profile can be used, but is not necessary.

Note: You do not need to add a CFBundleIdentifer field to the build.settings file when you are ready to submit your app to the app store. This is done automatically by Corona.

Ad Hoc Provisioning Profile

To obtain your Ad Hoc Provisioning profile to test on your device, you will need to create one in the iPhone Program Portal. From the Portal, click on the ‘Provisioning’ menu. From there click on the ‘Distribution’ tab:

Below this you will select the devices you wish to authorize for this profile. For most people, this will mean checking all of the devices available.

Now click the ‘Submit’ button.

You will now be returned to the Distribution tab where the status will most likely say ‘Pending’ . This process normally only takes a few seconds. Hitting the ‘Refresh’ button is normally enough time for it to be come active. Then you can ‘Download’ the profile. You will need to place it in the following directory:

/Users/(your user)/Library/MobileDevice/Provisioning Profiles/

If you do not have a ‘Provisioning Profiles’ folder, you will need to create it. Remember to substitute your username for (your user). For example:

/User/JohnGlenn/Library/MobileDevice/Provisioning Profiles/

Distribution Provisioning Profile

In order to submit your app to the app store, you will need to download the Distribution Provisioning Profile. This process is very similar to obtaining the Ad Hoc profile. Click on the Distribution tab in the Provisioning section of the Program Portal:

Instead of selecting ‘Ad Hoc’, this time we’re going to use ‘App Store’ for the distribution method.

Give your profile a name, such as “TestApp_distribution” and click on the ‘Submit’ button. You will be brought back to the Distribution Provisioning Profiles list, where you should see your profile listed and marked as ‘Pending’ in the Status column. Refresh the page and you should be able to download your profile into the same folder that you used for your Ad Hoc profile.

Building your App using Corona

Building your application using Corona is a simple process once you have your provisioning profiles in place. You must also make sure that you have a connection to the internet. You can build your application for testing in the XCode Simulator, or for testing on a device.

To build your application, open the Corona Simulator and open a project (select File > Open ... to open your project, or choose one from the Corona welcome window). Then select File > Build > IOS ... The following dialog appears:

Fill in the application name and version number fields with the relevant information, and select the target device (iPhone or iPad) from the Device Compatibility drop-down menu. To test the compiled application in the XCode Simulator select XCode Simulator from the Build For drop-down menu, or Device to build an app bundle for testing on a device. Lastly, select the appropriate provisioning profile from the ‘Code Signing Identity’ drop-down menu, either adhoc or distribution.

Note: if you have not loaded these profiles into the standard location on your hard drive, you will have no options in this drop down menu. Provisioning profiles should be placed in the following directory as mentioned in previous sections of this document:

/Users/(your user)/Library/MobileDevice/Provisioning Profiles/

Once you have entered all the relevant information, you may hit ‘Build’. Once Corona has completed the build, it will output an application to the ‘Save to folder’ you have chosen. By default this location is set to the desktop, and you will see an option to ‘Show in Finder’.

Congratulations! You now have an application file that can be placed on your device, or submitted to the App Store, depending on which provisioning profile you selected.

Customization

Application Icon

The application icon for iPhone should be a 57 x 57 PNG image file (or 72 x 72 for iPad). It should have the name Icon.png and be located in the assets project folder. For iPhone / iPod touch apps, an additional high-resolution 114 x 114 icon named Icon@2x.png is now also required to support Retina displays.

MyProject/
        Icon.png        <--- required for iPhone/iPod/iPad
        Icon@2x.png     <--- required for iPhone/iPod
        Icon-72.png     <--- required for iPad
        main.lua
        ...

Add the following to your build.settings file:

settings = 
{
    iphone =
    {
        plist =
        {
             CFBundleIconFile = "Icon.png",
             CFBundleIconFiles = {
                    "Icon.png" , 
                    "Icon@2x.png" , 
                    "Icon-72.png" , 
             },
        },
    },
}

Note: the App Store requires a 512 x 512 pixel version of the icon, so you should always create the icon in this higher-resolution. Please refer to the Apple iOS Human Interface Guidelines for the latest official App Store requirements.

Using a pre-rendered icon (no gloss)

To keep iOS from rendering your icon with the default gloss across its top, add the following plist setting to your project's build.settings file:

settings = 
{
        iphone = {
                plist = {
                        UIPrerenderedIcon = true,
                },
        },
}            

For more information about build.settings, see Build Configuration.

Launch Image

When your application launches, you can choose to display a launch image before your application finishes initializing and is ready to display its interface. By using an image that looks like the initial user interface, you can create the illusion of a faster application launch. Alternatively, you can use this image for a “splash screen” displaying your application title or company logo.

The launch image for iPhone should be named Default.png and be the dimensions of the screen. It should be located in the assets project folder.

MyProject/
        Default.png     <---
        Icon.png
        main.lua
        ...

For the iPad, Apple encourages the use of launch images for all orientations supported by your application, and the App Store reviews may reject applications that don’t conform to this rule. The iPad uses the following naming conventions for orientation-specific splash screen files:

Default-Portrait.png
Default-PortraitUpsideDown.png
Default-Landscape.png
Default-LandscapeLeft.png
Default-LandscapeRight.png 

See the “Orientation Support” section in the Corona API Reference for more information about using different orientations in your app.

Testing your App on your iPhone or iPad

To run the application on your iPhone or iPad, select the adhoc profile during the build process, as detailed above. You may then use either iTunes, XCode, or the iPhone Configuration Utility to transfer the application file.

To use iTunes, drag the application into your iTunes Library and then synch your device normally.

However, it is considerably faster to use either the iPhone Configuration Utility or the XCode Organizer. Also, these methods allow you to test on devices that are not synchronized to your iTunes account.

The iPhone Configuration Utility is available as a separate download from the iPhone Dev Center (http://developer.apple.com/iphone). In the “Downloads” area near the bottom of the page, you’ll find it in the “Other Downloads” section:

With your iPhone connected to your computer, launch the iPhone Configuration Utility and then click the “Add” button at the top left:

The final step is to click on your device name under the “Devices” section on the left; this will show a list of all currently installed (or added but not yet installed) iPhone apps. Click the “Install” button next to the app you added to the utility:

Finally, XCode provides a convenient method for installing iPhone applications. With the phone connected, open XCode’s Organizer window (Window > Organizer), and look for the name of your device under the ‘Devices’ list on the left. Make sure that the colored indicator is green; if it is not green, powering the iPhone off and on again will usually establish a proper connection.

At this point, you can simply drag the newly built application file and drop it in the ‘Applications’ area at the bottom of the window, and it will automatically install on the iPhone.

Note: if you are repeatedly testing versions of the same application, it is usually a good idea to delete the previous version from the iPhone before each new install, to remove any cached or associated data.

Submitting your App to the App Store

Once you have built and tested your Application with Corona, it’s time to submit it to the App Store. To do this, you will need to access “iTunes Connect” from the iPhone Dev Center. If you are currently browsing the ‘iPhone Developer Program Portal’, you will need to exit the portal and return to the ‘iPhone Dev Center’.

Once you are back in the ‘iPhone Dev Center’, you will need to click on ‘iTunes Connect’ in the right hand column.

If you are planning on releasing your application for free, you can skip ahead.

If you are planning on charging for your application, you will need to agree to Apple’s contracts. To do this, click on the ‘Contracts, Tax, & Banking Information’ link.

When you have read and agreed to the Paid Applications contract, you will need to fill out the necessary banking, contact and tax information. Once you have completed this, you will be able to submit your application for sale.

Now go back to the iTunes Connect screen by hitting the ‘Done’ button.

Once you are there, click on the ‘Manage Your Applications’ button.

From this point you will begin Apple’s ‘Add New Application’ process. Answer the questions appropriately. When you get to the upload section, you will need the following items:

• The application, zipped in an archive.
• A large icon in PNG format, very similar to the normal 57x57 icon, but 512x512 pixels in size.
• At least one screenshot of the application to serve as the primary screenshot
• Any additional screenshots that you may have (up to 4 more)

Note: you should add your application’s icon during the Corona build process by placing the icon file (named ‘Icon.png’ with dimensions of 57 x 57 pixels) in the same directory as all your other code and image assets. The rounded corners and ‘shiny icon’ effect will be added automatically. You can also add an application splash screen by placing a file named ‘Default.png’ (320 x 480 pixels) with your other assets before building.

When you go to upload files, be sure to click the upload button for each, and wait for it to complete before moving on to the next upload. When you have completed this, click ‘Continue’.

The pricing screen will allow you to select the availability of your app as well as the pricing tier. If you have agreed to the contract and filled out the necessary paperwork, you may still get a warning if the paperwork has not gone through yet. That particular process may take several weeks. You will still be able to continue, but your application will not become available until after your contract information has been processed and your application reviewed. You can also specify which worldwide stores you want to make your application available in.

Once you are finished with this stage, hit the ‘Continue’ button to select any additional languages you wish to support.

Hit ‘Continue’ when you have completed this.

You should now see the Review screen. Check over this to make sure everything is in order before submitting your application. If everything is in order, hit the Submit button.

Now your application should be added to the review process! This can take time, so be patient: as of this writing, approvals are often taking around two weeks, but longer delays are definitely not unheard of. Apple has strict guidelines on what they will allow into the app store, so don’t be surprised if you have to make changes to get your application published. If you don’t feel that you have received enough guidance regarding the changes they want, you can try writing back to ask for further detail.

To learn more about Apple’s design philosophy for mobile applications, consult their Mobile Human Interface Guidelines on the Apple developer portal: