Html5 Native App Part Three

This is the third installment of our tutorial on building a native mobile app using web technologies. We have been building a simple photo gallery app using images from the Tumblr microblogging service. In part one we built the user-interface framework, and in part two we built the touch-enabled photo gallery.

http://goo.gl/vJMcC

The demo from part two can be tested using your web browser, or by scanning this QR Code with your smartphone. All three menu items are now working, including the "Reading Cats Gallery" which was implemented using the Photoswipe library.

In this post we'll be using Cordova to package our project as a native Android app.

Game Plan

  • Introduction
  • Installing Cordova
  • Cordova-izing Our App
  • Emulating for Android
  • Adding Native Functionality
  • Adding a Cordova Plugin
  • Uploading to the Google Play Store

Things get complicated, so hold on to your cats! I've listed some alternative and potentially simplier approaches in the conclusion.

Introduction - From PhoneGap to Cordova

This post is three years late. My interest in HTML5 native apps is re-kindling. ;)

In earlier posts I mentioned that we'd be using PhoneGap to convert our MeowReader HTML5 app into a native app. Since I wrote those earlier posts PhoneGap was purchased by Adobe, with the core technology becoming the open-source Apache Cordova. Cordova is a framework and API for creating cross-platform native HTML5 apps.

In this post we'll start with the app developed in part 1 & part 2 and we'll compile it into an Android app. Then we'll deploy it to the Google Play store.

If you have an Android device install the sample MeowReader app now.

Installing Cordova

The installation of Cordova will be different depending on your OS. I used a Windows 8 laptop with the Cordova Command Line Interface (CLI).

Regardless of the OS the following will need to be installed and configured.

OS Specific Installation Instructions:

The MeowReader HTML5 App

The app we've been working on is a combination of HTML, CSS and Javascipt files. Since last time, I've upgraded to a newer version of Photoswipe, but the core functionality is the same. The app pulls images from my Meow Reader Tumblr making them available in a swipeable image gallery.

The code is available as Open Source on GitHub.

Preparing the App for Cordova

1) To create a native Android app the first step is creating a cordova project. From the command line:

cordova create meowreader com.stungeye.meowreader MeowReader

This will create a skeleton Cordova project in a meowreader folder.

2) We then add the Cordova Device plugin:

cordova plugin add org.apache.cordova.device

Only required if you wish to use the device api.

3) Place our app files (index.html, css folder, js folder) in to the meowreader\www folder. Ensuring that our index.html file includes the following script tag:

<script type="text/javascript" src="cordova.js"></script>

Testing Using an Android Emulator

1) From the command line again, add project support for the Android platform:

cordova platform add android

You may need to following the Cordova Android Platform Guide to ensure that all your tooling is properly configured.

2) Fill in the core configuration elements in the config.xml file found in the project root folder. Config.xml Documentation

3) Test the application using the stock Android emulator:

cordova emulate android

I prefer to use the GenyMotion Android Emulator, which needs to be used like this:

cordova run android --device=device-name

The device name can be found once a GenyMotion emulator is running using:

adb devices

Adding Some Native Functionality

Our Meow Reader app doesn't require any native functionality, but imagine we wanted to make use of the device's back button. This is something we normally cannot access from an HTML 5 app. In our Javascript setup code we could add the following:

document.addEventListener("deviceready", onDeviceReady, false);

function onDeviceReady() { 
    document.addEventListener("backbutton", backKeyPressed, false);
}

function backKeyPressed() {
   console.log("The back key was pressed!");
}

Adding a Cordova Plugin

Extra native functional can be added to a Cordova app through plugins. If, for example, we want our app to be able to detect a network connect we'd install the Connection Plugin:

cordova plugin add cordova-plugin-network-information

Our Javascript can now perform network detections:

function network_is_present() {
    return navigator.connection.type != Connection.NONE;
}

If navigator.connection isn't working you may have to apply the Android specific config.xml tweaks described here.

Take some time to explore what's available in the Cordova Plugin Ecosystem.

Google Play Store

Our final task is deployment of our Android application to the Google Play Store.

1) Before you deploy you'll need to produce the Play Store Required Graphic Assets, such as app screenshots, app store icons, promo & banner graphics.

2) Your app will also require launcher icons. These will be used as the app icon once it has been installed on an Andoird device.

I built my icons using the Android Asset Studio Tools, placing the generated mipmap folders into meowreader\platforms\android\res and adjusting the AndroidManifest.xml file:

<application android:hardwareAccelerated="true" android:icon="@mipmap/ic_launcher" android:label="@string/app_name">

3) Android requires that all apps be digitally signed with a certificate before they can be installed. Android uses this certificate to identify the author of an app.

I followed the official instructions on manually creating a keystore/private key.

I then added a ant.properties file to the platform\android\ folder:

key.store=/Users/username/Documents/my-release-key.keystore
key.alias=meowreader

Details here.

Don't lose this keystore! You can't upgrade your app without it.

4) Build the signed application (APK) file from the command line:

cordova build android --release

5) Create a developer account for the Google Play Store and add a new app (with the assets from step 1). Lastly, upload the APK file from step 4 to the APK section of the Play Store app listing.

Conclusion

And so ends part three of our HTML5 native app tutorial. I hope you found it helpful. Follow me on Twitter if you want to hear about future tutorials. Don't forget to install the demo Meow Reader app from the app store.

I've described but one way to build a Cordova application, one that depends heavily on command line tools. If you aren't comfortable at the command line you might want to look into Adobe's PhoneGap Desktop app or their paid PhoneGap build service.

Since deploying the Meow Reader application I developed and deployed a second HTML5 app to the Android store, the Winnipeg New app. If you live in Winnipeg and are interested in learning more about Cordova, check out the Winnipeg Android Meetup on June 23, 2015.