Web widget providers

In the latest release, apps that implement Windows widgets can choose to populate the widget content with HTML served from a remote URL. Previously, the widget content could only be supplied in the Adaptive Card schema format in the JSON payload passed from the provider to the Widgets Board. Because web widget providers must still provide an Adaptive Card JSON payload, you should follow the steps for implementing a widget provider in Implement a widget provider in a C# Windows App or Implement a widget provider in a win32 app (C++/WinRT).

Specify the content URL

Widget providers pass a JSON payload to the Widgets Board with a call to WidgetManager.UpdateWidget. For a web widget, instead of providing a body object defining the widget content, you should specify an empty body object and instead include a metadata object with a webUrl field that points to the URL that will supply the HTML content for the widget.

{ 
    "type": "AdaptiveCard", 
    "$schema": "http://adaptivecards.io/schemas/adaptive-card.json", 
    "version": "1.6", 
    "body": [], 
    "metadata": 
    { 
        "webUrl": "https://www.contoso.com/widgetprovider.html" 
    } 
} 

Handle resource requests

Widget providers can specify a web request filter string for a widget in the WebRequestFilter attribute of the Definition element in the provider's package manifest file. Whenever the widget content requests a resource by URI that matches the filter, the request will be intercepted and redirected to the widget provider's implementation of IWidgetResourceProvider.OnResourceRequested.

The filter pattern is expressed using the format described in Match Patterns. The filter string in the registration must use Punycode where necessary. All content types will be redirected when matched so the filter should only resolve to content intended to be obtained through the IWidgetResourceProvider in the application. For more information on the widget provider package manifest format, see Widget provider package manifest XML format.

To handle resource requests, widget providers must implement the IWidgetResourceProvider interface.

internal class WidgetProvider : IWidgetProvider, IWidgetResourceProvider

In the implementation of the OnResourceRequested method, widget providers can provide the requested resources by setting the WidgetResourceRequestedArgs.Response property to a WidgetResourceResponse object containing the requested resource. When obtaining the resource asynchronously, the provider should request a deferral by calling WidgetResourceRequestedArgs.GetDeferral and then complete the deferral when the resource has been set.

async void IWidgetResourceProvider.OnResourceRequested(WidgetResourceRequestedArgs args)
{
    var deferral = args.GetDeferral();

    if (args.Request.Uri.Length > 0)
    {
        if (args.Request.Uri == "https://contoso.com/logo-image")
        {
            string fullPath = Windows.ApplicationModel.Package.Current.InstalledPath + "/Assets/image.png";
            var file = await StorageFile.GetFileFromPathAsync(fullPath);
            var response = new WidgetResourceResponse(RandomAccessStreamReference.CreateFromFile(file), "OK", 200);
            response.Headers.Add("Content-Type", "image/png");
            args.Response = response;
        }
    }

    deferral.Complete();
}

If the provider does not set a response on the WidgetResourceRequestedArgs object passed into the method, the system will retrieve the resource from the web. In this case, the provider can choose to modify the Headers property of the WidgetResourceRequestedArgs.Request object, such as to provide user context or tokens, and the system will use the updated headers when retrieving the resource from the web.

Handle messages to and from web content

To receive string messages from the widget's content that has been posted using the window.chrome.webview.postMessage JavaScript method, widget providers can implement the IWidgetProviderMessage interface and implement the OnMessageReceived method.

internal class WidgetProvider : IWidgetProvider, IWidgetProviderMessage
...
public void OnMessageReceived(WidgetMessageReceivedArgs args)
{
    Console.WriteLine($"Message received from widget {args.WidgetContext.Id}: {args.Message}");
}

Widget providers can send a message to the web content of the widget by calling WidgetManager.SendMessage. You must provide the ID of the widget to which the message is sent, which is the value specified in the Id attribute of the Definition element in the provider's package manifest file. For more information see Widget provider package manifest XML format. The message string can be simple text or the serialized form of an object interpreted by the web content. For more information, see PostWebMessageAsString.

var message = $"{{ \"current_location\": \"{ location }\" }}";
WidgetManager.GetDefault().SendMessageToContent("Weather_Widget", message);

Limitations and requirements

• This feature is available only to users in the European Economic Area (EEA). In the EEA, installed apps that implement a feed provider can provide content feed in the Widgets Board.