Device & OS Integration¶

Device and OS integration APIs, often called web capabilities, are the part of the platform that lets a Progressive Web App behave like an installed application: share into and out of the system share sheet, open and save real files, register as a file or URL-scheme handler, draw into the title bar, talk to USB, Bluetooth, serial and NFC hardware, keep the screen awake, take payments and sign in with passkeys. They matter because they decide what a PWA can replace. Most of them were created or accelerated by Google's Project Fugu, and their support splits sharply: a core set works in every engine, while a large and growing set ships only in Chromium-based browsers. This page explains how that landscape came to be, how to use these APIs safely with progressive enhancement, how the permission and user-activation gates work, how origin trials fit in, and where each capability stands in September 2026.

What "capabilities" means for a PWA¶

A PWA's baseline is a web page with a manifest and a service worker. Everything in this section adds integration points on top of that baseline. It helps to sort them by where the integration happens, because that determines how you ship, test and detect them.

Background execution is covered in Background & Engagement, and storage primitives such as the origin private file system in Caching & Offline. The manifest mechanics behind the first three rows are documented in Advanced & Integration Members; this section focuses on the APIs and the runtime behavior you build around them.

The "needs installation" column is the one that surprises teams most. Declarative integrations have nothing to attach to until the browser creates an OS-level app, so they are inert in a browser tab. Several imperative APIs also behave differently when installed: Chromium grants File System Access permissions persistently for installed apps (Chrome 122 and later), Periodic Background Sync requires an installed app, and on iOS and iPadOS the Badging API and Web Push exist only for Home Screen web apps. See Installability Criteria for what it takes to become installable.

Project Fugu: goals and history¶

In November 2018 Google announced the Web Capabilities project, codenamed Project Fugu after the pufferfish that is a delicacy when prepared well and dangerous when not. The name is the thesis: powerful APIs are valuable only if they are designed so that a malicious site cannot abuse them. Chrome's own description calls it "an effort to close gaps in the web's capabilities enabling new classes of applications to run on the web", and the status page describes it as "a cross-company effort with the objective of making it possible for web apps to do anything iOS, Android, or desktop apps can." Microsoft and Intel engineers have authored or co-authored many of the resulting proposals alongside Google; Window Controls Overlay and manifest protocol handling, for example, started as Microsoft Edge explainers. The broader timeline is in History & Evolution.

The capabilities process¶

Chrome's original announcement defines six steps every capability goes through. They map directly to Chromium's Blink launch process and to the entries you see on chromestatus.com:

flowchart LR
    A["1. Identify the developer need"] --> B["2. Create an explainer"]
    B --> C["3. Get feedback, iterate"]
    C --> D["4. Move to a specification"]
    D --> E["5. Origin trial"]
    E --> F["6. Ship"]
    C -. "no support / no need" .-> X["Dropped"]
    E -. "design changes" .-> D

1. Identify the developer need. A use case, not an API: "edit a local file in place", "configure a microcontroller over a serial port".
2. Create an explainer. A design document in a public repository (usually under the WICG GitHub organization) describing the problem, non-goals and sample code.
3. Get feedback and iterate on the explainer. Public discussion with web developers and other browser vendors, plus a formal request for their standards positions.
4. Move the design to a specification and iterate. Usually a WICG Community Group draft first, sometimes later adopted by a W3C Working Group.
5. Origin trial. The implementation ships in stable Chrome, but only for origins that register (see origin trials below).
6. Ship it. The feature is enabled by default after an "Intent to Ship" is approved by Blink's API owners.

The Fugu status page groups proposals into five public stages: under consideration, work has begun, available behind a flag, in an origin trial and available in stable. It also states plainly that "many ideas never make it past the explainer or origin trial stage." Declarative Link Capturing, url_handlers and the original handle_links proposal are examples: each ran as an experiment and was replaced or abandoned.

What Fugu shipped, and when¶

The table lists representative capability launches in Chrome, with dates from Chromium's release schedule and versions from MDN's browser-compat-data. Pre-Fugu APIs that the project later extended are included for context.

The Fugu API tracker (fugu-tracker.web.app) now simply redirects to a saved search in the Chromium issue tracker filtered on the proj-fugu label, and the Chrome team maintains a Fugu showcase of production apps that use the APIs.

The fault line Fugu exposed¶

Fugu's design goals were security, privacy and user trust: permissions the user controls and can revoke, transparency when an API is in use, and choosers instead of blanket access. Mozilla and Apple accept that framing for some APIs and reject it for others. Their core objections recur across their positions:

