July 6, 2015 3:56 pm

Project Westminster in a nutshell

Hi, I’m Kiril Seksenov an Engineer on the Microsoft Edge Web Apps team, I’m so happy to talk to you in depth about Project Westminster.

About Universal Windows Platform Bridges

Universal Windows Platform Bridges consist of a toolkit of three components: developer tools, Store ingestion processing, and Universal Windows Platform runtime frameworks. Today we’ll address Project Westminster, which gives you the ability to leverage your existing web development workflow and publish your responsive website to the Windows Store. The team calls these published websites Hosted Web Apps, since the majority of the content is being served from your website.

Project Westminster in a nutshell

Project Westminster makes it simple for you to bring existing Hosted Web Apps to Windows 10.

Project Westminster embraces “the way of the web” by giving you the opportunity to publish an app while continuing to use your tools, developing your code and deploying to the host you desire. Just enter your app’s start page URL and define the app’s scope of URLs in the app manifest to create a Universal Windows Platform app. Continue with platform integration by pushing code to your servers, feature detecting for and directly calling Universal Windows APIs. Once deployed, hit F12 on a Windows machine to test and debug your app.

1_breakDownEdge

Through the Application Content URI Rules (ACURs) or URL allow list you’ll be able to give remote URLs direct access to Universal Windows APIs from remote HTML, CSS, and JavaScript.2_tools

While building Hosted Web Apps, Project Westminster is agnostic to the developer workflow that you’ve chosen. Simply put, you can keep using your favorite code editor, source control and hosting service while developing your website.

Once your website is published as a Hosted Web App in the Windows 10 Store you are able to continuously deploy updates by pushing changes to your servers – no need to re-submit your app to the Store. You also gain the opportunity to integrate with the platform by directly calling into the Windows namespace from JavaScript hosted on your servers without the need for packaged code.

Better JavaScript app support

Project Westminster represents an evolution in our continued Web App investment. HTML/JavaScript apps have existed on the platform since Windows 8. However, they were restricted to packaged apps. What this meant was that the app could not directly navigate to a remote URL. Remote in app content could be navigated to only through the WebView control. With Windows 8.1, the Web App Template for Windows used the WebView model to assist developers in publishing websites as apps. In Windows 10, we give the JavaScript app host the ability to directly navigate to remote pages. This eliminates the need to load two web framework instances, as is the case when using the WebView. This is great when developers don’t require the granular control provided by the WebView’s API set. We also enable hosted code running in the app host to directly call Universal Windows APIs. This eliminates the need for packaged code to integrate with the platform.

A Standards approach

Developers who build for the web do so to build apps that run in any browser or on any platform.  For that reason we are also contributing to the development of the W3C Manifest for Web Apps.  When complete, this will be a single, common manifest that will support web apps in all environments.

In the meantime, Microsoft along with other developers in the community have been supporting a new open source project called Manifoldjs. Manifoldjs is the simplest way to build hosted apps across all platforms.  Manifoldjs starts with the W3C manifest and from it, builds hosted apps for Windows 10, along with apps for iOS, Android, FireFoxOS and Chrome. If you don’t yet have a W3C manifest on your website, don’t worry, Manifoldjs will build one for you as well.  You can use Manifoldjs to generate apps on the website, or as a command line tool. Once you have node.js installed, just simply type “npm install manifoldjs –g” and you’re set.  Find out more about Manifoldjs by visiting the project’s website at www.manifoldjs.com .  

Where does this bridge go?

This bridge enables you to publish your responsive Web App on Windows 10 as a true UWP app. Project Westminster also makes it even easier to integrate your web app with Windows features like Cortana voice commands and authentication. Platform capabilities are only available when your site is running as a Universal Windows Platform App in the App Host on Windows 10. Your web app will not be able to call platform APIs when navigated to in Microsoft Edge or other browsers. Your web app will also not be able to run ActiveX, Flash, and other legacy components that aren’t available in Microsoft Edge.

