Initial Feedback

[David-Ossim]

There's a lot here that I'm aligned with. Very excited to see clear ideas about the future of Widgets and PWA!

I like defining Widget structure + behavior inside the PWA manifest as the Widget is a projection of the PWA. Defining the Widget within the PWA makes this projection clearer and likely simplifies future PWA+Widget concerns packaging, registration, communication, etc. (Sidebar: I think there's still a separate need to create standalone web-based widgets. A utility widget, like a clock, probably doesn't need to interact with an app or browser experience.)

Looking at the current WidgetDefinition sample, these are my initial thoughts. Happy to dive into any further!

{
  "name": "Agenda",
  "id": "widget-agenda",
  "url": "/widgets/agenda/",
  "type": "text/calendar",
  "template": "agenda",
  "data": "/widgets/data/agenda.ical",
  "update": "900",
  "icons": [ ],
  "backgrounds": [ ],
  "actions": [ ],
  "ms-acn": {
    "prefer": "medium",
    "small": "/widgets/data/agenda-acn-small.json",
    "medium": "/widgets/data/agenda-acn-medium.json",
    "large": "/widgets/data/agenda-acn-large.json"
  }
}

• name
  • LGTM. Just want to call out that the name a PWA is packaged with here should be able to be localized at time of user install.
• id
  • Can you explain a bit about what this id accomplishes? Is it intended to disambiguate WidgetDefinitions defined in the same manifest? Could the same thing client be identified by querying WidgetClients?
• url
  • Makes sense. I assume if a url is present, then type,template,and data are ignored. For Windows-specific PWA widgets, having a separate field that expects Adaptive Card template endpoints is a must.
• type
  • This appears to be bound to template. I don't yet see why separating mime type from the template will help developers.
• template
  • I'd prefer a template_url that points to some standardized template structure that all browsers know how to render and bind to data. No strong opinion though. For my use cases as a developer, I'm more likely to use url or ms-acn.
• data
  • LGTM. Love the data/template segregation.
• update
  • This already makes me nervous :) It makes initial sense that this would be managed by or similarly to Periodic Sync to respect resource utilization. However, periodically updating the Widget, independent of app activity, breaks the projection paradigm. When a user reads a message from a friend, views an unseen item, or does some action in the app that the Widget makes them aware of, they will expect the Widget to respond to that action. If there's a 900 second delay, or even a 5 second delay, that Widget would appear unresponsive. There's definitely a need to guard users from noisy widget updates, but the fixed time period may not be sufficient. Ideally, a widget refresh could be requested in the service worker.
• icons
  • Where would these icons be displayed to users? Do they differ from action icons?
• backgrounds
  • Makes sense for providing background images to lay the widget template over. I'm curious if this is also intended to support light/dark mode. From my understanding, the template would remain the same and the renderer would need to know which components to use. Maybe that's better described under a visual_display_mode.
• actions
  • Agreed with aligning this with Notification actions and surfacing them in the service worker.

[aarongustafson]

There's a lot here that I'm aligned with. Very excited to see clear ideas about the future of Widgets and PWA!

Thanks @David-Ossim!

I like defining Widget structure + behavior inside the PWA manifest as the Widget is a projection of the PWA. Defining the Widget within the PWA makes this projection clearer and likely simplifies future PWA+Widget concerns packaging, registration, communication, etc.

Agreed.

(Sidebar: I think there's still a separate need to create standalone web-based widgets. A utility widget, like a clock, probably doesn't need to interact with an app or browser experience.)

Totally agree. My gut says widgets like this might fall into the "rich widget" camp as they would require a higher level of autonomy for running bespoke code.

• name

  • LGTM. Just want to call out that the name a PWA is packaged with here should be able to be localized at time of user install.

Agreed. Localization is a whole other nut we are trying to crack.

• id

  • Can you explain a bit about what this id accomplishes? Is it intended to disambiguate WidgetDefinitions defined in the same manifest? Could the same thing client be identified by querying WidgetClients?

Yes, the id is for disambiguation in the WidgetClients interface as name may not be unique.