• Consent is not meaningful for low-level access. A user cannot evaluate whether granting a site access to a USB device, a serial port or a folder is safe. Mozilla's File System Access position argues that meaningful consent for cross-site access to the local file system is not possible.
• Devices are not built for hostile input. Firmware on USB, HID and Bluetooth peripherals assumes a trusted host driver. A web page is not one.
• Fingerprinting surface. Fonts, screens, idle state, sensors and connected devices all add entropy. WebKit's tracking-prevention documentation lists APIs it has "decided to not yet implement due to fingerprinting, security, and other concerns", including Web Bluetooth, Web MIDI, Magnetometer, Web NFC, WebHID, Serial, WebUSB and User Idle Detection.

The result is a web with three tiers, described next. Because every browser on iOS and iPadOS uses WebKit, the WebKit column of any support table is also the iPhone column for Chrome, Edge and Firefox on those devices; see iOS & iPadOS.

Standardized across engines vs Chromium-only¶

"Is it standardized?" is the wrong question. Almost every Fugu API has a specification, usually a WICG Community Group report, and several have W3C Working Group drafts. The useful question is how many engines implement it, because that determines whether you can build on it or only enhance with it.

Tier 1: works in every engine¶

These are safe foundations. You still feature-detect, because versions and platform details differ, but the fallback path is for old browsers, not for a whole engine.

• Web Share (navigator.share()), everywhere except Chrome on Linux, Firefox desktop and Android WebView: see Web Share API.
• Screen Wake Lock: Chrome 84, Firefox 126, Safari 16.4 (inside iOS Home Screen web apps only from iOS 18.4).
• Async Clipboard read and write: Chrome 66/76, Firefox 125/127, Safari 13.1.
• Media Session: Chrome 73 desktop, Firefox 82, Safari 15.
• Web Push and Notifications: covered in Push Notifications and Web Push on iOS & Safari.
• Web Authentication and passkeys, Payment Request (Safari supports it with Apple Pay; Firefox only behind a flag): see Authentication & Passkeys and Payments.
• Origin private file system, Web Locks, Storage persistence, Geolocation, Gamepad, Permissions API query().

Tier 2: Chromium plus one other engine¶

These have a real second implementation, which makes them more durable, but still leave a large population without support.

• Badging API: Chromium desktop and Safari (iOS/iPadOS 16.4 Home Screen web apps, macOS Sonoma web apps). Firefox has no implementation. See Badging API.
• Web MIDI: Chromium and Firefox 108 (gated by a site-permission add-on).
• Web Serial: Chromium desktop and Firefox 151 on desktop (also add-on gated). Safari opposes it.
• Document Picture-in-Picture: Chrome 116 desktop and Firefox 151 desktop.
• Digital Credentials API: Chrome 141 and Safari 26.
• registerProtocolHandler(): Chromium desktop and Firefox, though only Chromium supports the manifest protocol_handlers member.

Tier 3: Chromium-only¶

Everything else in this section ships only in Chromium-based browsers, and in many cases only on some Chromium platforms: File System Access pickers, File Handling, manifest protocol_handlers, launch_handler, Window Controls Overlay, Web Share Target (Android and ChromeOS), WebUSB, WebHID, Web Bluetooth, Web NFC, Idle Detection, Local Font Access, Window Management, EyeDropper, Compute Pressure, Contact Picker, Keyboard Lock, Background Sync, Periodic Background Sync, Background Fetch, Payment Handler, FedCM and getInstalledRelatedApps().

"Chromium-only" hides further variation that you must test:

• Platform gaps inside Chromium. WebHID, EyeDropper, Local Font Access, Window Controls Overlay and File Handling are desktop-only. Web NFC and the Contact Picker are Android-only. Web Share is absent from Chrome on Linux. EyeDropper is unavailable on Linux Wayland.
• Android WebView. Most capability APIs are missing from WebView (Web Share, Web Bluetooth, WebUSB, Push, Background Sync), so the same site inside a native app's WebView loses them. Trusted Web Activities run in the full browser and keep them; see Trusted Web Activity.
• Other Chromium browsers. Edge and Opera track Chromium versions closely. Samsung Internet lags and sometimes differs (it ships Web Share Target, but its partial Contact Picker support was removed in version 22). Brave ships some APIs, such as File System Access, only behind a flag. Vendors can also disable a feature through server-side configuration.

Where the other engines stand¶

The standards-positions repositories are the authoritative record. The table summarizes the recorded positions for capabilities discussed in this section as of September 2026. "No position" means an issue exists or the API was never formally reviewed, without a recorded verdict.

Sources: Mozilla standards positions and WebKit standards positions. Positions change; always follow the linked issue before making a roadmap decision. Isolated Web Apps have their own page because they unlock APIs that are not available to ordinary PWAs at all.

