Adding to home screen allows mobile websites and PWA's to open like native apps without registering in the Apple or Google App Stores. Currently, it is very difficult to get users to add web apps to their home screen, limiting the utility of mobile websites compared to native apps. See related Medium blog post.
This drop-in JS Library for mobile websites effectively guides a user to add the website to their home screen on both IOS and Android.
Instructions and UI in this library have been "battle-tested" and has yielded an ~85% home screen install rate on IOS and Android across all ages in past implementations.
Here is a demo (please open on your phone) of library use within a hypothetical app "Aardvark" 
All major browsers on IOS and Android are supported. Here are the guides shown for each platform/browser:
All major browsers on IOS and Android are supported, but in the edge case of a non-compliant or desktop browser, a message is shown to redirect the user to a supported browser. (This feature can be toggled on/off using the showErrorMessageForUnsupportedBrowsers flag.)
User is guided to open the link in the system browser.
These apps all use SFSafariViewController and can be handled similarly.
Make sure your site has the minimum requirements for installing a web app on homescreen for IOS and Android.
-
At
https://your-website.com/apple-touch-icon.png, include a square icon of your app that is (1) at least 40 x 40 pixels and (2) specifically namedapple-touch-icon.png(example). -
At
https://your-website.com/manifest.json, include a web manifest filemanifest.json(example). Reference the manifest in your index HTML file.index.html<head> ... <link rel="manifest" href="manifest.json"> .. </head>
This should be a quick drop-in library into your mobile website.
-
Include the library JavaScript and CSS files in your header (You can use JSDelivr CDN if you're just using the library directly and not making any changes):
index.html<head> ... <link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/philfung/add-to-homescreen@1.8/dist/add-to-homescreen.min.css"> <script src="https://cdn.jsdelivr.net/gh/philfung/add-to-homescreen@1.8/dist/add-to-homescreen.min.js"></script> ... </head>
-
Call the library onload.
index.html<script> document.addEventListener('DOMContentLoaded', function () { // document.getElementById('addToHomeScreen').addEventListener('click', function () and add <button id="addToHomeScreen">Add to Home Screen</button> somewhere on your page to get a button instead. window.AddToHomeScreenInstance = new window.AddToHomeScreen({ appName: 'Aardvark', // Name of the app. // Required. appIconUrl: 'apple-touch-icon.png', // App icon link (square, at least 40 x 40 pixels). // Required. assetUrl: 'https://cdn.jsdelivr.net/gh/philfung/add-to-homescreen@1.8/dist/assets/img/', // Link to directory of library image assets. // Required. showErrorMessageForUnsupportedBrowsers: window.AddToHomeScreen.SHOW_ERRMSG_UNSUPPORTED.ALL, // Show an error message if add-to-home-screen is not supported for this browser // (e.g. "adding to home screen is not supported in IOS Firefox, please open this [website] in IOS Safari instead." or "adding to home screen is not supported on desktop, please open this [website] in your mobile browser instead". You can also set more granular permissions to show error messages only on mobile browsers and not on desktop browsers, etc) // Optional. Default: window.AddToHomeScreen.SHOW_ERRMSG_UNSUPPORTED.ALL allowUserToCloseModal: false, // Allow user to close the 'Add to Homescreen' message? Not allowing will increase installs. // Optional. Default: false. maxModalDisplayCount: -1 // If set, the modal will only show this many times. // Optional. Default: -1 (no limit). (Debugging: Use this.clearModalDisplayCount() to reset the count) }); ret = window.AddToHomeScreenInstance.show('en'); // show "add-to-homescreen" instructions to user, or do nothing if already added to homescreen // The only argument is the language to show the messages in (currently only 'de', 'en', 'pt' and 'fr' are available). }); </script> </body>
Here's an example implementation.
- Make changes
- Test locally:
Start local server
npm install
npm start
Load an example page http://127.0.0.1:8081
- Build the library into the
distdirectory
npm run build
- Save the dist directory to a CDN of your choice. Follow the steps in the previous section.
No dependencies. This is written in raw ES6 javascript and all css is namespaced to minimize codebase conflict and bloat.
- Bug: Fix browser instructions:
- Android
- Edge
- Android
- Bug: Fix in-app browser detection:
- IOS
- Google App
- Medium App
- Android
- Threads
- Google App
- Medium App
- IOS
