Running iPhone Webapps From the Home Screen Only

Webapps are essentially applications that run from a web browser and are typically served from a controlled environment. We are all familiar with GMail, Google Maps, Pandora, and other great examples of web applications. In the context of mobile devices webapps can run entirely from the device. You can also choose to host data remotely and store the code in the device, or the other way around.

Whatever modality you choose, Safari iPhone allows you to save a shortcut of your web page and open it directly from the home screen. iPhones, iPad and iPod Touch users are familiar with the “Add to Home Screen” option. The importance of this feature is that helps webapps to look and feel like native applications. Although native apps are more responsive to the user’s input, with appropriate settings your webapp will not envy anything from a native iPhone application.

Here are some of the things you will need to do to assure a seamless transition from pure web application to iPhone webapp:

Prevent the page from zooming

By default the iPhone renders regular web pages inside a view port that is 980 pixels width. The native resolution of the device is 320px width by 480px height and pages larger that that are proportionally scaled. You can control the way Safari handles the browser’s viewport by adding the following meta tags to the HEAD tag of you HTML code:

1
2
3
4

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

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

As you can see these tags will instruct Safari about how do you want the page to be rendered. If you prefer you can also combine all the settings in one single tag:

1
2
3
4
5
6

<meta
    name="viewport"
    content="initial-scale=1.0;
    maximum-scale=1.0;
    user-scalable=no;
    width=device-width">

<meta
    name="viewport"
    content="initial-scale=1.0;
    maximum-scale=1.0;
    user-scalable=no;
    width=device-width">

Add references to a an icon and your startup application image

If you do not specify an icon and a startup image Safari will make a screen shoot of you page and use it as the icon of you application when users add it to the home screen. Safari will also remember the last screen of you application and use is a initial view every time that you app is opened. To prevent the default behavior you can link to two different files that Safari can use as icon and startup image.

1
2

<link rel="apple-touch-icon-precomposed" href="my-icon.png">
<link rel="apple-touch-startup-image" href="my-startup-image.png">

<link rel="apple-touch-icon-precomposed" href="my-icon.png">
<link rel="apple-touch-startup-image" href="my-startup-image.png">

The size of your icon must be 57×57 pixels and you startup image must be 320×460 pixels (20 pixels are used to display the top status bar with information about the phone carrier, battery, time, etc.). If you use PNG images with the same proportions Safari should be able to re-scale them. If you are planning to use JPEG it is better to stick to the standard dimensions.

Make sure your webapp will only run from the home screen

If you want user to visit use your web application from Safari iPhone, they will need to do the following:

1. Open Safari
2. Tap in the address bar
3. Type-in your application URL (if the remember it)
4. Love your application before decide if it’s worthy to bookmark it or add it to the home screen

I know that the following may sound extreme but what if running your webapp from Safari is not an option? In the case of a native application users do not have the option to run an application unless they download it first. If users really hate the application they will probably to delete it immediately (assuming they did not pay for it). If users kinda like the newly downloaded application the icon will stay in the home for future use.

Many people know about an iPhone application name Torch, a very simple app that turns you iPhone into a flashlight. Torch has one screen with the picture of a flashlight and when you tap on it the screen becomes white; tap again and it will restore the previous screen. Easy, right? No question that this application can be reproduced as a webapp. Now, imagine that you drop your car keys in a parking lot and you need Torch to use you iPhone as a pseudo-flashlight. Remember the list about, if Torch was a webapp you will need to open Safari, think hard to remember the URL of the webapp, type it in the address bar, and pray for your cellphone to have signal at that moment (this is assuming you are not drunk coming from a party).

The point is that the chances of your webapp of being used after the first user’s review are limited by Safari browser. If you provide the same type of experience of the AppStore, meaning that you webapp can only run from the home screen when tapping on its icon, user won’t have to think hard to open that webapp a second time. In short, if your webapp is easy to access, the chances of you application of being open more that once are definitely higher.

Enforcing starting up from the Home Screen

If we detect whether or not a webapp is started from the browser or from the home screen, we can tweak the application to make sure the will only atrt from the home screen. Here is quick recipe:

Detect if the webapp has been opened from an iPhone

You will have to decide what is going to be the behavior when the webapp is opened from a regular browser. I will assume for now that the application must run the home screen only.

This is an easy way to detect the iPhone environment:

1
2
3
4
5