Progressive enhancement and feature detection¶

Capabilities are enhancements by definition. A photo editor that can save back to the original file with File System Access still has to download a copy in Safari; a hardware configurator that uses Web Serial still has to explain what to do in Firefox for Android. The engineering pattern is always the same: baseline that works everywhere, enhanced path when the capability is present, and UI that only offers what will work.

Detect at the right depth¶

Presence of an interface is only the first of several questions. Each layer can fail independently:

Two more rules keep detection honest:

• Detect with the global object that owns the API. "showOpenFilePicker" in window, "serial" in navigator, "launchQueue" in window, "BarcodeDetector" in globalThis. Checking typeof Serial works too but is easier to shadow by accident.
• Never infer one capability from another, or from the user agent. OPFS support says nothing about pickers; Web Share on macOS Safari says nothing about Web Share Target. User-agent sniffing breaks every time a browser adds support, and Chromium's User-Agent Client Hints (navigator.userAgentData) are not available in Firefox or Safari anyway.

A capability detection module¶

Keep detection in one module so that UI code asks a named question and the answer can be logged, tested and overridden. Every check below is synchronous and cheap; nothing prompts the user.

// Synchronous, side-effect-free feature detection for capability APIs.
// Answers "does this browser expose the API?", never "will the user allow it?".

const nav = globalThis.navigator ?? {};
const win = globalThis;

function canShareFiles() {
  // canShare() must exist AND accept a file: Firefox for Android exposes
  // canShare() but returns false for files.
  if (typeof nav.canShare !== "function") return false;
  try {
    const probe = new File(["probe"], "probe.txt", { type: "text/plain" });
    return nav.canShare({ files: [probe] });
  } catch {
    return false;
  }
}

function matchesDisplayMode(...modes) {
  return modes.some((mode) => win.matchMedia?.(`(display-mode: ${mode})`).matches);
}

export const capabilities = Object.freeze({
  // Tier 1: cross-engine
  share: typeof nav.share === "function",
  shareFiles: canShareFiles(),
  wakeLock: "wakeLock" in nav,
  clipboardWrite: typeof nav.clipboard?.write === "function",
  mediaSession: "mediaSession" in nav,
  opfs: typeof nav.storage?.getDirectory === "function",
  webAuthn: typeof win.PublicKeyCredential === "function",
  paymentRequest: typeof win.PaymentRequest === "function",
  userActivation: "userActivation" in nav,
  permissionsQuery: typeof nav.permissions?.query === "function",

  // Tier 2: Chromium + one other engine
  badging: typeof nav.setAppBadge === "function",
  midi: typeof nav.requestMIDIAccess === "function",
  serial: "serial" in nav,
  documentPiP: "documentPictureInPicture" in win,

  // Tier 3: Chromium-only
  fileSystemAccess: typeof win.showOpenFilePicker === "function",
  fileHandling: "launchQueue" in win && "files" in (win.LaunchParams?.prototype ?? {}),
  windowControlsOverlay: "windowControlsOverlay" in nav,
  usb: "usb" in nav,
  hid: "hid" in nav,
  bluetooth: "bluetooth" in nav,
  nfc: "NDEFReader" in win,
  contactPicker: "contacts" in nav && "ContactsManager" in win,
  idleDetection: "IdleDetector" in win,
  localFonts: typeof win.queryLocalFonts === "function",
  windowManagement: typeof win.getScreenDetails === "function",
  eyeDropper: "EyeDropper" in win,
  computePressure: "PressureObserver" in win,

  // Context, not capability: are we running in an installed app window?
  installedWindow: matchesDisplayMode("standalone", "minimal-ui", "window-controls-overlay", "fullscreen"),
});

// Development aid: override detection from the console to test fallbacks,
// e.g. localStorage.setItem("cap:off", "fileSystemAccess,share").
export function isEnabled(name) {
  let disabled = [];
  try {
    disabled = (localStorage.getItem("cap:off") ?? "").split(",");
  } catch {
    // Storage can throw in some privacy modes; detection still works.
  }
  return Boolean(capabilities[name]) && !disabled.includes(name);
}

installedWindow is a context signal, not a capability: it tells you that declarative integrations may be active, not that they are. Detecting Installed Apps covers the reliable techniques.

Enhancing the UI without flashes or dead buttons¶

Render the baseline control in HTML and upgrade it when the capability is present. Hiding enhanced controls by default avoids a flash of a button that does nothing, and loading the enhanced code with import() keeps it out of the bundle for browsers that cannot use it.

import { isEnabled } from "./capabilities.js";

