Chapter 53: Web Notifications API & Native Push

Creating Desktop Notifications

Configure native desktop visual payloads using the Notification constructor, body copy, app icons, hero images, monochrome status badges, and metadata payloads.

LEARNING OBJECTIVES ⌵

Construct and dispatch native OS notifications using the new Notification(title, options) constructor.
Implement visual asset properties including icon, image, and badge according to multi-DPI platform specifications.
Attach custom serializable application payloads and state using the data attribute.
Configure internationalization properties including text direction (dir) and language tags (lang).

🎬 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 of a native notification like sending a formatted physical parcel through the postal service. A simple letter just has a recipient name and a message. But a high-priority certified package includes a sender seal, a preview photo of the contents, a status label, and a custom tracking barcode.

+─────────────────────────────────────────────────────────────────────────────+
|                        DESKTOP NOTIFICATION ANATOMY                         |
+─────────────────────────────────────────────────────────────────────────────+
|                                                                             |
|  +-----------------------------------------------------------------------+  |
|  | [icon]  TITLE: John Doe sent a message                       [10:30 AM]|  |
|  | (Avatar)                                                              |  |
|  |         BODY: "Hey! Can you review the quarterly deployment pull      |  |
|  |         request when you get a chance?"                               |  |
|  |                                                                       |  |
|  | +-------------------------------------------------------------------+ |  |
|  | |                                                                   | |  |
|  | |                      [image] (Hero Banner)                        | |  |
|  | |                 High-Resolution Chart / Preview                   | |  |
|  | |                                                                   | |  |
|  | +-------------------------------------------------------------------+ |  |
|  |                                                                       |  |
|  |  [badge] (Android Status Bar)  │  [data: { conversationId: "c-481" }] |  |
|  +-----------------------------------------------------------------------+  |
|                                                                             |
+─────────────────────────────────────────────────────────────────────────────+

When you instantiate new Notification(title, options), you aren't rendering HTML or CSS. You are supplying a structured dictionary to the operating system's native graphics subsystem. The operating system takes your text, fetches your image URLs, and places them into its proprietary system UI containers.

Technical Deep Dive & Specifications

The NotificationOptions Dictionary

The W3C specification defines the complete configuration dictionary passed as the second parameter to new Notification(title, options):

dictionary NotificationOptions {
  NotificationDirection dir = "auto";
  DOMString lang = "";
  DOMString body = "";
  DOMString tag = "";
  USVString image;
  USVString icon;
  USVString badge;
  VibratePattern vibrate;
  EpochTimeStamp timestamp;
  boolean renotify = false;
  boolean silent = false;
  boolean requireInteraction = false;
  any data = null;
  sequence<NotificationAction> actions = [];
};

Visual Asset Specifications & Platform Nuances

Property	Purpose	Recommended Resolution	Platform Behavior & Notes
`icon`	Main brand logo or sender profile avatar	`192 x 192 px` (Square PNG/WebP)	Shown on Windows Action Center (left/right), macOS banner (right), Android drawer (large right icon).
`image`	Large hero preview or content screenshot	`720 x 360 px` (2:1 aspect ratio)	Rendered below body text in Windows 10/11 toasts and Android drawer. Ignored by macOS Notification Center.
`badge`	Monochrome status symbol for small displays	`96 x 96 px` (Alpha mask PNG)	Displayed on Android status bar when notification is present. Must contain white shapes on transparent background.
`requireInteraction`	Keeps the notification on screen until dismissed	`Boolean`	On Windows/Chrome, prevents the toast from auto-hiding after 5-7 seconds. Useful for critical 2FA codes or VoIP calls.
`data`	Custom metadata attachment	Any structured cloneable data	Carried throughout the notification lifecycle. Accessible in event handlers (`event.target.data`).
`dir` & `lang`	Text direction and localization	`'ltr'`, `'rtl'`, `'auto'`	Sets layout flow and typography rules for internationalization (e.g., `lang: 'ar-EG'`, `dir: 'rtl'`).

Cross-Platform Layout Variations

