HTML5: debugging the offline application cache on Safari Mobile

Sometimes the cache manifest file doesn't work. More specifically, this HTML5 feature seems to have some problems on mobile browsers. The reason is pretty simple: mobile browsers are different from desktop browsers in the sense that they offer limited functionalities to web developers. Fortunately, there are a couple of solutions you can adopt to fix these problems.

Incorrect content type

The first thing you have to check is the correct mime type for the cache manifest file. The content type must be text/cache-manifest. Add the following line to your .htaccess file if your web server doesn't support this content type:


AddType text/cache-manifest .manifest

Wrong file name

On Safari Mobile the name of the file must end with the extension .manifest. All other extensions, such as .cache are ignored.

HTTP errors

Make sure that all the files listed in your manifest file can actually be fetched by the browser. If your server returns an HTTP error, then the caching process will fail under the hood.

Media elements

There's no actual problem with images but some problems may arise with videos, especially on Safari. For example, if you embed a YouTube video using the default Google's embedding markup and then you specify the URL of the video in the NETWORK section of your manifest file, Safari will return an error when you launch your app offline, for example after adding it to the home screen.

You can try to fix this problem by using the HTML5 video element:


<video src="videos/video.mp4" controls></video>

Caching a video in the manifest file is possible:


CACHE MANIFEST
# Version 1

CACHE:
videos/video.mp4

On Safari this works when you're still online, but when you launch your app from the home screen your video will be disabled by the browser due to a recent modification in the handling of web apps which now are treated as native apps.

Updating and reloading cache

Apple's documentation states that:

Important: You must modify the manifest file to trigger a cache update. Changing the HTML file that declares the manifest has no effect on users returning to your site unless you change the manifest file as well. If the manifest file is unchanged, the HTML file that declares the manifest is loaded directly from the cache.

This is a manual update. You can also use the JavaScript APIs for that purpose:


function updateSite( event ) {
    window.applicationCache.swapCache();
}
window.applicationCache.addEventListener( "updateready",
    updateSite, false );

However:

Note: Using JavaScript to add and remove resources from the application cache is not supported.

The official Apple's documentation on the DOMApplicationCache can be found here.

Articles