// Baseline: <a download> works in every browser.
// Enhanced: save back to the file the user opened, where File System Access exists.
export async function setUpSave(button, getDocumentBlob) {
  if (!isEnabled("fileSystemAccess")) {
    button.addEventListener("click", () => downloadCopy(getDocumentBlob()));
    return;
  }

  // Only browsers that can use it download the enhanced module.
  const { saveWithPicker } = await import("./fs-save.js");
  button.textContent = "Save";
  button.addEventListener("click", async () => {
    try {
      await saveWithPicker(getDocumentBlob()); // must run inside the click (user activation)
    } catch (err) {
      if (err.name === "AbortError") return; // user closed the picker: not an error
      if (err.name === "NotAllowedError" || err.name === "SecurityError") {
        // Blocked by policy, permission or a missing gesture: fall back rather than fail.
        downloadCopy(getDocumentBlob());
        return;
      }
      throw err;
    }
  });
}

function downloadCopy(blob) {
  const url = URL.createObjectURL(blob);
  const a = Object.assign(document.createElement("a"), { href: url, download: "document.txt" });
  document.body.append(a);
  a.click();
  a.remove();
  // Revoke after the navigation has started; revoking synchronously can cancel it.
  setTimeout(() => URL.revokeObjectURL(url), 30_000);
}

The same pattern appears throughout this section: File System Access falls back to <input type="file"> and downloads, Web Share falls back to copying a link, Hardware & Device APIs fall back to explaining the native tool the user needs.

Error names are part of the contract¶

Capability APIs use DOMException names consistently enough that one handler can classify most failures:

The permission model¶

A capability call passes through a series of gates before anything reaches the user or the device. Knowing which gate rejected a call is most of debugging.

flowchart TD
    A["Page calls a powerful API"] --> B{"Secure context?"}
    B -->|No| X1["API missing or SecurityError"]
    B -->|Yes| C{"Permissions Policy allows it in this frame?"}
    C -->|No| X2["NotAllowedError / SecurityError"]
    C -->|Yes| D{"Transient user activation required?"}
    D -->|"Yes, but none"| X3["NotAllowedError"]
    D -->|"Yes and present, or not required"| E{"Stored permission state"}
    E -->|denied| X4["NotAllowedError, no prompt"]
    E -->|granted| G["API proceeds"]
    E -->|prompt| F["Browser prompt or chooser"]
    F -->|"User declines / cancels"| X5["NotAllowedError or AbortError"]
    F -->|"User allows / picks"| H{"OS-level permission?"}
    H -->|Blocked| X6["Error or empty result"]
    H -->|Allowed| G

Gate 1: secure context¶

Every capability API in this section requires a secure context: HTTPS, or http://localhost and loopback addresses during development. In an insecure context most of them are simply not exposed (navigator.serial is undefined), so feature detection returns false rather than throwing. Check window.isSecureContext when detection unexpectedly fails on a staging server.

Gate 2: Permissions Policy¶

Permissions Policy (formerly Feature Policy) lets a document restrict which powerful features it and its iframes may use. Each feature has a token and a default allowlist, which for nearly all capabilities is self: the top-level document and same-origin frames may use it, cross-origin iframes may not unless delegated.

Permissions-Policy: serial=(self), usb=(), hid=(), bluetooth=(), web-share=(self "https://embed.example.com"), screen-wake-lock=(self)

<iframe src="https://embed.example.com/player" allow="web-share; screen-wake-lock; clipboard-write"></iframe>

Capability-related tokens recognized by Chromium include bluetooth, camera, clipboard-read, clipboard-write, compute-pressure, display-capture, fullscreen, gamepad, geolocation, hid, identity-credentials-get, idle-detection, local-fonts, microphone, midi, payment, picture-in-picture, publickey-credentials-create, publickey-credentials-get, screen-wake-lock, serial, usb, web-share, window-management and xr-spatial-tracking, plus web-app-installation behind a flag. The authoritative list is the Permissions Policy features registry.

Cross-browser behavior differs in an important way: MDN's compatibility data lists the Permissions-Policy header as Chromium-only, while the iframe allow attribute works in all engines (Firefox 74, Safari 11.1). Setting a restrictive header is therefore defense in depth for Chromium users, not a cross-browser control. Only Chromium exposes a script API to test the policy, document.featurePolicy.allowsFeature("serial"). Permissions and Content Security Policy cover policy design for production.

Gate 3: prompts, choosers and pickers¶

Capabilities obtain consent in three different ways, and they persist differently:

Pickers are the model Mozilla and Apple are most comfortable with, which is why Web Share, Payment Request and WebAuthn are cross-engine while device choosers are not.