+─────────────────────────────────────────────────────────────────────────+
|                  CROSS-PLATFORM RENDERING MATRIX                        |
+─────────────────────────────────────────────────────────────────────────+
|  Feature             | Windows 10/11 | macOS Sonoma | Android 14 | iOS 16.4+ (PWA) |
|──────────────────────┼───────────────┼──────────────┼────────────┼─────────────────|
|  `title` & `body`    |  ✅ Full      |  ✅ Full     |  ✅ Full   |  ✅ Full        |
|  `icon` (Avatar)     |  ✅ Supported |  ✅ Supported|  ✅ Supported|  ✅ Supported  |
|  `image` (Hero View) |  ✅ Supported |  ❌ Ignored  |  ✅ Supported|  ❌ Ignored     |
|  `badge` (Status)    |  ❌ Ignored   |  ❌ Ignored  |  ✅ Supported|  ❌ Ignored     |
|  `requireInteraction`|  ✅ Supported |  ⚠️ System DND| ✅ Supported|  ❌ Unsupported |
+─────────────────────────────────────────────────────────────────────────+

💻 Interactive Code Playground

Starter Code

Save this file as index.html and run it in a local web server with permissions granted:

Line-by-Line Code Breakdown

Lines 176–188: Constructs the options payload object conforming to the W3C NotificationOptions dictionary.
Line 183: requireInteraction: reqIntIn.checked instructs the host OS (on Windows and Chrome) to keep the toast on screen until the user explicitly dismisses or clicks it.
Lines 185–188: data: { ... } injects custom application metadata (deployment IDs, routing URLs, or timestamps) that survives the IPC transfer and is readable from event handlers.
Line 191: new Notification(titleIn.value, options) executes the constructor, triggering the host OS notification bridge.

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">
  <title>Lesson 53.3 - Desktop Notification Studio</title>
  <style>
    :root {
      --bg: #090d16;
      --card-bg: #131b2e;
      --border: #233354;
      --accent: #38bdf8;
      --text: #f1f5f9;
      --muted: #94a3b8;
    }
    * { box-sizing: border-box; margin: 0; padding: 0; }
    body {
      font-family: system-ui, -apple-system, sans-serif;
      background: var(--bg);
      color: var(--text);
      display: flex;
      justify-content: center;
      align-items: center;
      min-height: 100vh;
      padding: 1.5rem;
    }
    .studio-container {
      background: var(--card-bg);
      border: 1px solid var(--border);
      border-radius: 16px;
      padding: 2rem;
      max-width: 650px;
      width: 100%;
      box-shadow: 0 25px 50px rgba(0, 0, 0, 0.5);
    }
    h1 { font-size: 1.4rem; color: var(--accent); margin-bottom: 0.5rem; }
    p.desc { font-size: 0.85rem; color: var(--muted); margin-bottom: 1.5rem; }

