• Added support for the shortcuts manifest member on macOS. Shortcuts are available in the File menu and the Dock context menu. Users can set up custom keyboard shortcuts for them in System Settings > Keyboard > Keyboard Shortcuts > App Shortcuts. (106137954)
• Added support for the categories manifest member on macOS. When creating a Launchpad folder containing web apps, the folder is automatically named accordingly. (116480550)

🎉

# Where it all started

I had the original idea for “projections” way back in 2019. Inspired by OS X’s Dashboard Widgets and Adobe AIR, I’d begun to wonder if it might be possible to project a component from a website into those kinds of surfaces. Rather than building a bespoke widget that connected to an API, I thought it made sense to leverage an installed PWA to manage those “projections.” I shared the idea at TPAC that year and got some interest from a broad range of folks, but didn’t have much time to work on the details until a few years later.

In the intervening time, I kept working through the concept in my head. I mean in an ideal world, the widget would just be a responsive web page, right? But if that were the case, what happens when every widget loads the entirety of React to render their stock ticker? That seemed like a performance nightmare.

In my gut, I felt like the right way to build things would be to have a standard library of widget templates and to enable devs to flow data into them via a Service Worker. Alex Russell suggested I model the APIs on how Notifications are handled (since they serve a similar function) and I was off to the races.

I drafted a substantial proposal for my vision of how PWA widgets should work. Key aspects included:

• A declarative way to define and configure a widget from within the Web App Manifest;
• A progressively enhanced pathway for devs to design a widget that adapts to its host environment, from using predefined templates to using custom templates to full-blown web-based widgets (with rendering akin to an iframe);
• A collection of recommended stock templates that implementors should offer to support most widget types;
• Extensibility to support custom templates using any of a variety of templating languages; and
• A complete suite of tools for managing widgets and any associated business logic within a Service Worker.

# Widgets became a reality

After continuing to gently push on this idea with colleagues across Microsoft (and beyond), I discovered that the Windows 11 team was looking to open up the new Widget Dashboard to third-party applications. I saw this as an opportunity to turn my idea into a reality. After working my way into the conversation, I made a solid case for why PWAs needed to be a part of that story and… it worked! (It no doubt helped that companies including Meta, Twitter, and Hulu were all invested in PWA as a means of delivering apps for Windows.)

While the timeline for implementation didn’t allow us to tackle the entirety of my proposal, we did carve out the pieces that made for a compelling MVP. This allowed us to show what’s possible, see how folks use it, and plan for future investment in the space.

Sadly, it meant tabling two features I really loved:

• Stock/predefined templates. A library of lightly theme-able, consistent, cross-platform templates based on common data structures (e.g., RSS/Atom, iCal) would make it incredibly simple for devs to build a widget. If implemented well, devs might not even need to write a single line of business logic in their Service Worker as the browser could pick up all of the configuration details from the Manifest.
• Configurable widget instances. Instead of singleton widgets, these would allow you to define a single widget type and replicate it for different use cases. For example, a widget to follow a social media user’s profile could be defined once and the individual instances could be configured with the specific account to be followed.

I’m sincerely hopeful these two features eventually make their way to us as I think they truly unlock the power of the widget platform. Perhaps, with enough uptake on the current implementation, we can revisit these in the not-too-distant future.

To test things out, I decided to build two widgets for this site:

1. Latest posts
2. Latest links

Both are largely the same in terms of their setup: They display a list of linked titles from this site.

# Designing my widget templates

Given that they were going to be largely identical, I made a single “feed” template for use in both widgets. The templating tech I used is called Adaptive Cards, which is what Windows 11 uses for rendering.

Adaptive Card templates are relatively straightforward JSON:

