Library that allows you to control new Add to Home Screen prompt behavior
npm install add-to-homescreen-controlThis library allows you to programatically show Add to Home Screen banner. This feature is available from Chrome 68 but the library works on the older versions aswell. It's recomennded to read useful information section before using this library to avoid common problems and gotchas.
- enable(): void - enables capturing of beforeinstallprompt event and all the librarys behavior. You need to invoke this function as fast as you can to use all the other parts of this library.
- prompt(): Promise - shows the Add to Home Screen banner (if the criteria are met) and resolves when user decides either to install or decline on Add to Home Screen. The resolved Promise value is an object with two values:
- outcome: string - outcome of the homescreen installation. Contains accepted if the app was succesfully installed, otherwise contains dismissed string.
- platform: string - platform used for installation
- canPrompt(): boolean - returns true if the ATHS criteria are met and prompt() method can be fired
1. Install the library
`````
npm i add-to-homescreen-control -d``
2. Enable it as soon as you canjs``
import ATHS from 'add-to-homescreen-control'
ATHS.enable()prompt()
3. Show the Add to Home Screen banner whenever you want to with method. The banner will appear only if the criteria are met. You can handle unmet criteria in two ways:
- make use of the fact that prompt() returns a Promise (recommended):``js``
ATHS.prompt()
.then(({ outcome }) => console.log('user interacted with ATHS banner with outcome of', outcome))
.catch(err => console.log(err))
- or you can use canPrompt property to check if the prompt() method is available:
- The web app is not already installed
- The user has interacted with the domain for at least 30 seconds
- Your index.html includes Web App Manifest with at least following propertiesshort_name, name, start_url, icons (at least 192px and 512px), display (standalone, fullscreen, minimal-ui)
- You have registered Service Worker with a fetch event handler (can't be a dummy one)
You can succesfully use librarys prompt() method only if this criteria are met. Otherwise it'll end up as a rejected promise.
You can use canPrompt variable to detect if the criteria are already met.
This criteria are different for other browsers.
- Firefox
- MS Edge
- Opera
- It's a good practice to show ATHS prompt in a context and as a response to user gesture (for example button click). Showing it right after it's available is an anti-pattern.
- banner can be shown only once per navigation route.
- Once user click x` on a banner it can't be shown again for a significant amount of time (currently ~3 months)