PhoneGap Tutorial 1 Push Notifications documents the end to end release for a push notification Adobe PhoneGap application and release to iOS and Android. This guide will be especially useful for those of you just running PhoneGap on windows without access to an Apple Mac.
I will be aiming to release a series of PhoneGap tutorials and cover many topics.
The second part of this tutorial will cover all the code changes and configuration for push notifications to work.
Please note this tutorial is quite detailed therefore you should allow 2 hours for each part of it. If you have any questions please add to the comments below or drop me a message using the “Offline Send us a message” tab at the bottom of the page and I will answer as soon as I can, or if I am on-line this will be shown.
If you find this tutorial useful please comment and share, for information on future tutorials please subscribe to my blog at the bottom of the screen, and good luck with the tutorial!
NOTE: The source code for all our tutorials is available on public repositories via BitBucket and Git. The source code for this repository can be downloaded via a git shell or terminal (Linux) using the below command
git clone https://firstname.lastname@example.org/gothailand/push-tutorial.git
- The client will be on either iOS or Android device and the PhoneGap test server a windows based machine, using a cloud server is advisable or you will need to configure a machine on your internal network to be accessible externally.
- The Windows machine that runs the PhoneGap developer server must be Internet facing and accessible by the mobile test devices.
- For releasing an iOS app an iOS developer account is required, you can enroll here as an individual or company https://developer.apple.com/programs/enroll/ the cost at the time of writing is $99 annually for an individual account or $299 annually for an enterprise account.
- For releasing an Android app a Google Play Store developer account is required, you can enroll here for a one off cost at the time of writing of $25 https://play.google.com/apps/publish/signup/
- An Adobe PhoneGap build account, the free account allows you to maintain and build one PhoneGap application, this is adequate for this tutorial.
- For push notifications a Google account registered with Firebase
Out of scope
- Configuration Management – I would recommend using github or BitBucket to maintain your code although I will cover that in a separate tutorial. BitBucket may be the best starting out as this allows Private repositories on the free account.
- Cordova command line implementation using npm and nodejs – it is also possible to write, build and test your app without PhoneGap developer giving access to a wider choice of plug-ins etc but this is a little more complex and requires an Apple Mac system to build the iOS version. I may also cover the PhoneGap CLI on Linux and Mac OS in other tutorials (subscribe to my blog for updates)
- Install the required PhoneGap developer/test software on your Windows machine and mobile device.
- Create an outline “Hello World” application and test this on your PhoneGap developer application
- Create required Android and Apple signing keys required to create release versions of your application
- Package and build the binaries using Adobe PhoneGap build
- Release the application to the App stores
- Add Push notification to the code, test Push Notification via Firebase Cloud Messaging and the Postman API application
Install all required software
- PhoneGap developer
The latest releases for PhoneGap developer can be found at https://github.com/phonegap/phonegap-app-desktop/releases
This will be required for testing of the Push Notifications to the mobile devices you can download here https://www.getpostman.com/
- Open SSL-32
This will be required for certificate generation, the software is available at https://slproweb.com/products/Win32OpenSSL.html
Once installed Modify the following environment variables in Control Panel -> System -> Advanced System Settings (Advanced Tab -> Environment Variables)
System Variables -> New ‘OPENSSL_CONF’ set to C:\OpenSSL-Win32\bin\cnf\openssl.cnf (or the location you installed Open SSL)
Mobile Device Software
- PhoneGap Developer
This is the mobile client software that allows us to test the application without going through the full build release process, it is available on the Apple App Store or Google Play just by searching “PhoneGap Developer”
Create our base application
Now we have all the relevant software installed we will create our base application on PhoneGap.
- Start PhoneGap developer on windows and you should see the following screen
- Click on the (+) button and select “Create New PhoneGap Project” and select the “Hello World’ Template
- Configure your application as below
C:\repository is where I am going to store all my PhoneGap code, Push Tutorial is the title of the application and I have created a unique application identifier, this is important once we release our app to the store.
- The application should now be running and accessible by the mobile developer app, I am going to do one more thing which aids in the build and release process. This is move the config.xml from the application root directory to the ‘www’ directory. When we make PhoneGap releases we only have to upload the compressed www directory not the full PhoneGap directory. So firstly stop the application running using the square stop button.
- Move the config.xml file from the C:\repository\Push Tutorial directory to the C:\repository\Push Tutorial\www directory and restart the PhoneGap developer application with the green ‘play’ button.
A quick word on the directory structure (below)
The hooks, platforms and plug-ins directories are directories created by the PhoneGap developer app to emulate the application and we do not need to touch these, the only directory we are now concerned with is the the www directory, this contains all our code and will be the directory that we zip up to make our release to Adobe PhoneGap.
Test our base application
- You should now have PhoneGap developer installed on your Android or iOS device, start the application and then change the server name (using port 3000) to match the DNS of your externally accessible machine that has the PhoneGap server running on it. You may need to create firewall rules in windows and your cloud provider configuration to allow access to this port on your machine.
- Clicking connect should take a little while for the app to download an then execute. Two screens will be displayed as below, the first as the device is loading the application the second once the device is ready. This is important as there are many development functions that cannot take place until your device is ‘Ready’ such as Push Notifications.
You have now created and launched your first PhoneGap application, one final useful thing worth noting is the ability to debug your code using the ‘Server Log’ of the PhoneGap developer application. If you click the ‘Terminal’ type icon in the application (below) you can view important activities of your application. In the example below you can see and ‘appzip’ was downloaded by your device and also the application has issued a console message of: Device Ready.
Create Store Applications and Signing Keys
Application signing keys are required for any iOS release, these can be generated using XCode on a Macintosh but also there is a process for doing this in Windows that I will detail. Android also requires signing keys for any Production release to the store.
iOS Certificates and App ID registration
- Create an iOS distribution Certificate at https://developer.apple.com/account by selecting the option below
Then select certificate Production, and (+) to add the certificate
- Select Production -> App Store and Ad Hoc and ‘Continue’
You will then get a page about generating a ‘csr’ file in order to generate a certificate, we will do that next for the moment just click ‘Continue’
- We need to generate a ‘key’ file and ‘csr’ file these are both required during the key generation process, open up a command prompt and change to the bin directory of your Open SSL installation.
- Issue the below command to generate the ‘key’ and ‘csr’ files
openssl req -nodes -newkey rsa:2048 -keyout private_key_push_tutorial.key -out cer_sign_request_push_tutorial.csr
- Configure your certificate as below, you can use the values relevant to you, the only important thing is note the password we will use this later on
If you do a ‘dir’ in the bin directory now you will notice a new ‘csr’ and key files. I like to maintain these keys in my code releases so create a ‘keys’ directory in your phonegap structure and place the new key files in there, these can then be maintained in your configuration management choice.
- Now we have a ‘csr’ file we can generate the iOS distribution certificate. Select ‘continue’
- You will now have the option to download your distribution certificate, again save this into your project ‘keys’ directory keeping the default name ios_distribution.cer
- To get our final.p12 key file for the Adobe PhoneGap build we need to issue 2 more commands to generate the .p12 file, open up a command prompt and change directory to your application ‘keys directory
C:\OpenSSL-Win32\bin\openssl x509 -in ios_distribution.cer -inform DER -out app_pem_file.pem -outform PEM C:\OpenSSL-Win32\bin\openssl pkcs12 -export -inkey private_key_push_tutorial.key -in app_pem_file.pem -out ios_dist.p12
The first command generates a .pem file from the distribution certificate we created, the second command a .p12 key file (note you need to use the password set when generating the key file) you should then see the below files
- We will also need a provisioning profile for the PhoneGap build deployment. From the certificates left hand side menu select ‘Provisioning Profiles’ and Distribution. Then (+) to add a provisioning profile.
- Select Distribution -> App Store and ‘Continue’
- Select the App ID of the one we have created as below and continue
- You will now be at a select certificates page, you need to select the distribution certificate that we created in the first set of steps, also it will have todays date on it as the options are all dated. Once you have selected the correct distribution certificate ‘Continue’
- Name the profile as below then select ‘Continue’
- The next page you will get an option to download the profile, save this profile to your ‘keys’ directory in your application folder and select done, your provisioning profile page should now look like below.
- We now have a .p12 file and Provisioning Profile for the Adobe PhoneGap deployment. Also while we are here we will generate our .p8 certificate, this will be required for registering Push Notifications on Firebase later in the tutorial. Firstly select ‘All’ from ‘Keys’ then (+) to add your new key
- Set the ‘Key Description’ and select the APN’s check box only, then ‘Continue’ and ‘Confirm’ the key generation
- You will now be given the option to download the key, again save this to your ‘keys’ directory for your application, also note the Key ID, this is important and will be required when setting up Push Notifications in Firebase.
- Before creating your application you first need to register the application with the App Store. Select Identifiers -> App IDs and then (+) to register your new App ID
- Enter your App ID Description and it is important to take note of your Team ID (App ID Prefix) this will also be required to register for Firebase Cloud messaging. Also set the explicit App ID to the value when creating your PhoneGap project earlier. Within the ‘App Services’ ensure ‘Push Notifications’ is checked then select ‘Continue’ -> ‘Register’ -> ‘Done’
You should now have all the iOS certificates you need and a register iOS application, you can now create the application in itunesconnect.
iOS App Store Application creation
- Log into https://itunesconnect.apple.com/ with your Apple developer account
- Select ‘My Apps’ from the home screen then ‘+’ -> ‘New App’
- In the ‘New App’ screen create the values as below
Note: The bundle ID is the same as the App ID we created in the previous section, also the SKU can be anything unique, so for the case of this I am using the bundle name as that should always be unique.
Your iOS app now is almost ready for submission, you just need to populate all the App data, provide screen-shots as per Apple dimensions, add descriptions etc. I won’t go into detail of that in this tutorial but it is all fairly self explanatory. The better information you give the more likely your app is to be accepted after review by Apple. We also need to attach the generated binary but we will do that once we have generated it through Adobe PhoneGap build.
You can enter information in here and use ‘Save’ prior to submitting the app for review once the binary is added.
To generate the Android release certificate we need to use the java utility ‘keytool’ this should already be in your path so using a command prompt just change to your applications key directory and execute the below command.
keytool -genkey -v -keystore android_rel.keystore -alias android_rel -keyalg RSA -keysize 2048 -validity 10000
It is important to make a note of the keystore alias you use here and also the password you set. You will also need to populate some information the same as the Apple key generation, I entered mine as below.
This will generate and android_rel.keystore file that along with the alias and the password will be required by Adobe PhoneGap build.
Android App Store Application creation
- Login in to the publishing area of the google play store at https://play.google.com/apps/publish and select “Create Application”
- Populate the create application prompt as below
- Similar to Apple in the ‘Product Details’ screen you can populate all your information and choose to ‘Save as Draft’ prior to us generating the binary using Adobe PhoneGap build.
We are now in a position to generate our application binaries to upload to the store. We have created the required key files for Adobe PhoneGap build (android_rel.keystore and ios_dist.p12) we have create the outline apps on the 2 app stores and we have a working hello world app that has been tested on PhoneGap developer.
Generate Binaries using Adobe PhoneGap Build
- Firstly we need to create a zip archive of our code in the ‘www’ directory, I use the 7zip utility to do this, please see screenshot below.
- We should then have a www.zip file in our application directory this is the file we will upload to PhoneGap build.
- Open and sign in to the Adobe PhoneGap build site at https://build.phonegap.com
- In the ‘Apps’ menu select ‘+ new app’
- At the next screen select ‘Upload a zip file’
- select the www.zip file that we created in step 1 and then the zip will be uploaded and you will be presented with the application overview
- We are almost ready to build the app but first we need to upload the keys we created earlier and unlock them. From the profile menu we need to select ‘Edit Account’
- In ‘Edit Account’ select the ‘Signing Keys’ tab, then ‘Add Key’ from iOS
- We will name our key ‘Push Tutorial’ and we will need to specify the .p12 key file and the provisioning profile we created, these should be in your application ‘keys’ directory. Now ‘Submit’ your key.
- You now need to unlock your key by clicking on the ‘lock’ icon and entering the password you used when generating the Apple key file in the section above.
The lock icon should then go into an ‘unlocked’ state
- Now we need to add the Android key and populate the details as below using the password and alias from when we generated the Android keys selecting the android_rel.keystore file from our ‘keys’ location, then ‘Submit’ the key
- Then we need to ‘unlock’ the key using the password we used when generating the keys in the Android section above – these should be the same in our case ‘anypassword’ then ‘Submit’ and your key should be unlocked.
- If you go back to your ‘Apps’ section you should be ready to ‘build’ your application, select ‘Ready to build’
- On the first run you will get an error on your iOS build but your Android and Windows app will build, we need to select the keys to use to make the Production builds (Don’t worry too much about the Windows build we will remove this build during the Push notification code changes)
Select your keys as below and the iOS and Android apps will automatically start rebuilding
Once the apps have rebuild your applications should look like this
Now lets download the application binaries and put them in a new folder called ‘release’ in our application directory, you just need to click on the blue ‘ipa’ and ‘apk’ button to download the binaries.
We are now ready to upload our binaries to the stores and Submit our applications for review.
Release binaries to the App Stores and Submit for Review
We are now in a position to submit our apps to the store, I will go through the Android process first as the iOS release will require a little intervention from a Mac Owner, unfortunately this is the only step that does require a Mac, but all is not lost I have a solution for you!
Android App Store Release
- From the Google Play Store select ‘App Releases’ then ‘Manage Production’
Then select ‘Create Release’
- In the new release to production screen Enable Google Play App Signing if prompted
Then select ‘Browse Files’ from the ‘APKs to Add’ section
Select your .apk file from your application ‘release’ directory and upload it, you should then see the APK information below the Browse section
iOS App Store Release
Unfortunately this is the only area we will need access to a Mac to upload the binary to iTunesConnect so we can add it to the release and submit for review.
You will need to download ‘Application Loader’ from the App Store or initiate it through XCode and upload it through the menu option
XCode > Open Developer Tool > Application Loader
Alternatively I am happy to do this for a small ‘beer money’ donation 🙂 and much cheaper than some Internet sites out there advertise!
If you make a $10 donation to my paypal account I will upload an ipa file to your iTunesConnect account 5 times, you can make a donation safely using the paypal link below, once you have made the payment please email email@example.com and attach your .ipa file and your iTunesConnect login details, also include the id you made the paypal payment with if it is not the same as the email address you send the .ipa from. All requested uploads will made within 12 hours.
A lot of work has gone into this series of tutorials so donations do not hurt the cause of me adding to the series 🙂
If you have any queries around this process please contact me online by using the “Support Agent Online” tab at the bottom of the page.
Many thanks for contributing!
Once the .ipa file is uploaded you need to add it to your build you are going to submit. The submitted ipa will appear in the below box and then you can use the ‘Submit for Review’ button. There may be a couple of other application fields you need to populate but that should be self explanatory during the submit process, an Apple review usually takes in the region of 24 hours and they will reply with either Approved or the reasons they have rejected the application and you will need to go through the submission process again.
Please continue to the second tutorial that builds upon this basic application to implement Push Notifications using Firebase.