PWACompat is a library that brings the Web App Manifest to non-compliant browsers for better Progressive Web Apps. This includes creating splash screens for Mobile Safari, and supporting IE/Edge's Pinned Sites feature.

So, if you've created a manifest.webmanifest but want to have wide support everywhere else—through legacy HTML tags for icons and theming—look no further. Just include the minified script pwacompat.min.js (or bundle/serve it yourself) in your page:

<link rel="manifest" href="manifest.webmanifest" />
<script async src="https://cdn.jsdelivr.net/npm/pwacompat@2.0.9/pwacompat.min.js"
    integrity="sha384-VcI6S+HIsE80FVM1jgbd6WDFhzKYA0PecD/LcIyMQpT4fMJdijBh0I7Iblaacawc"
    crossorigin="anonymous"></script>

And you're done! 🎉📄

For more on the Web App Manifest, read 📖 how to add a Web App Manifest and mobile-proof your site, watch 📹 theming as part of The Standard, or check out 📬 the Web Fundamentals post on PWACompat.

PWACompat takes your regular manifest and enhances other browsers

Best Practice & Caveats

While PWACompat can generate most icons, meta tags etc that your PWA might need, it's best practice to include at least one <link rel="icon" ... />. This is standardized and older browsers, along with search engines, may use it from your page to display an icon. For example:

<link rel="manifest" href="manifest.webmanifest" />
<script async src="path/to/pwacompat.min.js"></script>
<!-- include icon also from manifest -->
<link rel="icon" type="image/png" href="res/icon-128.png" sizes="128x128" />

If you're looking for the best load performance, you can also defer loading PWACompat until after your site has loaded. This is the approach taken in Emojityper.

iOS

PWACompat looks for a viewport tag which includes viewport-fit=cover, such as <meta name="viewport" content="viewport-fit=cover">. If this tag is detected, PWACompat will generate a meta tag that makes your PWA load in fullscreen mode—this is particularly useful for devices with a notch.

Old Versions

Prior to iOS 12.2, Mobile Safari opens external sites in the regular browser, meaning that flows like Oauth won't complete correctly. This isn't a problem with PWACompat, but is an issue with PWAs on iOS generally.

Prior to iOS 11.3, Mobile Safari would not respect the start_url paramater inside the manifest. If you want to emulate this behavior (and redirect the user to the start page), then you could detect navigator.standalone (indicating that your site is loaded in PWA mode) and set a flag in window.sessionStorage. If the flag is not yet set, then you should redirect to your site's start URL.

Session Storage

PWACompat uses window.sessionStorage to cache your site's manifest (and on iOS, any updated icons and generated splash screens). This expires after a user navigates away from your page or closes their tab.

Details

What does PWACompat actually do? If you provide a Web App Manifest, PWACompat will update your page and:

Create meta icon tags for all icons in the manifest (e.g., for a favicon, older browsers)
Create fallback meta tags for various browsers (e.g., iOS, WebKit/Chromium forks etc) describing how a PWA should open
Sets the theme color based on the manifest

For Safari, PWACompat also:

Sets apple-mobile-web-app-capable (opening without a browser chrome) for display modes standalone, fullscreen or minimal-ui
Creates apple-touch-icon images, adding the manifest background to transparent icons: otherwise, iOS renders transparency as black
Creates dynamic splash images, closely matching the splash images generated for Chromium-based browsers

For IE and Edge:

Adds meta tags for the Pinned Sites feature

For PWAs on Windows with access to UWP APIs:

Sets the titlebar color

Do you think PWACompat should support backfilling more HTML tags needed for older browsers? Let us know!

Demo

For a demo, try adding Emojityper or the demo site to an iOS home screen (to see splash screens and icons). You can also install Emojityper from the Microsoft Store (where the titlebar color is automatically set the manifest's theme_color).

Support

This is supported in most modern browsers (UC Browser, Safari, Firefox, Chrome, IE10+), and fails silenty when unsupported. Mobile Safari benefits the most from PWACompat, as generating a large number of splash screens manually is a complex task.

Web App Manifest

Your Web App Manifest is:

normally named manifest.webmanifest (although some folks name it manifest.json)
referenced from all pages on your site like <link rel="manifest" href="path/to/manifest.webmanifest" />
and should look a bit like this:

{
  "name": "Always Be Progressive",
  "short_name": "Progressive!",
  "display": "browser",
  "start_url": "/",
  "background_color": "#102a48",
  "icons": [
    {
      "src": "res/icon-256.png",
      "sizes": "256x256"
    },
    {
      "src": "res/icon-128.png",
      "sizes": "128x128"
    }
  ]
}

For more information on the Web App Manifest, and how e.g., modern browsers will prompt engaged users to install your site to their home screen, check out Web Fundamentals. There's also a number of online generators.

Release

Compile code with Closure Compiler.

// ==ClosureCompiler==
// @compilation_level ADVANCED_OPTIMIZATIONS
// @output_file_name pwacompat.min.js
// ==/ClosureCompiler==

// code here

alexktzk / pwacompat