add-to-homescreen 📱

Motivation

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 Library

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"

Browser Support

All major browsers on IOS and Android are supported. Here are the guides shown for each platform/browser:

IOS - Safari browser

IOS - Chrome browser

Android - Chrome browser

Browser Fallback Support

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.)

Desktop users

In-App Browsers

Facebook and Linkedin in-app browsers on IOS and Android

User is guided to open the link in the system browser.

Twitter, Instagram and Threads in-app browsers on IOS

These apps all use SFSafariViewController and can be handled similarly.

iPhone users not on Safari or Chrome or in-app browser

Android users not on Chrome or in-app browser

Installation

Prerequisite

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 named apple-touch-icon.png(example).
At https://your-website.com/manifest.json, include a web manifest file manifest.json (example). Reference the manifest in your index HTML file.

index.html
```
<head>
...
<link rel="manifest" href="manifest.json">
..
</head>
```

Usage (If you're not making changes to library)

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();             // show "add-to-homescreen" instructions to user, or do nothing if already added to homescreen
});
</script>
</body>

Here's an example implementation.

Usage (If you're making changes to library)

Build the library:

npm run build

Test locally:

npm start

Next, save the dist directory to a CDN of your choice. Follow the steps in the previous section.

Dependencies

No dependencies. This is written in raw ES6 javascript and all css is namespaced to minimize codebase conflict and bloat.

License

Todos

[ ] Bug: Fix browser instructions:
- Android
  - [ ] Edge
[ ] Bug: Fix in-app browser detection:
- IOS
  - [ ] Reddit
  - [ ] Google App
  - [ ] Medium App
- Android
  - [ ] Twitter
  - [ ] LinkedIn
  - [ ] Threads
  - [ ] Instagram
  - [ ] Reddit
  - [ ] Google App
  - [ ] Medium App

Version	Downloads (Last 7 Days)	Published
1.0.1	3	9 months ago
1.0.0	0	9 months ago