Vega Web App Development Best Practices for Vega TV

TV Web apps built with HTML and JavaScript are typically designed 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. Make sure to set the initial focus to actionable elements when the web app launches. That way customers can start using the app from the first key press. This also helps in making the app accessible to AX customers. Click hereto see how set the initial focus to WebView. To set the intial focus, see Set the initial focus to WebView.

Navigate with the remote control

Make sure the app can be fully navigated using remote key events. This includes handling directional keys (DPAD), Enter, and Back buttons appropriately. Implement focus management using tabindex, and handle key events to shift focus dynamically. Its best to handle key events on their web app layer as the following shows.

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

Handle the back button and app closing

Have the back button take the customer to previous pages in the page history, and if there is no more back navigation possible, display popup before closing the app. Make the popup clearly indicate they have reached the end of the back navigation, and if they press back again, they will exit the app. This improves user experience by preventing accidental exits and sets the right customer expectations. For close button handling, see onCloseWindow. For back button handling, see goBack().

Handle errors

Web apps are expected to handle different error cases, including network connectivity errors, SSL certificate errors, and HTTP errors. It’s recommended to show interstitial page using which customers can either retry or take necessary steps to re-load or exit the app. Present a page so customers can either retry or take necessary steps to re-load 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() API’s to achieve it. This 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. Also make sure to persist the necessary app state information when the app goes into the background, as it may be terminated when the system needs more resources, such as memory.

The motivation behind this request is based on how video playback is handled when a web app moves into the background. In such cases, the hardware decoder used for video decoding is released, allowing other apps to utilize it. When the web app returns to the foreground, users may experience a temporary black screen while the decoder is re-initialized and begins rendering video frames again. This process may take a few seconds. If the web app terminates video playback and navigates back to the content detail page before going to the background, the black screen issue can be avoided.

Avoid relying on the userAgent

Vega WebView userAgent contains strings representing device information, OS information, and WebEngine information. This information may changes on different device hardware in the future, so its better not to depend on this information unless its absolutely necessary.

Ex:

Copy code Copied to clipboard.

Mozilla/5.0 (Linux; Vega 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 should be preferred over generic containers like <div> or <span> whenever possible. For screen reader support, make use of ARIA (Accessible Rich Internet Applications) roles, labels, and attributes to provide meaningful context, especially for custom components. Set web app titles so that when the app launches, it can be read by a screen reader.

Enable Vega media controls

Customers may interact with the app using various input methods, remote control, voice commands, or a companion device like a mobile remote app. Ensure seamless media playback control across all these modalities. To support this, 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.

Related topics

• Vega Web App Overview
• Vega Web App Performance Best Practices
• Vega Web App Best Practices - Web Workers
• Vega Web App Best Practices - WebGL

Last updated: Sep 30, 2025