Chapter 85: Progressive Web Apps (PWAs)

PWA Installation & The beforeinstallprompt Event

Intercepting browser install heuristics, managing deferred prompts, designing custom in-app install flows, and tracking post-install analytics.

LEARNING OBJECTIVES ⌵

Understand the browser heuristics and criteria required to trigger the PWA installability flow.
Intercept the beforeinstallprompt event, cancel the default browser mini-infobar, and save the event object in memory.
Trigger the native OS installation dialog programmatically via deferredPrompt.prompt() and capture the user's decision using deferredPrompt.userChoice.
Track successful application installations using the appinstalled lifecycle event and CSS display-mode detection.

🎬 INTERACTIVE VISUAL PIPELINE Core Architecture Simulation

🌐

1. Input

Directives & Tags

⚙️

2. Parse

Tokenizer & AST

🌳

3. Layout

Box Model & Flow

🎨

4. Render

GPU Paint & Composite

PHASE 1: INPUT & DIRECTIVES

Browser receives declarative markup stream, parsing tag tokens and initializing component state.

📖 The Mental Model & Story (Intuitive Foundation)

Imagine browsing an online store. The moment you land on the homepage, a sales representative blocks your view with a clipboard, shouting: "Sign this lifetime membership contract right now!" You would immediately close the tab in frustration. However, if the representative waits until you have customized three items, added them to your cart, and expressed satisfaction before gently saying, "Would you like to install our app on your home screen for instant tracking and 1-tap checkout?", you are far more likely to accept.

Browsers historically showed an intrusive, automated banner (the "mini-infobar") the instant a site met basic PWA criteria.

Modern PWA architecture empowers frontend engineers to intercept that aggressive default banner (e.preventDefault()), stash the installation capability in memory, and present a beautifully branded, contextual in-app install button at the exact psychological moment of peak user delight (e.g., after completing a purchase, finishing a lesson, or creating a new document).

Technical Deep Dive & Specifications

Chromium PWA Installability Criteria

To trigger the beforeinstallprompt event, the application must satisfy strict browser heuristics:

