Installable Web Apps

Considering the wonders promised in the introduction to this chapter, the implementation details are surprisingly simple. In fact, only three steps are required:

1. Register a service worker.

2. Create a web app manifest file.

3. Add a link to the manifest from the web app.

Seeing as we already have a service worker registered in our web app, we are already a third of the way there. Let’s take the final two steps.

First, we will create a web app manifest.

The manifest is a simple JSON file that describes how a web app should launch, behave, and look. It really is as simple as that.

Begin by making sure that your code is in the state we left it in at the end of the last chapter by running the following commands in the command line:

git reset --hard
git checkout ch09-start

Next, create a file called manifest.json in the public directory of the Gotham Imperial Hotel project, with the contents shown here:

{
  "short_name": "Gotham Imperial",
  "name": "Gotham Imperial Hotel",
  "description": "Book your next stay, manage reservations, and explore Gotham",
  "start_url": "/my-account?utm_source=pwa",
  "scope": "/",
  "display": "fullscreen",
  "icons": [
    {
      "src": "/img/app-icon-192.png",
      "type": "image/png",
      "sizes": "192x192"
    },
    {
      "src": "/img/app-icon-512.png",
      "type": "image/png",
      "sizes": "512x512"
    }
  ],
  "theme_color": "#242424",
  "background_color": "#242424"
}

While the contents of manifest.json are relatively self-explanatory, we will delve into the details of manifest files in “Anatomy of a Web App Manifest”.

Next, add the following HTML tag to the head of index.html and my-account.html. This will let the browser know that a manifest file is available for this site:

<link rel="manifest" href="/manifest.json">

This is it!

Everything else is up to the browser now.

How Browsers Decide When to Show an App Install Banner

When the browser determines that a site is suitable for being installed and that the user might care enough about that site that she may want a shortcut to it on her homescreen, it will trigger a web app install banner (shown in Figure 9-2).¹

Figure 9-2. A web app install banner on Chrome

The browser will only show the web app install banner on sites that it considers to be worthy of a place on the user’s homescreen—apps that meet certain minimal criteria for providing an app-like experience.

At the time of writing, these criteria are the following:

1. The site is served over HTTPS.

2. The site has a service worker registered.

3. The site has a web app manifest containing at least the four mandatory fields (detailed in “Anatomy of a Web App Manifest”).

In addition, the browser only shows the web app install banner once it believes the user might care enough about this web app to want a permanent shortcut to it on her homescreen. The heuristics of how the browser determines this differ from browser to browser, and between different browser versions. For example, when initially launching this feature, both Opera and Chrome showed the install banner when a user had visited the app twice over two separate days during the course of two weeks. These heuristics have since been changed to increase the frequency of install banners and are still being continuously tweaked by different browser vendors to fine-tune the user’s experience.

To summarize, the browser will show the install banner if the following conditions are met:

if (
  the web app is served over HTTPS &&
  the web app has a service worker registered &&
  it has a valid manifest file that includes all required attributes &&
  that manifest file is linked from a page visited by the user &&
  the browser determines the user has shown a lasting interest in the web app &&
  an install banner for this web app was not shown and rejected in the past
) then {
  a web app install banner will be shown
}

Anatomy of a Web App Manifest

Before we move on, let’s explore the web app manifest format.

Any valid JSON file can be a manifest file, but in order to trigger a web app install banner, the manifest file must at the very least contain the following attributes:

name and/or short_name

The manifest file must include either a name, a short_name, or (preferably) both.

name is the full name of the app. It is used when there is room to display a longer name, such as in the app install banner and in the app’s launch screen.

If your app has a particularly long name, short_name gives you the chance to provide a shorter alternative to be used where there isn’t enough room to display the full name. The short name is used next to the app’s icon, in the task manager, and anywhere else where the full name doesn’t fit. Make sure the short_name isn’t longer than 15 characters so that it isn’t truncated on the homescreen.

