Add to home screen allows websites and PWA's to work 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 such 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:
![](https://private-user-images.githubusercontent.com/1054593/261181359-f4f763e6-a3fa-4871-ae4a-699fd57bbcf6.gif?jwt=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJnaXRodWIuY29tIiwiYXVkIjoicmF3LmdpdGh1YnVzZXJjb250ZW50LmNvbSIsImtleSI6ImtleTUiLCJleHAiOjE3MjU0NzMyMjAsIm5iZiI6MTcyNTQ3MjkyMCwicGF0aCI6Ii8xMDU0NTkzLzI2MTE4MTM1OS1mNGY3NjNlNi1hM2ZhLTQ4NzEtYWU0YS02OTlmZDU3YmJjZjYuZ2lmP1gtQW16LUFsZ29yaXRobT1BV1M0LUhNQUMtU0hBMjU2JlgtQW16LUNyZWRlbnRpYWw9QUtJQVZDT0RZTFNBNTNQUUs0WkElMkYyMDI0MDkwNCUyRnVzLWVhc3QtMSUyRnMzJTJGYXdzNF9yZXF1ZXN0JlgtQW16LURhdGU9MjAyNDA5MDRUMTgwMjAwWiZYLUFtei1FeHBpcmVzPTMwMCZYLUFtei1TaWduYXR1cmU9ODExODI0NTVjNWNhODNhNzJkOGRmNzE1MTg3MjY3ODRjMzM2MjExNDcwNDU5YTNkNWUwYmM3MDE3NDFjOGVlYiZYLUFtei1TaWduZWRIZWFkZXJzPWhvc3QmYWN0b3JfaWQ9MCZrZXlfaWQ9MCZyZXBvX2lkPTAifQ.CidvlGFgOrgeEAMad_Wave9ULJH1U0Q6ie4o6NeqHa8)
![](https://private-user-images.githubusercontent.com/1054593/261181375-122d6a59-4657-421f-8c9f-17e6467b8485.gif?jwt=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJnaXRodWIuY29tIiwiYXVkIjoicmF3LmdpdGh1YnVzZXJjb250ZW50LmNvbSIsImtleSI6ImtleTUiLCJleHAiOjE3MjU0NzMyMjAsIm5iZiI6MTcyNTQ3MjkyMCwicGF0aCI6Ii8xMDU0NTkzLzI2MTE4MTM3NS0xMjJkNmE1OS00NjU3LTQyMWYtOGM5Zi0xN2U2NDY3Yjg0ODUuZ2lmP1gtQW16LUFsZ29yaXRobT1BV1M0LUhNQUMtU0hBMjU2JlgtQW16LUNyZWRlbnRpYWw9QUtJQVZDT0RZTFNBNTNQUUs0WkElMkYyMDI0MDkwNCUyRnVzLWVhc3QtMSUyRnMzJTJGYXdzNF9yZXF1ZXN0JlgtQW16LURhdGU9MjAyNDA5MDRUMTgwMjAwWiZYLUFtei1FeHBpcmVzPTMwMCZYLUFtei1TaWduYXR1cmU9ZjFkY2E0YWI5MWI0YTRlYjNiODc5ZjU1MDY0ZWU4NTNhZmFmMDYwMmRjZWUwYmNlYzllMWNkNjYyMDI1MWMzMSZYLUFtei1TaWduZWRIZWFkZXJzPWhvc3QmYWN0b3JfaWQ9MCZrZXlfaWQ9MCZyZXBvX2lkPTAifQ.IEFmzzf-jAbD8zZV8OZwjiEdyEKhg3vyTRSFkuGqxIc)
![](https://private-user-images.githubusercontent.com/1054593/261181388-53f06e82-61f3-4173-890e-0a6a42026dea.gif?jwt=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJnaXRodWIuY29tIiwiYXVkIjoicmF3LmdpdGh1YnVzZXJjb250ZW50LmNvbSIsImtleSI6ImtleTUiLCJleHAiOjE3MjU0NzMyMjAsIm5iZiI6MTcyNTQ3MjkyMCwicGF0aCI6Ii8xMDU0NTkzLzI2MTE4MTM4OC01M2YwNmU4Mi02MWYzLTQxNzMtODkwZS0wYTZhNDIwMjZkZWEuZ2lmP1gtQW16LUFsZ29yaXRobT1BV1M0LUhNQUMtU0hBMjU2JlgtQW16LUNyZWRlbnRpYWw9QUtJQVZDT0RZTFNBNTNQUUs0WkElMkYyMDI0MDkwNCUyRnVzLWVhc3QtMSUyRnMzJTJGYXdzNF9yZXF1ZXN0JlgtQW16LURhdGU9MjAyNDA5MDRUMTgwMjAwWiZYLUFtei1FeHBpcmVzPTMwMCZYLUFtei1TaWduYXR1cmU9YzRmYjViYjczMmIzYzgxMzA0MGIyMTg1NTgyZTdhYTQ4Y2ZmNzI3MDc1NmQyNjA4YWE4MWRiZDk0YjdiNjQxMyZYLUFtei1TaWduZWRIZWFkZXJzPWhvc3QmYWN0b3JfaWQ9MCZrZXlfaWQ9MCZyZXBvX2lkPTAifQ.qsTzZRBMuJbaWQPnQE8YS79uCOQ_YzK1D0aTBj1p2Os)
User is guided to open the link in the system browser.
These apps all use SFSafariViewController and can be handled similarly.
![ios-non-compliant](https://private-user-images.githubusercontent.com/1054593/261148164-054f7a08-4576-4452-93e9-5810969c0653.png?jwt=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJnaXRodWIuY29tIiwiYXVkIjoicmF3LmdpdGh1YnVzZXJjb250ZW50LmNvbSIsImtleSI6ImtleTUiLCJleHAiOjE3MjU0NzMyMjAsIm5iZiI6MTcyNTQ3MjkyMCwicGF0aCI6Ii8xMDU0NTkzLzI2MTE0ODE2NC0wNTRmN2EwOC00NTc2LTQ0NTItOTNlOS01ODEwOTY5YzA2NTMucG5nP1gtQW16LUFsZ29yaXRobT1BV1M0LUhNQUMtU0hBMjU2JlgtQW16LUNyZWRlbnRpYWw9QUtJQVZDT0RZTFNBNTNQUUs0WkElMkYyMDI0MDkwNCUyRnVzLWVhc3QtMSUyRnMzJTJGYXdzNF9yZXF1ZXN0JlgtQW16LURhdGU9MjAyNDA5MDRUMTgwMjAwWiZYLUFtei1FeHBpcmVzPTMwMCZYLUFtei1TaWduYXR1cmU9NWMwOTE3MjcyZTBmYWU3ODU4YTdhMTc1ZTBjODgyMTA5NWUxMGYyODAyMWI3MTBmNzViZTFlZWQ1ZGVjODRjMSZYLUFtei1TaWduZWRIZWFkZXJzPWhvc3QmYWN0b3JfaWQ9MCZrZXlfaWQ9MCZyZXBvX2lkPTAifQ.17k_WJoAW4TFmmnn3zDWcbLU6qwO4Tsrvv7yVnC0lSk)
![android-non-compliant](https://private-user-images.githubusercontent.com/1054593/261148189-0072304f-4ec5-4cab-b14b-e96a5226ae79.png?jwt=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJnaXRodWIuY29tIiwiYXVkIjoicmF3LmdpdGh1YnVzZXJjb250ZW50LmNvbSIsImtleSI6ImtleTUiLCJleHAiOjE3MjU0NzMyMjAsIm5iZiI6MTcyNTQ3MjkyMCwicGF0aCI6Ii8xMDU0NTkzLzI2MTE0ODE4OS0wMDcyMzA0Zi00ZWM1LTRjYWItYjE0Yi1lOTZhNTIyNmFlNzkucG5nP1gtQW16LUFsZ29yaXRobT1BV1M0LUhNQUMtU0hBMjU2JlgtQW16LUNyZWRlbnRpYWw9QUtJQVZDT0RZTFNBNTNQUUs0WkElMkYyMDI0MDkwNCUyRnVzLWVhc3QtMSUyRnMzJTJGYXdzNF9yZXF1ZXN0JlgtQW16LURhdGU9MjAyNDA5MDRUMTgwMjAwWiZYLUFtei1FeHBpcmVzPTMwMCZYLUFtei1TaWduYXR1cmU9ZmM2ZmViMDkzYjQ2YTY5ZGFkOWUzNDE5YjZhZGVkMjU5MThmMzBlN2I2ZjY0OTJlZWVlNmE3MmEyZTEwNDMzNyZYLUFtei1TaWduZWRIZWFkZXJzPWhvc3QmYWN0b3JfaWQ9MCZrZXlfaWQ9MCZyZXBvX2lkPTAifQ.u1CNFALmlixeiWoerNezlsWWqhNEGBUrC5t-gz5OtSM)
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.9/dist/add-to-homescreen.min.css"> <script src="https://cdn.jsdelivr.net/gh/philfung/add-to-homescreen@1.9/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.9/dist/assets/img/', // Link to directory of library image assets. 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
dist
directory
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.
- add to Dock/Taskbar for Desktop (coming soon!!)
- Fix browser instructions:
- Android
- Edge
- Android
- Fix in-app browser detection:
- IOS
- Google App
- Medium App
- Android
- Threads
- Google App
- Medium App
- IOS