Skip to content
Tutorials Center
My learning

Topics

Lesson 9 of 37 ยท Web App Manifest

Shortcuts, Share Target and More Manifest Features

Go beyond the basics: add app shortcuts, screenshots, share_target, file and protocol handlers, launch_handler and related fields to your PWA manifest.

The basic manifest makes an app installable. The rest of the manifest vocabulary makes it feel integrated: long-press the icon for quick actions, share a link from another app straight into yours, get a rich install dialog with screenshots, open files of a certain type with your PWA. Many of these are Chromium-first features, so treat them as enhancements: your app must work without them.

shortcuts

Shortcuts appear when the user long-presses the app icon on Android, right-clicks it on desktop or the taskbar, or opens its context menu. Each shortcut deep-links into a part of your app.

JSON
{
  "shortcuts": [
    {
      "name": "New note",
      "short_name": "New",
      "description": "Start a blank note",
      "url": "/new?source=shortcut",
      "icons": [{ "src": "/icons/new-96.png", "sizes": "96x96" }]
    },
    {
      "name": "Search notes",
      "url": "/search",
      "icons": [{ "src": "/icons/search-96.png", "sizes": "96x96" }]
    }
  ]
}

Rules to keep in mind: the url must be inside the manifest scope; platforms show only a few shortcuts (often four); and a shortcut url has to work offline too, so cache those pages.

screenshots

Screenshots make the install dialog richer: Chrome on Android and desktop show them in an expanded dialog, and some stores use them as listing images.

JSON
{
  "screenshots": [
    { "src": "/shots/home-wide.png", "sizes": "1280x720", "type": "image/png",
      "form_factor": "wide", "label": "Notes list on desktop" },
    { "src": "/shots/home-narrow.png", "sizes": "720x1280", "type": "image/png",
      "form_factor": "narrow", "label": "Notes list on a phone" }
  ]
}

form_factor is wide (desktop) or narrow (mobile). Use real screenshots of the app at a consistent aspect ratio, and give them a label for accessibility.

share_target

With share_target, your installed PWA appears in the system share sheet. When a user shares a link or text from another app, your app opens with the data.

JSON
{
  "share_target": {
    "action": "/share",
    "method": "GET",
    "params": { "title": "title", "text": "text", "url": "url" }
  }
}

The system opens /share?title=...&text=...&url=... and your page reads the query string. For files, use POST with multipart/form-data and a files entry:

JSON
{
  "share_target": {
    "action": "/share-file",
    "method": "POST",
    "enctype": "multipart/form-data",
    "params": {
      "title": "title",
      "files": [{ "name": "photos", "accept": ["image/*"] }]
    }
  }
}

A POST share goes to your server (or to your service worker's fetch handler, which can intercept it and store the files for offline use).

Reading the incoming data is ordinary URL parsing, so you can try it now:

JS Read shared data from the URL

Press Run (or Ctrl + Enter) to see the console output here.

No output.

file_handlers and protocol_handlers

file_handlers register your app to open file types.

JSON
{
  "file_handlers": [
    {
      "action": "/open",
      "accept": { "text/markdown": [".md"], "text/plain": [".txt"] }
    }
  ]
}

When the user double-clicks a .md file, your installed PWA opens at /open, and your script receives the files through window.launchQueue.setConsumer(...). Supported on desktop Chromium.

protocol_handlers register custom schemes such as web+trail:

JSON
{
  "protocol_handlers": [
    { "protocol": "web+trail", "url": "/open?link=%s" }
  ]
}

Custom schemes must start with web+ (a handful of standard ones like mailto are also allowed). %s is replaced with the encoded link.

launch_handler, edge_side_panel and others

  • launch_handler controls what happens if the user opens your app while a window is already open: { "client_mode": "navigate-existing" } reuses the window, "focus-existing" just focuses it and lets you handle the launch in JavaScript, "navigate-new" opens another window.
  • edge_side_panel (Edge only) lets the app run in the browser side panel and has a preferred_width value.
  • widgets (Windows) define widget templates for the Windows widget board.
  • note_taking names a new_note_url so the system can launch your app as a quick-note tool.
  • scope_extensions let one app cover several origins you own.
  • related_applications and prefer_related_applications point to native apps and tell the browser whether to favor them over the PWA. Setting prefer_related_applications to true suppresses the install prompt, so leave it false unless you mean it.
  • iarc_rating_id supplies an age rating code used by some stores.

Don't add all of these. Choose the ones that match what your app really does.

Validating a manifest in code

Because strict JSON and the many optional members make typos easy, a validation step belongs in your build. The stand-in below shows a rule-based validator for the members of this lesson. Run it, then break something and run it again.

JS Stand-in: validate advanced manifest members

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Feature support and graceful behavior

All of these members are ignored by browsers that do not understand them. That is a deliberate design of the manifest: unknown members cause no error. It means you can add them freely, but you must also never rely on them for core functionality. If a user shares from a browser without share_target, they can still paste a link. If they cannot long-press for shortcuts, the links also exist in your UI.

When a feature is important to you, detect it where possible. For file handlers, 'launchQueue' in window tells you whether your app can receive launched files:

JavaScript
if ('launchQueue' in window) {
  launchQueue.setConsumer(async (launchParams) => {
    for (const handle of launchParams.files) {
      const file = await handle.getFile();
      console.log('Opened', file.name);
    }
  });
}

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Where do manifest shortcuts appear?

    Shortcuts give quick actions from the app icon's context menu.
  2. 2. Which share_target method is needed to receive files?

    Files can only be shared with POST and a multipart/form-data enctype.
  3. 3. What must a custom protocol handler scheme look like?

    Custom schemes must use the web+ prefix, apart from a few standard allowed schemes.
  4. 4. What happens when a browser does not support a manifest member?

    Unknown members are ignored, so treat these features as enhancements.
  5. 5. Setting prefer_related_applications to true will...

    It tells the browser to favor the native app, which usually hides the PWA install prompt.

Summary

  • shortcuts add quick actions to the app icon; their URLs must be in scope and work offline.
  • screenshots with form_factor enrich the install dialog.
  • share_target lets your app receive shared text, links and files; file_handlers and protocol_handlers add open-with integration.
  • launch_handler controls reuse of windows; other members target specific platforms.
  • Unsupported members are ignored, so use them as enhancements only.

Next: Service Worker Basics