Chromium's help center describes both lifetime controls: "Allow this time" means the site "will be able to use the requested feature only during your current visit", and "To protect your data, Chrome removes permissions from sites you haven't used recently." Design for permissions that disappear. Query the state at launch, not once at install.

Querying permission state¶

The Permissions API reports "granted", "denied" or "prompt" for a named permission. It is supported everywhere (query() since Chrome 43, Firefox 46, Safari 16), but the set of names varies by browser, and the specification requires a rejected promise with a TypeError when the name is not supported. Treat that rejection as "unknown", not as "denied".

// Returns "granted" | "denied" | "prompt" | "unsupported".
export async function permissionState(name) {
  if (typeof navigator.permissions?.query !== "function") return "unsupported";
  try {
    const status = await navigator.permissions.query({ name });
    return status.state;
  } catch (err) {
    // TypeError: this browser does not recognize the permission name
    // (e.g. "local-fonts" outside Chromium, "clipboard-read" in Firefox and Safari).
    if (err instanceof TypeError) return "unsupported";
    throw err;
  }
}

// Keep UI in sync when the user changes the permission in site settings.
export async function watchPermission(name, onChange) {
  if (typeof navigator.permissions?.query !== "function") return () => {};
  let status;
  try {
    status = await navigator.permissions.query({ name });
  } catch {
    return () => {};
  }
  const handler = () => onChange(status.state);
  status.addEventListener("change", handler);
  onChange(status.state);
  return () => status.removeEventListener("change", handler);
}

Support data as of September 2026, from MDN's browser compatibility data. Safari's change event on PermissionStatus is marked partial. navigator.permissions.request() and revoke() are not shipped anywhere by default; request permissions through each API's own method.

Page-embedded permission controls¶

Chromium has been moving the moment of consent into the page with browser-rendered elements. The user's click on a browser-controlled element is an unambiguous signal of intent, and it gives users who previously denied a permission a way to recover without digging into settings. The <geolocation> element shipped in Chrome 144 (January 2026) on desktop and Android after an origin trial of the more general Page Embedded Permission Control. Mozilla rates the general PEPC proposal negative but the <geolocation> element positive; WebKit opposes PEPC. Use the element as an enhancement over a regular button that calls navigator.geolocation.

User activation: transient and sticky¶

Most capabilities that open browser UI require transient user activation: the call must happen shortly after a genuine user interaction. The HTML Standard defines two states per window:

Sticky activation

Set the first time the user interacts with the page and never reset for the life of the document. Gates features that must not fire on load: autoplay with sound, navigator.vibrate(), the beforeunload confirmation dialog, VirtualKeyboard.show().

Transient activation

Set on each interaction and valid for a limited duration, and it can be consumed. Gates everything that opens a window, picker, chooser or sheet.

Activation is triggered only by trusted events of these types: keydown (except Escape, browser-reserved shortcuts and keys such as Caps Lock), mousedown, pointerdown with a mouse pointer, pointerup with a non-mouse pointer, and touchend. Note that click is not in the list; it is the preceding mousedown/pointerup that activates, which is why a click handler has activation. Synthetic events from dispatchEvent() never activate. Scrolling and hovering never activate.

How long activation lasts¶

The specification leaves the duration to implementations ("should be at most a few seconds"). All three engines use 5 seconds: Chromium's kActivationLifespan is base::Seconds(5), Firefox's dom.user_activation.transient.timeout preference defaults to 5000 milliseconds, and WebKit's defaultTransientActivationDuration is 5_s. Any await between the click and the capability call spends that budget.

Consumption and propagation¶

Some APIs consume activation when they succeed: window.open(), navigator.share(), PaymentRequest.show() and fullscreen requests, among others. Consumption clears transient activation in every window in the frame tree, which prevents a single click from opening a popup and a share sheet, or from being replayed by an iframe. Activation propagates upward: a click in an iframe activates its ancestors, and a click in a document also activates same-origin descendant frames. Service workers have an analogous rule: clients.openWindow() and WindowClient.focus() are allowed only for a short time after the user clicks a notification, while the notificationclick event is being handled.

APIs gated by user activation¶

The list is based on MDN's features gated by user activation, which is non-exhaustive; each API page in this section notes its own requirement.

Checking activation and keeping it¶

navigator.userActivation exposes both states (isActive for transient, hasBeenActive for sticky) in Chrome 72, Firefox 120 and Safari 16.4. Use it to choose a path, not as a security check.

The classic bug is fetching data after the click and then calling the API:

// Broken: on a slow network the fetch takes longer than 5 seconds, activation
// expires, and navigator.share() rejects with NotAllowedError.
shareButton.addEventListener("click", async () => {
  const blob = await (await fetch("/reports/latest.pdf")).blob();
  await navigator.share({ files: [new File([blob], "report.pdf", { type: "application/pdf" })] });
});

