TIL: Don’t forget your Web Manifest file

We’re primarily a web shop. We’re dipping our toes into mobile app development, but our collective expertise is in making products and services for the web. And like everyone else, our use of the web has shifted from our desktops and laptops to our phones.

As we’re creating and prototyping new ideas, we keep developing websites that we think might also be good apps. So a few of us are using “Add to Home Screen” on these products, which has mostly been great, but we ran into something annoying: we couldn’t figure out how to hide the Safari toolbars as we navigate this new website-as-app.

We’re all familiar with this hasn’t-been-updated-since-2016 document from Apple explaining the meta tags required to hide Safari user interface components:

<meta name="apple-mobile-web-app-capable" content="yes">
<meta name="apple-mobile-web-app-status-bar-style" content="default">
<!-- Not needed but suggested -->
<meta name="viewport" content="initial-scale=1, user-scalable=no, viewport-fit=cover, width=device-width">

However, even with those added to our whole app, once the user navigates away from the first page the Safari browser toolbars show up again. Maddening.

I’ll save you the hassle we had finding a solution: you need to include a Web Application Manifest file with a few parameters.

This json file is used by both mobile and desktop browsers to figure out how this new website-as-app should function. It’s also predictably not mentioned by Apple’s documentation, and the W3C spec is still just an editor’s draft. But it works!

There’s a number of parameters you can add to this file, but these are the ones that solved our problem:

"display": "standalone",
"scope": "https://your.app.url/"

The display tells the browser to treat this as a standalone application, with no browser window ui. The scope tells the browser which URLs in the app should be treated as standalone. Easy peasy.

Now that you have this file, I’d also suggest adding more helpful parameters like a name, icons, launch image, etc. The Mozilla documentation is pretty thorough and helpful.