• url

  • Makes sense. I assume if a url is present, then type,template,and data are ignored. For Windows-specific PWA widgets, having a separate field that expects Adaptive Card template endpoints is a must.

Yes, url would be used for a Rich Widget (if supported). If Rich Widgets aren’t supported, the implementor would fall back to the Templated Widget using the data feed of a supported type that gets routed into the template (if it’s supported by the host, of course). If the type or template are not supported, that specific widget would not be offered.

• type

  • This appears to be bound to template. I don't yet see why separating mime type from the template will help developers.

It’s actually bound to the data as an affordance to enable the host to ignore a data feed as unsupported. It saves the step of MIME discovery.

• template

  • I'd prefer a template_url that points to some standardized template structure that all browsers know how to render and bind to data. No strong opinion though. For my use cases as a developer, I'm more likely to use url or ms-acn.

The template property is intended to refer to one of a common set of template names that hosts have implemented. I provided some examples here. This leaves the actual implementation specifics up to the host. I see these templates being an entry point to widget creation, but recognize that some platforms may want to enable more customization between a Templated Widget and a Rich Widget. That could be accomplished through optional, platform-specific extensions like my speculative ms-acn one.

Hypothetically, you might start with a baseline "content-feed," for instance, that gets implemented in a number of hosts, but if you also include the ms-acn, that additional info could be routed to the widget renderer on platforms that support it. Does that make sense?

• data

  • LGTM. Love the data/template segregation.

:-)

• update

  • This already makes me nervous :) It makes initial sense that this would be managed by or similarly to Periodic Sync to respect resource utilization. However, periodically updating the Widget, independent of app activity, breaks the projection paradigm. When a user reads a message from a friend, views an unseen item, or does some action in the app that the Widget makes them aware of, they will expect the Widget to respond to that action. If there's a 900 second delay, or even a 5 second delay, that Widget would appear unresponsive. There's definitely a need to guard users from noisy widget updates, but the fixed time period may not be sufficient. Ideally, a widget refresh could be requested in the service worker.

Ultimately this is about balancing performance on the device. Just as hosts throttle Service Worker background tasks, push notifications, etc. I could imagine a scenario where a host needs to limit widget communication as well. I do strongly believe there should be a Widget Lifecycle that handles freeze/thaw events to ensure widgets get updated so as to be relevant, but I also want developers to think a bit about how often they want data to update so they can plan for the worst case scenario (slow device/network). And most time-sensitive widgets (e.g., a stock ticker) do create affordances for this with "last updated at" indications and a manual refresh button.

• icons

  • Where would these icons be displayed to users? Do they differ from action icons?

If the widget supports an app icon in the UI, this could be piped in. But the app icon could also be used. This would only be necessary if the widget needed a bespoke icon.

• backgrounds

  • Makes sense for providing background images to lay the widget template over. I'm curious if this is also intended to support light/dark mode. From my understanding, the template would remain the same and the renderer would need to know which components to use. Maybe that's better described under a visual_display_mode.

We are working on user-preferences separately.

• actions

  • Agreed with aligning this with Notification actions and surfacing them in the service worker.

:-)

[aarongustafson]

@David-Ossim I just made a ton of additions to the proposal to (hopefully) clarify things a bit more. Would love your thoughts.

[David-Ossim]

@aarongustafson This definitely clarifies some of the implementation and the role of the service worker. Pretty much aligns with my understanding from previous chats. A few random questions:

1. Is Install/Uninstall/Resume an exhaustive list of out-of-the-box actions?
2. Can we assume we always get a change to refresh data on "resume"? I'm assuming throttling would occur on showWidget().
3. Nitpick - closeWidget() sounds more like hiding or something softer than uninstalling. Maybe uninstallWidget()?
4. The link “the user login video, above" leads to a 404
5. Is there any relationship between Microsoft's Adaptive Cards and the template? My understanding is that all Widget hosts would support their flavor of calendar/content/etc templates and then potentially support separate custom rendering for things like Adaptive Cards or whatever makes sense for the platform. Is that accurate?