The fix is to prepare the payload before the gesture, and to recover gracefully when you could not:

let prepared = null;

// Start the download when the share UI becomes visible, not when the user clicks.
export function prepareReport() {
  prepared ??= fetch("/reports/latest.pdf")
    .then((res) => {
      if (!res.ok) throw new Error(`HTTP ${res.status}`);
      return res.blob();
    })
    .then((blob) => new File([blob], "report.pdf", { type: "application/pdf" }))
    .catch((err) => {
      prepared = null; // allow a retry
      throw err;
    });
  return prepared;
}

// Wire it once: shareButton.addEventListener("click", () => onShareClick(shareButton));
export async function onShareClick(button) {
  const file = await prepareReport(); // usually already resolved: no activation spent

  if (navigator.userActivation && !navigator.userActivation.isActive) {
    // Too slow: activation expired while waiting. Ask for a fresh click. The next
    // click runs this same handler, finds the file already prepared and shares at once.
    // (Do not add a second listener here: both would run and the second share()
    // would reject because the first one consumed the activation.)
    button.textContent = "Ready: tap to share";
    return;
  }
  await shareFile(file);
}

async function shareFile(file) {
  if (!navigator.canShare?.({ files: [file] })) {
    location.assign(URL.createObjectURL(file)); // fallback: open the PDF
    return;
  }
  try {
    await navigator.share({ files: [file], title: "Latest report" });
  } catch (err) {
    if (err.name !== "AbortError") throw err; // AbortError = user closed the sheet
  }
}

Origin trials: trying APIs before they ship¶

An origin trial enables an experimental feature in stable Chrome for origins that opt in with a token, so you can test it with real users before it is standardized. Most Fugu APIs spent months in one.

How Chrome origin trials work¶

1. Pick a trial on the Chrome origin trials site and register your origin. You can optionally match all subdomains; tokens are not issued for origins on the Public Suffix List.
2. Deliver the token with the page, in any of three ways: a <meta http-equiv="origin-trial" content="TOKEN"> element, an Origin-Trial: TOKEN response header, or a <meta> element that script inserts before the feature is used.
3. Service workers and shared workers need the header. Dedicated workers inherit from their parent document, but a service worker is not a document, so the token must be in the Origin-Trial header of the service worker script response.
4. Third-party trials let an embed provider enable a feature on every site that includes its script. The token must come from an external script served by the registered origin; it does not work in a <meta> tag, an inline script or a header.
5. Tokens are verified on the device without network access, and each token carries its own expiry. Renew it when the trial is extended.

Chromium's launch process bounds the experiment. An initial origin trial may run for at most 12 milestones, and each extension may add 6 milestones at a time only with demonstrated progress on the specification, TAG review, other vendors' signals and web-platform tests. Trials are "gapless": they normally end one milestone after the version that enables the feature by default, so a successful API keeps working through the switch. A safeguard automatically disables a trial globally if usage exceeds 0.5% of all Chrome page loads, and some trials also exclude a small subset of users even when the page has a valid token.

// Inject an origin-trial token at run time, e.g. only for users in an experiment cohort.
// Must run before the code that uses the feature.
export function enableOriginTrial(token) {
  const meta = document.createElement("meta");
  meta.httpEquiv = "origin-trial";
  meta.content = token;
  document.head.append(meta);
}

// Feature detection is still the source of truth: the token can be expired,
// the trial can be disabled, or the user can be in the excluded subset.

location = /sw.js {
    # Service workers only see origin-trial tokens delivered in the header.
    add_header Origin-Trial "YOUR_TOKEN" always;
    add_header Cache-Control "no-cache" always;
}

import express from "express";

const app = express();
const ORIGIN_TRIAL_TOKEN = process.env.ORIGIN_TRIAL_TOKEN;

app.get("/sw.js", (req, res, next) => {
  // Documents can use <meta>, but the service worker needs the header.
  if (ORIGIN_TRIAL_TOKEN) res.set("Origin-Trial", ORIGIN_TRIAL_TOKEN);
  // serve-static only adds its own Cache-Control when none is set, so this one is kept.
  res.set("Cache-Control", "no-cache");
  next();
});

app.use(express.static("dist"));
app.listen(8080);

Check the result in Chrome DevTools under Application > Frames > (frame) > Origin trials, which shows each token's status (Success, Expired, WrongOrigin and others), expiry and matching options. For local development, enable the feature in chrome://flags instead of using a token.

Other vendors and deprecation trials¶

