ionic-react-pwa-install
v1.0.2
Published
[![npm package][npm-badge]][npm] ![npm][npm-downloads]
Downloads
24
Readme
Ionic React PWA Install
Install handler for Ionic React PWA applications.
Installing a PWA applications (i.e. add to home screen) are handled differently by the different browser applications and devices being used. Currently Chrome, Edge and Samsung browsers support this natively and this can be captured and handled via the beforeinstallpromptevent. On iOS devices, Firefox Mobile or Opera mobile the application has to be install manually via the browser menu options. This can make it very hard to develop a consistent experience for users a PWA application using different browsers and applications.
A number PWA helper packages have been developed to alleviate this situation and this one is intended to support Ionic PWA application installations.
What this package does
This package provides a simple way to add a installer for Ionic PWA applications. It provides:
- information if this applications natively supports a PWA installation
- an interface function to call the installer or display instructions on how to do this.
Demo and Example
To view the demo visit - https://ionic-react-pwa-demo.netlify.com.
To see the demo source code see - https://github.com/drffej/ionic-react-pwa-install-demo.
Installation
To use the package, this assumes you will be using Ionic as the UI
$ npm i --save ionic-react-pwa-install
Usage
- Import
IonicPWAInstallProvider
anduseIonicPWAInstall
- Wrap your App with the
IonicPWAInstallProvider
. useIonicPWAInstall
returns the following interface:
type IonicPWAInstallInterface = {
isSupported: boolean; // returns true if platform specific installer is supported
isInstalled: boolean; // returns true if application is running as an app windows
platform : string // returns platform type one of 'native', 'other', 'firefox', 'idevice', 'opera'
pwaInstall : () => Promise<boolean> | null // call the platform specific installer or display instructions
}
- Use the
supported
andisInstalled
( fromuseReactPWAInstall
) functions to determine whether to show the appropriate Install button (or banner,popup,etc...) - Call
pwaInstall
depending on the value ofsupported
andisInstalled
.
import { useIonicPWAInstall, IonicPWAInstallProvider} from 'ionic-react-pwa-install'
const App: React.FC = () => {
const { isSupported, isInstalled, platform, pwaInstall, pwaManualInstall} = useIonicPWAInstall()!
return (
<IonApp>
<IonPage>
<IonHeader>
<IonToolbar>
<IonTitle>Ionic PWA Demo</IonTitle>
</IonToolbar>
</IonHeader>
<IonContent class="ion-padding">
<h1>PWA Data</h1>
<p>Is install prompt available? { isSupported ? 'true' : 'false'}</p>
<p>Is installed? {isInstalled ? 'true' : 'false'}</p>
<p>Platform? {platform}</p>
{(isSupported && !isInstalled) &&
<IonButton onClick={pwaInstall}>Install supported</IonButton>
}
</IonContent>
</IonPage>
</IonApp>
)};
const container = document.getElementById('root');
const root = createRoot(container!);
root.render(
<React.StrictMode>
<IonicPWAInstallProvider>
<App />
</IonicPWAInstallProvider>
</React.StrictMode>
);
Interface Details
IonicPWAInstallProvider
: Context provider, required.useIonicPWAInstall
: React hook that providespwaInstall
,iSupported
,isInstalled
andplatform
isSupported
: Helper to decide if the install button should be shown to the user. Returns true in 2 cases:- the beforeinstallpromptevent event is supported, and it has fired
- manual installation is supported
isInstalled
: Helper to decide if the install button should be shown to the user. Returns true if the user is currently visiting the site from the installed 'standalone' app.platform
: Help to decide what platform is being usedpwaInstall
: Will open the installation dialog according to the user's platform. This function returns a promise. The promise is returns False if the user cancels the native installation process. The promise returns True when the native installation was successful. For manual installs, it will open instructions to show to how to manually install the PWA application
The following logic can be used to help decide what dialog box to call
isSupported
| isInstalled
| platform
| Action
:-------------|:--------------|:-----------|:------
TRUE
| FALSE
| native
| Native installation available via pwaInstall
.
TRUE
| TRUE
| native
| Site running as standalone app, no action.
TRUE
| FALSE
| pwasafari
, firefox
or idevice
or opera
| Manual installation available, display instructions via pwaInstall
.
Further Reading
For more information see this guide about how to promote PWA installation from an Ionic PWA. See pwa is installable on the criteria to get the installation prompt.
Acknowledgements
A lot of the package ideas and some of the code is based on the react-pwa-install
package. See https://github.com/zoltangy/react-pwa-install for details.
The main differences are:
- Uses Typescript
- Uses Vite as the bundler
- Use Ionic UI instead of material UI
- Exposes the platform type