| description | title | author | ms.author | ms.date | ms.topic | ms.prod | keywords |
|---|---|---|---|---|---|---|---|
Ensure your PWA provides a great experience for Xbox |
Tailor your PWA for Windows |
MSEdgeTeam |
msedgedevrel |
12/20/2018 |
article |
microsoft-edge |
progressive web apps, PWA, Edge, Windows, UWP, Xbox, Xbox One, TVJS |
You can extend a web application and make it available as an Xbox One app via Microsoft Store while still continuing to use your existing frameworks, CDN and server backend. And like all Universal Windows Platform (UWP) apps, Progressive Web Apps (PWAs) running on Xbox One can also call native Windows 10 APIs. There are already a number of PWAs available for the Xbox One, particularly in the category of media playback apps.
For the most part, you can package your PWA for Xbox One in the same way you would for Windows, using the PWA Builder tools or Visual Studio IDE to generate the appxmanifest file required to run your PWA as a UWP app. However, there are several key differences this guide will walk you through.
To get started, follow these steps to activate Xbox One Developer Mode . With Developer Mode activated, set up Device Portal for Xbox to gain remote access to your Xbox from the browser in your dev environment.
Now you're ready to deploy your app for testing using either PWA Builder or Visual Studio.
PWA Builder is a Node.js app you can install from Node Package Manager (NPM). It uses the metadata of your website to generate native hosted apps across Android, iOS and Windows. If your site already has a web app manifest, PWA Builder will use it to generate platform-specific installation packages. Otherwise, PWA Builder will generate a basic manifest.json file based on the characteristics of your site.
- Node.js, which includes NPM.
-
Open a Node command prompt to install PWA Builder:
npm install pwabuilder --global -
Run PWA Builder on your website URL:
pwabuilder https://example.com/ -windows10The -windows10 flag limits package generation to Windows 10 (UWP). You can omit it to generate packages across all supported platforms, including iOS and Android. See the PWA Builder docs for more info.
-
From the Device Portal for Xbox, go to Home > My games & apps > Add, choose the option to upload loose files, and select the Windows 10 app manifest folder generated by PWA Builder in the current directory.
-
Step through the wizard to complete the installation process. Once installed. you'll be able to see and launch your PWA from the Xbox One dashboard.
The free, full-featured Visual Studio Community 2017 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 Professional and Enterprise versions provide even more features.
- Visual Studio 2017: any version, including the free Community edition.
- Windows 10 SDK: Select this optional component in the Visual Studio 2017 Installer.
-
Follow the steps to set up and run your PWA as a Universal Windows app. With this, you'll have a fully functioning Windows 10 app capable of accessing Universal Windows APIs.
-
You can now deploy and debug your PWA (as a UWP app) on the Xbox One (as with any other Windows 10 remote device) using the Visual Studio remote debugger. Alternately, you can install your PWA using the Device Portal for Xbox using the following steps.
-
From the Device Portal for Xbox, go to Home > My games & apps > Add, choose the option to upload App Package and Dependencies.
-
Navigate to the package folder you generated for your app in Step 1 and select the .appx file for upload. The .appx file is a UWP app package file that can be sideloaded on any device for testing purposes.
-
Next tap the Dependencies button and select the dependencies sub-folder for your app and upload each one. This step is only required for deploying apps from the Device Portal for Xbox. Visual Studio delivers dependencies when remote debugging and the end user’s machine will already have these installed when delivered from the Microsoft Store.
-
With the app package and the dependencies uploaded, click the Go button under the Deploy section and the app will be installed. You're ready to launch your app from Xbox!
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. As such, consider how your app might be used at that distance as opposed to the traditional desktop web browser experience with a mouse and keyboard. For design and UX guidance, check out Designing for Xbox and TV.
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 by calling setDesiredBoundsMode and specifying useCoreWindow:
var applicationView = Windows.UI.ViewManagement.ApplicationView.getForCurrentView();
applicationView.setDesiredBoundsMode(Windows.UI.ViewManagement.ApplicationViewBoundsMode.useCoreWindow);For more, check out the Windows.UI.ViewManagement namespace documentation.
User input methods for Xbox are gamepad or remote control, which use a XY navigation system, allowing the user to shift the focus from control to control by moving up, down, left, and right.
As such, you'll want to make sure your app works well with XY navigation. Also, be sure to disable mouse mode, which is on by default for UWP apps (and probably not applicable to your app's Xbox experience).
The following code turns off mouse mode and enables gamepad input to generate DOM keyboard events:
navigator.gamepadInputEmulation = "keyboard";Alternately, you can specify gamepad, which also turns off mouse, does not generate DOM keyboard events, and allows you to use the standard web and/or WinRT gamepad APIs.
To enable directional navigation, check out the TVJS library, discussed next.
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.
Directional navigation is a TVJS feature that provides automatic two-dimensional navigation within the pages of your TV app. With it, there's no need to trap and handle navigation within the pages of your app, or to explicitly specify all the valid focus targets for each element in the UI. Automatic focus handling enables users can navigate around in an intuitive and robust way.
As your user navigates the app UI with the controller direction buttons, the automatic focus algorithm looks at the set of potential focus targets, determines the next element to move to and then automatically sets focus to that element. To determine the next element, 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 <textarea> elements are focusable. To enable focus on other elements, assign them a valid tabindex.
<div tabindex=”0″>This div is eligible for focus</div>Check out the DirectionalNavigation documentation to learn how to change the root element, set initial focus, override next focus, optimize controls for focus, customize the input. There's also a number of other useful samples.
If you're building a media playback PWA for Xbox One, be aware of the following considerations.
The Microsoft Edge browser on Xbox One does not support Encrypted Media Extensions (EME). If your media PWA uses it for digital rights management (DRM), you won't be able to run it from the browser on your Xbox. Instead, prototype and test it as a Xbox One app using PWABuilder or Visual Studio, as described above. You can also run it on the Microsoft Edge browser on Windows, where EME is fully supported.
If your app is a media app, it is important that your app responds to the media controls initiated by the user via on-screen buttons, Cortana voice commands, the System Media Transport Controls in the nav pane, or the Xbox and Xbox One SmartGlass apps on other devices. Take a look at the MediaPlayer control from the TVJS library, which automatically integrates with these controls. Alternately, you can manually integrate with the System Media Transport Controls.
At the time of this writing, cbcs encoding support is limited to the PlayReady client for XBox One (version 1709 or higher). If the media for your PWA only supports cbcs encryption, be aware that your app's functionality will be likely be limited (or completely unavailable) on Windows.
South Ridge Video: A sample video app for Xbox built with React.js and hosted on a web server.
Designing for Xbox and TV: Design your Universal Windows Platform (UWP) app so that it looks good and functions well on Xbox One and television screens.
Xbox best practices: Follow these best practices to tailor your app for Xbox One.
PWAs in the Microsoft Store: Here's how (and why!) to Submit your PWA to the Microsoft Store.
UWP on Xbox One: A complete guide to UWP app development for Xbox One.