[w3c/manifest] # Proposal: Add `start_failure_callback` and `fetch_failure_callback` to the Web App Manifest (Issue #1191)

JerryJWChan created an issue (w3c/manifest#1191)

### Summary
This proposal introduces two new optional properties to the Web App Manifest:
- `start_failure_callback`
- `fetch_failure_callback`

These properties allow a Progressive Web App (PWA) to **gracefully handle startup or fetch failures** that occur **before any service worker or app code can execute** — for example, when the user launches the PWA while offline after having cleared all site data.

---

##  Problem Statement

Currently, when a user clears all site data and later tries to open an installed PWA **while offline**, the app becomes unrecoverable:

- The service worker and caches are deleted.  
- The manifest’s `start_url` cannot be fetched.  
- The browser displays a generic “You’re offline” or “This site can’t be reached” message.  
- Developers have **no mechanism** to present a branded, meaningful recovery experience.

This creates a poor user experience and undermines the perceived reliability of PWAs as “installable apps.”

---

## Example Scenario

1. User installs a PWA and adds it to their home screen.  
2. Later, they choose **“Clear browsing data → All site data”**.  
3. The next time they tap the PWA icon:
   - The service worker and cache storage are gone.
   - The browser cannot reach the `start_url` (offline).
   - A generic error page appears instead of the app.  

**Result:**  
The PWA appears broken, with no opportunity for recovery or explanation.

---

## Proposed Solution

Introduce two manifest properties `start_failure_callback` and `fetch_failure_callback` that specify developer-defined fallback handlers executed **before** any service worker or document fetch occurs.

### 1. Exmaple of the improved manefest.json
`json`
{
  "name": "MyApp",
  "start_url": "/index.html",
  "start_failure_callback": "/fallback/startup-handler.js",
  "fetch_failure_callback": "/fallback/network-handler.js"
}

### 2. Example of `start_failure_callback`
`js`
```js
self.onstartfailure = (event) => {
  return Response.html(`
    <html>
      <body style="font-family: sans-serif; text-align: center; padding: 2rem;">
        <h1>Offline</h1>
        <p>Your local data has been cleared or you are offline.</p>
        <p>Please reconnect to restore the app.</p>
      </body>
    </html>
  `);
};
```

### 3. Example of `fetch_failure_callback`
`js`
```js
self.onfetchfailure = (info) => {
  return Response.html(`
    <h1>Offline</h1>
    <p>Cannot reach ${info.url}. Please check your connection.</p>
  `);
};
```
# Security & Execution Context

- These callback scripts are stored in the **browser’s protected app registry**, alongside the manifest, not in origin storage.  
- They persist even if site data is cleared.  
- They run in a **restricted, sandboxed environment**:
  - No access to cookies, localStorage, IndexedDB, or service worker scopes.
  - Limited to producing a simple `Response` object (HTML, text, or JSON).
  - Can use safe APIs like `navigator.onLine` to detect connectivity state.
- Their purpose is purely **recovery UX**, not data access or mutation.  
- Browsers may implement a simple sandbox API surface such as:

`js`
```js
self.onstartfailure = (event) => Response.html("Offline");
self.onfetchfailure = (info) => Response.text("Cannot reach " + info.url);
```
# Benefits of this proposal

1. **Graceful failure** – PWAs can display branded recovery or offline screens instead of browser error pages.
2. **Improved resilience** – Apps remain self-descriptive even after total data loss.
3. **User trust** – Users are reassured that the app isn’t “broken.”
4. **Developer control** – Developers can guide users to reconnect or reinstall cleanly.
5. **Spec alignment** – Extends the declarative philosophy of start_url and the Manifest with minimal additional complexity.
6. **Low implementation cost** – Requires only limited browser integration without new storage or permissions models.

# Relationship to Existing Standards

### Service Workers:
Complements Service Workers, rather than replacing them.
These callbacks cover the pre-Service-Worker phase of app startup — when no script context exists yet to intercept requests.

### Web App Manifest:
Fully compatible with the existing declarative model.
The new properties (start_failure_callback and fetch_failure_callback) would simply extend the manifest schema alongside start_url, display, scope, etc.

### Offline-first model:
Strengthens the reliability story of PWAs by ensuring that users can always see something meaningful even in the worst-case offline scenario.

### Browser UX consistency:
Provides a standardized way for browsers to handle offline startup gracefully, replacing inconsistent or generic “offline” error pages with developer-defined content.

### Lifecycle alignment:
Works alongside manifest lifecycle events (beforeinstallprompt, appinstalled) and could be extended later with telemetry or recovery lifecycle events (onPwaRecoveryShown).





-- 
Reply to this email directly or view it on GitHub:
https://github.com/w3c/manifest/issues/1191
You are receiving this because you are subscribed to this thread.

Message ID: <w3c/manifest/issues/1191@github.com>

Received on Sunday, 26 October 2025 03:52:57 UTC