Let’s look at an example. If your app’s full name is relatively short, you can feel free to provide it as either the short_name or the name and just ignore the other parameter. But if your app’s name is relatively long (e.g., Gotham Imperial Hotel), providing both the full name as well as a shorter alternative (e.g., Gotham Imperial), can ensure the device doesn’t truncate the app’s name automatically (showing “Gotham Imperial” is much better than “Gotham Imperial Hot…”).

start_url

The URL to open when the icon is clicked. This could be the root of your domain or even an internal page.

For the Gotham Imperial Hotel, we are using the My Account page as the first page shown when the app is launched from the homescreen, not the home page. We are also appending a utm_source=pwa tag to the querystring, which can be used by our Analytics software to track visitors that launch from the homescreen. If you do the same in your app, make sure your service worker knows how to match a request with or without the utm_source in the querystring (the code in “Implementing App Shell” properly matches these requests because it uses pathname which does not include the querystring).

icons

An array containing one or more objects, each describing an icon that the web app can use. Each of these objects contains the following attributes: src (an absolute or relative URL to the image), type (the file type), and sizes (the pixel dimensions of the image). For a web app install banner to trigger, the manifest must contain at least one icon which is at least 144 pixels x 144 pixels.

As each device will choose the icon size from this array that would look best in its screen resolution, it is recommended to have at least a 192 x 192 icon and a 512 x 512 icon to cover most devices and uses.

display

Controls the display mode the app launches in (Figure 9-3).

Possible values include the following:

• browser—open the app in the browser.

• standalone—open the app without the browser’s chrome (the browser’s user interface, such as the location bar).

• fullscreen—open the app without any of the browser or device’s chrome (e.g., on an Android device, this would mean hiding both the browser’s UI and the status bar at the top of the screen).

  To use the parlance of desktop apps, you can think of standalone and fullscreen as apps that open maximized or in full-screen mode, respectively, while browser behaves like any link clicked in the browser.

  For the web app install banner to show, the display property must be set to either fullscreen or standalone.

  

  Figure 9-3. Left to right: display modes browser, standalone, and fullscreen

In addition to the minimal set of attributes described above, the web app manifest also supports the following attributes:

description

A description of the app.

orientation

Lets you enforce a certain screen orientation. This can be useful if your app’s layout fits a portrait layout or a landscape layout better. For example, many games choose to enforce a landscape mode, while text-heavy apps often prefer portrait mode (Figure 9-4).

The most common possible values for orientation are:

• landscape

• portrait

• auto

Figure 9-4. A web app locked to the portrait orientation

theme_color

The theme color tells your browser and device to tint its UI to match your site (Figure 9-5). This color choice would affect things like the browser’s location bar, the color of your app in the task switcher, and even the color of your device’s status bar.

Figure 9-5. A site with a theme_color blending perfectly with the phone’s UI

The theme color can also be set by a page using a meta tag (e.g., <meta name="theme-color" content="#2196F3">). If a page has a theme-color meta tag, that setting will overwrite the theme_color set in the manifest. Note that while the meta tag lets you set, or overwrite, the theme color of individual pages, the theme_color setting in the manifest file affects your entire app.

background_color

This sets the color of your app’s splash screen and the app’s background color while it loads. Once loaded, any other background color defined in the page (through a stylesheet or inline with HTML tags) will overwrite this setting; but by setting this to the same color as your page’s background color, you can guarantee a smooth transition from the instant your app launches to when it is fully rendered. Not setting this color would cause your app to start with a white background, which is then replaced with your page’s background color.

scope

Defines the scope of the app. When the user is in a full-screen/standalone app and navigates to another URL that is within this scope, the URL opens within the fullscreen/standalone app. If, however, the user clicks a link that would take her to a destination outside of this scope, the link opens in a regular browser window.

