Give Your HTML5 Web Game a Native-like Experience

Without using a wrapper or building an app artifact

by Tommy Leung on February 5, 2020 4 minute read

You can give your HTML5 game developed with a framework like Phaser native-like trimmings on mobile without using a wrapper like PhoneGap, Cordova, or Capacitor.

For access to native APIs unsupported by the browser or deployment to the App Store, you will still require one of the wrappers above.

But if you just want the general look and feel or a quick way to test how your game would look natively without going through the entire build process then there is another way.

In this article we will look at using meta tags like mobile-web-app-capable, viewport, and others as well as a manifest.json to give your mobile web game a native-like experience.

Add to Home Screen

Add to Home Screen has been a feature of iOS since the very first iPhone where you can save a webpage to the home screen and it will appear with an icon like any other app.

It can then be launched in full-screen mode without the Safari UI.

Setting this up couldn't be easier. You only need to add a meta tag to your index.html.

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

Android has a similar feature with a similar meta tag.

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

The only difference is the lack of apple- in the name attribute. While you can do it this way for Android, it is recommended to use the Web App Manifest instead.

A simple manifest.json for games would look something like this.

1
2
3
4
5
6


{
	"short_name": "Zelda",
  	"name": "The Legend of Zelda",
	"display": "fullscreen",
	"orientation": "landscape"
}

Then add a link tag in your HTML.

<link rel="manifest" href="manifest.json">

Status Bar Options

Games generally hide the status bar completely for an immersive experience. We can't do the same thing with this setup. You'll need a native wrapper.

But you can make it minimally intrusive by using this meta tag.

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

This will make the text white and allow the web page's background color to show through. Better than nothing!

There's a lesser-known viewport setting to go along with this for an even better experience. Check the Viewport section below.

Launch Image

By default, iOS will use a screenshot of the app from the last time it was launched as the launch image.

You can specify a different image with this meta tag.

<link rel="apple-touch-startup-image" href="launch.png">

Android will automatically create a launch image from the name, background-color, and icons fields in your manifest.json. You can't customize it but it is a lot less work. 🤷‍♂️

App Icon

iOS will auto-generate an icon based on what was on the screen when the app was added to the home screen but you can specify a different icon with meta tags.

<link rel="apple-touch-icon" href="custom_icon.png">

<!-- you can also specify specific images for different resolutions -->
<link rel="apple-touch-icon" sizes="152x152" href="touch-icon-ipad.png">
<link rel="apple-touch-icon" sizes="180x180" href="touch-icon-iphone-retina.png">
<link rel="apple-touch-icon" sizes="167x167" href="touch-icon-ipad-retina.png">

If no meta tags are specified then iOS will look at the web root for these files:

apple-touch-icon-80x80.png
apple-touch-icon.png

For Android you need to specify the icons field in your manifest.json.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


{
	// ...
	"icons": [
		{
			"src": "images/icons-192.png",
			"type": "image/png",
			"sizes": "192x192"
		},
		{
			"src": "images/icons-512.png",
			"type": "image/png",
			"sizes": "512x512"
		}
  ]
}

Viewport

This last meta tag is also the most important but you probably already have it.

Many index.html templates for mobile web apps include a viewport meta tag like this:

<meta name="viewport" content="width=device-width, initial-scale=1">

This will work well for most cases but we can do better than that for games.

<meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1, user-scalable=no, viewport-fit=cover">

The 2 key properties to look at are user-scalable and viewport-fit.

Any zooming or scaling for a game should happen in the HTML canvas element that your game runs in and not the webpage around it. Odds are your canvas will already take up the entire page and this won't be a problem.

Next is viewport-fit. It is lesser-known but it lets your game use the full edge to edge display on iPhone X and newer. You'll still have the status bar but at least your game will be under it. 😅