Skip to main content
September 30, 2016
Mobile

UWP Hosted Web App on Xbox One (App Dev on Xbox series)



https://www.youtube.com/watch?v=2lOxaTmAja4&feature=youtu.be

For the fourth installment in the series, we are open sourcing yet another sample app: South Ridge Video, an open source video app developed as a hosted web application built with React.js and hosted on a web server. South Ridge can easily be converted to a UWP application that takes advantage of native platform capabilities and can be distributed through the Windows Store as any other UWP app. The source code is available on GitHub right now, so make sure to check it out.

If you missed the previous blog post from last week on Background Audio and Cross Platform Development with Xamarin, make sure to check it out. We covered how to build a cross-device music experience using Xamarin and how to support background audio on the Universal Windows Platform, including the Xbox One. To read the other blog posts and watch the recordings from the App Dev on Xbox live event that started it all, visit the App Dev on Xbox landing page.

South Ridge Video

image1

What if you could extend the investment put into your web application and make it available as an Xbox One Windows Store app? What if you could also continue to use your existing web frameworks, CDN and server backend, yet still be able to use native Windows 10 APIs?

You can! A Hosted Web App (HWA) is a web app that can be submitted to the Store just like any other Universal Windows Platform (UWP) app. Since you’ve already invested in the development of the web app, your transformation into a HWA can be done rather quickly and easily.

To do this, you’ll reuse your existing code and frameworks as if you were developing for the browser. Let’s take a look at the South Ridge Video example app on GitHub. This is an app built with React.js and uses a web server back-end.  The application is delivered by the server when the app is launched and the UWP app will host that web content.

However, the HWA is not just a simple wrapper; you can also call into native Windows 10 APIs, such as adding an event to the user’s calendar. You can even use APIs such as toast notifications and camera capture or media transport controls with background audio. Note that when accessing sensitive APIs, make sure you declare the required App Capability in the appmanifest.

Now that your web app is ready and you want to turn it into a HWA, let’s take a look at the things you need to do to get it ready for Windows Store distribution to Xbox One.

Local Testing on a retail Xbox One

First, you need to put your retail Xbox One into developer mode so you can deploy and test the app. This is pretty straightforward; it involves installing an app from the Windows Store. Go here to see the steps on how to activate dev mode and how it works.

Now that you have your Xbox ready for deployment, let’s review the ways you can generate the app. There are three main options:

  • Using a web browser-based tool, such as Windows App Studio, to generate it for you
  • On a Mac or PC using Manifold.js
  • On a PC using Visual Studio

Let’s drill down into each option to see which best fits your needs.

Windows App Studio

Let’s start with the browser-based option, using Windows App Studio to create the HWA. Windows App Studio is a free online app creation tool that allows you to quickly build Windows 10 apps.

  1. Open Windows App Studio in your web browser.
  2. Click Start now!
  3. Under Web app templates, click Hosted Web App.
  4. Follow the on-screen instructions to generate a package ready for publishing to the Windows Store.
  5. You can then download the generate package that you’ll publish to the Store.

On a Mac using Manifold.js

What you need:

  • A web browser
  • A command prompt

ManifoldJS is a Node.js app that easily installs from NPM. It takes the meta-data about your web site and generates native hosted apps across Android, iOS and Windows. If your site does not have a web app manifest, one will be automatically generated for you. For example, take a look at the web app manifest for South Ridge Video.

  1. Install NodeJS, which includes NPM (Node Package Manager)
  2. Open a command prompt and type “NPM install -g manifoldJS”
    1. npm install -g manifoldjs
  3. Run themanifoldjs command on your web site URL:
    1. manifoldjs http://southridge.azurewebsites.net
  4. Follow the steps in the video below to complete the packaging (and publish your Hosted Web App to the Windows Store)
image2

A couple notes about using Manifold.js

  • If you have a W3C manifest, it will use that for app info; otherwise, it will be created automatically.
  • Use the -windows10 platform flag to generate only for UWP.

