Protocol handler registration lets PWAs handle custom URL schemes

Why protocol handlers matter for PWAs

Clicking a mailto: link opens your email app. Clicking a tel: link opens your phone app. Clicking a custom scheme like obsidian:// opens that specific app.

Today, PWAs can only register protocol handlers using the existing navigator.registerProtocolHandler() API, which requires JavaScript to run and has platform-specific limitations. An emerging WICG proposal adds manifest-based protocol handler registration for PWAs, allowing them to declare support for URL schemes declaratively.

According to a WICG discourse proposal, this feature "will allow web developers to register web applications as URL protocol handlers via a property in the web app manifest." This is a Chrome origin trial as of early 2026.

The current state: JavaScript-based registration

Before the manifest approach, protocol handler registration required JavaScript:

// User must have installed your PWA first
if (navigator.registerProtocolHandler) {
  navigator.registerProtocolHandler('web+music', 'https://yourapp.com/open?url=%s', 'My Music App');
}

Limitations of the JavaScript API

• No discoverability: Users can't see which apps handle which schemes before clicking links
• Platform-specific UI: Permission prompts vary by browser and can be confusing
• Requires script execution: The site must load and run JavaScript before registration
• No manifest validation: No compile-time check that your handler URLs are valid
• Poor ecosystem integration: OS-level app associations don't recognize web handlers

The manifest approach: Declarative registration

The proposed manifest-based approach declares handlers in your manifest.json:

{
  "protocol_handlers": [
    {
      "protocol": "mailto",
      "url": "/compose?email=%s"
    },
    {
      "protocol": "web+music",
      "url": "/play?track=%s"
    },
    {
      "protocol": "web+note",
      "url": "/view?note=%s"
    }
  ]
}

Advantages

• Declarative: Handlers are discoverable before your PWA installs
• Manifest validation: Browsers can validate handler URLs as part of manifest parsing
• Better integration: Can hook into OS-level app association UI
• No script dependency: Registration doesn't require JavaScript execution
• Better UX for users: Clearer permission prompts and handler selection

The decision framework: Should you adopt this?

This is experimental. Chrome has an origin trial; Safari and Firefox have no public implementation. Use this rubric to decide:

Experimental status checklist

Before shipping:

• [ ] You've reviewed the WICG proposal and Chrome intent to ship
• [ ] You understand this is an origin trial feature that may change
• [ ] You have a fallback strategy for browsers that don't support manifest handlers
• [ ] You're prepared to remove or update handlers if the spec changes
• [ ] Your use case doesn't depend on this for core functionality

When it makes sense

| Scenario | Recommendation | |----------|----------------| | Public-facing PWA with diverse users | Wait for the feature to ship in stable browsers | | Enterprise PWA with controlled environment | Participate in the origin trial if you need custom schemes | | Personal tools or internal dev tools | Safe to experiment; you control the environment | | Marketplace-listed PWA | Avoid until multi-browser support exists |

Use cases that justify adoption

• Email clients: Handle mailto: links when installed
• Note-taking apps: Handle custom schemes like obsidian:// via web+note
• Content tools: Handle web+article or web+bookmark schemes
• Developer tools: Handle web+debug or custom devtool schemes

Security and privacy considerations

Scheme restrictions

Browsers will restrict which schemes PWAs can register:

• Allow: mailto:, tel:, web+* (custom web schemes)
• Block: http:, https:, file:, and any scheme that could be used for phishing
• Site-specific: Some schemes like web+banking may have additional validation

User consent flow

Even with manifest-based registration, users must opt in:

1. User clicks a link like web+music:track-id-123
2. Browser checks installed PWAs for handler registration
3. Browser prompts user: "Open in My Music App?"
4. User grants permission once
5. Future links open directly

Fingerprinting concerns

Protocol handler registration could be used for fingerprinting (detecting which apps are installed). Browsers may implement:

• Permission prompts that don't reveal installed handlers until user interaction
• Rate limiting or quota on handler registration
• Opt-out of handler discovery for privacy-conscious users

Implementation steps for origin trial participants

1. Enable the origin trial

If you have a Chrome origin trial token, add it to your HTML:

<meta http-equiv="origin-trial" content="YOUR_TOKEN_HERE">

2. Update your manifest

{
  "protocol_handlers": [
    {
      "protocol": "web+music",
      "url": "/play?track=%s"
    }
  ]
}

3. Implement your handler endpoint

// /play?track=track-id-123
export async function onRequestGet({ url, request }) {
  const trackId = url.searchParams.get('track');
  // Validate track ID, redirect to full experience
  return Response.redirect(`/tracks/${trackId}`, 302);
}

4. Test across browsers

• Chrome (with origin trial enabled): Should work
• Safari, Firefox: Fall back to JavaScript registration or show "no handler" message
• Mobile browsers: Handler selection UI varies significantly

5. Monitor telemetry

Track:

• How many users grant handler permission
• Which schemes are used most frequently
• Browser/OS breakdown of handler usage
• Conversion rates from link click to app install

What to tell users

When explaining protocol handlers:

On the app store listing

"This app can open web+music: links directly. After installation, clicking web+music: URLs will open in this app."

In your app settings

"Handle web+music links: On/Off" — toggle for opting out of handler registration

When the permission prompt appears (if browser shows one)

"My Music App wants to handle web+music: links. Allow?"

The future of protocol handlers

The WICG proposal is early. Likely next steps:

1. Chrome ships in stable: After origin trial feedback and implementation refinement
2. Safari and Firefox evaluate: Adoption depends on implementation complexity and security reviews
3. Spec stabilization: WICG moves proposal to W3C incubation or formal spec
4. Ecosystem tooling: DevTools shows registered handlers, linters validate manifest entries

For now, this is experimental. If you're building production PWAs, implement JavaScript-based registration as a fallback and consider manifest-based registration as an enhancement for Chrome users participating in the trial.

What this means for your PWA product strategy

Protocol handlers are a growth and retention lever:

• Growth: Users discover your app when clicking links to custom schemes
• Retention: Your app becomes the default handler for its content ecosystem
• Lock-in: Users with custom-scheme workflows depend on your app
• Discovery: App stores can feature apps that handle popular schemes

For ecosystem PWAs (note-taking, content management, developer tools), protocol handlers are table stakes for native competition. For consumer PWAs, they're a nice-to-have until multi-browser support emerges.

The next step

Protocol handler registration is one half of deep linking. The other half is URL routing robustness—ensuring your app handles deep links gracefully even when the user isn't logged in, has network errors, or encounters stale content. Combined with robust routing, protocol handlers turn your PWA from a website into a first-class citizen of the OS.

Don't build critical user flows on experimental features. But do experiment, provide feedback to the WICG, and prepare your architecture for when protocol handlers ship in stable browsers. Your users expect native-level integration—that's what makes PWAs compelling.