Skip to content

Latest commit

 

History

History
124 lines (94 loc) · 6.29 KB

README.md

File metadata and controls

124 lines (94 loc) · 6.29 KB
Raw

react-pwa-install

npm package npm

Install handling for your React PWA.

The problem this package is trying to solve

Since intalling a PWA (aka Add to home screen) is handled differently by different browsers, it's rather hard to give this option to users conveniently. Currently only Chrome, Edge and Samsung Internet support this feature natively using the BeforeInstallPromptEvent. On iOS devices, FireFox mobile or Opera mobile the user needs to perform some manual steps to install the app to the home screen. Very few know this option even exists.

What this package does

This package provides a simple way to add a custom PWA installing capability to your app on several platforms, while not trying to do too much in terms of when and how or how often the install prompt is shown to the user. This is application dependent and should be left for the app developer to define.

  • If a user is visiting your PWA from a browser that supports the native BeforeInstallPromptEvent, then this method will be used for the installation. ( Currently: Chrome - mobile and desktop, Edge - mobile, Samsung internet )
  • If a user is visiting your PWA from a browser that supports "manual installation", then instructions will be shown to them. ( Currently iOS devices, FireFox - mobile, Opera - mobile).

Demo

To view the demo visit: https://zoltangy.github.io/react-pwa-install-demo/ (view source code).

Installation

To use the package, you also need to install @material-ui/core.

$ npm i --save react-pwa-install @material-ui/core

Prerequisites

Make sure that your PWA is installable. You can use Lighthouse from Chrome DevTools to run a PWA Audit.

Please also read this guide on best practices to promote the installation of your app.

Usage

  1. Import ReactPWAInstallProvider and useReactPWAInstall
  2. Wrap your App with the ReactPWAInstallProvider.
  3. Use the supported and isInstalled (desctructed from useReactPWAInstall) functions to determine whether to show your Install button (or banner,popup,etc...). Generally, the install button should only be shown if supported returns true and isInstalled returns false. (You should add the app specific criterias on top of this: amount of time spent on the site, certain engagement, etc.)
  4. Call pwaInstall (desctructed from useReactPWAInstall) when the user clicked on the install button. See the list of options below. You might want to handle rejection (or possible rejection) here, and not prompt the user again for a certain period of time or until a new meaningful engagement.
import React from "react";
import ReactDOM from "react-dom";
import ReactPWAInstallProvider, { useReactPWAInstall } from "react-pwa-install";
import myLogo from "img/logo.png";

function App() {
  const { pwaInstall, supported, isInstalled } = useReactPWAInstall();

  const handleClick = () => {
    pwaInstall({
      title: "Install Web App",
      logo: myLogo,
      features: (
        <ul>
          <li>Cool feature 1</li>
          <li>Cool feature 2</li>
          <li>Even cooler feature</li>
          <li>Works offline</li>
        </ul>
      ),
      description: "This is a very good app that does a lot of useful stuff. ",
    })
      .then(() => alert("App installed successfully or instructions for install shown"))
      .catch(() => alert("User opted out from installing"));
  };

  return (
    <div>
      {supported() && !isInstalled() && (
        <button type="button" onClick={handleClick}>
          Install App
        </button>
      )}
    </div>
  );
}

ReactDOM.render(
  <ReactPWAInstallProvider enableLogging>
    <App />
  </ReactPWAInstallProvider>,
  document.querySelector("#root")
);

API

  • ReactPWAInstallProvider: Context provider, required. For debug purposes, the enableLogging property can be used.
  • useReactPWAInstall: React hook that provides pwaInstall, supported, isInstalled
  • supported: Helper function to decide if the install button should be shown to the user. Returns true in 2 cases:
    • the beforeinstallprompt event is supported, and it has fired
    • manual installation is supported
  • isInstalled: Helper function 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.
  • pwaInstall: Will open the installation dialog according to the user's platform. See below for options. This function returns a promise. The promise is rejected only if the user cancels the native installation process. The promise is fulfilled when the native installation was successful or when the manual installation steps were shown.

Options for pwaInstall

The following options are available to customize the install dialog:

Prop type Default Value Description
title (optional) string Install Web App The header of the dialog window
logo (optional) string - Path to an image representing the app, typically the icon
features (optional) React.ReactNode - A list of features, see "Usage" for an example
description (optional) string - Description of the app

Customization

To customize the colors and fonts of the dialog, you can wrap the ReactPWAInstallProvider with a Material-UI ThemeProvider. See https://material-ui.com/customization/theming/ for more info.