On a Windows PC using Visual Studio

What you need:

  • Visual Studio 2015. The free, full-featured Visual Studio Community 2015 includes Windows 10 developer tools, universal app templates, a code editor, a powerful debugger, Windows Mobile emulators, rich language support and much more—all ready to use in production. The same is true for Professional or Enterprise variants of VS 2015.
  • (Optional) Windows Standalone SDK for Windows 10. If you are using a development environment other than Visual Studio 2015, you can download a standalone Windows SDK for Windows 10 installer. Note that you do not need to install this SDK if you’re using Visual Studio 2015 Update 3; it is already included.

Steps to create the HWA (go here to see all these steps with screenshots):

  • Pick the website URL and copy it into your clipboard.
  • Launch Visual Studio 2015.
    1. Click File.
    2. Click New Project.
    3. Under JavaScriptthen Windows Universal, click Blank App (Windows Universal).
  • Delete the VS project template generated code.
    1. Since this is a hosted web app where the content is served from a remote server, you will not need most of the local app files that come with the JavaScript template by default. Delete any local HTML, JavaScript, or CSS resources. All that should remain is theappxmanifest file, where you configure the app and the image resources.
  • Open the appxmanifestfile.
    1. Under the Application tab, find the Start page text field.
    2. Replace html with your website URL.
  • Set the boundaries of your app.
    1. Application Content URI Rules (ACURs) specify which remote URLs are allowed access to your app and to the Universal Windows APIs. At the very minimum, you will need to add an ACUR for your start page and any web resources utilized by that page. For more information on ACURs, click here.
    2. Open theappxmanifest file.
    3. Click theContent URIs.
    4. Add any necessary URIs for your start page.

For example:

  1. 1. http://southridge.azurewebsites.net2. http://*.azurewebsites.net
  2. Set theWinRT Access to All (for each URI you added).
  • At this point, you have a fully functioning Windows 10 app capable of accessing Universal Windows APIs! You can now deploy to the Xbox One using the remote debugger as if it were any Windows 10 remote device, or you can use the Device Portal (covered in the next section).

Installing your HWA on the Xbox One for local testing

At this point, you now have an app package (APPX) or a manifest folder (Manifold.js), containing the files you need to install or publish your application. You can “side-load” your HWA to the Xbox by using the Device Portal (go here for more information about the Device Portal for Xbox One). One you’ve logged into the portal, you can then deploy your app.

APPX Deployment (Visual Studio / App Studio)

Here are the steps (go here to see these steps below with screenshots):

  1. Go to the Apps tab on the portal.
  2. You’ll see two buttons to upload items to the device: App Package and Dependencies.
  3. Tap the App Package button and navigate to the package folder you generated for your app. In there, you’ll find an appx file. Select that file and upload it.
  4. Now tap the Dependencies button, navigate again to your package folder and drill down to the dependencies sub folder. This contains the dependencies that your app needs to run – upload each one in the folder. (Note that you only need to do this when deploying via the Portal. Visual Studio delivers dependencies when remote debugging and the end user’s machine will already have these installed when delivered via the Store.)
  5. With the app package and the dependencies uploaded, click the Go button under the “Deploy” section and the app will be installed.
  6. Now go to the Xbox and launch the app!

Loose Files Deployment (Manifold.js)

The only difference between deploying an app packages with Manifold.js is that you have “loose” files instead of an APPX package. In the steps above, instead of uploading an APPX and Dependencies, you choose the “upload loose files” option and select the manifest folder. The portal will look in that folder for the manifest file and gather all the required pieces to complete the installation.

Design and User Experience Considerations for Xbox One apps

Designing for the “10-Foot Experience”

Xbox One is considered a “10-foot experience”, meaning that your users will likely be sitting a minimum of 10 feet away from the screen. You’ll want to consider the app’s ability to be used at that distance as opposed to being accessed within a web browser, from two feet away, with a mouse and keyboard. This article explains how to make sure you get the best user experience for the 10-foot experience scenario.

