Ever wonder what’s involved in turning your web app into an app you can launch from a mobile device? On the Amazon Appstore, it’s pretty easy, and involves just a few steps you can learn about here. One of those steps is adding a JSON file called the web-app-manifest to your web app.

This manifest file contains information required to run your app on a mobile device, and the basic manifest file is created for you on the developer portal. Where you put that manifest file can make a difference though. You should know about that and how to edit your manifest file in order to give your app access to features like geolocation on the device.

Where can you put the Manifest, and what difference that makes.

While we recommend that you put the manifest file at the root of your web app, you can put the manifest file anywhere on your server. The location of your manifest file determines what pages will render in the context of your app, and which pages will render in the default browser. The pages in the sub-domains under your manifest will be accessible by your app and will render in the context of your app. Any pages outside of those domains or directories will open in the default browser instead of in the context of your app.

Take a look at what pages will and won’t be accessible from your mobile app depending on where you put the manifest. Note the special case of www. and m. addresses in yellow below.

If you put your manifest here… These pages will open in your app But these pages will open in a browser http://foo.com/web-app-manifest.json http://*.foo.com/* http://*.notFoo.com/* http://bar.foo.com/web-app-manifest.json http://*.bar.foo.com/* http://*.notBar.foo.com/* http://m.foo.com/web-app-manifest.json http://*.foo.com/* http://*.notFoo.com/* http://www.foo.com/web-app-manifest.json http://*.foo.com/* http://*.notFoo.com/* http://foo.com/MyApp/web-app-manifest.json http://foo.com/MyApp/* http://foo.com/notMyApp/* http://*.foo.com/MyApp/* http://bar.foo.com/MyApp/web-app-manifest.json http://bar.foo.com/MyApp/* http://bar.foo.com/* http://notBar.foo.com/* http://notBar.foo.com/MyApp/* http://bar.foo.com/notMyApp/*

SSL Note:

If the manifest is delivered with https://, then the entire app must be delivered over SSL as well.

If the manifest is delivered with http://, the app may be still be served over SSL.

If you use any permissions (IAP, Geo Location, Login), you must use SSL.

Now that you have a good idea where to put your manifest, what to put in it?

Contents of the web-app-manifest.json file

The manifest created automatically for you will look like this:

{

"verification_key" : "c8efxxxx-xxxx-xxxx-xxxx-xxxxe5b239e9",

"version" : "0.00(0)",

"type" : "web",

"last_update" : "2013-11-19 23:40:17+0000"

}

“verification key” connects your website to your app.

*This is the only required field in the manifest.

“version” helps you track the version that you have submitted

“type” lets us know that in this case, the app is a web-app

“last_update” is when this manifest file was created (you can change it to match your updates)

In addition to the elements above, you may also wish to add one of these elements:

“permissions” specifies the permissions your app will request (these will require SSL use). They consist of:

“Created_by” = you.

“launch_path” identifies the file you want your app to open

iap = In App Purchasing geolocation = Get location information auth = if you request user credentials for login (facebook connect, google, your own.)

A finished web-app-manifest.JSON that uses all available fields might look like this:

1 2 3 4 5 6 7 8 9 10 11 12 13 14 { "verification_key": " c8efxxxx-xxxx-xxxx-xxxx-xxxxe5b239e9", "launch_path": "index.html", "permissions": [ "iap", "geolocation", "auth" ], "type": "web", "version": "0.1a", "last_update": "2013-04-08 13:30:00-0800", "created_by": "webappdev" }

Updating your web-app-manifest.JSON file

If after your app launches, you decide you want to update you web-app-manifest.JSON file, the app on device will not automatically update with new JSON file data. You will need to publish an updated version of your app. You can create an updated version of your native app in the dev portal by using the ‘Add an upcoming version’ link at the top of the developer portal page for your app (see below).

Once your new version submission is underway, you can submit and verify a new manifest, and then submit the new app version for publication.

A Tip to Remember!

Please be sure to configure your server to accommodate .JSON MIME types! For example:

.json -> application/json

.webapp -> application/x-web-app-manifest+json

More Information

You can find detailed documentation on the web-app-manifest.JSON file and on HTML5 app submission on our Dev Portal here.

Should you have any additional questions about the web app manifest file and how it is used, please send us a quick note so we can get you the answer you need.