Progressive Web Apps

How to integrate Add To Home Screen into your PWA

pwa-add-to-home-screen

Add to Home screen (A2HS for short) is fundamental to the Progressive Web App experience as it allows for a full native-app experience, which includes the launching of apps from the user’s home screen. In this guide, we’ll go over the reasons why A2HS is necessary, how it is used and how to make an app A2HS-ready, both on mobile and on desktop.

Supporting browsers

A2HS is very close to being a universal feature between browsers. Currently, it is currently supported by Mobile Chrome/Android Webview (from version 31 onwards), Opera for Android (from version 32 onwards) and Firefox for Android (from version 58 onwards). For a more detailed view, you can check CanIUse website.

PWA Add to Home screen in action

When coming across a site that’s PWA Add to Home screen enabled (A2HS-Enabled), a banner notifying that the site can be added to your Home screen can be seen at the bottom of the user interface:

Soomzone PWA Add to Home screen
Soomzone – one of SimiCart’s proud projects

The banner used to be a lot bigger but fortunately, the newer versions of mobile browsers have made it less intrusive for the user experience. The notification itself won’t be shown for a second time if the user choose to close it.

How to make your web app A2HS-enabled on mobile

For your web app to be A2HS-enabled, first there are a few criteria that need to be satisfied:

  • Your website must be served from a secure (HTTPS) connection.
  • A service worker registered (which is vital for offline capability and performance improvement)
  • A properly configured manifest.json file.

Once these criteria are met, a beforeinstallpromt will be fired asking for the user’s permission to install Progressive Web App.

Configuring your manifest.json file

Usually located deep in the root folder of a web app, your web manifest file is a file that contains all of your website’s necessary information—such as your app’s title, paths to different icons, background color, etc—in a JSON format. A web manifest file is crucial to a functional web-app as it allows for proper presentation of your web app on various stages of the user experience.

Your typical manifest file for a web-app with functional Add to Home screen feature should look something like this:

{
  "background_color": "orange",
  "description": "Cute and random little cat pictures.",
  "display": "fullscreen",
  "icons": [
    {
      "src": "icon/cat-icon.png",
      "sizes": "192x192",
      "type": "image/png"
    }
  ],
  "name": "Cute cat pictures",
  "short_name": "Cats",
  "start_url": "/pwa-examples/a2hs/index.html"
}

It should be noted that within a JSON (JavaScript Object Notation) structure, properties are also known as ‘members‘. They’re the fields that indicate the type of information you want to provide. Usually, a property/member contains a key-value pair, with key being the name of the property and value being, well, the value of the property.

For instance, you could see that in the example below background_color is the name of the type of information that you want to provide and orange is the value of said information.

"background_color": "orange"

Required members

For a manifest.json to be functional, there are five required members:

name, short-name, icons, display, start_url

name: Indicates your app’s name which is displayed under the icon of your app on the home screen and various other places. Keep the value of your name property short and simple.

short-name: When the value of your ‘name’ property fails to fit within the user’s screen, the value of this property is then the replacement to it. It’s recommended that your short-name should be under 20 characters and lower. In fact, shoot for 10 characters.

icon: Indicates your app’s icon image, which can consist of several images for different OSs and devices. It’s always better to have an array of variables as your icon member’s value as you don’t want your app to fail to present itself.

For example, iOs alone requires 4 different sizes for 4 of its device:

  • iPhone: 120 x 120 pixels & 180 x 180 pixels
  • iPad Pro: 167 x 167 pixels
  • iPad & iPad mini: 152 x 152 pixels

Even Google Chrome requires at least 2 different sizes for full usability on iOS and Android:

  • 512 x 512 pixels
  • 192 x 192 pixels

A safer approach, however, is to provide a large icon (512 x 512 pixels) and a smaller icon (192 x 192 pixels). As Google has put it, a192-pixel icon is always the optimal choice as your app user’s OS can scale down the icon—should the need arise—with reasonable accuracy.

In order for your image icon to be called, a set of properties is used, namely src, types and sizes.

src: is used to provide the path to the icon’s image.

types: is used to provide the kind of file type of the image.

sizes: is used to provide a width x height description of the image’s dimension.

"icons" : [ 
    {
       "src" : "/imgs/icon152.png",
       "type" : "image/png",
       "sizes" : "192x192"
    },
    {
       "src" : "/imgs/icon215.png",
       "type" : "image/png",
       "sizes" : "512x512"
    }
]

display: Indicates how the app should be displayed. For an immersive and app-like experience, it’s recommended that you should set it to fullscreen (no UI is shown). However, options such as standalone. minimal-ui is also available which is less costly performance-wise but at the cost of losing the immersive experience (status bar might still be shown).

start_url: Indicates the path from which your application starts. Your start_url value could be a simple ‘/’ if your application starts from the same .root directory where your manifest.json is stored.

background_color: Indicates the background color in certain app contexts. More specifically, this field can be used to set the background color for splash screen, which is the initial screen when the user first launches the app from the Home screen icon.