Designing for TV and understanding the “TV SafeZone”

Television manufacturers will apply a “safe-zone” around the content that can clip your app. By default, we apply a safe border around your app to account for this, however you can ensure that your app takes the full screen size using following code:

[code]

var applicationView = Windows.UI.ViewManagement.ApplicationView.getForCurrentView();
applicationView.setDesiredBoundsMode(Windows.UI.ViewManagement.ApplicationViewBoundsMode.useCoreWindow);

[/code]

Understanding and managing XY focus and navigation

You’ll want to consider your app’s ability to handle XY navigation by the user and disable the “Mouse Mode” that’s turned on by default for UWP apps. This is important because users’ main input method for Xbox One is a handheld controller. See here for more on how to work with XY focus and navigation. Use the following code to enable XY navigation using JavaScript:

[code]

navigator.gamepadInputEmulation = "keyboard";

[/code]

To enable directional navigation, you can use the TVJS library which is discussed below.

Considering your app’s appearance when another app is snapped

When users run an app on Xbox One, a second app may be ‘snapped’ to the right of the main app. When this is the case, the main app is considered to be in Fill Mode. While testing your app, open Cortana or another ‘snappable’ app to see how your app appears. You want to make sure your UI is still usable and has a graceful transition between Full Screen and Fill Mode. Implement an adaptive UI to make sure the user has the best experience for this scenario.

Integrate with the System Media Controls

If your app is a media app, it is important that your app responds to the media controls initiated by the user via the on-screen buttons, Cortana (typically through speech), the System Media Transport Controls in the nav pane or the Xbox and SmartGlass apps on other devices. Take a look at the MediaPlayer control from TVJS which automatically integrates with these controls or check out how to manually integrate with the System Media Transport Controls.

TVJS

TVJS is a collection of helper libraries that make it easier to build web applications for the TV. If you are building a hosted web app that will also run on the Xbox, TVJS can help add support for Directional navigation, as well as provide several controls that make it easier to interact with content on the TV.

DirectionalNavigation

Directional navigation is a feature that provides automatic two-dimensional navigation within the pages of your TV app. Apps won’t need to trap and handle navigation within their pages, or to explicitly specify all the valid focus targets for each element in the UI. With automatic focus handling, users can navigate around in an intuitive and robust way.

When users enter directional input to move from one element to another, the automatic focus algorithm looks at the set of potential focus targets, determines the next element to move to and then automatically sets the focus to that element. To determine the element to move to, the algorithm combines directional input, past focus history, and the physical layout of UI elements on the page.

To enable directional navigation, include the following script reference:

<script src=”directionalnavigation-1.0.0.0.js”></script>

By default, only a, button, input, select, and text area elements are considered focus-able. To make other elements focus-able, set a valid tab index on the element.

<div tabindex=”0″>This div is eligible for focus</div>

Make sure to check out the documentation to learn how to change the root element, set initial focus, how to override next focus, best ways to optimize controls for focus and how to customize the input. Don’t miss the samples as well that go through a lot of great examples.

Submitting your app to the Windows Store

Once you’re happy with the app after testing it on Xbox, it’s time to publish it to the Windows Store!

Depending on which route you took to build the app, the process is a little different on how you build the package for Store submission.

Xbox One and Hosted Web Apps are a great way to deliver your web application to millions of Xbox One users and enter the living room experience with minimal effort.

Wrap up

Make sure to check out the app source on our official GitHub repository, read through some of the resources provided, watch the event if you missed it and let us know what you think through the comments below or on twitter.

Next time we will release another app experience and go in-depth on how to build great Internet of Things experiences using the Universal Windows Platform and how to make them shine on the Xbox One.

Until then, happy coding!

Resources for Hosted Web Apps

Previous Xbox Series Posts

Tags:
adaptive ui
API
hosted web apps
HWA
open source
UI
Windows 10
Windows Store
Xbox One