Building an Offline Mobile Web Application

If you’re interested in building a mobile web application that works offline and is virtually indistinguishable from a native installed application, this post explains most (if not all) of what you need to know. (To see an example of an offline mobile web application, see the post, Porting an AIR Application to HTML.)

What is an Offline Mobile Web Application?

An offline mobile web application has the following properties:

  • It’s written in HTML, CSS, and JavaScript, and it’s served from a web server.
  • It functions without an internet connection.
  • When users save the application to their home screen, they get a custom icon and start-up image (the image that is displayed briefly on iOS while the app is loading and initializing).
  • The application can be updated over the network just by opening it (as opposed to going through an app store).

The Components of an Offline Mobile Web Application

There are four primary pieces of functionality that offline mobile web applications need:

  1. Configuration. For iOS devices, there are a few tags you can add to your application to make it look and act much more like a native application.
  2. Custom icons and start-up images. To fit in with native applications, offline web applications should specify custom icons and start-up images for iOS.
  3. Caching. Offline web applications use the HTML5 application cache to make themselves available offline.
  4. Updating. Offline mobile web applications need to update the local cache when the application has changed on the server.

Configuration

On iOS, you can use several different meta tags to make your mobile web application look and feel much more like a native application. For instance, to get rid of the browser chrome when your application is launched from the home screen (in other words, to tell iOS to use a minimal web control rather than full-blow Safari to display your application), use the following tag:

<meta name="apple-mobile-web-app-capable" content="yes" />

To customize the look of the iOS status bar, you can use a meta tag with the "name" attribute set to "apple-mobile-web-app-status-bar-style". In my HTMLCompass example, I wanted the status bar to be as unobtrusive as possible, so I configured it to be black and translucent like this:

<meta name="apple-mobile-web-app-status-bar-style" content="black-translucent"/>

Finally, it’s important to configure Safari’s viewport using a meta tag with the name "viewport". In order to configure the viewport properly for my HTMLCompass example (including preventing the user from zooming in and out of the application), I use the following tag:

<meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=0"/>

For more information on configuring web applications on iOS, see Apple’s document, Configuring Web Applications. For a detailed description of everything you can do with your application’s viewport, see Viewport Settings for Web Applications.

Custom Icons and Start-up Images

Creating custom icons for your application is an important part of making it look like it belongs installed on a device. It’s not strictly necessary, but default icons (or icons derived from screenshots) will not give your application a high-quality, polished look and feel. (Note that I believe this is currently only supported on iOS devices; Android seems to use your "favicon" as your application’s icon, instead.)

Specifying custom icons is as easy as including one or more link tags in the <head> section of your application. The only trick is to make sure that you specify different icons for different screen resolutions. On iOS devices, that currently means icons for pre-retina screens (iPhone 3G and 3GS), retina displays (iPhone 4 and iPhone 4S), and the iPad. Below are the tags referencing the various icons for my HTMLCompass example:

<!-- Home screen icons -->
<link rel="apple-touch-icon" sizes="57x57" href="icons/apple-touch-icon-57x57.png" />
<link rel="apple-touch-icon" sizes="72x72" href="icons/apple-touch-icon-72x72.png" />
<link rel="apple-touch-icon" sizes="114x114" href="icons/apple-touch-icon-114x114.png" />

Specifying start-up images is almost as easy, however in addition to taking different screen resolutions into account, you also have to take into account different orientations for the iPad (iPhones and iPods can’t start applications in landscape mode). Below are tags referencing the three start-up images I created for my HTMLCompass example (note that I didn’t bother making one for the iPhone 3G or 3GS):

<!-- iPad -->
<link rel="apple-touch-startup-image" href="starts/ipad-landscape.jpg" media="screen and (min-device-width: 481px) and (max-device-width: 1024px) and (orientation:landscape)" />
<link rel="apple-touch-startup-image" href="starts/ipad-portrait.jpg" media="screen and (min-device-width: 481px) and (max-device-width: 1024px) and (orientation:portrait)" />
<!-- iPhone (retina) -->
<link rel="apple-touch-startup-image" href="starts/iphone-retina.jpg" media="screen and (max-device-width: 640px)" />