What happens at the Windows OS level

Since JavaScript is a natively supported language on the Windows platform, all that’s been described so far is possible through your existing language and framework choices.

At the OS level, the right policy bounds have been set to allow code hosted on your web server to directly call platform APIs. You define these bounds in the app manifest when you place the set of URLs that make up your Hosted Web App in the Application Content URI Rules (ACURs).

If a URL is defined within the app’s bounds (ACURs) it can be granted access to the platform through the “WindowsRuntimeAccess” attribute. The Windows namespace will be injected and present in the script engine when a URL with appropriate access is loaded in the App Host. This makes Universal Windows APIs available for the app’s scripts to call directly. As a developer you just need to feature detect for the Windows API you’d like to call and if available proceed to light-up platform features.  For WindowsRuntimeAccess, these attributes will give the following access:

  • all: Remote JavaScript code has access to all UWP APIs and any local packaged components.
  • allowForWeb: Remote JavaScript code has access to custom in package code only.  Local access to custom C++/C# components.
  • none: Default.  The specified URL has no platform access

Here is an example of how to implement a Live Tile and update it from remote JavaScript:

This code will produce a tile that looks something like this:

4_liveTile1 4_liveTile2 4_liveTile3

You benefit from all web platform improvements and updates. The web platform that powers the Microsoft Edge browser, including the new rendering engine built for the modern web is also behind Project Westminster. Project Westminster follows the way of the web, allowing developers to use familiar techniques, keeping their resources on a server feature detecting for Windows capabilities prior to calling them. If platform capabilities are not available, and the web app is running in another host, developers can provide the user with a standard default experience that works in the browser.

Since, even today, users do not always have an internet connection, creating a standard offline experience is important for developers. Even though the premise of Hosted Web Apps is to keep most code remote and not alter the web workflow, we encourage you to provide varying levels of offline support for your app.

What kind of offline experience can my Hosted Web App support?

At minimum you should include a local default error page that will be displayed automatically by the app if there is a navigation error to the remote website. The required name for the default page that will be displayed is msapp-error. You are free to set the content and style of this page and can also able to display the actual error as it’s passed through the query parameter.

5_explorer

Of course, there are HTML technologies like IndexedDB, localStorage and AppCache, which are supported by Microsoft Edge. A local page can be kept in your app package that can still provide a basic offline experience.

Can I have a mix of local and remote content?

Yes, you can switch between the different URI schemas to navigate between local and remote content.

The app host allows navigations between local and remote pages. Navigation to a local page can be done using the ms-appx:/// or ms-appx-web:/// protocols, allowing you to load html/css/JS from inside the package for an offline experience. In the app host, navigation between ms-appx-web:/// and https:// protocols allows you to switch between local and hosted pages.

URI schema Description
https:// Web content over secure socket layer used for staging and live deployment environments.
http:// Web content over standard transfer protocol to be used in development environments where it’s a burden to configure a SSL cert.
ms-appx-web:/// Content a developer has included within their app package, but should be treated, and behaves as, web content.
ms-appx:/// Local packaged content. Default CSP applied.

 What happens in the Windows Store?

Any application built with Project Westminster will be a Universal Windows Platform App and publishable to the Windows 10 Store. When you enter URLs in the app manifest and package the app you’ll have all that’s required to submit to the Store. From there you’ll be able to follow the standard developer submission flow for any Universal Windows App. Once submitted, your app will be discoverable by users and have the ability to be installed across the range of Windows 10 devices.

Developer Experience for Project Westminster

To get started with Project Westminster or as we call it, Hosted Web Apps on Windows, you’ll need Windows 10. You are able to create Hosted Web Apps using Visual Studio 2015 or the Command Line Interface. In this article, we’ll walk you through how to create your application and debug it using Visual Studio. Check out our Yeoman generator for Windows 10 Web Apps or ManifoldJS if you prefer using the CLI.

For additional information, check out these links

