Provide icons for web apps in GNOME Web (Epiphany)

I recently made a small contribution to the GNOME Web browser in the form of a patch to put web standards first when choosing icons for use with their installable web apps. As there was no documentation of how this worked in previous versions, I’ll document this here.

The following applies to GNOME Web version 3.21.2 and newer. (Web follows GNOME desktop’s version numbers.)

GNOME Web (formerly known as Epiphany) has a seriously powerful feature where you can install any website as an application and have it show up in the activities overview as any other app would. It’s a convenient way to manage frequently used web apps and services, while also providing some isolation from the wide-open web for sensitive websites and logins.

Even if GNOME Web isn’t your preferred browser for daily browsing, your productivity and security could benefit from moving a few tabs that you always keep open into web apps.

For these apps to do their job, they need to be able to grab beautiful icons for any website. Previous versions of GNOME Web would prefer the “pinned site” mechanism built for Internet Explorer in Windows 8, the msapplication-TileImage meta data property. Since the inclusion of my patch, however, GNOME Web will prefer standard HTML icons over any vendor-specific methods such as apple-touch-icon and msapplication.

Create Web Application dialog in GNOME Web showing Slight Future as a web app

Below is a complete list of the different methods GNOME Web can use to find an icon. The list is sorted in the order of preference when choosing an icon as used in GNOME Web.

<link href="/icon_vector.svg" rel="icon" sizes="any">
<link href="/icon_256.png" rel="icon" sizes="256">
<link href="/icon_128.jpg" rel="icon" sizes="128">
<meta name="msapplication-tileimage" content="/icon144.png">
<link href="/icon_128.jpg" rel="apple-touch-icon">
<meta property="og:image" content="/icon256.png">
<meta name="og:image" content="/icon192.png">
<meta itemprop="image" content="/icon192.png">
<link href="/favicon.ico" rel="shortcut icon">

The preferred icon is a vector, specified as a linked relational icon with the sizes="any" attribute. Followed by the largest size sizes attribute available. If none of these web standard methods are available, GNOME Web will start looking for vendor-specific methods such as apple-touch-icon and msapplication, followed by any OpenGraph image, and finally a icon with an unspecified size (assumed to be a small favicon.) If none of these icons are included in the document, GNOME Web will try to request /favicon.ico from the root of the server.

All icons regardless of their size will be scaled to exactly 192x192 px and rasterized to a PNG file. Earlier versions of GNOME Web used icons at 144x144 pixels (like msapplication) or smaller. The sum of these changes is that more apps will now get better icons at higher resolutions.

Any web developer who focuses on the current web standards will find their app or website will just work on GNOME Web. If you want to target GNOME specifically, you can consider to provide a variant of your web app’s icon that complies with the Icons and artwork section in the GNOME Human Interface Guidelines.

GNOME Web only supports a single size specified in the sizes attribute. While the below syntax is standards-compliant (and the .icns format is supported in GNOME Web), it’s not supported as of version 3.21.2:

<link href="/icon.icns" rel="icon" sizes="192x192 256x256 512x512">

As of Web 3.21.2, it will also allow case insensitive matching of <meta> tags (allowing for creative interpretations of the HTML standard) rather than require lowercase markup. Web app names now will be prefilled with <meta name="application-name" value="App Name"> names.

Installed web apps will also identify themselves with the new user agent “Epiphany/<version> (Web App)”. There are some more details on tweaks and changes in the patches attached to GNOME bug #767257 and bug #767123.

I guess this can be seen as the second article in the series where I document previously undocumented icon selections in browsers who don’t document it themselves. Check out the first part, “All about icons for Microsoft Edge”.

I’ll create a document for web developers in the GNOME wiki someday soon to provide some reference for web developers who will bother with how their app or website appears and functions in GNOME Web.