{“type”:“AdaptiveCard”,“$schema”:“http://adaptivecards.io/schemas/adaptive-card.json”,“version”:“1.6”,“body”: [{“$data”:“${take(items,5)}”,“type”:“Container”,“items”: [{“type”:“TextBlock”,“text”:“[${title}](${url})”,“wrap”:true,“weight”:“Bolder”,“spacing”:“Padding”,“height”:“stretch”}],“height”:“stretch”}],“backgroundImage”: {“url”:“https://www.aaron-gustafson.com/i/background-logo.png”,“verticalAlignment”:“Bottom”,“horizontalAlignment”:“Center”}}

What this structure does is:

1. Create a container into which I will place the content;
2. Extract the first five items from the data being fed into the template (more on that in a moment);
3. Loop through each item and
   • create a text block,
   • populate its content with Markdown to generate a linked title (using the title and url keys from the item object)
   • Set some basic styles to make the text bold, separate the titles a little and make them grow to fill the container; then, finally
4. Set a background on the widget.

The way Adaptive Cards work is that they flow JSON data into a template and render that. The variable names in the template map directly to the incoming data structure, so are totally up to you to define. As these particular widgets are feed-driven and this site already supports JSONFeed, I set up the widgets to flow the appropriate feed into each and used the keys that were already there. For reference, here’s a sample JSONFeed item:

{“id”:“…”,“title”:“…”,“summary”:“…”,“content_html”:“…”,“url”:“…”,“tags”:[],“date_published”:“…”}

If you want to tinker with Adaptive Cards and make your own, you can do so with their Designer tool.

# Defining the widgets in the Manifest

With a basic template created, the next step was to set up the two widgets in my Manifest. As they both function largely the same, I’ll just focus on the definition for one of them.

First off, defining widgets in the Manifest is done via the widgets member, which is an array (much like icons and shortcuts). Each widget is represented as an object in that array. Here is the definition for the “latest posts” widget:

{“name”:“Latest Posts”,“short_name”:“Posts”,“tag”:“feed-posts”,“description”:“The latest posts from Aaron Gustafson’s blog”,“template”:“feed”,“ms_ac_template”:“/w/feed.ac.json”,“data”:“/feeds/latest-posts.json”,“type”:“application/json”,“auth”:false,“update”:21600,“icons”:[{“src”:“/i/icons/webicon-rss.png”,“type”:“image/png”,“sizes”:“120x120”}],“screenshots”:[{“src”:“/i/screenshots/widget-posts.png”,“sizes”:“387x387”,“label”:“The latest posts widget”}]}

Breaking this down:

1. name and short_name act much like these keys in the root of the Manifest as well as in shortcuts: The name value is used as the name for the widget unless there’s not enough room, in which case short_name is used.
2. You can think of tag as analogous to class in HTML sense. It’s a way of labeling a widget so you can easily reference it later. Each widget instance will have a unique id created by the widget service, but that instance (or all instances, if the widget supports multiple instances) can be accessed via the tag. But more on that later.
3. The description key is used for marketing the widget within a host OS or digital storefront. It should accurately (and briefly) describe what the widget does.
4. The template key is not currently used in the Windows 11 implementation but refers to the expected standard library widget template provided by the system. As a template library is not currently available, the ms_ac_template value is used to provide a URL to get the custom Adaptive Card (hence “ac”) template. The “ms_” prefix is there because it’s expected that this would be a Microsoft-proprietary property. It follows the guidance for extending the Manifest.
5. The data and type keys define the path to the data that should be fed into the template for rendering by the widget host and the MIME of the data format it’s in. The Windows 11 implementation currently only accepts JSON data, but the design of widgets is set up to allow for this to eventually extend to other standardized formats like RSS, iCal, vCard, and such.
6. update is an optional configuration member allowing you to set how often you’d like the widget to update, in seconds. Developers currently need to add the logic for implementing this into their Service Worker, but this setup allows the configuration to remain independent of the JavaScript code, making it easier to maintain.
7. Finally, icons and screenshots allow us to define how the widget shows up in the widget host and how it is promoted for install.

When someone installs my site as a PWA, the information about the available widgets gets ingested by the browser. The browser then determines, based on the provided values and its knowledge of the available widget service(s) on the device, which widgets should be offered. On Windows 11, this information is routed into the AppXManifest that governs how apps are represented in Windows. The Windows 11 widget service can then read in the details about the available widgets and offer them for users to install.

# Adding widget support to my Service Worker

As I mentioned earlier, all of the plumbing for widgets is done within a Service Worker and is modeled on the Notifications API. I’m not going to exhaustively detail how it all works, but I’ll give you enough detail to get you started.

First off, widgets are exposed via the self.widgets interface. Most importantly, this interface lets you access and update any instances of a widget connected to your PWA.

# Installing a widget

When a user chooses to install a widget, that emits a “widgetinstall” event in your Service Worker. You use that to kickoff the widget lifecycle by gathering the template and data needed to instantiate the widget:

self.addEventListener(“widgetinstall”,(event)=>{console.log(</span><span class="token string">Installing </span><span class="token interpolation"><span class="token interpolation-punctuation punctuation">${</span>event<span class="token punctuation">.</span>widget<span class="token punctuation">.</span>tag<span class="token interpolation-punctuation punctuation">}</span></span><span class="token template-punctuation string">);event.waitUntil(initializeWidget(event.widget));});

The event argument comes in with details of the specific widget being instantiated (as event.widget). In the code above, you can see I’ve logged the widget’s tag value to the console. I pass the widget information over to my initializeWidget() function and it updates the widget with the latest data and, if necessary, sets up a Periodic Background Sync:

asyncfunctioninitializeWidget(widget){awaitupdateWidget(widget);awaitregisterPeriodicSync(widget);return;}

The code for my updateWidget() function is as follows:

asyncfunctionupdateWidget(widget){const template =await(awaitfetch(widget.definition.msAcTemplate)).text();const data =await(awaitfetch(widget.definition.data)).text();try{await self.widgets.updateByTag(widget.definition.tag,{ template, data });}catch(e){console.log(</span><span class="token string">Couldn’t update the widget </span><span class="token interpolation"><span class="token interpolation-punctuation punctuation">${</span>tag<span class="token interpolation-punctuation punctuation">}</span></span><span class="token template-punctuation string">, e);}return;}

This function does the following:

1. Get the template for this widget
2. Get the data to flow into the template
3. Use the self.widgets.updateByTag() method to push the template and data to the widget service to update any widget instances connected to the widget’s tag.

As I mentioned, I also have code in place to take advantage of Periodic Background Sync if/when it’s available and the browser allows my site to do it:

asyncfunctionregisterPeriodicSync(widget){let tag = widget.definition.tag;if(“update”in widget.definition){registration.periodicSync.getTags().then((tags)=>{// only one registration per tagif(!tags.includes(tag)){periodicSync.register(tag,{minInterval: widget.definition.update,});}});}return;}

This function also receives the widget details and:

1. Looks to see if the widget definition (from the Manifest) includes an update member. If it has one, it…
2. Checks to see if there’s already a Periodic Background Sync that is registered for this tag. If none exists, it…
3. Registers a new Periodic Background Sync using the tag value and a minimum interval equal to the update requested.

The update member, as you may recall, is the frequency (in seconds) you’d ideally like the widget to be updated. In reality, you’re at the mercy of the browser as to when (or even if) your sync will run, but that’s totally cool as there are other ways to update widgets as well.¹

# Uninstalling a widget

When a user uninstalls a widget, your Service Worker will receive a “widgetuninstall” event. Much like the “widgetinstall” event, the argument contains details about that widget which you can use to clean up after yourself:

self.addEventListener(“widgetuninstall”,(event)=>{console.log(</span><span class="token string">Uninstalling </span><span class="token interpolation"><span class="token interpolation-punctuation punctuation">${</span>event<span class="token punctuation">.</span>widget<span class="token punctuation">.</span>tag<span class="token interpolation-punctuation punctuation">}</span></span><span class="token template-punctuation string">);event.waitUntil(uninstallWidget(event.widget));});

Your application may have different cleanup needs, but this is a great time to clean up any unneeded Periodic Sync registrations. Just be sure to check the length of the widget’s instances array (widget.instances) to make sure you’re dealing with the last instance of a given widget before you unregister the sync:

asyncfunctionuninstallWidget(widget){if(widget.instances.length ===1&&“update”in widget.definition){await self.registration.periodicSync.unregister(widget.definition.tag);}return;}

# Refreshing your widgets

Widget platforms may periodically freeze your widget(s) to save resources. For example, they may do this when widgets are not visible. To keep your widgets up to date, they will periodically issue a “widgetresume” event. If you’ve modeled your approach on the one I’ve outlined above, you can route this event right through to your updateWidget() function:

self.addEventListener(“widgetresume”,(event)=>{console.log(</span><span class="token string">Resuming </span><span class="token interpolation"><span class="token interpolation-punctuation punctuation">${</span>event<span class="token punctuation">.</span>widget<span class="token punctuation">.</span>tag<span class="token interpolation-punctuation punctuation">}</span></span><span class="token template-punctuation string">);event.waitUntil(updateWidget(event.widget));});

# Actions

While I don’t want to get too into the weeds here, I do want to mention that widgets can have predefined user actions as well. These actions result in “widget click” events being sent back to the Service Worker so you can respond to them:

self.addEventListener(“widgetclick”,(event)=>{const widget = event.widget;const action = event.action;switch(action){// Custom Actionscase“refresh”:event.waitUntil(updateWidget(widget));break;}});

For a great example of how a widget can integrate actions, you should check out the demo PWAmp project. Their Service Worker widget code is worth a read.

# Result!

With all of these pieces in place, I was excited to see my site showing up in the Widget Dashboard in Windows 11.

You can view the full source code on GitHub:

• “Feed” Adaptive Card Template
• Widget definitions in the Manifest
• Widgets code in my Service Worker

I’m quite hopeful this will be the first of many places PWA-driven widgets will appear. If you’s like to see them supported elsewhere, be sure to tell your browser and OS vendor(s) of choice. The more they hear from their user base that this feature is needed, the more likely we are to see it get implemented in more places.

# Addendum: Gotchas

In wiring this all up, I ran into a few current bugs I wanted to flag so you can avoid them:

• The icons member won’t accept SVG images. This should eventually be fixed, but it was keeping my widgets from appearing as installable.
• The screenshots members can’t be incredibly large. I’m told you should provide square screenshots no larger than 500px ×500px.

• Scroll to Text Fragment
• Service Workers and Shared Workers can access the Permissions API.
• Notification API in dedicated workers.
• Reporting API.
• Screen Orientation API.
• Screen Wake Lock API.
• unprefixed Fullscreen API
• Push in web apps saved to the home screen on iOS
• “id” member in Web App Manifest
• Badging API.
• third-party browsers can Add to Home Screen

# What I had to work with

The previous iteration of Tipr was built in my hotel room while I was on site doing some consulting for a certain Silicon Valley company. I was rocking a Palm Treo 650 at the time and that day a few of my colleagues had lined up to wait for the release of the very first iPhone. At the time, web apps were the only way to get an “app” on the iPhone as there was no SDK or even an App Store.

I did a lot of PHP development back in the day, so armed with all of the mobile web development best practices of the day, I set about building the site and making it speedy. Some of the notable features of Tipr included:

• Inlining CSS & JS file contents into the HTML.
• Using PHP output buffers to compress the HTML on the server before sending it over the wire.
• Server side processing in PHP.
• Client side processing via XHR to a PHP-driven API.

At the time, most of these approaches were very new. As an industry, we weren’t doing a whole lot to ensure peak performance on mobile because most people’s mobile browsers were pretty crappy. This was the heyday of Usablenet’s “mobile friendly” bolt-on and WAP. Then came Mobile Safari.

# A lot has changed since 2007

The Tipr site has remained largely untouched since I built it in the Summer of 2007. That October, I added a theme switcher that made the site pink for October (Breast Cancer Awareness Month). I added a free text message-based interface using the then-free TextMarks service and a Twitter bot as well. But as far as the web interface went, it remained largely untouched.

Here are a handful of things that have come to the web in the intervening years:

• HTML5 Form Validation API
• SVG support
• CSS3
• Media Queries
• Web App Manifest
• Service Worker (and its precursor the AppCache)
• Flexbox
• CSS Grid

Phew, that’s a lot! While I haven’t made upgrades in all these areas, I did sprinkle in a few, mainly to make it a true PWA and boost performance.

# Moving from PHP to a “static” site

Much of my work over the last few years has been in the world of static site generators (e.g., Jekyll, Eleventy). I’m quite enamored of Eleventy, having used it for a number of projects at this point. Since I know it really well, it made sense to use it for this project too. The installation steps are minimal and I already had a library of configuration options, plugins, and filters to roll with.

While in the process of migrating to Eleventy, I also took the opportunity to

• Swap raster graphics for SVGs,
• Set up a Web App Manifest,
• Add a Service Worker, and
• Update the site’s meta info to reflect current best practices.

I also swapped out the PHP logic that governed the pink color theme for a simple script in the head of the every page. Since the color change is an enhancement, rather than a necessity, I didn’t feel like it was something I needed to manage another way.

The greatest challenge in moving Tipr over to a static site was setting up the tip calculation engine, which had been in PHP to ensure it would work even if JavaScript wasn’t available.

# Migrating the core logic to isomorphic JavaScript

When I originally built Tipr, JavaScript on the back-end wasn’t a thing. That’s why the core tip calculation engine was built in PHP. At the time, even XHR was in its infancy, so the fact that I could use PHP to do the calculations for both the server-side—for when JavaScript wasn’t available—and client-side—when it was—was pretty amazing.

Today, JavaScript is ubiquitous across the whole stack, which made it the logical choice for building out the revised tip calculator. As with the original, I needed the calculation to work on the client side if it could—saving a round trip to the server—but to also have the ability to fall back to a traditional form submission if the client-side approach wasn’t feasible. That would be possible by having client-side JavaScript for the form itself, with the server-side piece handled by Netlify’s Edge Functions (integrated through Eleventy’s Edge plugin).

From an architectural standpoint, I really didn’t want to have my logic duplicated in each place, so I began to play around with ensconcing the calculation logic in a JavaScript include, so I could import it into the form page itself and a JavaScript module that the Edge Function could use.

You can view Tipr’s source on GitHub, but here’s a basic rundown of the relevant directories and files:

netlifyedge-functionstipr.jssrc_includesjstipr.jsjprocess.njkindex.htmlnetlify.toml

#src/_includes/js/tipr.js

This file contains the central logic of the tip calculator. It’s written in vanilla JavaScript with the intent that it would be understandable by the widest possible assortment of browsers out there.

#src/index.html

The homepage of the site is also home to the tip calculation form. Below the form is an embedded script element containing the logic for interacting with the DOM for the client-side version of the tip calculator. I include the logic at the top of that script:

<script>{%include“js/tipr.js”%}//TherestoftheJavaScriptlogic</script>

#src/j/process.njk

This file exists solely to export the JavaScript logic from the include in a way that it can be consumed by the Edge Function. It will render a new JavaScript file called “process.js” and turns the central processing logic into a JavaScript module that Deno can use (Deno powers Netlify’s Edge Functions):

---layout:falsepermalink:/j/process.js---{%include“js/tipr.js”%}export{process};

#netlify/edge-functions/tipr.js

We define Edge Functions for use with Netlify in the netlify/edge-functions folder. To make use of the core JavaScript logic in the Edge Function, I can import it from the module created above before using it in the function itself:

import{ process }from“./…/…/_site/j/process.js”;functionsetCookie(context, name, value){context.cookies.set({name,value,path:“/”,httpOnly:true,secure:true,sameSite:“Lax”,});}exportdefaultasync(request, context)=>{let url =newURL(request.url);// Save to cookie, redirect back to formif(url.pathname ===“/process/”&& request.method ===“POST”){if( request.headers.get(“content-type”)===“application/x-www-form-urlencoded”){let body =await request.clone().formData();let postData = Object.fromEntries(body);let result =process( postData.check, postData.percent );setCookie( context,“check”, result.check );setCookie( context,“tip”, result.tip );setCookie( context,“total”, result.total );returnnewResponse(null,{status:302,headers:{location:“/results/”,}});}}return context.next();};

What’s happening here is that when a request comes in to this Edge Function, the default export will be executed. Most of this code is directly lifted from Netlify’s Edge Functions demo site. I grab the form data, pass it into the process function, and then set browser cookies for each of the returned values before redirecting the request to the result page.

On that page, I use Eleventy’s Edge plugin to render the check, tip, and total amounts:

{%edge%}{%setcheck=eleventy.edge.cookies.check%}{%settip=eleventy.edge.cookies.tip%}{%settotal=eleventy.edge.cookies.total%}<trid=“check”><thscope=“row”>Check&nbsp;</th><td>${{check}}</td></tr><trid=“tip”><thscope=“row”>Tip&nbsp;</th><td>${{tip}}</td></tr><trid=“total”><thscope=“row”>Total&nbsp;</th><td>${{total}}</td></tr>{%endedge%}

Side note: The cookies get reset using a separate Edge Function.

#netlify.toml

To wire up the Edge Functions, we use put a netlify.toml file in the root of the project. Configuration is pretty straightforward: you tell it the Edge Function you want to use and the path to associate it with. You can choose to associate it with a unique path or run the Edge Function on every path.

Here’s an excerpt from Tipr’s netlify.toml as it pertains to the Edge Function above:

[[edge_functions]]function=“tipr”path=“/process/”

This tells Netlify to route requests to /process/ through netlify/edge-functions/tipr.js. Then all that was left to do was wire up the form to use that endpoint as its action:

<formid=“calc”method=“post”action=“/process/”></form>

# Isomorphic Edges

It took a fair bit of time to figure this all out, but I’m pretty excited by the possibilities of this approach for building more static isomorphic apps. Oh, and the new site… is fast.

In this talk, Aaron Gustafson walks you through a host of new web platform features you can use today to grant your web projects app-like super powers. Learn the simple steps you can take to improve how users discover and install your software offerings.

I’ll be using this post to collect the articles as they publish. You can also check out the series on dev.to or on the canonical site.

• Welcome to #30DaysOfPWA
• Day 1 - Introducing Progressive Web Apps
• Day 2 - Deconstructing Progressive Web Apps
• Day 3 - Make Progressive Web Apps Installable
• Day 4 - Make Progressive Web Apps Reliable
• Day 5 - Make Progressive Web Apps Work Offline
• Day 6 - Make Progressive Web Apps Capable
• Day 7 - Developing Progressive Web Apps
• Day 8 - Introducing Advanced Capabilities of PWAs
• Day 9 - Creating Application Shortcuts
• Day 10 - Sharing Content From and With Your App
• Day 11 - Displaying Content More Like An App
• Day 12 - Caching Your App Data
• Day 13 - Synchronizing App Data in the Background
• Day 14 - Notifying Users Of Updates
• Day 15 - Tools: Getting Started / Building New PWA
• Day 16 - Tools: Getting Started / Converting your web app to a PWA
• Day 17 - Tools: Debug Your PWA (Part 1)
• Day 18 - Tools: Debug Your PWA (Part 2)
• Day 19 - Tools: Auditing Your PWA
• Day 20 - Tools: Test Automation for PWA
• Day 21 - Tools: Packaging Your PWA
• Day 22 - Best Practices for PWA: Installability
• Day 23 - Best Practices for PWA: Engagement
• Day 24 - Best Practices for PWA: Distribution
• Day 25 - Best Practices for PWA: Reliability
• Day 26 - Best Practices for PWA: Maintainability
• Day 27 - Best Practices for PWA: Authentication
• Day 28 - Best Practices for PWA: UI/UX
• Day 29 - Recap: From Core Concepts to Best Practices!
• Day 30 - PWA: Learning Resources For Beginners

This was a really fun series to put together; many thanks to all of my friends and colleagues who contributed. They are:

• @beth_panx,
• @nitya,
• @kennethrohde,
• @diekus,
• @seaotta,
• @webmaxru,
• @Justinwillis96,
• @amruthasrin,
• @patrickbrosset,
• @noobtiger11,
• @jaylynsatwork,
• @devteutsch,
• @JudahGabriel, and
• @metulev.

# CSS tweaks

The first step was to add in the prefers-color-scheme Media Query. If you’re unfamiliar, it looks a little something like this:

/* Your regular rules go here /@media(prefers-color-scheme: dark){/ Overrides for the “dark” theme go here /}@media(prefers-color-scheme: light){/ Overrides for the “light” theme go here */}

I only wanted to add a “dark” theme as my default is pretty much a “light” theme anyway. For the most part, this was pretty straightforward… just swapping color values, being sure to use the specific properties I wanted to change (e.g., background-color, border-color) rather than the shorthand. The only tricky/convoluted bit was updating my fancy link underlines (which don’t use text-decoration).

# Tweaking SVGs

You may not have realized it, but SVGs also support the prefers-color-scheme Media Query. Most of my SVGs were black & white already, so I had no color definitions in them. Adding an embedded stylesheet to swap out colors did the trick though:

svg{background-color: white;}path{fill: black;}@media(prefers-color-scheme: dark){svg{background-color: #454545;}path{fill: #fffcf4;}}

While most of these SVGs are in my HTML, some are referenced in my Web App Manifest. At the time I’m writing this, no browsers support SVG icons in the Manifest, but it’s something we (the Edge team) are working on adding for Chromium. And, when we land it, my hope is that we’ll include dark/light icon support by rastorizing the vector files in each of these contexts.

# Tweaking the Manifest

Continuing in the realm of speculation, there’s a proposal to support user-prefered color schemes in the Manifest as well. That proposal calls for a user_preferences block, wherein certain keys can be redefined. Here’s what I did, based on our discussions:

“user_preferences”:{“color_scheme_dark”:{“background_color”:“#5b5b5b”,“icons”:[{“src”:“/i/icon.svg”,“type”:“image/svg+xml”,“sizes”:“512x512”,“purpose”:“any monochrome maskable”},{“src”:“/i/icon-reverse.png”,“type”:“image/png”,“sizes”:“512x512”,“purpose”:“any monochrome maskable”},{“src”:“/i/notification-icon-reverse.png”,“type”:“image/png”,“sizes”:“256x256”,“purpose”:“any monochrome maskable”}]}},

I’m not sure yet whether my color-adapting SVG icon would need to be included here so as not to be replaced by the PNG versions, so I went ahead and included it anyway.

And that’s pretty much it. With just a little bit of time, I got it all set up. If you happen to use the new theme and something looks wonky, please let me know.

I briefly presented on a bunch of the different efforts I’m involved with at the W3C’s TPAC yesterday. Here’s a rundown of what I discussed as well as links you can follow if you want to get involved.

# Indicating an app’s policies & other legalese

Many app catalogs enable developers to provide links to things like their app’s Privacy Policy and Terms of Use. There is no way, however, to semantically indicate this information in your markup; the closest you can get is link[rel="license"], but that’s limited in scope. Rather than propose including more link or meta elements (which would need to be included on every page of your site), we think it makes more sense to roll this information into the Manifest as part of a policies object.

My proposal enables developers to provide URLs for an app’s accessibility statement, content license, and policies governing privacy, security, support, and usage. Developers would be free to include whichever policies their app has and they can be URLs within the app itself or link off to other websites (such as the publisher’s). Here’s what that could look like:

“policies”:{“accessibility”:“/accessibility”,“usage”:“/terms”,“privacy”:“http://publisher.tld/privacy”}

So far, this seems to meet the needs of several of the app catalogs I’ve spoken with. I don’t know that browsers will make use of this information, but I could see it being useful in the context of an installed PWA as well as in app listings within the browser UI too.

In a related effort, I’m pushing for the Microsoft Store to support accessibility statements, which are helpful for explaining application functionality and providing details of any known accessibility limitations within an app.

# Identifying an app’s publisher

When you’re considering installing any app, you want to know you can trust who’s behind it. Phishing sites are everywhere though, so we have to believe that phishing apps are here too (or not too far off). You want to be able to trust that an app purporting to be from your bank actually is from your bank. With such high stakes, opening up the possibility for an app to identify its publisher is quite dangerous, which is why this proposal has taken a while to germinate.

From the developer side of things, my proposed implementation is relatively straightforward. First, the app identifies its publisher in the Manifest:

“publisher”:{“name”:“Organization Name”,“url”:“https://organization.tld/”}

The problem is that I could put anything in there, declaring my publisher to be any company or individual. In order to substantiate my app’s claim, the listed publisher needs to claim the app too. The publisher could do this by enumerating the apps it owns in a text file located at https://organization.tld/.well-known/published-web-apps:

https://origin1.tld/manifest.jsonhttps://origin2.tld/static/manifest.json

Instead of using a text file, it may be possible to piggyback on the proposed web-app-origin-association file, but I’m concerned with overloading web-app-origin-association and confusing developers who are using it for URL handling.

Regardless of the mechanism, even with this bi-directional attestation, however, the system still has a gaping security hole: the publisher["name"] string can’t be validated this way. It would be relatively easy for an attacker to host 2 websites, one of which looks like your bank’s app and the other which merely hosts the published-web-apps file in order to support the bogus app’s claim of being published by your bank.

This is where the proposed processing algorithm adds an opaque validation step. Implementors are encouraged to verify that the publisher’s domain actually matches the claimed name. There are a number of services that offer name-to-url (or vice versa) lookup, but an implementor could even have a manual process in place to verify the provided information (which app catalogs do as a regular part of their business).

In the end, the publisher value will either be a validated name and URL pair or, if validation fails, the web app’s URL host string (e.g., “twitter.com”), which many implementors already use as the publisher name.

# Enabling server-side content negotiation

Though many folks these days focus their efforts on running as much code as possible on the client, there is a lot of value in making significant changes to your app on the server, before responding to a request. We’ve heard a number of use cases from folks building PWAs and have put together three proposals to help address them:

1. A Client Hint to indicate whether the app is installed. The Sec-CH-App-Installed header would give a server information about whether or not a user agent is representing the app in an “installed” state. The value would be a boolean true or false. We are discussing exposing this information via a DOM API as well.
2. A Client Hint to indicate the display mode. We already have a way of detecting the display mode of a web app using matchMedia() and CSS’s display-mode media feature, but that is all client side code. The Sec-CH-Display-Mode header would provide the display value (taking into account display_override) on the server side as well.
3. Using the Referer header to indicate installation source. I was working with a partner that wanted to beta their PWA to only people who’d installed their PWA from a specific app catalog. Even if they had supplied a separate Manifest with a unique start_url to that catalog, that would not have allowed them to limit their app’s distribution if the URL was shared. And so we proposed that the browser provide a catalog-associated Referer header when the PWA is first launched (and in the absence of a true referral). This feature has shipped in Edge for PWAs installed via the Microsoft Store and we are encouraging other app catalogs and browsers to consider the same approach.

It’s worth noting that all of these features can be used for analytics and (potentially) to violate someone’s privacy. That is why we’ve suggested they sit under the umbrella of the Privacy Sandbox.

# Adapting app UI to user preferences

Shortly after OSes began rolling out support for color schemes (e.g., “light” and “dark” modes), I saw a need for web apps to be able to adapt to these user preferences. In CSS we have the prefers-color-scheme Media Query, but the Manifest had no way of accounting for these sorts of changes. My initial proposal centered around adding support for Media Queries in the ImageResource spec. Short of having CSS-driven, adaptive SVG web app icons (which I’m also working on), being able to associate an ImageResource bitmap with a Media Query seems like the way to go.

Here’s what that might look like in the context of the icons member:

“icons”:[{“src”:“/icons/play-later.png”,“type”:“image/png”,“size”:“512x512”,“media”:“(prefers-color-scheme: light)”},{“src”:“/icons/play-later-reverse.png”,“type”:“image/png”,“size”:“512x512”,“media”:“(prefers-color-scheme: dark)”}]

This approach would be applicable wherever ImageResource gets used, which includes app icons, shortcut icons, and screenshots within the context of the Manifest as well as the Notifications and Payment Request APIs.

Beyond images, however, as Jen Simmons pointed out, we need the ability to adapt colors within the Manifest as well. It’s early days in discussing this right now, but we’re thinking about adding a generic means of redefining Manifest keys, based on a particular context. It is going to be a challenge to figure this out because we don’t want to force Manifest authors to redefine an entire nested structure (such as a shortcut) just to swap out a single part of that object. But more on that in a moment.

Here is a simple example of how this might look:

“user_preferences”:[{“context”:“(prefers-color-scheme: dark)”,“redefine”:{“theme_color”:“#bdbdbd”,“background_color”:“#000000”}}],

Ideally developers would not use this mechanism for redefining their icons, using the ImageResource option instead, but it does open the door to complexity.

# Web app translations

Speaking of complexity, have you ever tried to build a web app that is translated into multiple languages? It’s an incredibly challenging task and the Manifest does not make it any easier. At present, the guidance for creating multi-lingual Manifests is to use a separate file for each language or make it a dynamic file that can be adjusted on the server side based on path or query string adjustments.

I’m currently working on a proposal to address this within a single document by introducing a translations member. My proposal offers two approaches, one favoring simpler Manifests, the other more useful for complex Manifests.

For simple Manifests, translations could be embedded directly within the Manifest file as members of the translations object, keyed by language code:

{“name”:“Good dog”,“description”:“An app for dogs”,“lang”:“en”,“translations”:{“fr”:{“name”:“Bon chien”,“description”:“Une application pour chiens”}}}

For complex Manifests that may need to redefine text in shortcuts, screenshot labels, and the like, I proposed enabling translations to be managed in a separate file, offering alternative strings only for the items that need it. Using this approach, the above example could become:

// manifest.json{“name”:“Good dog”,“description”:“An app for dogs”,“lang”:“en”,“translations”:{“fr”:“manifest.fr.json”}}// manifest.fr.json:{“name”:“Bon chien”,“description”:“Une application pour chiens”}

One serious challenge (as with the user_preferences block, discussed above) is how to manage changing individual parts of a complex Manifest component. For example, you would likely need to change the text label of a shortcut, but may not need to change its url or icon. Thomas Steiner suggested that JSON Path may be a good solution here as it could enable you to do something like

{“name”:“Good dog”,“description”:“An app for dogs”,“lang”:“en”,“shortcuts”:[{“name”:“Pet Me”,“url”:“/pet-me/”},{“name”:“Feed Me”,“url”:“/feed-me/”}],“translations”:{“fr”:{“name”:“Bon chien”,“description”:“Une application pour chiens”,“$[‘shortcuts’][0][‘name’]”:“Nourrissez-moi”,“$[‘shortcuts’][1][‘name’]”:“Caressez-moi”}}}

This is still something we are actively working through, but it’s promising for sure.

# Consider getting involved

There is a lot of really interesting work happening in Manifest-land these days. If you’d like to get involved, please follow the links and chime in on the discussions. We’d love to have you!