pwa install prompt flow

Have you ever wondered how web applications can ask users to install them on their devices? It's a common request in Progressive Web Apps (PWAs), but did you know that it requires a specific flow of events and some technical trickery? In this article, we'll dive into the PWA install prompt flow, exploring its ins and outs, including best practices and edge cases.

The Technique

The PWA install prompt is triggered by the beforeinstallprompt event. This event is dispatched to the global object (usually a JavaScript file) when the browser determines that your web app meets certain criteria, such as being served over HTTPS and having a manifest file with a valid icon.

To use this feature, you need to add an event listener for the beforeinstallprompt event on the window object. When triggered, you can choose to defer or cancel the prompt, or show it immediately.

window.addEventListener('beforeinstallprompt', (e) => {
  // Handle the event here
});

Defering the Prompt

One of the most common use cases for the PWA install prompt is to allow users to interact with your web app before showing them the install prompt. This can be achieved by deferring the prompt using the preventDefault() method.

window.addEventListener('beforeinstallprompt', (e) => {
  e.preventDefault();
  // Show a custom UI or perform other actions here
});

Custom UI

To create a more seamless user experience, you can show a custom UI while deferring the prompt. This could be an overlay with a "Get Started" button that takes users to your app's main page.

window.addEventListener('beforeinstallprompt', (e) => {
  e.preventDefault();
  const getStartedButton = document.getElementById('get-started');
  getStartedButton.addEventListener('click', () => {
    window.deferredPrompt.prompt();
  });
});

iOS Safari Special Case

iOS Safari has some special requirements for showing the PWA install prompt. You need to add a meta tag with name set to apple-mobile-web-app-capable and content set to yes. This tells the browser that your app is capable of running in standalone mode.

<meta name="apple-mobile-web-app-capable" content="yes">

Concrete Examples

Example 1: Simple Install Prompt

This example shows a simple PWA install prompt without any customization.

window.addEventListener('beforeinstallprompt', (e) => {
  e.preventDefault();
  window.deferredPrompt.prompt();
});

Example 2: Custom UI with Get Started Button

In this example, we show a custom UI with a "Get Started" button that takes users to the app's main page.

window.addEventListener('beforeinstallprompt', (e) => {
  e.preventDefault();
  const getStartedButton = document.getElementById('get-started');
  getStartedButton.addEventListener('click', () => {
    window.deferredPrompt.prompt();
  });
});

Example 3: Deferred Prompt with Overlay

This example shows a deferred prompt with an overlay that blocks the rest of the page.

window.addEventListener('beforeinstallprompt', (e) => {
  e.preventDefault();
  const overlay = document.createElement('div');
  overlay.id = 'overlay';
  overlay.style.position = 'fixed';
  overlay.style.top = '0px';
  overlay.style.left = '0px';
  overlay.style.width = '100%';
  overlay.style.height = '100%';
  overlay.style.background = 'rgba(0, 0, 0, 0.5)';
  document.body.appendChild(overlay);
});

When NOT to Use It

While the PWA install prompt is a powerful tool for getting users to install your app, there are some cases where you should avoid using it:

• If your app is not served over HTTPS, the browser will not trigger the beforeinstallprompt event.
• If your manifest file does not have a valid icon or other required fields, the prompt will not be shown.
• On iOS Safari, if you do not add the required meta tag, the prompt will not work.

Related Apiary Lessons

If you're interested in learning more about PWAs and their features, check out our other articles on:

• Building a Progressive Web App
• PW A Manifest File
• PW A Install Prompt

Conclusion

In this article, we explored the PWA install prompt flow, including best practices and edge cases. From deferring the prompt to showing a custom UI, you now have the tools to create a seamless user experience for your web app users. Remember to follow the requirements for iOS Safari and test your implementation on different devices.

As the bees say: "A PWA is like a honeycomb – it's all about creating a sweet experience for your users!"