Promoting Your Vue.js PWA Installation

Installing your web application into the user’s devices

Photo by Rob Hampson on Unsplash

Did you ever make your Progressive Web Application (PWA) possible to be installed on a phone or desktop device? Well, it is possible and effortless to achieve, especially if we are using Vue.js.

Using Vue CLI, we only need to choose the right features when creating a project, and everything is automatically set up for us. If you already have a project running that is not a problem, the plugin can be added whenever we want.

Once a user installs your PWA, it can be run like any other native app.

Why would I want a user to install my PWA?

The same reason you’d want a user to install your app from any app store. Users who install are your most engaged users. Users who install a PWA have better engagement metrics than casual visitors, including more repeat visits, longer time on site and higher conversion rates, often at parity with native app users on mobile devices. — web.dev

Criteria

To be able to install a PWA, some rules must be fulfilled. Some of those rules are:

• The web app not being installed already;
• Be served over HTTPS;
• Include a Web App Manifest;

Different browsers have similar criteria, although minor differences can exist.

Using Vue CLI, we can get it working without doing any code. Let’s try it.

Create the Project

Start by creating a new project using Vue CLI with PWA support.

vue create your-project-name

To answer the first question, pick “Manually select features” …

Manual select features

… which will allow us to enable PWA support.

Enable Progress Web App (PWA) Support

The next questions answer as you like. It won’t have any impact on the experiment that we are doing here.

The installation of the application can not be accomplished in development mode, so to test it, we need to create a distribution build and then serve it using a simple HTTP server.

# enter inside the project
cd your-project-name
# create a production build
yarn build # or npm run build
# enter inside the build generated
cd dist/
# run the application
npx http-server

Note that when we create the production build, a dist folder is generated in the root of the project and inside this folder, between others, a file named manifest.json , one of the requirements to install the app. To customize its values, check the documentation of the plugin documentation.

Now, if we open http://localhost:8080/ in our browser, we can see the default template generated by the Vue CLI. To Google Chrome, the localhost is considered a secure domain, so another requirement is already being fulfilled.

Here we have two ways to trigger a pop-up that asks us if we want to install the application:

1. Clicking the in the three dots vertical icon in the top right corner of Chome and then in “Install your-project-name”;

1. Clicking in the install icon inside the navigation bar.

Without writing any code, we already have a PWA that can be installed in a mobile or desktop device. However, it is not likely that most users will use these options to install the application.

With a little customization, we can promote the installation of our application inside the web app itself to have more people using it as a native app.

Let’s customize it! 📝

Customization

First, let’s add Vuetify (an awesome UI library) to the project to create a promoting banner to install the application:

vue add vuetify

When it asks to choose a preset, pick the Default (recommended) for this experiment.

Once Vuetify is installed, open the App.vue file and replace its content by:

<template>
  <div id="app">
    <v-app>
      <v-banner
        v-if="deferredPrompt"
        color="info"
        dark
        class="text-left"
      >
        Get our free app. It won't take up space on your phone and also works offline!
        
        <template v-slot:actions>
          <v-btn text @click="dismiss">Dismiss</v-btn>
          <v-btn text @click="install">Install</v-btn>
        </template>
      </v-banner>
<div class="pa-4 text-center">
        <img alt="Vue logo" src="./assets/logo.png" />
        <h1>Customize Your Vue.js PWA Installation</h1>
      </div>
    </v-app>
  </div>
</template>
<script>
export default {
  name: "App",
  data() {
    return {
      deferredPrompt: null
    };
  },
  created() {
    window.addEventListener("beforeinstallprompt", e => {
      e.preventDefault();
      // Stash the event so it can be triggered later.
      this.deferredPrompt = e;
    });
window.addEventListener("appinstalled", () => {
      this.deferredPrompt = null;
    });
  },
  methods: {
    async dismiss() {
      this.deferredPrompt = null;
    },
    async install() {
      this.deferredPrompt.prompt();
    }
  }
};
</script>

Now, if we build and run the application (you may need to force a cache refresh CRTL + F5) …

yarn build
cd dist
npx http-server

… we see a page with a promoting banner informing us that we can install this application in our device. To prompt the pop-up to install the app, we just click on the “Install” button or dismiss it by clicking in the “Dismiss” button.

Promotion banner to install the application

Install

Clicking in the install button and then confirming it will open a native application without the banner. Even if we refresh it, the banner won’t appear because one item of the criteria is not being fulfilled: “The web app not being installed already.”. Once we uninstall the application, the banner will appear again.

Native application

Dismiss

When we click on the dismiss button, the banner disappears, but if we refresh the page, it will appear again. Considering that this is not user friendly, let’s make the banner appear again only 15 days after the user clicks in the dismiss button.

First, let’s add to the project a little library to help us handle cookies …

yarn add -D js-cookie

… and then, import it in our App.vue

...
<script>
import Cookies from "js-cookie";
export default {
  name: "App",
...

Now, let’s change the dismiss function to create a cookie that expires in 15 days. The value of the cookie is not important here, just its existence.

...
async dismiss() {
  Cookies.set("add-to-home-screen", null, { expires: 15 });
  this.deferredPrompt = null;
},
...

To finalize, we change the event listener that stashes the event to do it only if the cookie does not exist or expired:

window.addEventListener("beforeinstallprompt", e => {
  e.preventDefault();
  // Stash the event so it can be triggered later.
  if (Cookies.get("add-to-home-screen") === undefined) {
    this.deferredPrompt = e;
  }
});

And it is done! Now we can click in the dismiss button and refresh the application. The banner won’t be visible.

Notes

Even without promoting the installation of our applications, users can do it if we follow all the criteria defined by the browsers. However, not many users will do it so, promoting the installation of your application is essential.

To have a deeper understanding of how to make a PWA installable, how to create a custom install experience and what are the best patterns to promote it, I advise you to check the web.dev website.

Source code available in Github.