Microsoft Edge runs its own origin trials program for Edge-originated features, with the same token mechanism. Firefox runs origin trials too: you request a token through a pre-filled Bugzilla template and deliver it with an Origin-Trial header or <meta> tag. WebKit does not run a public origin-trial program comparable to Chrome's; experimental WebKit features are tried in Safari Technology Preview or through Safari's feature-flag settings. Chrome also runs deprecation trials, which temporarily re-enable a removed feature for sites that need migration time.

Capability support matrix¶

The matrix covers the capabilities documented in this section and in Background & Engagement. Numbers are the first version with default-on support; "Chromium desktop" is Chrome and Edge on Windows, macOS and Linux unless noted.

Support data as of September 2026. Versions come from MDN's browser-compat-data (release 8.1.3), chromestatus.com and the individual pages linked in the last column, which carry footnotes for each ⚠️. For live data use caniuse and the "Browser compatibility" section of each MDN page. Edge follows the Chromium version for all Chromium features. The iOS column applies to every browser on iOS and iPadOS, since they all use WebKit.

Deciding what to build on¶

The matrix answers "where does it work?". The decision you actually face is "what happens to users where it does not?". Four questions settle most cases:

flowchart TD
    A["Capability needed for a feature"] --> B{"Supported in every engine your users run?"}
    B -->|Yes| C["Build on it; detect for old versions"]
    B -->|No| D{"Is there an acceptable fallback?"}
    D -->|Yes| E["Progressive enhancement: baseline + enhanced path"]
    D -->|No| F{"Can you require a browser for this feature?"}
    F -->|"Yes: internal tool, kiosk, enterprise"| G["Require Chromium; say so clearly and early"]
    F -->|No| H{"Is it the core of the product?"}
    H -->|Yes| I["Consider native, TWA wrapper, or Isolated Web App"]
    H -->|No| J["Ship without it where unsupported"]

Some practical guidance from how teams deploy these APIs:

• Consumer apps: build on tier 1; use tier 2 and 3 as enhancements that visibly improve Chromium and Android without degrading iOS. A share button, a "save back to file" option and an app badge are good examples.
• Hardware configurators and internal tools: a hard Chromium requirement is often acceptable (factory floors, education labs, device setup pages). Detect early and show a clear "open this page in Chrome or Edge on a computer" message instead of a broken UI.
• Store distribution: a Trusted Web Activity inherits Chrome's capabilities on Android. It does not add capabilities that Chrome lacks.
• Beyond the PWA security model: raw TCP/UDP sockets and similar APIs are offered only to Isolated Web Apps, which are packaged and signed and are not installed from ordinary websites.

PWA vs Native vs Hybrid and When to Build a PWA expand this decision beyond capabilities.

How to track capability status¶

Capability support moves with every Chromium milestone (every four weeks through Chrome 152, and every two weeks since Chrome 153 shipped on 8 September 2026, according to the Chromium release schedule) and a few times a year in Safari. Build a habit, and ideally a script, instead of relying on memory or old blog posts.

On chromestatus, the "Consensus & Standardization" block of a feature entry records the other engines' signals with links to the positions issues, and each Chrome stage links the blink-dev threads: Intent to Prototype, Intent to Experiment (the origin trial), and Intent to Ship. Reading the Intent to Ship thread is the fastest way to learn the edge cases and the concerns reviewers raised.

Automating the check¶

MDN publishes its compatibility data as a single JSON file. A small script can print the support for the exact capabilities your app uses, so you can run it in CI or before a planning meeting instead of re-reading tables.

// Node 18+ (global fetch). Usage: node scripts/capability-report.mjs
// Prints browser support for the capabilities this app depends on, from MDN's browser-compat-data.

const BCD_URL = "https://unpkg.com/@mdn/browser-compat-data/data.json";

// Map human-readable names to BCD paths. Add every capability your app feature-detects.
const FEATURES = {
  "Web Share": "api.Navigator.share",
  "Share target (manifest)": "manifests.webapp.share_target",
  "File System Access": "api.Window.showOpenFilePicker",
  "File handlers (manifest)": "manifests.webapp.file_handlers",
  "Badging": "api.Navigator.setAppBadge",
  "Screen Wake Lock": "api.WakeLock",
  "Web Serial": "api.Serial",
  "Window Controls Overlay": "api.WindowControlsOverlay",
};

const BROWSERS = ["chrome", "chrome_android", "edge", "firefox", "firefox_android", "safari", "safari_ios"];

function lookup(data, path) {
  return path.split(".").reduce((node, key) => node?.[key], data)?.__compat;
}

