Overview of Vega Web Apps

Vega WebView components display web-based content in your Vega app, including HTML, JavaScript, and CSS. Using this component, you can reuse existing web content for your app. Some examples are static pages (Help pages, Terms and Conditions), login screens, or the presentation layer of your app. The WebView component uses the Chromium engine, which is customizable (custom headers, or DOM storage for instance) and supports data communication between the WebView source and the containing Vega app through the Messaging Bridge.

Make sure your web content is optimized for TV devices, which includes focus navigation for remote-control/directional-pad (D-Pad) input. Click/Touch/Drag UX implementations are seldom compatible with a TV user experience, and TV devices often use less power than desktop and mobile devices. Optimize your web content by reducing animations for TV, for instance. For more guidance on performance and fluidity, see Development Best Practices for Web Apps.

Layers of the WebView stack

The following diagram shows the layers of the code stack for WebView.

The following list describes the layers of the WebView code stack from the previous diagram, starting at the bottom and going to the top:

1. WebView core components: The following set of core components offers a range of APIs that parse and render web content within a WebView window.
2. Media stack: The OS API that provides access to hardware acceleration. It can also include the software audio and video decoder supported by the System-on-a-Chip (SoC) and Board Support Package (BSP) of the platform to decode a frame.
3. DRM: The API that handles the digital rights management (DRM) license and keys. This API works with a decoder component to decrypt the frames in the ARM Trust Zone, or Trusted Execution Environment (TEE).
4. Graphics: The API that provides the surface and subsurface for web content and media rendering.
5. Keyboard: The service that provides an on-screen keyboard for WebView.
6. App framework: The framework that provides a life-cycle manager, package manager, event manager, and more.
7. Chromium: The Chromium web engine, optimized for Vega. The engine is responsible for parsing and rendering web pages, including HTML, CSS, and JavaScript.
8. UI Framework: A cross-platform toolkit that supports a reactive programming, which is a declarative programming style, similar to React. The framework enables component developers to interact with operating system (OS) level API surfaces by exposing cross-platform API abstractions.
9. Native Vega WebView Component: A component written in C++ that enables WebView for the developer.
10. React Native WebView API: The software interface between Amazon and your React Native for Vega app.
11. React Native for Vega App: An app created by the developer.

Quick setup of your web app

Step 1: Add an app template

npm install @amazon-devices/webview@~3.3.0

For more details, see Create an app from a template.

Step 2: Add the required services to your manifest.toml file

[wants]

# If Web App needs keyboard support
[[wants.service]]
id = "com.amazon.inputmethod.service"

# If Web App needs video playback
[[wants.service]]
id = "com.amazon.media.server"

# Required for emitting metrics from video playback
[[wants.service]]
id = "com.amazon.mediametrics.service"

# Required for video playback on stable APIs
[[wants.service]]
id = "com.amazon.mediabuffer.service"
[[wants.service]]
id = "com.amazon.mediatransform.service"

# If Web App needs audio playback
[[wants.service]]
id = "com.amazon.audio.stream"

# Required for audio management features to work in WebView, features like audio focus, volume control 
[[wants.service]]
id = "com.amazon.audio.control"

# To enable accessibility support for your app, we recommend you add the UCC service with the Service Registrar
[[wants.service]]
id = "com.amazon.kepler.ucc.publisher"

# Uncomment below section to enable encrypted media playback (DRM content)
# [[wants.service]]
# id = "com.amazon.drm.key"
# [[wants.service]]
# id = "com.amazon.drm.crypto"
# [[needs.privilege]]
# id = "com.amazon.privilege.security.file-sharing"

# Enable Group-IPC to access media services
[[wants.service]]
id = "com.amazon.gipc.uuid.*"
[offers]
[[offers.service]]
id = "com.amazon.gipc.uuid.*" 

# You may add other services as needed

Step 3: Import and use the WebView component in your App.tsx file

 
import { WebView } from "@amazon-devices/webview";
import * as React from "react";
import { useRef } from "react";
import { View, StyleSheet } from "react-native";

export const App = () => {
  const webRef = useRef(null);
  return (
    <View style={styles.container}>
      <WebView
        // headers: {},
        ref={webRef}
        hasTVPreferredFocus={true}
        source={{
          // Replace with your URL.
          uri: "https://www.example.com",
          // or to reference a file located at <root>/assets/index.html
          // uri: "file:///pkg/assets/index.html"
        }}
        javaScriptEnabled={true}
        onLoadStart={(event) => {
          console.log("onLoadStart url: ", event.nativeEvent.url)
        }}
        onLoad={(event) => {
          console.log("onLoad url: ", event.nativeEvent.url)
        }}
        onError={(event) => {
          console.log("onError url: ", event.nativeEvent.url)
        }}
      />
    </View>
  );
};

// Styles for layout, which are necessary for proper focus behavior
const styles = StyleSheet.create({
  container: { flex: 1 }
});

WebView props

For a full list of props for the WebView component, see Vega WebView Component Reference.

Supported media formats

Vega Web App supports the following audio and video formats.

Supported audio formats

• FLAC
• MP3
• Opus
• Vorbis
• AAC
• PCM 8-bit unsigned integer
• PCM 16-bit signed integer little endian
• PCM 24-bit signed integer little endian
• PCM 32-bit float little endian
• PCM 16-bit signed integer big endian
• PCM 24-bit signed integer big endian
• PCM μ-law
• PCM A-law
• AAC-LC
• AAC-SBR
• AAC-PS
• AAC Scalable (MPEG-2)

Supported video software formats

• Theora
• MPEG4 Part 2

Supported video hardware formats

• VP8
• VP9
• H.264
• H.265

Support for Digital Rights Management (DRM)

WebView currently supports Widevine and PlayReady. Widevine supports HW_SECURE_ALL for video, and SW_SECURE_CRYPTO for audio. PlayReady supports SL3000 for video, and SL2000 for audio.

Checking if a device supports DRM content

WebView supports hardware DRM (Widevine L1 and PlayReady SL2000/3000), and software DRM (Widevine L3), as long as the device supports it. To check the availablily of DRM, Web Apps can use requestMediaKeySystemAccess method.

const system = 'com.widevine.alpha';
const config = [
  {
    audioCapabilities: [
      {
        contentType: 'audio/mp4;codecs="mp4a.40.2"',
        encryptionScheme: 'cenc',
        robustness: 'SW_SECURE_CRYPTO'
      }
    ],
    videoCapabilities: [
      {
        contentType: 'video/mp4;codecs="avc1.42E01E"',
        encryptionScheme: 'cenc',
        robustness: 'HW_SECURE_ALL'
      }
    ]
  }
];

navigator.requestMediaKeySystemAccess(system, config)
  .then(() => console.log('DRM supported'))
  .catch(() => console.log('DRM not supported'));

Usage notes

• The robustness field in the config determines the level of DRM being queried. Use HW_SECURE_ALL for hardware-backed DRM and SW_SECURE_CRYPTO for software DRM. Audio is not supported through hardware, so use SW_SECURE_CRYPTO for audio content.
• If the device does not support the requested DRM configuration, the promise will reject.
• Check for both hardware and software DRM levels and gracefully fall back based on availability.

Related topics

• Developer Guide for Web Apps
• Performance Best Practices for Web Apps
• Vega WebView Component Reference

Last updated: Apr 28, 2026