iOS delivery
In this TechNote, we'll cover what you need to do to submit your app to Apple's iOS App Store.
Apple is concerned that apps in its store work as described and do not cause any security risk. They also care that the apps provide some unique functionality and follow their [http://developer.apple.com/library/ios/#documentation/UserExperience/Conceptual/MobileHIG/Introduction/Introduction.html Human Interface Guidelines]. The results have been good: Apps in the iOS App Store are usually pretty good, and the store is now one of the largest software resellers on the planet.
The method used will be to take an AppStudio app, use PhoneGap Build to produce a .ipa file, then submit that to Apple.
You can use this procedure for any AppStudio project. It will also work if your project uses the [http://docs.phonegap.com/en/2.9.0/index.html PhoneGap API]. It will not work if you are using third party PhoneGap plug ins: for those, you will need to use the PhoneGap SDK method.
Start by testing your app as much as possible while it is still a web app. It will be much easier to make changes, fixes and improvements at this stage.
Beginning May 1st 2013, apps submitted to the Apple App Store…
1. must be built for iOS devices with Retina display and iPhone apps must also support the 4-inch display on iPhone 5
2. will no longer accept new apps or app updates that access UDIDs
Cordova/PhoneGap fulfills requirement (1) since version 2.5.0 and fulfills requirement (2) since version 1.7.0.
For security purposes, Apple has a strong signing process. This involves certificates which identify the developer, which need to be included in the build process. Apple issues these certificates as part of its developer program.
Apple has good instructions on its website about its policies, procedures and how to get the certificates. This is probably the most complex and confusing part of submitting an app, so it's good to pay attention carefully. Don't be discouraged: hundreds of thousands of developers have gone through it successfully.
You will need a Mac to do this and have XCode installed. You can download XCode from the [https://developer.apple.com/devcenter/ios/index.action iOS Developer Center].
Enroll as [https://developer.apple.com/programs/ios/ enroll as an iOS Developer] to submit apps to the App Store. It costs $99.00 USD per year.
Sign on using your Apple ID and go into the [https://developer.apple.com/account/overview.action Certificates, Identifiers & Profiles.] You'll see tabs under iOS. Your account needs to have admin privileges.
These are the important ones for AppStudio developers:
The Development certificate identifies you and your development computer. Start by clicking on the Plus (+) button to add a new certificate.
Choose ''iOS App Development Certificate''.
Instructions will then display telling you how to create a CSR file. Go ahead and do it. The next screen uploads the CSR file - do that as well and click Generate. It will take a few minutes to generate the file. You can do a refresh of your browser to see the status of the request.
Once the file is generated, Apple's website will instruct you to download the certificate. Double click on it to install it in your keychain.
Next, choose App IDs in the Identifiers section. Click on the Plus (+) to add a new App ID.
For App ID Description, enter the short name of your app. You will want to use this consistently.
Don't check anything in App Services for now.
For App ID Suffix, choose '''Explicit App ID'''. The Bundle ID should be your domain name (in reverse) followed by your app name.
com.nsbasic.sampleapp
If everything is correct, Submit it.
Next, set up the list of devices you will be using. This list will be built into the Provisioning Profile. Your test build will only run on the devices listed. You can list up to 100 devices. They can be iPod, iPads or iPhones.
It will ask you to Assign a new Apple Device. This is the device you will use for your testing. You will need to enter a description on the device ("Bill's iPhone 5") and the Device ID. Get the Device ID (UDID) from iTunes with the device plugged in. In the Summary screen, click on "Serial Number" and it will change to "Identifier (UDID)". Right click on it to copy it and paste it into the Devices screen.
A Provisioning Profile is a file which tells iTunes which devices your app may be installed on. A Distribution Provisioning File is used for the App Store. Use a Development Provisioning File for testing.
To create one, go into Provisioning Profiles and click on the plus ("+") button. Choose '''iOS App Development''' for testing. Your App ID should show up on the next screen - click on Continue. Next, select your Certificate, then the devices to be included (there is a handy Select All button). Finally, give the profile a name like sampleapp.development. The Provisioning Profile is then created and you can download it.
[http://Https://build.phonegap.com PhoneGap Build] is a web service which takes your project and returns a file which can be uploaded to the App Store.
To use it, you will need to create your own account with them. They have both a free and a paid plan. For a single project, PhoneGap Build is free.
Once you have the account, enter its name and password into Preferences.
One of the project properties is named configxml. This is used to create the config.xml file which is passed to PhoneGap Build. It contains much of the information that PhoneGap Build needs to create your app. The default configxml file will work, though you may wish to do some customization. It's worth consulting [https://build.phonegap.com/docs/config-xml PhoneGap's config.xml documentation] to see all the options.
Here is the default config.xml:
<?xml version="1.0" encoding="UTF-8"?>
<widget
xmlns = "http://www.w3.org/ns/widgets"
xmlns:gap = "http://phonegap.com/ns/1.0"
id = "com.nsbasic.{id}"
version = "{version}">
<name>{title}</name>
<description>{description}</description>
<!-- Icons: Expand this section with sizes for platforms you are targeting.-->
<icon src="{icon}" gap:role="default" width="57" height="57"/>
<preference name="splash-screen-duration" value="2000" />
<gap:splash src="{splashscreen}"/>
<!-- Platforms: Uncomment this section and customize as needed.
<gap:platforms>
<gap:platform name="android" minVersion="2.1" />
<gap:platform name="webos" />
<gap:platform name="ios" />
<gap:platform name="symbian.wrt" />
<gap:platform name="blackberry" project="widgets"/>
</gap:platforms> -->
<!-- sample feature specification -->
<!-- <feature name="http://api.phonegap.com/1.0/network"/> -->
<!-- sample preference specification -->
<!-- <preference name="autorotate" value="false" readonly="true"/> -->
<!-- <preference name="orientation" value="default" > -->
<!-- <preference name="fullscreen" value="true" > -->
</widget>
Field with are surrounded by brackets, like {version}, are automatically filled in by AppStudio from the other information in the project.
A full set of icons will include the following square images, in png or jpg format. For example, 29.png is a 29x29 png format image.
29.png 48.png 57.png 58.png 64.png 72.png 76.png 114.png 120.png 144.png 152.png 320.png 1024.png
Here is which ones need to be included in your build. This goes into config.xml: Note how the icons are organized in an icon folder.
Set these files up in an folder, structured like this:
icons
ios
57.png
72.png
114.png
144.png
Add the folder name, icons, to manifest in Project Properties.
If you do not supply an icon, the default AppStudio icon will be shown.
The following files are needed (.png also OK)
iPhone and iPod: 320x480.jpg 480x320.jpg 640x1136.jpg 1136x640.jpg iPad: 640x960.jpg 768x1004.jpg 960x640.jpg 1024x748.jpg 1536x2048.jpg 2048x1536.jpg
Here are the lines you need in configxml:
Set these files up in an folder, structured like this:
splash
ios
320x480.jpg
480x320.jpg
640x1136.jpg
1136x640.jpg
(etc...)
Add the folder name, splash, to manifest in Project Properties.
According to Apple's application guidelines, a tablet (iPad) application should not hide the status bar while a handheld (iPhone) application should hide status bar.
The above dimensions are assuming that you have chosen to follow this recommendation. If you choose a different path, then you should increase or decrease the image height based on the size of the status bar.
An iPhone app should include one launch image in portrait orientation; an iPad app should include one launch image in portrait orientation and one launch image in landscape orientation.
If you do not supply a splash screen, the default PhoneGap splash screen will be shown.
To properly build for the App Store, PhoneGap Build needs the Certificate and Provisioning file. To set them up, sign into PhoneGap Build using your ID, then go into [https://build.phonegap.com/people/edit Edit Settings]. Choose the Signing Keys tab.
For '''Title''', enter the name of your app.
For '''Certificate''', select your .p12 file. To get the .p12 file, go into Keychain Access on your Mac and do the following:
Before it exports the .p12 file, it will ask you to provide a password. Remember this: PhoneGap will need the password to unlock the certificate.
For '''Provisioning Profile''', select your .mobileprovision file.
The settings screen will display a lock icon beside your newly created key. Click on the lock, and it will ask you for the certificate password. This unlock will expire, so you will need to unlock it again from time to time.
An AdHoc Build can only be run on designated devices. It is designed for testing, not for release.
- In AppStudio, choose "Build Native App with PhoneGap". This will upload your app to PhoneGap's servers so it can be packaged.
- Log into PhoneGap Build and choose your app. It should have an error box beside the iOS build status. The problem is that the signing key hasn't been chosen yet. Do so from the picker that appears.
- You may see a 'locked' icon as well. If so, click on it. It will request your certificate password and unlock it for one hour.
- Choose 'Rebuild' and wait a minute or two. The ipa file should now be generated: you can download it.
- To run the ipa file on your device, drag it into iTunes and sync. It should be installed and appear on the Home screen.
- If the app is already installed on the device, you will have to delete it from the device before syncing the app.
[https://itunesconnect.apple.com/WebObjects/iTunesConnect.woa iTunes Connect] manages your apps in the App Store. There are a number of steps that need to be done in it before an app can be submitted.
There are a number of contracts that [https://itunesconnect.apple.com/WebObjects/iTunesConnect.woa/wo/5.0.9.13.3 need to be agreed to] before you can submit. If you want to sell your app, you also need to supply banking information so payments can be direct deposited. Tax documents may also need to be filed.
Some of this paperwork cannot be done electronically. Expect to spend up to a month completing all of this if you are selling your app.
Other than that, the procedure is straight forward: follow the process on the website.
Use [https://itunesconnect.apple.com/WebObjects/iTunesConnect.woa/wo/2.0 Manage Your Apps] to add, view, and manage your App Store apps.
Before adding an app, collect the information you will need for it. Some of the fields you need to enter can only be set up when adding a new app: they cannot be changed later. Other fields can be changed later, but will trigger a review of your app. There are helpful prompt icons beside each field to help you with the input.
For more information on setting up fields, read "[http://developer.apple.com/library/ios/#documentation/LanguagesUtilities/Conceptual/iTunesConnect_Guide/8_AddingNewApps/AddingNewApps.html#//apple_ref/doc/uid/TP40011225-CH13-SW1 Adding New Apps]".
The Bundle ID Suffix should contain your company name and the app name:
com.nsbasic.Project1
This needs to match the id field in the configxml project property. If the project's name is Project1, it will look like this:
id = "com.nsbasic.{id}"
- From your Version Details page, click the Ready to Upload Binary button.
- Follow the instruction on the screen.
- When complete, you will be able to upload the binary using the Application Loader.
- If you want to upload again, you will need to repeat these steps.
Before you can upload, you need the Application Loader. You will only need to do this the first time.
- Log in to http://itunesconnect.apple.com
- Go to "Manage Your Applications"
- Use "Download Application Loader" link at the bottom of the page to download, then install.
- Start the Application Loader
- Log on with your Apple ID.
- Click on Deliver Your App. The Application Loader will check with iTunes Connect to see if any apps are "Waiting for Upload", and display a list. Select the correct one.
- Select the ipa file on your system when it asks you for it.
- Application Loader with then perform a series of tests on the file. If it passes, the file will get uploaded to iTunes Connect.
- The status in iTunes Connect will change to "Waiting for Review".
- A week or so later, expect an email from Apple either saying the app is approved or with a list of issues to correct.