Chapter 85: Progressive Web Apps (PWAs)

App Shortcuts & Badging API

Enhancing native OS integration with dynamic app icon badges and manifest-driven contextual Quick Action menus.

LEARNING OBJECTIVES ⌵

Configure the shortcuts array in manifest.webmanifest to expose OS right-click / long-press Quick Action context menus.
Implement the Badging API using navigator.setAppBadge() and navigator.clearAppBadge() to indicate unread notifications.
Update app icon badges directly from the Service Worker background thread in response to incoming Web Push notifications.
Design seamless deep-linking navigation flows for app shortcut targets with specialized launch query parameters.

🎬 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)

Think about how you interact with native messaging and email apps on your smartphone or desktop:

When you glance at your phone's home screen or your computer's dock/taskbar, you don't have to open the email app to see if you have unread messages. A little red badge with the number "5" sits directly on the app icon (The Badging API).
When you want to immediately compose a message or scan a QR code, you don't launch the app, wait for the home screen to load, and navigate through three nested menus. Instead, you long-press the app icon on Android/iOS or right-click the taskbar icon on Windows/macOS, and a popup menu appears with direct shortcuts: "New Chat", "Scan Code", or "My Orders" (App Shortcuts).

Historically, web applications had no way to display numeric indicators on the operating system taskbar or provide contextual OS jump lists. The Badging API and App Shortcuts API bridge this gap, giving PWAs identical desktop and mobile launcher capabilities to native Swift, Kotlin, and C# apps.

Technical Deep Dive & Specifications

App Shortcuts in the Web App Manifest

The shortcuts member is an array of objects defined within manifest.webmanifest. Operating systems render these shortcuts when the user long-presses the home screen icon on mobile or right-clicks the pinned taskbar icon on desktop:

                  +----------------------------------------------+
                  |           OS APP ICON CONTEXT MENU           |
                  +----------------------------------------------+
                  |  [🚀 Orbit Task Manager]                     |
                  +----------------------------------------------+
                  |  📝 New Task          (/tasks/new?src=quick) |
                  |  🔍 Search Inbox      (/search?src=quick)    |
                  |  📊 View Analytics    (/stats?src=quick)     |
                  +----------------------------------------------+
                  |  App Info / Uninstall                        |
                  +----------------------------------------------+

{
  "name": "Orbit Task Manager",
  "short_name": "Orbit",
  "start_url": "/dashboard.html",
  "display": "standalone",
  "shortcuts": [
    {
      "name": "Create New Task",
      "short_name": "New Task",
      "description": "Directly open the new task composer",
      "url": "/tasks/new.html?shortcut=create",
      "icons": [{ "src": "/icons/shortcut-new.png", "sizes": "96x96" }]
    },
    {
      "name": "Search Records",
      "short_name": "Search",
      "description": "Instant search across all project items",
      "url": "/search.html?shortcut=search",
      "icons": [{ "src": "/icons/shortcut-search.png", "sizes": "96x96" }]
    }
  ]
}

The Badging API Specification

The Badging API operates on the navigator object in window contexts and on the self.navigator object inside Service Worker global scopes.

+-----------------------------------------------------------------------------------+
|                                 THE BADGING API                                   |
+-----------------------------------------------------------------------------------+
|  1. Numeric Badge: navigator.setAppBadge(42)                                      |
|     --> Displays "[ 42 ]" badge on dock/taskbar icon                              |
|                                                                                   |
|  2. Unflagged / Generic Dot: navigator.setAppBadge()                              |
|     --> Displays a solid notification dot on platforms that don't support numbers|
|                                                                                   |
|  3. Clear Badge: navigator.clearAppBadge() or navigator.setAppBadge(0)           |
|     --> Completely removes the badge from the application icon                    |
+-----------------------------------------------------------------------------------+

Method	Context	Parameters	Return Type	Description
`navigator.setAppBadge(count?)`	Window & Service Worker	`count` (Optional integer >= 1)	`Promise<void>`	Sets a numeric badge or generic flag on the app icon.
`navigator.clearAppBadge()`	Window & Service Worker	None	`Promise<void>`	Removes the current badge from the app icon.

💻 Interactive Code Playground

Starter Code: Dynamic Badging & Shortcut Handler

Below is a complete application demonstrating interactive badging controls, task counts, and shortcut URL parameter detection.

Line-by-Line Code Breakdown

