Add smart install prompt for supported browsers

2026-05-06 09:05:00 -04:00
parent f383339465
commit 7e0699d5bd
3 changed files with 156 additions and 0 deletions
@@ -0,0 +1,107 @@
+// Browser-aware install UX for supported PWAs.
+// Shows a real install button only when the browser exposes the install prompt,
+// and falls back to platform-specific instructions for iOS Safari.
+(function () {
+    'use strict';
+
+    const installBtn = document.getElementById('installAppBtn');
+    if (!installBtn) return;
+
+    const ua = navigator.userAgent || '';
+    const isIos = /iphone|ipad|ipod/i.test(ua);
+    const isIosSafari = isIos && /safari/i.test(ua) && !/crios|fxios|edgios/i.test(ua);
+
+    let deferredPrompt = null;
+
+    function isStandalone() {
+        return window.matchMedia('(display-mode: standalone)').matches || window.navigator.standalone === true;
+    }
+
+    function hideInstallButton() {
+        installBtn.classList.add('d-none');
+        installBtn.dataset.installKind = '';
+    }
+
+    function showInstallButton(kind, label, iconClass) {
+        installBtn.dataset.installKind = kind;
+        installBtn.classList.remove('d-none');
+        installBtn.querySelector('.install-label').textContent = label;
+        installBtn.querySelector('i').className = `bi ${iconClass}`;
+        installBtn.setAttribute('aria-label', label);
+        installBtn.title = label;
+    }
+
+    function showHelpModal(title, message, stepsHtml) {
+        const modalEl = document.getElementById('installHelpModal');
+        const modalTitleEl = document.getElementById('installHelpModalLabel');
+        const modalMessageEl = document.getElementById('installHelpMessage');
+        const modalStepsEl = document.getElementById('installHelpSteps');
+
+        if (!modalEl || !modalTitleEl || !modalMessageEl || !modalStepsEl) return;
+
+        modalTitleEl.textContent = title;
+        modalMessageEl.textContent = message;
+        modalStepsEl.innerHTML = stepsHtml;
+        bootstrap.Modal.getOrCreateInstance(modalEl).show();
+    }
+
+    function refreshInstallUi() {
+        if (isStandalone()) {
+            hideInstallButton();
+            return;
+        }
+
+        if (deferredPrompt) {
+            showInstallButton('prompt', 'Install App', 'bi-download');
+            return;
+        }
+
+        if (isIosSafari) {
+            showInstallButton('ios', 'Add to Home Screen', 'bi-box-arrow-down');
+            return;
+        }
+
+        hideInstallButton();
+    }
+
+    window.addEventListener('beforeinstallprompt', function (event) {
+        event.preventDefault();
+        deferredPrompt = event;
+        refreshInstallUi();
+    });
+
+    window.addEventListener('appinstalled', function () {
+        deferredPrompt = null;
+        hideInstallButton();
+    });
+
+    window.matchMedia('(display-mode: standalone)').addEventListener?.('change', refreshInstallUi);
+
+    installBtn.addEventListener('click', async function () {
+        const kind = installBtn.dataset.installKind;
+
+        if (kind === 'prompt' && deferredPrompt) {
+            deferredPrompt.prompt();
+
+            try {
+                await deferredPrompt.userChoice;
+            } catch {
+                // Ignore prompt result errors; the browser owns the final install flow.
+            }
+
+            deferredPrompt = null;
+            refreshInstallUi();
+            return;
+        }
+
+        if (kind === 'ios') {
+            showHelpModal(
+                'Add to Home Screen',
+                'Safari on iPhone and iPad installs web apps from the Share menu.',
+                'Tap <strong>Share</strong> in Safari, then choose <strong>Add to Home Screen</strong>.'
+            );
+        }
+    });
+
+    refreshInstallUi();
+})();