Web App Manifest & Installability

Concept#

The Web App Manifest (manifest.json)#

A Web App Manifest is a simple JSON file that tells the browser about your web application and how it should behave when installed on the user's desktop or mobile device.

To register the manifest, link it in the HTML head:

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

Core Manifest Properties#

{
  "short_name": "eLearn",
  "name": "eLearn Advanced Coding Academy",
  "description": "Learn advanced coding concepts interactively.",
  "icons": [
    {
      "src": "/icons/icon-192.png",
      "type": "image/png",
      "sizes": "192x192",
      "purpose": "any maskable"
    }
  ],
  "start_url": "/?source=pwa",
  "display": "standalone",
  "background_color": "#09090b",
  "theme_color": "#4F46E5"
}

Key attributes:

• display: Defines the window display mode. standalone removes browser address bars and navigation buttons, making the app look like a native application.
• icons: Array of app icons. maskable icons ensure the device OS can crop/shape the icon border safely.
• start_url: The path loaded when the user launches the installed app.

Browser Install Criteria#

For a browser (like Chrome) to trigger the native Add to Home Screen installation prompt, the app must satisfy strict criteria:

1. Linked valid manifest.json.
2. Served over secure HTTPS.
3. Registered Service Worker with a fetch handler.
4. Have at least one 192x192 or 512x512 pixel icon.

Common Mistakes#

1. Hardcoding the start_url to a static dynamic path#

If you set start_url: "/dashboard/settings", the app will load the settings panel instead of the home page on launch, confusing users. Set it to the root path: "/" or "/?source=pwa".

2. Not providing maskable icons#

If your manifest does not define purpose: "any maskable" for circular icons, Android devices will render the icon inside an ugly white border box instead of cropping it semantic-ly.

Best Practices#

• Capture the beforeinstallprompt event: Intercept the browser's default install prompt and render a custom, styled in-app "Install App" button instead:

  let deferredPrompt;
  window.addEventListener('beforeinstallprompt', (e) => {
    e.preventDefault(); // Stop prompt
    deferredPrompt = e; // Save event
    showCustomInstallButton();
  });

• Configure Theme Color: Set theme_color to match your application's header or brand color to dye the mobile device's status bar.
• Append Source Tracking: Add ?source=pwa to the to track PWA usage metrics inside Google Analytics.