.form-grid {
      display: grid;
      grid-template-columns: 1fr 1fr;
      gap: 1rem;
      margin-bottom: 1.5rem;
    }
    .form-group { display: flex; flex-direction: column; gap: 0.35rem; }
    .form-group.full-width { grid-column: span 2; }
    label { font-size: 0.8rem; font-weight: 600; color: var(--muted); text-transform: uppercase; }
    input, textarea, select {
      background: #090d16;
      border: 1px solid var(--border);
      border-radius: 6px;
      color: #fff;
      padding: 0.6rem 0.8rem;
      font-size: 0.9rem;
      font-family: inherit;
    }
    input:focus, textarea:focus, select:focus {
      outline: none;
      border-color: var(--accent);
    }
    .checkbox-group {
      grid-column: span 2;
      display: flex;
      align-items: center;
      gap: 0.5rem;
      margin-top: 0.25rem;
    }
    .checkbox-group input { width: auto; }
    .btn-dispatch {
      background: var(--accent);
      color: #000;
      font-weight: bold;
      border: none;
      border-radius: 8px;
      padding: 0.85rem 1.5rem;
      width: 100%;
      font-size: 1rem;
      cursor: pointer;
      transition: background 0.2s;
    }
    .btn-dispatch:hover { background: #0284c7; color: #fff; }

/* Live Preview Box */
    .preview-box {
      margin-top: 1.5rem;
      border: 1px dashed var(--border);
      border-radius: 12px;
      padding: 1.25rem;
      background: rgba(0, 0, 0, 0.2);
    }
    .preview-title { font-size: 0.75rem; text-transform: uppercase; color: var(--muted); margin-bottom: 0.75rem; }
    .simulated-toast {
      background: #1e293b;
      border: 1px solid #334155;
      border-radius: 8px;
      padding: 1rem;
      display: flex;
      gap: 1rem;
    }
    .sim-icon {
      width: 48px;
      height: 48px;
      border-radius: 8px;
      background: #334155;
      object-fit: cover;
    }
    .sim-content { flex: 1; }
    .sim-header { font-weight: bold; font-size: 0.95rem; margin-bottom: 0.25rem; color: #fff; }
    .sim-body { font-size: 0.85rem; color: #94a3b8; line-height: 1.4; margin-bottom: 0.5rem; }
    .sim-hero { width: 100%; height: 120px; object-fit: cover; border-radius: 6px; }
  </style>
</head>
<body>
  <div class="studio-container">
    <h1>🎨 Notification Payload Studio</h1>
    <p class="desc">Configure rich desktop notification options and inspect the native payload structure.</p>

<div class="form-grid">
      <div class="form-group full-width">
        <label for="notif-title">Title</label>
        <input type="text" id="notif-title" value="🚀 Production Build Deployed">
      </div>

<div class="form-group full-width">
        <label for="notif-body">Body Message</label>
        <textarea id="notif-body" rows="2">Version v2.4.0 is now live across all 12 global edge regions. Zero downtime recorded.</textarea>
      </div>

<div class="form-group">
        <label for="notif-icon">Icon URL (Avatar/Logo)</label>
        <input type="text" id="notif-icon" value="https://cdn-icons-png.flaticon.com/512/1126/1126012.png">
      </div>

<div class="form-group">
        <label for="notif-image">Image URL (Hero Banner)</label>
        <input type="text" id="notif-image" value="https://images.unsplash.com/photo-1551288049-bebda4e38f71?w=600&auto=format&fit=crop&q=60">
      </div>

<div class="form-group">
        <label for="notif-dir">Text Direction</label>
        <select id="notif-dir">
          <option value="auto">Auto</option>
          <option value="ltr" selected>Left-to-Right (LTR)</option>
          <option value="rtl">Right-to-Left (RTL)</option>
        </select>
      </div>

<div class="form-group">
        <label for="notif-lang">Language Tag</label>
        <input type="text" id="notif-lang" value="en-US">
      </div>

<div class="checkbox-group">
        <input type="checkbox" id="notif-require-interaction">
        <label for="notif-require-interaction">Require User Interaction (Sticky on Windows/Chrome)</label>
      </div>
    </div>

<button class="btn-dispatch" id="btn-fire">Dispatch Native Desktop Notification</button>

<div class="preview-box">
      <div class="preview-title">Live Structural Preview</div>
      <div class="simulated-toast">
        <img class="sim-icon" id="preview-icon" src="https://cdn-icons-png.flaticon.com/512/1126/1126012.png" alt="icon">
        <div class="sim-content">
          <div class="sim-header" id="preview-title">🚀 Production Build Deployed</div>
          <div class="sim-body" id="preview-body">Version v2.4.0 is now live across all 12 global edge regions. Zero downtime recorded.</div>
          <img class="sim-hero" id="preview-hero" src="https://images.unsplash.com/photo-1551288049-bebda4e38f71?w=600&auto=format&fit=crop&q=60" alt="hero preview">
        </div>
      </div>
    </div>
  </div>

const previewTitle = document.getElementById('preview-title');
    const previewBody = document.getElementById('preview-body');
    const previewIcon = document.getElementById('preview-icon');
    const previewHero = document.getElementById('preview-hero');

// Live preview sync
    function updatePreview() {
      previewTitle.textContent = titleIn.value;
      previewBody.textContent = bodyIn.value;
      previewIcon.src = iconIn.value;
      previewHero.src = imageIn.value;
    }

[titleIn, bodyIn, iconIn, imageIn].forEach(el => el.addEventListener('input', updatePreview));

// Dispatch Native Notification
    document.getElementById('btn-fire').addEventListener('click', async () => {
      if (!('Notification' in window)) {
        alert('Notifications API is not supported in this browser.');
        return;
      }

if (Notification.permission !== 'granted') {
        const status = await Notification.requestPermission();
        if (status !== 'granted') {
          alert('Notification permission was not granted.');
          return;
        }
      }

// Build NotificationOptions dictionary
      const options = {
        body: bodyIn.value,
        icon: iconIn.value,
        image: imageIn.value,
        dir: dirIn.value,
        lang: langIn.value,
        requireInteraction: reqIntIn.checked,
        badge: 'https://cdn-icons-png.flaticon.com/512/1827/1827392.png',
        data: {
          deploymentId: 'dep_98412',
          createdAt: Date.now(),
          url: 'https://github.com'
        }
      };

// Construct and show
      const notification = new Notification(titleIn.value, options);

console.log('Dispatched Notification Instance:', notification);
      console.log('Attached metadata payload:', notification.data);
    });
  </script>
</body>
</html>

LIVE RENDER & DIAGNOSTICS CORE TEMP: 45°C

INSPECTING DOM: VALID

TAGS: SCANNING...

+────────────────────────────────────────────────────────────+
| 🎨 Notification Payload Studio                             |
| Configure rich desktop notification options...             |
|                                                            |
| [ Title: 🚀 Production Build Deployed                    ] |
| [ Body: Version v2.4.0 is now live across all 12...      ] |
| [ Icon URL: ... ]                 [ Image URL: ... ]       |
| [ Direction: LTR ]                [ Language: en-US ]      |
| [x] Require User Interaction (Sticky on Windows/Chrome)    |
|                                                            |
| [ Dispatch Native Desktop Notification (Blue CTA) ]        |
|                                                            |
| LIVE STRUCTURAL PREVIEW                                    |
| +────────────────────────────────────────────────────────+ |
| | [Icon] 🚀 Production Build Deployed                    | |
| |        Version v2.4.0 is now live across all 12...     | |
| |        +─────────────────────────────────────────────+ | |
| |        |             [Hero Image Banner]             | | |
| |        +─────────────────────────────────────────────+ | |
| +────────────────────────────────────────────────────────+ |
+────────────────────────────────────────────────────────────+

🏋️ Hands-On Exercise

🎯 The Challenge: E-Commerce Dispatch Alert Builder

Instructions:

Create a function dispatchOrderShippedAlert(order) that takes an order object with shape:
Construct and trigger a new Notification with:
- Title: "📦 Order #[id] Has Shipped!"
- Body: "Hi [customer], your package with [itemsCount] items ($[total]) is on its way."
- Icon: "https://cdn-icons-png.flaticon.com/512/709/709790.png"
- Require Interaction: Set to true if order.priority is true, otherwise false.
- Data: Attach { orderId: order.id, customer: order.customer, timestamp: Date.now() }.
If permission is not granted, request permission first.

🏁 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>Exercise 53.3 - Order Alert Builder Solution</title>
  <style>
    body { font-family: system-ui, sans-serif; background: #0f172a; color: white; padding: 2rem; }
    .card { background: #1e293b; border: 1px solid #334155; padding: 2rem; border-radius: 12px; max-width: 500px; }
    button { padding: 0.75rem 1.5rem; background: #38bdf8; color: #000; border: none; border-radius: 6px; cursor: pointer; font-weight: bold; }
    button:hover { background: #0284c7; color: #fff; }
    .log { margin-top: 1rem; font-family: monospace; font-size: 0.85rem; color: #94a3b8; }
  </style>
</head>
<body>
  <div class="card">
    <h2>E-Commerce Dispatch Hub</h2>
    <p style="color: #94a3b8; font-size: 0.9rem; margin-bottom: 1.5rem;">Click to trigger a high-priority order dispatch notification.</p>
    <button id="btn-ship">Dispatch Order #ORD-8941</button>
    <div class="log" id="log-msg">Status: Ready</div>
  </div>

  <script>
    async function dispatchOrderShippedAlert(order) {
      if (!('Notification' in window)) {
        throw new Error('Notifications not supported in this browser environment.');
      }

      // Step 1: Ensure permission
      let permission = Notification.permission;
      if (permission === 'default') {
        permission = await Notification.requestPermission();
      }

      if (permission !== 'granted') {
        throw new Error(`Notification permission denied (State: ${permission})`);
      }

      // Step 2: Construct options payload
      const title = `📦 Order #${order.id} Has Shipped!`;
      const options = {
        body: `Hi ${order.customer}, your package with ${order.itemsCount} items ($${order.total.toFixed(2)}) is on its way.`,
        icon: 'https://cdn-icons-png.flaticon.com/512/709/709790.png',
        badge: 'https://cdn-icons-png.flaticon.com/512/1827/1827392.png',
        requireInteraction: Boolean(order.priority),
        data: {
          orderId: order.id,
          customer: order.customer,
          total: order.total,
          timestamp: Date.now()
        }
      };

      // Step 3: Instantiate notification
      const notification = new Notification(title, options);

      return notification;
    }

    document.getElementById('btn-ship').addEventListener('click', async () => {
      const logEl = document.getElementById('log-msg');
      try {
        logEl.textContent = 'Preparing dispatch alert...';
        const notif = await dispatchOrderShippedAlert({
          id: 'ORD-8941',
          customer: 'Sarah Connor',
          itemsCount: 4,
          total: 289.50,
          priority: true
        });
        logEl.textContent = `✅ Notification dispatched successfully for order ${notif.data.orderId}!`;
      } catch (err) {
        logEl.textContent = `❌ ${err.message}`;
      }
    });
  </script>
</body>
</html>

Why this works:

The function validates input parameters and safely checks permissions before attempting construction.
It dynamically toggles requireInteraction based on the order's priority flag, ensuring critical orders don't disappear before the user views them on desktop.
It bundles the order metadata inside the data property for downstream event handling.

⚠️ Common Pitfalls

Relative Image URLs in Worker Contexts: Using relative paths like icon: '/img/logo.png' can break depending on the base URL context. Always use root-relative or absolute HTTPS URLs.
Assuming image Works on macOS: macOS UNUserNotificationCenter ignores the image (hero banner) property entirely. Keep your core message inside body and never rely solely on an image banner to convey critical info.
Non-Cloneable Data in data: The data property is serialized using the Structured Clone Algorithm. Passing objects containing DOM nodes, active WebSockets, or functions will throw a DataCloneError.

💡 Pro Tips

Android Status Bar Mask (Badge): The badge icon on Android requires a 96x96 PNG with pure white artwork and alpha transparency. Any colored pixels will be converted to a solid monochromatic silhouette by the Android OS.
Epoch Time Synchronization: Use the timestamp option (Date.now()) when notifying users of historical or scheduled events (e.g. "Meeting started 5 minutes ago") so the host OS displays the accurate relative time.

📌 Key Takeaways

The new Notification(title, options) constructor creates and dispatches native OS alerts.
icon displays the main square avatar/logo (192x192 px), while image displays a wide hero banner (supported on Windows and Android).
badge provides a monochrome status icon specifically for Android's system status bar.
requireInteraction: true keeps the desktop notification pinned until user dismissal on supported operating systems.
The data property allows arbitrary structured data to be attached and retrieved during lifecycle events.
--

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

? Question 1 / 3

Which property in the `NotificationOptions` dictionary prevents a desktop notification on Windows/Chromium from automatically disappearing after 5 seconds?

Topic: HTML Fundamentals

? Question 2 / 3

What happens if you assign a function or active DOM element to the `data` property of a notification?

Topic: HTML Fundamentals

? Question 3 / 3

Why should an Android notification `badge` asset be designed differently from an `icon` asset?

Topic: HTML Fundamentals

👨‍🚀 CADET FLIGHT DOSSIER

CADET EXPLORER

📖 The Mental Model & Story (Intuitive Foundation)

Technical Deep Dive & Specifications

The NotificationOptions Dictionary

Visual Asset Specifications & Platform Nuances

Cross-Platform Layout Variations

💻 Interactive Code Playground

Starter Code

Line-by-Line Code Breakdown

Expected Browser Render Output

🏋️ Hands-On Exercise

🎯 The Challenge: E-Commerce Dispatch Alert Builder

🏁 Starter Code Sandbox

⚠️ Common Pitfalls

💡 Pro Tips

📌 Key Takeaways

Which property in the NotificationOptions dictionary prevents a desktop notification on Windows/Chromium from automatically disappearing after 5 seconds?

What happens if you assign a function or active DOM element to the data property of a notification?

Why should an Android notification badge asset be designed differently from an icon asset?

Which property in the `NotificationOptions` dictionary prevents a desktop notification on Windows/Chromium from automatically disappearing after 5 seconds?

What happens if you assign a function or active DOM element to the `data` property of a notification?

Why should an Android notification `badge` asset be designed differently from an `icon` asset?