How code reuse and new reach works for Project Westminster

Project Westminster allows you to reuse your existing website code to gain more reach and discoverability when you publish to the Windows Store. Publishing your existing web app to the store means that your experience will be available across the entire family of Windows 10 devices. Including desktop, phone and Xbox, HoloLens, SurfaceHub and IoT in the future.

As you decide to adopt more of the Universal Windows Platform and provide native functionality, Project Westminster helps you take advantage of Windows features like Live Tiles, Cortana, Notifications, Calendar, Contacts and more by giving you the opportunity to call Universal Windows APIs directly from JS hosted on your server.

Wrapping up

To get started and see for yourself how straightforward it is to turn your website into an app on Windows 10 check out the Visual Studio instructions or if you prefer the CLI either ManifoldJS or our Yeoman generator for Web Apps. If you are interested in learning more check out the Microsoft Edge Web Summit talk on Hosted Web Apps. If you find bugs or issues, please leverage the Windows Feedback tool or MSDN forums.  If you have any new features, please submit them over at UserVoice.

Updated July 7, 2015 3:11 pm

Join the conversation

  1. Great project! I think there is a small typo in your updateLiveTile.js example:

    “`
    if (typeof Windows &&
    typeof Windows.UI &&
    typeof Windows.UI.Notifications === ‘undefined’) {
    “`

    the `===` operator should rather be a `!==`.

  2. Looks great!
    How does this with content like gambling or adult sites? Are they also allowed in the store?

  3. As a web developer, I’m super excited about this. I love the idea behind Westminister and ManifoldJS, and the reality that we can easily package up web apps as OS apps.

    I’m planning on using this for two of my side projects. My day job is also looking at bringing their web app to mobile; ManifoldJS may be just the ticket.

  4. My company has been deploying web apps using Chrome and Firefox for a while now, and I’m thrilled to see Microsoft finally getting on board with the web app manifest standards! I hope that you follow Mozilla’s lead (not Google’s) and let developers put apps directly onto web sites, and not make them go through a store. Having the option of going through a store to get apps is great, but it creates significant friction in the user experience if you already have the user at your site.

    (To see what I’m talking about, try installing our demo app from m.kaon.com/c/ka using Chrome, and then install it using Firefox. The Firefox user experience so much better, particularly for enterprise customers who might not have a google account they can use on their work machine.)

    One key issue for offline apps is the absurdly low limit IE put on offline appcache.manifest content (just 20MB last I checked). Firefox and Chrome removed these limits years ago. I’d love to embrace this new deployment option, but we won’t be able to until you remove this limitation. Is fixing this limit on your roadmap? Some of our applications are well over 1GB for offline use.

  5. Would it be acceptable to submit a UWP app using project Westminster for a web app that I do not control? Let’s say I would like to encapsulate my bank WebApp, which is already available for iOS but not on Windows. Would it pass the store screening?

  6. How can I append functionality (or change CSS styles) to remote web application with local (in app) JavaScript file?

    I want to show remote website app but call Windows.UI….. and other functions from local JS file(s). I want also alter CSS styles from remote site with local CSS styles.

    Is it any tutorial how to achieve this?

    • Yes you can call windows API’s. For instance, to change title bar color:

      var appView = Windows.UI.ViewManagement.ApplicationView.getForCurrentView();
      var titleBar = appView.titleBar;
      titleBar.backgroundColor = { r:255,g:0,b:0,a:0 };

  7. It’s good. But pressing the back button on Windows Phone would just quit the app…
    The expected behavior should be go back to the previous page. How can I do that?

    • You have to get a reference in your JS to the system navigation manager and then listen to the onbackrequested event. Something like this:

      var systemNavigationManager = Windows.UI.Core.SystemNavigationManager.getForCurrentView();
      systemNavigationManager.appViewBackButtonVisibility = Windows.UI.Core.AppViewBackButtonVisibility.visible;
      systemNavigationManager.addEventListener(“backrequested”, onBackRequested);

      // event handler
      function onBackRequested(eventArgs) {
      // navigate back or do whatever else you want to do

      // set handled to true, to prevent default behavior
      eventArgs.handled = true;
      }

  8. This is a cool concept and I have gotten a lot of neat things working with hosted web apps.

    One thing I would love to be able to do though, is display Microsoft pubCenter banner advertisements on my hosted web app, when running in the Westminster bridge.

    I have tried adding the pubCenter SDK to my VS project and referencing it from my remote .html file like this:

    but I cannot get it to work. I have tried ms-appx-web:/// schema as well, to no avail.

    I have also tried hosting the ad.js file from the advertising SDK on my own server and referencing it like that, but I receive errors when trying to load an ad control.

    My question is, is it possible for a hosted web app to access content that is referenced in the Visual Studio project? That would be amazing.

  9. Not working for me… Actually no JavaScript universal app will run.

    I get the message “the debugger cannot continue running the process. unable to start debugging”

    I’m using VS2015 Enterprise 14.0.23107.0 D14REL

    C# UWP’s compile and run fine.

  10. Followed the example given but all I get when I run the app is the square icon, it would appear that the site is not loaded into the app. Running Windows 10 (latest released version) and VS2015 Pro. Any hints?

  11. Our hosted web-app (PHP / HTML5 / MySQL on Linux Apache) needs a new Database and webspace (folder) for every new instance of the application. (it’s a discussion-board application)
    Today, the processing of creating a new database, creating a new folder, creating the connection-strings and so on is triggered via PayPal (Instant Payment Notification, through the $_POST method).
    The needed information for PayPal integration can be found easily:
    http://paypal.github.io/sdk/sample-apps/
    there:
    the IPN code samples:
    https://github.com/paypal/ipn-code-samples

    Is there any equivalent for the Windows 10 app store?
    At the dev.windows.com/
    I made the submission & completed everything**, but I could not find anything there from which I could start triggering the needed processes on my servers alongside with the customer is clicking on a “buy now” button or equivalent from within the windows app store.
    (**my verification status is still pending, the guys from Symantec are still checking the documents, but I do not think that this is the point…)

    If someone has an idea – even if its only a vague one: do not hesitate, let me know!

  12. Hi All,

    I am trying to make my responsive web application into Windows 10 Hosted App.
    Some of the links within the pages in my application opens up in a new window.
    After hosting my site in Windows 10 mobile app platform it is working fine .
    But If I click these links from mobile app window they are still opening in new browser tab.
    Below is my manifest code.The second url in “” is opening in
    a new browser window.Should i configure any other setting.

  13. Applications
    Application Id=”App” StartPage=”https://MyWebsite.com/”

    uap:ApplicationContentUriRules
    uap:Rule Type=”include” Match=”https://www.MyWebsite.com/” WindowsRuntimeAccess=”all”
    uap:Rule Type=”include” Match=”http://www.MyWebsite.net/smartgrid/” WindowsRuntimeAccess=”all”
    uap:ApplicationContentUriRules
    Application
    Applications

  14. After Hosting the website in windows 10 as Web App the links which will
    open in new tab in browser is still opening in browser instead of new tab in mobile window.
    If som one have any idea on how to handle this Please let me know!

  15. After Hosting the website in windows 10 as Web App the links which will
    open in new tab in browser is still opening in browser instead of new tab in mobile window.
    If some one have any idea on how to handle this Please let me know!

  16. Hi I am trying to follow the tutorial but unable to open a website built using manifest appcahe and internal offline functionality.
    The .shtml page loads fine but errors out -Your application manifest does not declare the following capabilities: internetClient privateNetworkClientServer

    I have enabled these capabilities on the App but still the issue persists none of the button click evetns are getting triggered.

  17. what do you mean by ms-appx:/// Local packaged content. Default CSP applied. CSP of the domain that the hosted web app is being served from?