add-to-homescreen-control
v0.6.0
Published
Library that allows you to control new Add to Home Screen prompt behavior
Downloads
1,216
Maintainers
Readme
Add to Home Screen banner control
This 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.
How to use this library
Available methods
enable(): void
- enables capturing ofbeforeinstallprompt
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. Containsaccepted
if the app was succesfully installed, otherwise containsdismissed
string.platform: string
- platform used for installation
canPrompt(): boolean
- returnstrue
if the ATHS criteria are met andprompt()
method can be fired
Installation and usage example
- Install the library
npm i add-to-homescreen-control -d
- Enable it as soon as you can
import ATHS from 'add-to-homescreen-control'
ATHS.enable()
- Show the Add to Home Screen banner whenever you want to with
prompt()
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):
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 theprompt()
method is available:
Useful information
Browser support
Add to Home Screen behavior is supported by most of the modern browsers but the banner encouraging users to install the app will be displayed only in Google Chrome. The process of adding website to the homescreen is different for every browser and this library is focused mostly on Chrome since the ATHS banner is present only there.
Add to Home Screen criteria (Chrome)
Before ATHS prompt can be shown the following criteria needs to be met:
- 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.
Good practices and gotchas
- 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)