function describe(statement) {
  // BCD support statements can be arrays (newest first) or single objects.
  const s = Array.isArray(statement) ? statement[0] : statement;
  if (!s || !s.version_added) return "no";
  if (s.version_removed) return `removed in ${s.version_removed}`;
  let text = String(s.version_added);
  if (s.flags) text += " (flag)";
  if (s.partial_implementation) text += " (partial)";
  return text;
}

async function main() {
  const response = await fetch(BCD_URL);
  if (!response.ok) throw new Error(`Failed to download BCD: HTTP ${response.status}`);
  const data = await response.json();
  console.log(`MDN browser-compat-data ${data.__meta.version} (${data.__meta.timestamp})`);

  const rows = {};
  for (const [name, path] of Object.entries(FEATURES)) {
    const compat = lookup(data, path);
    if (!compat) {
      rows[name] = { error: `unknown BCD path ${path}` };
      continue;
    }
    rows[name] = Object.fromEntries(BROWSERS.map((b) => [b, describe(compat.support[b])]));
    if (compat.status?.experimental) rows[name].experimental = "yes";
  }
  console.table(rows);
}

main().catch((err) => {
  console.error(err);
  process.exitCode = 1;
});

Common pitfalls¶

• Feature detecting too shallowly. "setAppBadge" in navigator is true on Chrome for Android and Linux, where nothing appears. "share" in navigator is true in Firefox for Android, which cannot share files. Test the input with canShare() and know which platforms are no-ops.
• Spending the activation budget. Any network request or slow computation between the click and share(), showSaveFilePicker() or requestDevice() risks the 5-second limit. Prepare data ahead of the gesture.
• Calling two activation-consuming APIs from one click. The first consumes activation for the whole frame tree; the second fails with NotAllowedError.
• Treating TypeError from permissions.query() as "denied". It means the browser does not know the name. Fall back to calling the API from a gesture.
• Forgetting cross-origin iframes. Embedded widgets need allow="..." delegation for web-share, clipboard-write, screen-wake-lock, serial and the rest; the default allowlist is self.
• Testing declarative features in a tab. Share targets, file handlers, protocol handlers, shortcuts and Window Controls Overlay do nothing until the app is installed, and manifest changes need the update flow in App Identity & Updates before they reach the OS.
• Assuming a Chromium feature is on every Chromium platform. Check desktop versus Android versus ChromeOS versus Linux separately, and remember Android WebView.
• Depending on an origin trial. Trials end, can be globally disabled at 0.5% of page loads, and service workers silently lack the feature if the token is only in a <meta> tag.
• Prompting on load. Permission prompts without context get denied, Chromium switches sites with low notification acceptance to a quieter prompt, and grants disappear when Chromium removes permissions from unused sites. Ask at the moment of use.

Debugging capabilities¶

• Is it a secure context? Log isSecureContext. Staging servers on plain HTTP or unusual hostnames are the usual cause of "the API is undefined".
• Is it allowed in this frame? Chrome DevTools > Application > Frames lists the frame's permissions-policy allowed and disallowed features. In Chromium, document.featurePolicy.allowedFeatures() returns the list from the console.
• What is the permission state? Query it (see the helper above), and reset it from the site-information icon in the address bar or chrome://settings/content.
• Did activation expire? Log navigator.userActivation.isActive right before the call.
• Is the origin trial active? Application > Frames > Origin trials shows token status per frame; check the service worker's response headers for the Origin-Trial header.
• Is the OS integration registered? chrome://web-app-internals shows installed apps with their parsed manifest, including file handlers, protocol handlers, share target and launch_handler. On Android, chrome://webapks shows WebAPK state and lets you request an update.
• Device APIs have their own internals pages (about://bluetooth-internals, about://usb-internals, about://device-log), described in Hardware & Device APIs. General DevTools workflows are in Browser DevTools.

Pages in this section¶

Further reading¶

On this site

• History & Evolution: where Project Fugu fits in the PWA timeline
• Advanced & Integration Members: every manifest member behind OS integration
• Background & Engagement: push, badging and background execution
• Permissions: permission UX and policy design in depth
• iOS & iPadOS: what WebKit supports for Home Screen web apps
• Desktop Platforms: per-OS behavior of installed desktop PWAs
• Isolated Web Apps: APIs beyond the PWA security model
• On-device AI in the browser

External references

• Unlocking new capabilities for the web (Chrome for Developers): the original Fugu process
• Fugu showcase (Chrome for Developers)
• HTML Standard: tracking user activation
• User activation (MDN)
• Permissions specification (W3C) and Permissions API (MDN)
• Permissions Policy specification and Permissions-Policy header (MDN)
• Get started with origin trials (Chrome for Developers)
• Blink launch process (Chromium)
• Mozilla standards positions and WebKit standards positions
• WebKit tracking prevention: APIs not implemented