Running in 30 mins — 1: Create an iOS app with PhoneGap Build
I’ve been a fan of PhoneGap for quite sometime (circa 2011) but I’ve never felt the need to use the more “restrictive” PhoneGap build… that is until this week.
After my first 10 minutes of reading up on how the tech has matured over the years I realized that it’s quite a quick and strong option especially for those in my current position without access to a Mac with a working iOS environment (longer story).
Who can benefit from this article?
- If you don’t want to go through the unknowns of getting a new environment setup, then PhoneGap Build is going to be for you.
- If you want to get an HTML/CSS/Javascript app running as an app on your iPhone in 30 mins — then this tutorial is for you!
- You need to build a test iOS app but don’t have access to a mac.
- You do not need to push this app to the app store as yet and have access to the devices you want to run the application on
Prerequisites:
This tutorial assumes you already have the following
- Apple Developer account (99 USD/year)
- Basic knowledge of web technologies (HTML,CSS,javascript)
- Ability to use simple online services as well as basic file management and web usage; zipping, uploading etc from a computer.
- Using PATH variable and command line tools.
- A windows/ubuntu machine with a reliable Internet connection
PhoneGap account creation and free-ness
First thing to note, getting your first private app running with PGB (PhoneGap Build) is free! No matter how many builds or which of supported platforms (iOS, android and Windows) you need. You also have unlimited public apps as well. You will have an app size limit of 50Mb and you won’t be able to use private plugins — but this is fine if you just want to get up and running.
Second, account setup is a breeze. Pop over to PGB’s main site and hit ‘Sign In’ at the top right then just use your Facebook or Google account to get up in seconds.
Get your certificates in order!
As with all iOS development, you need to have your developer keys and related certificates etc setup for building and code signing the application.
The PGB interface is going to accept your code (we’ll get to that soon) to build and create an app or each of the target mobile operating systems, however for a successful iOS app to be produced you will need to upload and associate a key with PhoneGap Build.
Note that the following process works for Windows and should also work on Ubuntu.
We’ll need to create a Certificate Signing Request (.csr) first.
This is needed for the next step. You will need to ensure that your windows machine has OpenSSL installed. Ensure that OpenSSL’s bin directory is also in your PATH variable.
Open up a new terminal window and change to a directory to work on the certificates. I’d create a new directory for this work.
Next, create the key we’ll use to get the CSR. Run the following on the command line in the terminal.
openssl genrsa -des3 -out ios.key 2048This generates a key file named “ios.key”. Take note of the password you used to create this file, you’ll need it in a few minutes.
Next we have to create the actual CSR file. Running the following command will generate “ios.csr” using the “ios.key” file.
openssl req -new -key ios.key -out ios.csr -subj "/emailAddress=MY-EMAIL-ADDRESS, CN=COMPANY-NAME, C=COUNTRY-CODE"You will need to set your own email address, company name and country code accordingly. Get a full list of applicable country codes here.
Log into your Apple Developer Portal
You’re going to head on over to the developer.apple.com and login. Let’s get the base stuff setup for your app, if it’s not done as yet.
Create a Developer Certificate.
Hit “+” and enter your information. Ensure you select the “iOS Developer Certificate” option. Follow the wizard, you will need to upload a “ios.csr” file we created earlier as well as set the name and select type as “Developer Certificate”.
Now, download the resulting certificate to our working folder we’ll need it soon. Clicking on the certificate you want to use will give you the option to download. Ensure it is a Developer certificate and not Production.
Create a unique App ID for your application.
Go to the App ID section and hit “+”.
You’ll want to use the reverse domain convention and specify something like “com.auratechtt.limerader” for the Bundle ID. I’m using “com.atsl.lifebot” for this project as the Bundle ID and “SentryTest” as the Name.
Another thing to note about this step is that you will need to specify all the service entitlements for the application. For a new phonegap build application I needed to enable to iCloud service for some reason (there’s an error about an iCloud container if you try to build without it).
I suggest you enable iCloud here and add the iCloud container one time. You will be prompted to create and assign the container once you enable iCloud, just follow the onscreen prompts.
Leave all other services as default.
Add your Device(s) you want to have the development app run on
You will need your device(s) UUID to complete this step. You can get your UUID by following these steps.
Next, we need to register the devices we intend to install the app on. Go to the Devices section and hit “+”. You will need to get the UUID from your device(s) to add them. Assign a name that you’ll remember use and enter the UUID for the device as specified.
Do this for all devices you intend to run the app on.
Get your Provisioning Profile
Next we need to create the Provisioning profile that will be used to sign the app.
Go over the the Provisioning Profile section and click “+”. You’ll need to go through a short wizard and specify the following
- Select the Type as “iOS Development”
- Select the “Developer Certificate” you created and downloaded earlier (It’s important that these match).
- Select the devices you want to run this app.
- Select the App ID that this will be tied to (the one we created earlier)
- Enter the name for the Profile
Once you’ve successfully created the Provisioning Profile, download it to the same folder as the Developer Certificate we downloaded earlier and the “ios.key” file we started with.
Next, we have to convert the Developer Certificate downloaded earlier to the p12 format
Run the following in the terminal window at the location of the directory you downloaded the certificate to (NOTE that ios.key file will need to be in this folder as well). This command will create a PEM file out of our Developer Certificate.
openssl x509 -in ios_development.cer -inform DER -out ios_development.pem -outform PEMNext we want to use the “ios.key” file with the generated “ios_development.pem” file to create the final “ios_development.p12” file
openssl pkcs12 -export -inkey ios.key -in ios_development.pem -out ios_development.p12You will have to enter the original password you used to create the “ios.key” file at this stage. You will then be asked to create an export password for the new “.p12” file and to verify the password. Keep note of this export password, we’ll need it to unlock the keys in the PGB interface before building.
We should now have the following:
- p12 certificate file
- provisioning profile
- the export password for the p12 certificate
Keep these, we’ll need them when uploading the application to PGB.
About app and html structure
SO we have our certificates in order. Now we need to ensure our HTML app has the correct structure. You can use any HTML, CSS, Javascript based application here, however I would suggest you start with a simple app to make sure all is well before trying your more complex application code.
For the structure you just need to ensure two things are there:
- index.html exists in the root of your app and is your starting page
- config.xml is included and has some basic configurations in there
You will need to ensure that your config.xml is structured and filled out correctly.
You’ll need to ensure that the id for the app is filled out correctly based on the id that you created in the apple developer portal (I have “com.atsl.lifebot” set as mine).The rest of the information you can fill out based on what you would like them to be.
There are more items that can be added into here, however this should be the bare minimum.
Uploading and building
Let’s upload our app. Head on over to here after you’ve created your account and signed in to PGB.
Hit the “+ new app” button in the top-right corner and you’ll see your upload options. You can pull directly from your project in Git by connecting your Git account to PGB, or you can just zip your web application’s folder and upload it as a single zip file.
After upload, you should now be presented with the application build screen where you will see your different builds, platforms. You will be able to update your code as well as a few other things from here, the interface is pretty intuitive.
If you ended up on the application list page instead, click on the name of the application you just uploaded and it will take you to this page.
However, we’re not done. We need to add AND unlock the keys to be able to get a successful iOS app build.
Head over to the edit account section by accessing the menu to the top-right of the page. Next click on the “Signing Keys” tab.
Click “add a key” under the iOS section. Enter a title and select the files from your computer in the relevant section for the certificate (.p12 we generated) as well as the provisioning profile (.mobileprovisioning) we downloaded.
Once uploaded, you need to unlock the keys before you can use it to compile the iOS application. Click the lock to the right of the key and enter the export password we set when generating the .p12 file earlier.
Now head over back to the application main page and select the key under the iOS build section. Click rebuild.
Next you want to check your log after the build to ensure all went well. Click on the “Logs” button in the iOS section.
If everything was followed correctly, you should have a message in the log saying “Build Succeeded” and the provisioned devices.
Installing and testing
Now we want to get that app onto our iOS device to test. This is easily done by heading back to the Application Screen in PGB and using the largs QR code for the app, displayed to the right of this page.
Simply open the camera on the iOS device and scan the code. You’ll get the necessary prompts to install the app. Remember this will need to be one of the devices that was added when you created the provisioning profile.
Limits?
Now that you’re up and running, there are quite a bit of different things you’ll potentially want to research and look into. Apart from the limits mentioned already, the main limit I found was that you will need to stick to PhoneGap build compatible plugins.
It should be noted though that the plugins that are PGB compliant are pretty expansive.
Issues?
The only issue I encountered when building this tutorial was the issue I mentioned with the iCloud container needed to be created as an entitlement for the app. You can edit and add this to the App ID linked in your config.xml in the developer portal if you skipped that part.
I easily found this by reviewing the logs after building and doing a little googling.
Hydration?
This is an interesting feature I found that helped me debug and run changes quickly. Once turned on for the app, you don’t need to keep reinstalling after each code update-build cycle. The installed app will automatically pull the updated code to your device and run it.
Once you are happy with the application, you can take of Hydration, rebuild and reinstall the full app.
A word about ##.pgbomit
One of the features included with PGB is the ability to ignore certain directories not needed for building the application. This will reduce the deployed application size.
If you’re like me, you probably like to include “in development” assets and items not needed to actually build the application such as graphics, notes and other artifacts created during the development.
PGB allows you to ignore these directories when building the end app by dropping an empty file with the extension “.pgbomit”. There’s nothing that needs to go into the file or file name, just the extension. Once PGB sees the extension in the directory, it will ignore the entire directory.
Installation and some quirks I encountered
I had some odd installation issues using the iTunes side load method. I’m not sure how to resolve them as I found the scan QR and download method faster and more in line with my workflow.
Like this tutorial?
Hit clap to give me some love! Also check out here to find a listing of similar articles I’m doing. I’ll keep updating as I add new articles in like this.
References:
Here are the reference articles that fed into this should you want to get some more expansive information beyond what was presented here.