Optional members

Going by the book is one thing but there’s always room for you to try to be better. Below are our recommended members for a better more detailed manifest.json:

  • background_color: The background color in certain app contexts. More specifically, this member can be used to set the background color for splash screen, which is the initial screen when the user first launches the app from the Home screen icon.
  • scope: limits the extent a user can go. With this scope member, you don’t have to worry about some quick-witted users who use your app to browse other websites for god knows what reason. To scope your website, simply put a slash (‘/’) or put in your website’s full URL.
  • description: This one is self-explanatory.

Link the HTML to the manifest

When you’re done configuring your manifest file, save it in your website’s root directory so that it can later on be called with a relative path, i.e /manifest.json.

To finish setting up your manifest.json file, reference it in your HTML header.

<link rel="manifest" href="manifest.webmanifest">

Test your A2HS

There are many ways to go about testing your A2HS. One of them is by manually triggering the beforeinstallprompt event with Chrome DevTools. By doing it this way, you get to see first-hand the user experience, which is fundamental for an understanding of how the flow works.

How to test

On Chrome for Android:

  1. Create a remote debugging session on your phone or tablet
  2. Head over to the Application panel
  3. Choose the Manifest tab
  4. Choose Add to Home screen

Another less complicated way to test your A2HS feature is to use Lighthouse to audit your app. Lighthouse offers a variety of options and tests for developers to choose from, one of which is the “User Can Be Prompted To Install The Web App” criterion in “Progressive Web App” audit.

How to make your web app A2HS-enabled on desktop

A2HS is a feature that is no longer uniquely mobile. Desktop users now can install and launch PWA-enabled site from their desktop, just as how mobile users would from their Home screen.

Creating an install button

In order for your PWA to be made available on desktop, it’s important to have a button since it is not readily available in Chrome and the installation process have to be trigged by a user getsure.

<button class="add-button">Add to home screen</button>

Some simple styling should also be added:

.add-button {
  position: absolute;
  top: 1px;
  left: 1px;
}

Listen for beforeinstallprompt

Once the beforeinstallprompt has been fired, the code below will save a referrence to the event and update your user interface accordingly to show that the user can add your app to their home screen.

let deferredPrompt;

window.addEventListener('beforeinstallprompt', (e) => {
  // Stash the event so it can be triggered later.
  deferredPrompt = e;
  // Update UI notify the user they can add to home screen
  showInstallPromotion();
  ...
});

The installation process

A general way of dealing with the installation process is demonstrated in the code below:

window.addEventListener('beforeinstallprompt', (e) => {
  // Prevent Chrome 67 and earlier from automatically showing the prompt
  e.preventDefault();
  // Stash the event so it can be triggered later.
  deferredPrompt = e;
  // Update UI to notify the user they can add to home screen
  addBtn.style.display = 'block';

  addBtn.addEventListener('click', (e) => {
    // hide our user interface that shows our A2HS button
    addBtn.style.display = 'none';
    // Show the prompt
    deferredPrompt.prompt();
    // Wait for the user to respond to the prompt
    deferredPrompt.userChoice.then((choiceResult) => {
        if (choiceResult.outcome === 'accepted') {
          console.log('User accepted the A2HS prompt');
        } else {
          console.log('User dismissed the A2HS prompt');
        }
        deferredPrompt = null;
      });
  });
});

Upon closer inspection, you could see that:

  • The variable Event.prevenDefault() is there to stop Chrome 67 and earlier from automatically calling the install prompt
  • Event-related objects are placed in deferredPrompt for future uses.
  • The button for installation is set to display: block for the user to click.

Within the click handler, there are also actions such as:

  • display = ‘none’: hide the button once the installation process is over.
  • Take advantage of the prompt() method that comes with the beforeinstallprompt event to trigger the install prompt.
  • Take advantage of the userChoice property that comes with the beforeinstallprompt event to respond to the user’s interaction with the prompt.
  • deferredPrompt: is set to null since it is no longer useful.

With proper execution, your user should see something like this once the button is pressed:

Twitter PWA desktop install prompt

Upon clicking install, a standalone desktop app will instantly be created on the user’s desktop and the install button will be hidden from then on.

One thing to note

It’s important that you should know this is only the initial process of setting up a functional Progressive Web App. A Progressive Web App, by definition, not only functions like a native app but also better, thanks to its offline capability and performance improvement.

By allowing your users to add your app to their Home screen, you’re only expanding your app’s accessibility but not actually making any progress in the offline world. For a better reach, it’s recommended that you should take advantage of the Service Workers API for a full PWA experience.

Closing words

Even though PWA Add to Home screen is a feature that’s been around for quite a while, not that much people know and take full advantage of this feature. With Add to Homescreen, PWA can reliably offer its users an experience comparable to that of native apps or even better.

For Magento merchants looking for an all-around perfect Progressive Web App solution, here at SimiCart we offer a complete package for you and your store:

0 Comments

Luke Vu

    avatar
      Subscribe  
    Notify of