(Note that the size of these images must be exactly correct for them to function as expected.)

There’s a little more to know about configuring and specifying application icons. For instance, iOS automatically makes your icons appear three-dimensional and glossy by applying filters, however if you decide that you’d rather add such effects yourself, it’s possible to specify that your icons are "precomposed." For more information, see Apple’s documentation entitled Configuring Web Applications.

Caching

Caching your application so that it’s available for offline use is surprisingly easy. You essentially place a manifest file on your server which lists all the files that you want saved to the application cache. Below is the manifest file for HTMLCompass.com:

CACHE MANIFEST
 
# Version: 1.04

CACHE:
index.html
icons/favicon.png

You then need to reference the manifest file in your application’s <html> tag, like this:

<html manifest="compass.manifest">

That’s essentially it. For more information on the syntax of your manifest file (which supports additional functionality), see the cache manifest syntax section of the WHATWG offline web application specification.

Here are three important tips that will make working with cached web applications smoother:

  1. Don’t forget to configure the MIME type on your web server (as described here). If you don’t map the extension of your manifest file to the MIME type "text/cache-manifest," you will not get the caching behavior you’re expecting.
  2. I recommend adding a version comment to your manifest file (see example above). The version comment has no official use, however just making a change to your manifest file will cause your application to be re-downloaded. For example, if I change my index.html page without changing my manifest file, the local cache on the client will not be updated. After changing my index.html file, I can increment the version number in my manifest file which will cause the change to index.html to be picked up.
  3. Once your application has been cached, the development process becomes more difficult. Specifically, after you make a code change, it will not show up in your browser until you update the cache with the new version. Rather than having to make a change to your manifest file in order to pick up your application changes, the best solution I’ve found is to simply change the reference to your manifest file in your <html> tag so that it points to something nonexistent. For instance, when I’m developing, I change the reference to my manifest file to compass.manifest.TODO. That causes a 404 which causes the application to be reloaded from the server rather than loaded from the cache. (The reason I append "TODO" is so I’ll find it while performing one last check of my code before checking it in.)

Updating

Now that you have your application caching, you need to know how to update it. There are four simple steps to updating an offline web application:

  1. Change your manifest file so the browser knows to grab the new version (see previous section).
  2. Listen for an event letting you know that the new version of your application has been downloaded and is ready.
  3. Swap the old version for the new version.
  4. Reload the page (optional).

Telling clients that a new version of your application is ready is as easy as making a change to your manifest file (updating the "version" comment, most likely). In order to be notified of when the new version is downloaded and the cache is ready to be updated, simply listen for the updateready event on the applicationCache like this:

window.applicationCache.addEventListener('updateready', ...);

Inside your event handler, tell the application cache to update itself like this:

window.applicationCache.swapCache();

Updating your application cache is an asynchronous operation meaning
it happens in the background while the old version of your application loads, renders, and executes. That means even though you have just updated the cache with the new version of your application, the user will still see the old version. You can either do nothing (so that users will see the new version the next time they use the app), or you can programmatically refresh the page with code like this:

window.location.reload();

To put it all together, my HTMLCompass example has a function called checkForUpdate which looks like this:

function checkForUpdate()
{
  if (window.applicationCache != undefined && window.applicationCache != null)
  {
    window.applicationCache.addEventListener('updateready', updateApplication);
  }
}

function updateApplication(event)
{
  if (window.applicationCache.status != 4) return;
  window.applicationCache.removeEventListener('updateready', updateApplication);
  window.applicationCache.swapCache();
  window.location.reload();
}

There are several other events thrown by the application cache that you can hook into in order to achieve various functionality. For instance, when your code detects that a new version of your application is available, you may choose to show the user a notification or even a progress bar indicating how much is still left to download. For a full list of application cache events, see the event summary section of the offline web application specification.