Line 72–77 (new URLSearchParams(window.location.search)): Parses query strings (e.g. ?shortcut=create) passed when the user taps an OS shortcut context menu item, routing the user to the designated sub-view.
Line 81 ('setAppBadge' in navigator): Feature-detects Badging API support before making method calls.
Line 84 (await navigator.setAppBadge(count)): Asynchronously instructs the OS desktop shell (Windows Explorer, macOS Dock, Android Launcher) to draw the numeric overlay on the installed icon.
Line 87 (await navigator.clearAppBadge()): Removes any existing badge or indicator from the icon.
Line 101 (await navigator.setAppBadge()): Calling without arguments renders an uncounted notification flag/dot on platforms that support dot indicators.

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="#0d9488">
  <title>PWA Badging & Shortcuts</title>
  <link rel="manifest" href="manifest.webmanifest">
  <style>
    :root {
      --primary: #0d9488;
      --bg: #0f172a;
      --card-bg: #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;
    }
    .wrapper { max-width: 600px; width: 100%; }
    .card { background: var(--card-bg); border-radius: 12px; padding: 1.5rem; border: 1px solid #334155; margin-bottom: 1.5rem; }
    .btn-group { display: flex; gap: 0.5rem; flex-wrap: wrap; margin-top: 1rem; }
    button {
      background: var(--primary);
      color: white;
      border: none;
      padding: 0.6rem 1.2rem;
      border-radius: 6px;
      font-weight: bold;
      cursor: pointer;
    }
    button:hover { background: #0f766e; }
    .btn-danger { background: #ef4444; }
    .btn-danger:hover { background: #dc2626; }
    .badge-preview {
      display: inline-flex;
      align-items: center;
      justify-content: center;
      background: #ef4444;
      color: white;
      font-weight: bold;
      border-radius: 9999px;
      min-width: 24px;
      height: 24px;
      padding: 0 6px;
      font-size: 0.85rem;
    }
    .shortcut-alert {
      background: #134e4a;
      border: 1px solid #2dd4bf;
      color: #ccfbf1;
      padding: 1rem;
      border-radius: 8px;
      margin-bottom: 1rem;
      display: none;
    }
  </style>
</head>
<body>
  <div class="wrapper">
    <header>
      <h1>App Badging & Shortcuts</h1>
      <p>Managing OS-level taskbar indicators and deep-link launcher shortcuts.</p>
    </header>

<div id="shortcut-banner" class="shortcut-alert">
      ⚡ Launched via OS Quick Action: <strong id="shortcut-action">None</strong>
    </div>

<div class="card">
      <h2>Unread Notification Counter</h2>
      <p>Current Unread Count: <span id="count-display" class="badge-preview">0</span></p>
      <div class="btn-group">
        <button id="btn-inc">Add Notification (+1)</button>
        <button id="btn-flag">Set Dot Flag</button>
        <button id="btn-clear" class="btn-danger">Clear Badge</button>
      </div>
    </div>
  </div>

// 1. Detect App Shortcut Launch Parameter
    const urlParams = new URLSearchParams(window.location.search);
    const shortcutParam = urlParams.get('shortcut');
    if (shortcutParam) {
      banner.style.display = 'block';
      actionText.textContent = shortcutParam.toUpperCase();
    }

// 2. Badging API Wrappers
    async function updateBadge(count) {
      countDisplay.textContent = count;
      if ('setAppBadge' in navigator) {
        try {
          if (count > 0) {
            await navigator.setAppBadge(count);
            console.log(`[Badging] App badge set to ${count}`);
          } else {
            await navigator.clearAppBadge();
            console.log('[Badging] App badge cleared');
          }
        } catch (err) {
          console.error('[Badging] Error setting badge:', err);
        }
      } else {
        console.log('[Badging] Badging API is not supported on this platform.');
      }
    }

document.getElementById('btn-inc').addEventListener('click', () => {
      unreadCount++;
      updateBadge(unreadCount);
    });

document.getElementById('btn-flag').addEventListener('click', async () => {
      if ('setAppBadge' in navigator) {
        await navigator.setAppBadge(); // Undefined count = generic dot/flag
        countDisplay.textContent = '●';
        console.log('[Badging] Generic flag badge set.');
      }
    });

document.getElementById('btn-clear').addEventListener('click', () => {
      unreadCount = 0;
      updateBadge(0);
    });
  </script>
</body>
</html>

LIVE RENDER & DIAGNOSTICS CORE TEMP: 45°C

INSPECTING DOM: VALID

TAGS: SCANNING...

App Badging & Shortcuts
Managing OS-level taskbar indicators and deep-link launcher shortcuts.

[ ⚡ Launched via OS Quick Action: CREATE ]

Unread Notification Counter
Current Unread Count: [ 3 ]
[ Add Notification (+1) ] [ Set Dot Flag ] [ Clear Badge ]

(On Windows Taskbar / macOS Dock):
App Icon displays small red circle with "3" superimposed over the logo.

🏋️ Hands-On Exercise

🎯 The Challenge: Build a Background Push Notification Badge Handler

Instructions:

In sw.js, listen for the push event triggered by a server push payload.
Read the unread count from the push JSON payload (const data = event.data.json()).
Call self.navigator.setAppBadge(data.unreadCount) inside event.waitUntil().
Listen for notificationclick in sw.js and clear the badge using self.navigator.clearAppBadge() when the user opens the notification.

🏁 Starter Code Sandbox

// sw.js - Verified Solution
self.addEventListener('push', (event) => {
  let unreadCount = 1;
  let title = 'New Notification';
  let body = 'You have unread updates.';

  if (event.data) {
    try {
      const payload = event.data.json();
      unreadCount = payload.unreadCount || 1;
      title = payload.title || title;
      body = payload.body || body;
    } catch (e) {
      body = event.data.text();
    }
  }

  event.waitUntil(
    (async () => {
      // 1. Update OS App Icon Badge from background thread
      if ('setAppBadge' in self.navigator) {
        try {
          await self.navigator.setAppBadge(unreadCount);
          console.log('[SW Push] Updated OS app badge to:', unreadCount);
        } catch (badgeErr) {
          console.warn('[SW Push] Failed to set badge:', badgeErr);
        }
      }

      // 2. Show native system notification
      return self.registration.showNotification(title, {
        body: body,
        icon: '/icons/icon-192.png',
        badge: '/icons/badge-monochrome.png',
        data: { url: '/inbox.html' }
      });
    })()
  );
});

self.addEventListener('notificationclick', (event) => {
  event.notification.close();

  event.waitUntil(
    (async () => {
      // Clear badge when user responds to notification
      if ('clearAppBadge' in self.navigator) {
        await self.navigator.clearAppBadge();
      }

      // Focus existing window or open new tab
      const clientList = await self.clients.matchAll({ type: 'window', includeUncontrolled: true });
      for (const client of clientList) {
        if (client.url.includes('/inbox') && 'focus' in client) {
          return client.focus();
        }
      }
      if (self.clients.openWindow) {
        return self.clients.openWindow(event.notification.data.url || '/');
      }
    })()
  );
});

Why this works:

The Badging API is available directly on self.navigator in Service Workers, allowing instant icon updates before the user ever opens the application.
Clearing the badge on notificationclick maintains synchronization between UI state and OS launcher indicators.

⚠️ Common Pitfalls

Passing Negative or Non-Integer Numbers to setAppBadge(): Calling navigator.setAppBadge(-5) or navigator.setAppBadge(3.14) will throw a TypeError. The parameter must be a positive integer >= 1 (or 0 to clear).
Assuming Badges Work on Uninstalled Websites: On desktop Chrome/Edge, badges only render when the website is installed as a PWA or pinned to the taskbar/dock. Calling the API on an ordinary tab has no visible OS effect (though it won't throw an error).
Using Massive Multi-Megabyte Icons for Manifest Shortcuts: Shortcut icons should be small PNGs (96x96 or 192x192). Oversized icons slow down manifest parsing during OS registration.

💡 Pro Tips

Limit Manifest Shortcuts to 4 Items: While the W3C spec allows many shortcut entries, mobile operating systems (Android, iOS) typically display only the first 3 to 4 items in the quick actions menu. Place your highest-value actions first.
Add Tracking Parameters to Shortcut URLs: Always append distinct query parameters like ?source=manifest_shortcut_new to each shortcut's url. This gives your analytics pipeline exact visibility into how frequently power users leverage OS launcher menus.

📌 Key Takeaways

The shortcuts array in manifest.webmanifest creates native OS right-click and long-press launcher menus.
The Badging API (navigator.setAppBadge(), navigator.clearAppBadge()) sets numeric or dot indicators on the installed app icon.
Calling setAppBadge() without arguments displays an unnumbered notification dot.
Badges can be updated from background Service Workers during push events using self.navigator.setAppBadge().
Always detect support via 'setAppBadge' in navigator to ensure graceful degradation.
--

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

? Question 1 / 3

Where are App Shortcuts defined so that the operating system can render a long-press quick actions menu for the installed PWA?

Topic: HTML Fundamentals

? Question 2 / 3

What is the effect of calling `navigator.setAppBadge()` with no arguments provided?

Topic: HTML Fundamentals

? Question 3 / 3

Can `setAppBadge()` be called from inside a Service Worker during a background `push` event?

Topic: HTML Fundamentals

👨‍🚀 CADET FLIGHT DOSSIER

CADET EXPLORER

📖 The Mental Model & Story (Intuitive Foundation)

Technical Deep Dive & Specifications

App Shortcuts in the Web App Manifest

The Badging API Specification

💻 Interactive Code Playground

Starter Code: Dynamic Badging & Shortcut Handler

Line-by-Line Code Breakdown

Expected Browser Render Output

🏋️ Hands-On Exercise

🎯 The Challenge: Build a Background Push Notification Badge Handler

🏁 Starter Code Sandbox

⚠️ Common Pitfalls

💡 Pro Tips

📌 Key Takeaways

Where are App Shortcuts defined so that the operating system can render a long-press quick actions menu for the installed PWA?

What is the effect of calling navigator.setAppBadge() with no arguments provided?

Can setAppBadge() be called from inside a Service Worker during a background push event?

What is the effect of calling `navigator.setAppBadge()` with no arguments provided?

Can `setAppBadge()` be called from inside a Service Worker during a background `push` event?