Adding screenshots to your PWA install experience

You can improve your visitors' PWA install experience on mobile by adding product screenshots to your manifest file.

Background

In February 2022, OnlyRSS.org became a Progressive Web App (PWA). The plan wasn't really for anyone to install OnlyRSS on their mobile or desktop; it was for me to understand what was required to turn a website into a PWA—and the best way for me to understand that was to do it.

The Google Play and Apple App Store are great places to discover new apps. Once you find an app that might be useful, you get to read a description and view some screenshots of the app before you decide to install. There is no convenient store for PWAs, so initial discoverability is still an issue. However, once a visitor does happen upon your PWA-enabled website and is prompted to install your PWA, there is now a solution for providing the visitor with screenshots and a description. And all that's required is a few new entries in the existing manifest file.

New manifest file entries

Below, you can see the required entries in the manifest file for the screenshots and description. Webp images are supported, so after capturing suitable screenshots, I'd recommend using a tool such as CompressOrDie to convert them to webp and then compress them as best you can without degrading the quality too much (my images are ≈40 KB each).

The new entry in the manifest file:

"screenshots":[
  {
    "src":"pwaicons/screenshot1.webp",
    "sizes": "485x1024",
    "type": "image/webp"
  },
  {
    "src":"pwaicons/screenshot2.webp",
    "sizes": "485x1024",
    "type": "image/webp"
  }
],

Result

Once the new manifest entries have been added, when a visitor accesses your website on Chrome on Android (or Samsung Internet on Samsung devices), in addition to being prompted to install your PWA, they will have the option to swipe up on the install prompt and view your app description and screenshots [fig. 1]. The visitor can tap on the screenshots and view them full size.

Animated GIF showing the user expanding the PWA install prompt on a mobile phone, and then being presented with the PWA description and 2 screenshots.
Improved PWA install prompt, showing description and screenshots on Chrome on Android.

Compatibility

According to MDN Web Docs, app screenshots are supported in:

  • Edge on Desktop (≥88)
  • Chrome on Android (≥88)
  • Samsung Internet on mobile (≥15.0)

I've tested them on Android, where they work as advertised, but I had no luck getting them to work on Windows. I added additional screenshots to the manifest and set the 'platform' member to both 'wide' and 'windows', and neither resulted in the screenshots (or description) being visible. I've left those entries in my manifest file (in the hope that Edge/Chrome will support them in the future); they can be seen under the screenshots section of my manifest file.

Compatibility Update - Dec 2023

I finally managed to fix the issue where the screenshots were not showing during the desktop install. I updated the Manifest file with the following: 

  "screenshots":[
    {
      "src": "pwaicons/screenshot2.webp",
      "sizes": "485x1024",
      "type": "image/webp",
      "form_factor": "narrow",
      "label": "The About page shown on mobile."
    },
    {
      "src": "pwaicons/screenshot3.webp",
      "sizes": "1280x720",
      "type": "image/webp",
      "form_factor": "wide",
      "label": "The About page shown on desktop."
    },
  ],

The "form_factor": "wide" is required for so that the image thumbnails show during the desktop install.

Conclusions

Adding screenshots and a description to your PWA is yet another step in moving your app away from being "just a website" and towards being an "application". It's easy to implement and improves the installation experience for Android (and Samsung) visitors on mobile. I also suspect that in the future, these app screenshots and description will start to surface in web search results (alongside an install prompt) and maybe even in app stores 🤞.