Fix PWA Deep-Link Issues on Ubuntu 24.04 with Chrome Scope Config

by

Summary

A user reported a fragmented user experience while using a Progressive Web App (PWA) on Ubuntu 24.04. When attempting to launch a corporate virtual machine through the Windows App web interface, Chrome breaks the session flow by opening the connection in a standard browser tab instead of maintaining the isolated PWA window. This forces the user to manually click “Open in App” every single time, creating a redundant and inefficient workflow.

Root Cause

The failure stems from a mismatch between Deep Linking protocols and the PWA Manifest configuration:

  • URL Redirection Handling: The corporate VM service uses a specific URL scheme to trigger the connection. Chrome interprets this link as a navigation event for the main browser process rather than a signal to hand off the task to the installed PWA.
  • Scope Mismatch: The start_url defined in the web app’s manifest does not encompass the specific sub-path or protocol used by the VM connection string.
  • Link Capturing Failure: The “Supported Links” (Web App Handlers) feature in Chrome failed to claim the specific URL pattern used by the Windows App service, causing the OS to default to the primary browser instance.

Why This Happens in Real Systems

In complex enterprise environments, this is a common integration gap:

  • Protocol Conflict: Enterprise tools often use custom URI schemes (e.g., windowsapp://) that are not natively mapped to the PWA’s Web App Manifest.
  • Sandboxing Constraints: PWAs are designed to be isolated. If a link triggers a redirect to a domain or path not explicitly declared in the scope property of the manifest, the browser treats it as an external navigation.
  • Browser Policy vs. Manifest: Even if a site supports Web App Links, the browser’s security model may prioritize the main browser window to prevent “hijacking” unless the user has explicitly granted permission through the link handling settings.

Real-World Impact

  • Reduced Productivity: Users lose seconds of focus per session, which scales into significant lost time across large engineering teams.
  • Context Switching Fatigue: Forcing a user to move from a dedicated app window back to a cluttered browser tab breaks the mental model of the application as a standalone tool.
  • Operational Friction: In high-stakes environments (like managing production VMs), UI inconsistencies can lead to user errors or hesitation during critical interventions.

Example or Code

To resolve this at the application level, the manifest.json must explicitly define the scope and the handle_links capability.

{
  "name": "Windows App",
  "start_url": "/",
  "scope": "/",
  "display": "standalone",
  "handle_links": "auto",
  "prefer_related_applications": false
}

If the VM connection uses a specific path, the scope must be adjusted:

{
  "scope": "/vm-session/",
  "start_url": "/vm-session/launcher"
}

How Senior Engineers Fix It

A senior engineer approaches this through Manifest Engineering and Protocol Mapping:

  • Manifest Optimization: Ensure the scope property is wide enough to catch the redirection URL but narrow enough to maintain security.
  • Implementation of Web App Links: Implement the assetlinks.json (for Android/Web) or ensure the server sends the correct headers to allow the browser to associate the domain with the PWA.
  • Deep Link Testing: Use Chrome DevTools to inspect the Application Tab and verify if the “Scope” covers the exact URL being generated by the VM service.
  • User-Side Workaround (The “Patch”): If the developer cannot change the manifest, the engineer instructs the user to navigate to chrome://apps, right-click the app, and ensure “Start app when you sign in” or specific permission settings are enabled, or manually manage Protocol Handlers in Chrome settings.

Why Juniors Miss It

  • Surface-Level Troubleshooting: Juniors often look for “settings” in the UI (like the “Supported Links” window) without understanding that the source of truth is the JSON manifest sent by the server.
  • Assuming Browser Consistency: Juniors often assume Chrome handles all PWAs identically, failing to realize that Linux-specific window management and browser security policies can alter how redirects are handled.
  • Ignoring the “Scope” Concept: Most developers understand a URL, but few realize that a PWA’s “identity” is strictly bound to its defined URL Scope. If the link falls outside that scope, it is no longer the app; it is just a website.

Leave a Comment