Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/philfung/add-to-homescreen
Easily add a website/PWA to home screen on IOS/Android/Desktop
https://github.com/philfung/add-to-homescreen
add-to-homescreen desktop desktop-app desktop-application desktop-apps manifest-json mobile-app mobile-detect mobile-detection mobile-development mobile-web mobile-web-app mobile-website pwa pwa-apps standalone standalone-app webapp
Last synced: 4 days ago
JSON representation
Easily add a website/PWA to home screen on IOS/Android/Desktop
- Host: GitHub
- URL: https://github.com/philfung/add-to-homescreen
- Owner: philfung
- License: mit
- Created: 2023-08-15T22:30:21.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2025-02-07T03:36:13.000Z (14 days ago)
- Last Synced: 2025-02-10T13:08:48.688Z (11 days ago)
- Topics: add-to-homescreen, desktop, desktop-app, desktop-application, desktop-apps, manifest-json, mobile-app, mobile-detect, mobile-detection, mobile-development, mobile-web, mobile-web-app, mobile-website, pwa, pwa-apps, standalone, standalone-app, webapp
- Language: TypeScript
- Homepage:
- Size: 5.25 MB
- Stars: 173
- Watchers: 7
- Forks: 46
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# add-to-homescreen 📱 🖥️
## Motivation
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](https://medium.com/@philipfung/add-to-homescreen-websites-an-option-for-startups-in-2023-efb92f5e03ad).
## This Library
This drop-in JS Library for websites effectively guides a user to add the website to their home screen on IOS, Android and Desktop.
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)](https://philfung.github.io) of library use within a hypothetical app "Aardvark" 
## Language Support
Translated to 20+ [languages](https://github.com/philfung/add-to-homescreen/tree/main/src/locales).
## Browser Support
All major browsers with > 10% market share on IOS/Android/Desktop are supported.
Here are the guides shown for each platform/browser:
#### IOS - Safari browser
#### IOS - Chrome browser
#### Android - Chrome browser
#### Desktop Windows & Mac - Chrome & Edge browsers
#### Desktop Mac - Safari browser
#### In-App Mobile Browsers
In-App browsers on popular social apps are supported. Users are guided to open the link in the system browser, then the standard add-to-homescreen flow appears.
* Instagram ([IOS](https://github.com/user-attachments/assets/0d3ab224-1ac7-454e-b75d-21f6c52ffa87), [Android](https://github.com/user-attachments/assets/7e1d11fd-31ba-4b27-a13d-6beb079b4204))
* Facebook ([IOS](https://github.com/user-attachments/assets/4c8121a2-3c62-402f-be05-0c54bf108ddc), [Android](https://github.com/user-attachments/assets/45701ac3-d337-4fc4-8e82-3d03236bf3a5))
* X / Twitter ([IOS](https://github.com/user-attachments/assets/ed01b58e-5aab-48b9-8c42-d21d24cd2c03), Android - opens in system browser)
## Installation
### Prerequisite
Make sure your site has the minimum requirements for installing a web app on homescreen for IOS and Android and Desktop.
1. 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](https://github.com/philfung/add-to-homescreen/blob/main/apple-touch-icon.png)).
2. At `https://your-website.com/manifest.json`, include a web manifest file `manifest.json` ([example](https://github.com/philfung/add-to-homescreen/blob/main/manifest.json)). Reference the manifest in your index HTML file.
`index.html`
```html
...
..
```
### Usage (If you're not making changes to library)
This should be a quick drop-in library into your website.
1. Include the library JavaScript and CSS files in your header (You can use [JSDelivr CDN](https://cdn.jsdelivr.net/gh/philfung/add-to-homescreen@master/dist/) if you're just using the library directly and not making any changes):
`index.html`
```html
...
...
```
The code above will include a JavaScript file containing all the available translations for the locales this library supports. It is highly optimized to be small and quick to deliver over mobile networks. If however you want to
be even more highly optimized, the library also has JavaScript files built with just a single locale of translations, which is about 60% smaller.
For example, the Spanish file `add-to-homescreen_es.min.js` can be included as below. If you have a dynamic server environment and know the user's preferred locale, this can be a good option. To see all the supported locales, look in the `dist` folder.
```html
...
...
```
2. Call the library onload.
`index.html`
```javascript
document.addEventListener('DOMContentLoaded', function () {
window.AddToHomeScreenInstance = window.AddToHomeScreen({
appName: 'Aardvark', // Name of the app.
// Required.
appNameDisplay: 'standalone', // If set to 'standalone' (the default), the app name will be diplayed
// on it's own, beneath the "Install App" header. If set to 'inline', the
// app name will be displayed on a single line like "Install MyApp"
// Optional. Default 'standalone'
appIconUrl: 'apple-touch-icon.png', // App icon link (square, at least 40 x 40 pixels).
// Required.
assetUrl: 'https://cdn.jsdelivr.net/gh/philfung/[email protected]/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)
displayOptions:{ showMobile: true, showDesktop: true }, // show on mobile/desktop [Optional] Default: show everywhere
allowClose: true, // allow the user to close the modal by tapping outside of it [Optional. Default: true]
});
ret = window.AddToHomeScreenInstance.show('en'); // show "add-to-homescreen" instructions to user, or do nothing if already added to homescreen
// [optional] language. If left blank, then language is auto-decided from (1) URL param locale='..' (e.g. /?locale=es) (2) Browser language settings
});