+---------------------------------------------------------------------------------------+
|                          PWA INSTALLABILITY CRITERIA CHECKLIST                        |
+---------------------------------------------------------------------------------------+
| 1. Web App Manifest linked via <link rel="manifest">                                 |
| 2. Manifest includes: name / short_name, id, start_url, display (standalone/fullscreen)|
| 3. Manifest contains valid icons: at least 192x192 PNG and 512x512 PNG               |
| 4. Manifest includes a maskable icon (purpose: "maskable" or "any maskable")          |
| 5. Served over a Secure Context (HTTPS or http://localhost)                           |
| 6. Registered Service Worker with an active fetch event listener                      |
| 7. User Engagement Heuristic (User has spent >30 seconds on the page or interacted)   |
+---------------------------------------------------------------------------------------+

The `beforeinstallprompt` Lifecycle Flow

   BROWSER                           CLIENT DOM (UI)                     USER
      |                                     |                              |
      | 1. Checks PWA heuristics            |                              |
      |====================================>|                              |
      | 2. Fires 'beforeinstallprompt'      |                              |
      |------------------------------------>|                              |
      |                                     | [ Calls e.preventDefault() ] |
      |                                     | [ Stores e as deferredPrompt]|
      |                                     | [ Shows Custom Install UI ]  |
      |                                     |                              |
      |                                     | 3. User clicks "Install App" |
      |                                     |<=============================|
      |                                     |                              |
      | 4. deferredPrompt.prompt()          |                              |
      |<------------------------------------|                              |
      |                                     |                              |
      | 5. Shows Native OS Install Dialog   |                              |
      |===================================================================>|
      |                                     |                              |
      | 6. User clicks [Install] or [Cancel]|                              |
      |<===================================================================|
      |                                     |                              |
      | 7. Resolves deferredPrompt.userChoice                              |
      |    { outcome: 'accepted'|'dismissed'}|                             |
      |------------------------------------>|                              |
      |                                     |                              |
      | 8. Fires 'appinstalled' event       |                              |
      |------------------------------------>| [ Hides Install Button ]     |
      |                                     | [ Sends Telemetry Metric ]   |

Key Properties & Event Methods

API / Property	Type	Description
`event.preventDefault()`	Method	Cancels the default browser mini-infobar prompt.
`deferredPrompt.prompt()`	Method (Async)	Triggers the browser's native installation confirmation dialog.
`deferredPrompt.userChoice`	Promise	Resolves to an object: `{ outcome: 'accepted' \| 'dismissed', platform: string }`.
`window.addEventListener('appinstalled')`	Event	Dispatched once the OS finishes placing the app icon on the home screen or app launcher.

💻 Interactive Code Playground

Starter Code: Production Install Prompt Controller

Below is a complete, modular PWA installation manager with contextual UI presentation, outcome handling, and analytics logging.

Line-by-Line Code Breakdown

Line 87 (e.preventDefault()): Crucial method call that suppresses the browser's default mini-infobar, allowing you to orchestrate your own custom UI.
Line 90 (deferredPrompt = e): Stores the event reference in memory for later user-initiated execution.
Line 108 (await deferredPrompt.prompt()): Must be invoked from a user-initiated gesture (such as clicking the Install button); displays the operating system's native installation confirmation modal.
Line 111 (const { outcome } = await deferredPrompt.userChoice): Resolves when the user either clicks "Install" (outcome === 'accepted') or "Cancel" (outcome === 'dismissed').
Line 126 (window.addEventListener('appinstalled')): Dispatched by the browser immediately after the OS registers the PWA icon.

Expected Browser Render Output

SYS: ACTIVE

HULL: 98%

CORE: STABLE

NET: ONLINE

HTML STARSHIP CODE TERMINAL playground.html

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <meta name="theme-color" content="#4338ca">
  <title>PWA Installation Showcase</title>
  <link rel="manifest" href="manifest.webmanifest">
  <style>
    :root {
      --primary: #4338ca;
      --primary-hover: #3730a3;
      --bg: #0f172a;
      --surface: #1e293b;
      --text: #f8fafc;
    }
    body {
      font-family: system-ui, sans-serif;
      background-color: var(--bg);
      color: var(--text);
      margin: 0;
      padding: 2rem;
      display: flex;
      justify-content: center;
    }
    .container { max-width: 600px; width: 100%; }
    .card { background: var(--surface); border-radius: 12px; padding: 1.5rem; border: 1px solid #334155; margin-bottom: 1.5rem; }
    
    /* Custom Install Banner Component */
    .install-banner {
      display: none; /* Hidden until beforeinstallprompt fires */
      background: linear-gradient(135deg, #1e1b4b, #312e81);
      border: 1px solid #6366f1;
      border-radius: 12px;
      padding: 1.25rem;
      align-items: center;
      justify-content: space-between;
      margin-bottom: 1.5rem;
      box-shadow: 0 10px 25px -5px rgba(99, 102, 241, 0.3);
    }
    .install-banner.visible { display: flex; }
    .install-info { display: flex; align-items: center; gap: 1rem; }
    .app-icon { width: 48px; height: 48px; background: #6366f1; border-radius: 10px; display: flex; align-items: center; justify-content: center; font-size: 1.5rem; }
    
    .btn {
      background: #6366f1;
      color: white;
      border: none;
      padding: 0.6rem 1.2rem;
      border-radius: 8px;
      font-weight: bold;
      cursor: pointer;
      transition: background 0.2s;
    }
    .btn:hover { background: #4f46e5; }
    .btn-secondary { background: transparent; border: 1px solid #475569; color: #94a3b8; margin-right: 0.5rem; }
    .btn-secondary:hover { background: #334155; }
    .log-box { background: #020617; padding: 1rem; border-radius: 8px; font-family: monospace; font-size: 0.85rem; color: #38bdf8; max-height: 150px; overflow-y: auto; }
  </style>
</head>
<body>
  <div class="container">
    <header>
      <h1>PWA Installation Flow</h1>
      <p>Demonstrating deferred prompts and install telemetry.</p>
    </header>

<aside id="install-banner" class="install-banner" aria-label="Install App Banner">
      <div class="install-info">
        <div class="app-icon">🚀</div>
        <div>
          <strong style="display:block;">Orbit Productivity</strong>
          <small style="color: #cbd5e1;">Install on your desktop or homescreen</small>
        </div>
      </div>
      <div>
        <button id="btn-dismiss" class="btn btn-secondary">Later</button>
        <button id="btn-install" class="btn">Install App</button>
      </div>
    </aside>

<div class="card">
      <h2>Install Lifecycle Event Log</h2>
      <div id="event-log" class="log-box">Waiting for browser heuristics...</div>
    </div>
  </div>

// 1. Intercept beforeinstallprompt
    window.addEventListener('beforeinstallprompt', (e) => {
      // Prevent the default mini-infobar from appearing on mobile
      e.preventDefault();
      
      // Stash the event so it can be triggered later
      deferredPrompt = e;
      logEvent('Captured "beforeinstallprompt" event. Default banner prevented.');

// Check if user previously dismissed prompt in this session
      if (!sessionStorage.getItem('pwa_prompt_dismissed')) {
        installBanner.classList.add('visible');
        logEvent('Custom in-app install banner displayed to user.');
      }
    });

// 2. Handle Custom Install Button Click
    btnInstall.addEventListener('click', async () => {
      if (!deferredPrompt) {
        logEvent('No active install prompt available.');
        return;
      }

// Hide the promotional UI
      installBanner.classList.remove('visible');

// Show the native browser prompt dialog
      logEvent('Triggering deferredPrompt.prompt()...');
      await deferredPrompt.prompt();

// Wait for the user to respond to the prompt
      const { outcome, platform } = await deferredPrompt.userChoice;
      logEvent(`User response outcome: "${outcome}" on platform: "${platform}"`);

// We've used the prompt, so clear it
      deferredPrompt = null;
    });

// 3. Handle User Dismissal
    btnDismiss.addEventListener('click', () => {
      installBanner.classList.remove('visible');
      sessionStorage.setItem('pwa_prompt_dismissed', 'true');
      logEvent('User dismissed install banner for this session.');
    });

// 4. Listen for Successful Installation
    window.addEventListener('appinstalled', (evt) => {
      installBanner.classList.remove('visible');
      deferredPrompt = null;
      logEvent('🎉 Application successfully installed to the operating system!');
      // Dispatch telemetry event to server/analytics
    });
  </script>
</body>
</html>

LIVE RENDER & DIAGNOSTICS CORE TEMP: 45°C

INSPECTING DOM: VALID

TAGS: SCANNING...

PWA Installation Flow
Demonstrating deferred prompts and install telemetry.

+-------------------------------------------------------------------+
| [🚀] Orbit Productivity                               [ Later ]   |
|      Install on your desktop or homescreen            [ Install ] |
+-------------------------------------------------------------------+

Install Lifecycle Event Log
[02:45:10] Captured "beforeinstallprompt" event. Default banner prevented.
[02:45:10] Custom in-app install banner displayed to user.
(User clicks Install -> Native OS Dialog appears -> User clicks Confirm):
[02:45:18] Triggering deferredPrompt.prompt()...
[02:45:21] User response outcome: "accepted" on platform: "web"
[02:45:22] 🎉 Application successfully installed to the operating system!

🏋️ Hands-On Exercise

🎯 The Challenge: Build a Header-Integrated PWA Install Trigger

Instructions:

Create a navigation header with an "Install App" button that remains hidden by default (display: none).
Listen for the beforeinstallprompt event, prevent default behavior, and reveal the header button.
When the user clicks the button, call prompt(), evaluate userChoice, and log whether the user accepted or rejected the installation.
Hide the button permanently if the user installs the app or if appinstalled fires.

🏁 Starter Code Sandbox

SYS: ACTIVE

HULL: 98%

CORE: STABLE

NET: ONLINE

STARTER CODE SANDBOX exercise.html

LIVE RENDER & DIAGNOSTICS CORE TEMP: 45°C

INSPECTING DOM: VALID

TAGS: SCANNING...

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>Header Install Challenge - Solved</title>
  <style>
    body { font-family: system-ui, sans-serif; margin: 0; background: #0f172a; color: white; }
    header { display: flex; justify-content: space-between; align-items: center; padding: 1rem 2rem; background: #1e293b; }
    #header-install-btn { display: none; background: #10b981; color: white; border: none; padding: 0.5rem 1rem; border-radius: 6px; font-weight: bold; cursor: pointer; transition: background 0.2s; }
    #header-install-btn:hover { background: #059669; }
  </style>
</head>
<body>
  <header>
    <h2>CloudDesk PWA</h2>
    <button id="header-install-btn">📥 Install CloudDesk</button>
  </header>

  <main style="padding: 2rem;">
    <p>Use CloudDesk in your browser or install it as a native desktop application.</p>
  </main>

  <script>
    let installPrompt = null;
    const installBtn = document.getElementById('header-install-btn');

    // 1. Capture and reveal
    window.addEventListener('beforeinstallprompt', (e) => {
      e.preventDefault();
      installPrompt = e;
      installBtn.style.display = 'inline-flex';
    });

    // 2. Prompt execution on user gesture
    installBtn.addEventListener('click', async () => {
      if (!installPrompt) return;

      installBtn.disabled = true;
      await installPrompt.prompt();
      const choice = await installPrompt.userChoice;

      console.log(`[PWA Install] Outcome: ${choice.outcome}`);
      if (choice.outcome === 'accepted') {
        installBtn.style.display = 'none';
      } else {
        installBtn.disabled = false;
      }
      installPrompt = null;
    });

    // 3. Post-install cleanup
    window.addEventListener('appinstalled', () => {
      installBtn.style.display = 'none';
      installPrompt = null;
      console.log('[PWA Install] CloudDesk registered as installed OS application.');
    });
  </script>
</body>
</html>

Why this works:

Hiding the install button by default ensures that users on unsupported browsers (or users who already installed the PWA) never see a broken, non-functional button.
The prompt is only invoked directly from the button click event handler, satisfying browser security requirements for user gestures.

⚠️ Common Pitfalls

Calling prompt() Outside a User Gesture: Attempting to call deferredPrompt.prompt() inside a setTimeout() or immediately inside the beforeinstallprompt listener will throw a DOMException: The prompt() method must be called with a user gesture.
Reusing the Same deferredPrompt Object Twice: The beforeinstallprompt event is single-use. Once prompt() is called, the event object is consumed. If the user dismisses the dialog, you must wait for the browser to dispatch a new beforeinstallprompt event before calling prompt() again.
Assuming beforeinstallprompt Fires on iOS Safari: Apple WebKit on iOS does NOT support the beforeinstallprompt event. For iOS users, you must display instructional UI explaining how to tap the Safari "Share" button followed by "Add to Home Screen".

💡 Pro Tips

Detect Installed State on App Launch: Always check window.matchMedia('(display-mode: standalone)').matches on initialization. If true, the user is already inside the installed application, so you should completely disable all install promotional logic.
Contextual In-App Triggers Over Top Banners: Conversion rates increase significantly when install buttons are placed contextually (e.g., "Install offline music player" next to a download button) rather than using generic global banners across the top of the viewport.

📌 Key Takeaways

The browser fires beforeinstallprompt when the site meets all PWA installability criteria.
Call e.preventDefault() inside beforeinstallprompt to suppress the browser's default mini-infobar and retain the event in memory.
Call deferredPrompt.prompt() inside a user click handler to show the native OS installation dialog.
Inspect deferredPrompt.userChoice to capture whether the user accepted or dismissed the prompt.
The appinstalled event fires when the operating system successfully registers the PWA icon.
--

⭐ LEARN: HTML 🌟 ⚔️ QUIZ BATTLE ARENA // ACTIVE

? Question 1 / 3

What must frontend code do inside the `beforeinstallprompt` event handler to prevent the browser's default mini-infobar from appearing?

Topic: HTML Fundamentals

? Question 2 / 3

Under what constraint MUST `deferredPrompt.prompt()` be called by client JavaScript?

Topic: HTML Fundamentals

? Question 3 / 3

Which browser platform does NOT support the `beforeinstallprompt` event and requires manual user instructions for "Add to Home Screen"?

Topic: HTML Fundamentals

👨‍🚀 CADET FLIGHT DOSSIER

CADET EXPLORER

📖 The Mental Model & Story (Intuitive Foundation)

Technical Deep Dive & Specifications

Chromium PWA Installability Criteria

The beforeinstallprompt Lifecycle Flow

Key Properties & Event Methods

💻 Interactive Code Playground

Starter Code: Production Install Prompt Controller

Line-by-Line Code Breakdown

Expected Browser Render Output

🏋️ Hands-On Exercise

🎯 The Challenge: Build a Header-Integrated PWA Install Trigger

🏁 Starter Code Sandbox

⚠️ Common Pitfalls

💡 Pro Tips

📌 Key Takeaways

What must frontend code do inside the beforeinstallprompt event handler to prevent the browser's default mini-infobar from appearing?

Under what constraint MUST deferredPrompt.prompt() be called by client JavaScript?

Which browser platform does NOT support the beforeinstallprompt event and requires manual user instructions for "Add to Home Screen"?

The `beforeinstallprompt` Lifecycle Flow

What must frontend code do inside the `beforeinstallprompt` event handler to prevent the browser's default mini-infobar from appearing?

Under what constraint MUST `deferredPrompt.prompt()` be called by client JavaScript?

Which browser platform does NOT support the `beforeinstallprompt` event and requires manual user instructions for "Add to Home Screen"?