Launch Handler API: Control How Your Progressive Web App Launches

What Is the Launch Handler API?

The Launch Handler API represents a significant advancement in progressive web app (PWA) development, giving developers granular control over how their applications respond to launch events. This API addresses a fundamental challenge in modern web development: managing the user experience when users interact with your app through various entry points such as app shortcuts, deep links, or file associations.

By configuring launch behavior, you can ensure that your application provides a seamless, predictable experience regardless of how users access it. The API operates at the intersection of manifest configuration and JavaScript runtime behavior, providing both declarative configuration for simple use cases and programmatic flexibility for complex scenarios.

The Launch Handler API emerged from the Web Incubator Community Group (WICG) to address these considerations systematically, providing a standardized mechanism for controlling launch behavior across different platforms and devices. When combined with AI-powered automation features, PWAs can deliver intelligent, context-aware experiences that rival native applications.

Web App Manifest Configuration

The web app manifest serves as the configuration hub for PWA behavior, and the launch_handler member extends this configuration to encompass launch-specific behaviors. When you add launch_handler to your manifest, you declare how your application should respond when launched through various mechanisms. The manifest configuration establishes the default behavior, while the JavaScript API provides runtime flexibility for handling specific launch scenarios.

The launch_handler member is structured as a dictionary containing configuration options, with client_mode serving as the primary configuration property. This design accommodates future expansion with additional properties beyond client_mode, allowing the specification to evolve without breaking existing implementations.

Basic Configuration Example

{
 "name": "Music Player",
 "shortcuts": [
 { "name": "Now Playing", "url": "/" },
 { "name": "Library", "url": "/library" },
 { "name": "Favorites", "url": "/favorites" }
 ],
 "launch_handler": {
 "client_mode": "focus-existing"
 }
}

This configuration ensures that when users activate app shortcuts, the application focuses the existing window rather than creating new windows that might interrupt music playback.

Client Mode Values Explained

The client_mode property accepts several values, each representing a distinct launch handling strategy. Understanding these values requires recognizing their implications for both user experience and application state management.

auto (Default)

The auto value represents the default behavior, allowing the user agent to make contextually appropriate decisions. On mobile devices that typically support only single app instances, the user agent might choose to navigate existing windows. Conversely, on desktop platforms where multiple windows are standard, the user agent might create new windows to prevent potential data loss from navigation.

navigate-new

The navigate-new mode creates a new web app client to load the launch's target URL. This approach guarantees isolation between launch events and existing application state, making it suitable for applications that process independent tasks.

navigate-existing

The navigate-existing mode brings existing app instances into focus and navigates them to the target URL. If no existing client is open, the behavior falls back to navigate-new. This mode provides a middle ground between single-instance enforcement and task isolation.

focus-existing

The focus-existing mode represents the most sophisticated launch handling strategy. When an existing client is open, it comes into focus without navigation, and the target URL is communicated via LaunchParams for programmatic handling. This mode is essential for applications like music players, where interrupting playback to navigate away would degrade the user experience.

Array Syntax for Fallback

The client_mode property also supports array syntax for graceful degradation across platforms:

{
 "launch_handler": {
 "client_mode": ["focus-existing", "navigate-existing", "auto"]
 }
}

The user agent selects the first supported value from the array, falling back to subsequent options as needed. Our web development team can help you choose the right client mode for your specific use case.

The JavaScript API: LaunchQueue and LaunchParams

The JavaScript API provides the programmatic mechanism for handling launches within your application's code. Understanding these interfaces is essential for implementing sophisticated launch handling.

LaunchQueue Interface

The LaunchQueue interface is exposed through the window.launchQueue property and enables applications to register consumers that process incoming launch events. The LaunchQueue design addresses a subtle but important race condition: launch events could fire before page scripts attach event listeners.

By buffering launches until a consumer is set, LaunchQueue ensures no launch events are missed.

LaunchParams Interface

LaunchParams encapsulates all information about a launch event:

• targetURL: The URL that triggered the launch (must be within scope)
• files: Array of FileSystemHandle objects for file launches

Setting Up a LaunchConsumer

if ("launchQueue" in window) {
 window.launchQueue.setConsumer((launchParams) => {
 if (launchParams.targetURL) {
 const url = new URL(launchParams.targetURL);
 const params = url.searchParams;

 // Extract the track parameter from the URL
 const track = params.get("track");
 if (track) {
 audio.src = track;
 title.textContent = new URL(track).pathname.slice(1);
 audio.play();
 }
 }
 });
}

Implementing the Launch Handler API requires expertise in modern JavaScript development to ensure robust cross-browser compatibility and optimal performance.

Browser Support and Compatibility

The Launch Handler API currently has limited browser support, primarily available in Chromium-based browsers including Chrome and Edge. The API is marked as experimental, and developers should verify support before relying on it in production applications.

Feature Detection

if ("launchQueue" in window && "setConsumer" in window.launchQueue) {
 // Launch Handler API is supported
 implementLaunchHandling();
} else {
 // Provide fallback behavior
 console.log("Launch Handler API not supported");
}

Platform Considerations

Browser support varies significantly across platforms, particularly regarding multi-instance capabilities. Mobile platforms typically support only single app instances, influencing how user agents interpret the auto client mode. Desktop platforms may support multiple windows, allowing navigate-new behavior without the same concerns about resource constraints.

Sources

1. MDN Web Docs: Launch Handler API - Comprehensive technical reference covering interfaces, client_mode values, and code examples
2. Chrome for Developers: Launch Handler API - Practical implementation guide with use cases and best practices
3. WICG Web App Launch Handler Specification - Official specification with detailed algorithms and conformance requirements
4. MDN Web Docs: LaunchQueue - Detailed LaunchQueue interface documentation
5. MDN Web Docs: LaunchParams - LaunchParams properties and usage details