For example, if we were to set "scope": "/my-account/", the user will remain in our app as long as she navigates within this scope (e.g., /my-acount/talater or /my-account?sort=date). But once she clicks a link that leads outside of this scope (e.g., /index.html or https://pwabook.com) it will open in the browser.

In some browsers, scope is also used to set the Android Intent Filter. When a web app is installed and scope is set, any link that points to a page within the app’s scope will launch the app instead of opening it in the browser. For example, if a user that has previously installed our progressive web app clicks a link from a travel review site to https://www.GothamImperial.com/my-account, the link will launch our app instead of showing that page in the browser.

dir

The direction in which to display the text in the name, short_name, and description parameters. By default, it adopts the browser’s language setting, but it can also be set to any of the following values:

• ltr—for left-to-right languages such as English and Portuguese

• rtl—for right-to-left languages such as Hebrew and Arabic

• auto—use the browser’s language setting

lang

Specify the main language of the text in the name, short_name, and description parameters.

Together with the dir parameter, it can be used to display text properly in any language, including right-to-left ones.

prefer_related_applications

If you also have a native app, and you prefer that the browser offer that instead of your shiny new progressive web app, you can set prefer_related_applications to true.

When set to true, and a native app for the current platform is listed in related_applications, an install banner for your native app will be shown instead of a web app install banner. A native app install banner has the same requirements of a web app install banner, except for depending on a service worker.

related_applications

This parameter accepts an array of “application objects.” Each object can include a platform (e.g., play, itunes), a url in which the application can be found, and the id used to represent it in the specified platform.

The following example defines related Android and iPhone apps and tells the browser to prefer showing a native app install banner over the web app install banner:

"related_applications": [
  {
    "platform": "play",
    "url": "https://play.google.com/store/apps/details?id=com.goth.app",
    "id": "com.goth.app"
  }, {
    "platform": "itunes",
    "url": "https://itunes.apple.com/app/gotham-imperial/id1234"
  }],
"prefer_related_applications": true

Backwards, Sideways, and Future Compatibility

The way your installed app’s icon is shown in Android differs greatly from the way it is shown in Windows 8 and 10, which differs greatly from how a newer MacBook Pro would show it on the Touch Bar. Even within a single platform, the icons may vary greatly based on screen resolution.

Each platform, browser, OS, and device shows your app and its icon differently.

Frankly, it is an ever-changing minefield.

It would be impractical to attempt to keep up with the changes and cover the requirements of each platform in this book. Luckily, there are a number of great online tools which help you deal with these complexities in an elegant way—you can find them listed on https://pwabook.com/appicons.

In addition to the manifest file added earlier in this chapter, the Gotham Imperial Hotel has already been configured with some of the more important settings needed for displaying icons across different platforms. You can see these in the <HEAD> of index.html, as well as in the following code:

<link rel="apple-touch-icon" sizes="180x180" href="/img/apple-touch-icon.png">
<link rel="icon" type="image/png" href="/img/favicon-32x32.png" sizes="32x32">
<link rel="icon" type="image/png" href="/img/favicon-16x16.png" sizes="16x16">
<link rel="shortcut icon" href="/favicon.ico">
<link rel="mask-icon" href="/img/safari-pinned-tab.svg" color="#a3915e">
<meta name="msapplication-config" content="/browserconfig.xml">
<meta name="theme-color" content="#242424">

These settings include icons for adding a homescreen shortcut to iPhones (apple-touch-icon), the trusty favicon (shown in the browser tab and bookmarks), a Safari pinned tab icon (mask-icon), and a link to a Microsoft application config file (msapplication-config) that determines how your app looks like when pinned on a Windows device. In addition, we define the theme-color one more time for older browsers that won’t read it from the manifest file.

Summary

What started a few years ago as a simple add shortcut to homescreen option hidden deep in the browser’s menu has since evolved to installable web apps.

These apps combine all the benefits of native while avoiding many of its downsides, including the brutal installation model, replacing it with one that progressively earns a spot on the user’s device.

But with great power comes great responsibility. If we want our apps to stand shoulder to shoulder with native apps, we need to consider the kind of experience we give our users. We will explore this in depth in Chapter 11.

But first, we will venture even further away from the browser as we explore push notifications in Chapter 10.