if(navigator.userAgent.indexOf('iPhone') != -1){
    // This the right environment
}else{
    // Display message asking to open the app from an iPhone
}

if(navigator.userAgent.indexOf('iPhone') != -1){
	// This the right environment
}else{
	// Display message asking to open the app from an iPhone
}

Run your webapp in Full-screen

You will need to add an extra meta tag in the header of you HTML page to instruct the iPhone to display the page in full-screen mode.

1

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

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

This only works when that page is loaded from the home button and that is the key. Safari adds an extra property to the browser window.navigator object that specifies whether or not the page is running as standalone (full-screen mode). Your detection code should now look like this:

1
2
3
4
5
6
7
8
9

if (window.navigator.userAgent.indexOf('iPhone') != -1) {
    if (window.navigator.standalone == true) {
        // Initialize your app
    }else{
        // Display a message asking to add the app to the Home Screen
    }
}else{
    document.location.href = 'please-open-from-an-iphone.html';
}

if (window.navigator.userAgent.indexOf('iPhone') != -1) {
	if (window.navigator.standalone == true) {
		// Initialize your app
	}else{
		// Display a message asking to add the app to the Home Screen
	}
}else{
	document.location.href = 'please-open-from-an-iphone.html';
}

Putting everything together

In your webapp is opened from a regular browser you can redirect users to a different page. However, if an iPhone opens the webapp then you can request users to save it to the Home Screen and initialize you application only if the webapp is running in full-screen. The final experience is:

1. First time: users open you webapp from Safari
2. A message indicating to add to Home Screen is displayed
3. If users tap on the plus (+) button, a screen with the custom icon and the title of you page will be displayed
4. If the users choose to add to Home Screen, Safari will close and the Home Screen will be displayed with the icon of of you webapp
5. Users can tap on the icon and run the webapp (that’s what we want!)
6. Next time: Users only need to tap on the icon in the Home Screen and the custom startup image will be displayed while the webapp is loading (voila!)

Sample Code:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

<html xmlns="http://www.w3.org/1999/xhtml">
    <head>
        <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
        <meta name="apple-mobile-web-app-capable" content="yes">
        <meta name="viewport" content="initial-scale=1.0">
        <meta name="viewport" content="maximum-scale=1.0">
        <meta name="viewport" content="user-scalable=no">
        <meta name="viewport" content="width=device-width">
 
        <link rel="apple-touch-icon-precomposed" href="my-icon.png">
        <link rel="apple-touch-startup-image" href="my-startup-image.png">
 
        <title>My WebApp</title>
    </head>
    <body>
        <script>
            if (window.navigator.userAgent.indexOf('iPhone') != -1) {
                if (window.navigator.standalone == true) {
                    initialize();
                }else{
                    document.write('<p>Tap the + button and choose "Add to Home Screen"</p>');
                }
            }else{
                document.location.href = 'please-open-from-iphone.html';
            }
        </script>
    </body>
</html>

<html xmlns="http://www.w3.org/1999/xhtml">
    <head>
        <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
		<meta name="apple-mobile-web-app-capable" content="yes">
		<meta name="viewport" content="initial-scale=1.0">
		<meta name="viewport" content="maximum-scale=1.0">
		<meta name="viewport" content="user-scalable=no">
		<meta name="viewport" content="width=device-width">

		<link rel="apple-touch-icon-precomposed" href="my-icon.png">
		<link rel="apple-touch-startup-image" href="my-startup-image.png">

        <title>My WebApp</title>
    </head>
    <body>
		<script>
			if (window.navigator.userAgent.indexOf('iPhone') != -1) {
				if (window.navigator.standalone == true) {
					initialize();
				}else{
					document.write('<p>Tap the + button and choose "Add to Home Screen"</p>');
				}
			}else{
				document.location.href = 'please-open-from-iphone.html';
			}
		</script>
    </body>
</html>

By: Raul Sanchez
Category: How-To
Posted on: Tuesday, January 24, 2012

2 comment

eric Sunday 20th, January 2013 - 10:19:14 PM

Awesome!

Alessio Tuesday 18th, June 2013 - 01:10:01 PM

hi, i want to make my webapp in the Home screen, then the user can browse on the other pages of my website. If the user close and re-open my webapp it shows always the home page! Do you know any meta or other trick to enter on the last page viewed? Thanks a lot!