Development Best Practices for Web Apps

Open Beta Documentation Amazon offers this technical documentation as part of a pre-release, open beta. The features described might change as Amazon receives feedback and iterates on the features. For the most current feature information, see the latest Release Notes.

Developers typcailly design TV Web apps built with HTML and JavaScript to run across multiple platforms. The best practices for web development generally apply to Vega TV Web apps as well. This guide highlights the most relevant and commonly recommended practices for web app development within the Vega environment.

Handle the focus

Developers should handle the focus in their web apps for usability and accessibility. Set the initial focus to actionable elements when the web app launches so users can start using the app from the first key press. Setting the focus to actionable elements also helps with accessibility features. Click here to see how to set the initial focus to WebView. To set the initial focus, see Set the initial focus to WebView.

Navigate with the remote control

Make sure the user can navigate the app using remote key events. Remote key events include the directional keys on a (DPAD), such as the Enter and Back buttons. Implement focus management using tabindex, and handle key events to shift focus dynamically. It's best to handle key events on their web app layer as the following shows.

Copied to clipboard.

document.addEventListener('keydown', e => {
  if (e.key === 'ArrowRight') moveFocusRight();
});

Handle the back button and app closing

Develop the app so the back button takes the user to their previous pages. If no more back navigation is possible, display a popup before closing the app. Make the popup indicate they have reached the end of the back navigation, and if they press back again, they extit the app. This functionality improves user experience by preventing accidental exits and sets the right user expectations. For close button handling, see onCloseWindow. For back button handling, see goBack().

Handle errors

Handle different error cases in the web app, including network connectivity errors, SSL certificate errors, and HTTP errors. Present a page so users can either retry, reload, or exit the app.

WebView provides onError, onHttpError, and onSslError callbacks so apps can take the appropriate action.

Playback media

For smooth media playback across devices, web apps should check the device's media capabilities before attempting playback. Web apps can use MediaCapabilities, or canPlayType() APIs to achieve it. Checking device media capabilities helps avoid runtime errors, playback failures, or poor user experience.

For a list of our supported formats, see WebView supported media formats.

Handle the background activity

When the web app goes into the background with active playback, stop the video and go back to the content detail page. Persist the necessary app state information when the app goes into the background, since the system may terminate the app when it needs more resources, such as memory.

When an app moves into the background, the system releases the hardware decoder used for video decoding, so other apps can use it. When the web app returns to the foreground, users may see a black screen while the decoder reinitializes to begin rendering video frames again. This process often takes a few seconds. To avoid a black screen, terminate the web app video playback and navigate back to the content detail page before going to the background.

Avoid relying on the userAgent

Vega WebView userAgent contains strings representing device information, OS information, and WebEngine information. These strings may change for future hardware devices in the future, so don't depend on this information if you can avoid it.

Ex:

Copied to clipboard.

Mozilla/5.0 (Linux; Kepler 1.1; AFTCA002 user/1234; wv) AppleWebKit/537.36 (KHTML, like Gecko) Mobile Chrome/130.0.6723.192 Safari/537.36'

Consider accessibility

When developing web apps for Vega, accessibility must be a core consideration for an inclusive user experience for all. Unlike touch-based interfaces, TV apps rely on remote controls with directional navigation (DPAD). Make sure all focusable elements are reachable and follow a logical focus order. Use the tabindex attribute to define and manage focus, and always provide visible focus indicators to help users track which element is active.

Semantic HTML elements like <button>, <nav>, and <form> play a crucial role in enhancing accessibility and are better than generic containers like <div> or <span> whenever possible. For screen reader support, use ARIA (Accessible Rich Internet Applications) roles, labels, and attributes to provide meaningful context, especially for custom components. Set web app titles so when the app launches, screen readers can read it.

Enable Vega media controls

Users may interact with the app using various input methods, such as remote control, voice commands, or a companion device like a mobile remote app. Write your app with seamless media playback control for all of these input methods. To support such input, integrate with the Vega Media Controls API, which enables consistent media control functionality for each input method. For implementation details and integration steps, see the Example integrating VegaMediaControl in your app code.

Last updated: Feb 02, 2026