Build Web Apps with WebView

​

Set the initial focus to WebView

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

export const App = () => {
const webRef = useRef(null);
return (
  <View >
      <WebView
      ref={webRef}
      hasTVPreferredFocus={true}
      source={{
        uri: "https://www.example.com",
      }}
      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>
  );
};

​

Send and receive messages from WebView pages

• React Native for Vega -> Web: The injectJavaScript method.
• Web -> React Native for Vega: The onMessage prop.

​

Implement Vega device Fire TV features from a web page

​

Checking HDR format and codec support in WebView for Vega

​

Enable back-button remote key events in web JavaScript

• In the src/App.tsx file, set the allowSystemKeyEvents property to true.

​

Enable and use DevTools for debugging

• At the command prompt, run the following command.
  vega build -b Debug
  

1. Install and launch the debug app, which opens a WebView.
2. Perform port forwarding at the command prompt by running the following command.
   vda forward tcp:9229 tcp:9229.
   DevTools runs on port 9229.
   
3. Open Google Chrome, and then navigate to chrome://inspect/#devices.
4. Find DevTools in the Remote Target section, in the list of connected devices.
5. Open DevTools, by selecting inspect, and inspect the WebView.

​

Supported remote key events

​

Example checking for HDR using canPlayType()

>const video = document.querySelector('video');
>console.log(video.canPlayType('video/webm; codecs="vp09.02.10.10'));
probably

>console.log(video.canPlayType('video/mp4; codecs="hev1.2.4.L153.B0"'));
probably

​

Example checking for HDR using isTypeSupported()

>MediaSource.isTypeSupported('video/webm; codecs="vp09.02.10.10"');
true

>MediaSource.isTypeSupported('video/mp4; codecs="hev1.2.4.L153.B0"');
true

​

Example using HEVC

const hevcConfig = {
    type: 'media-source',
    video: {
        contentType: 'video/mp4; codecs="hvc1.2.4.L153.B0"',
        width: 3840,
        height: 2140,
        framerate: 60,
        bitrate: 20000000,
        transferFunction: 'pq',
        colorGamut: 'rec2020'
    }
};

navigator.mediaCapabilities.decodingInfo(hevcConfig)

​

How to override default media control handlers

• Disabling seek operation during advertisements.
• Disabling all media control during live playback.

• Web-based implementation using navigator.mediaSession. For this implementation, enable allowsDefaultMediaControl for these reasons.
  • It enables transport control for play, pause, skip forward, and skip backward.
  • It works directly in the web page without app code changes.
• Direct integration with the VegaMediaControl interface in your app code. For this integration, disable allowsDefaultMediaControl for these reasons.
  • It provides full access to the device’s media control capabilities.
  • It’s recommended for apps requiring deep system integration.

​

Web-based implementation using navigator.mediaSession

​

Example using navigator.mediaSession

// Web Page JavaScript Code (to be included in the web page)
// Get reference to video element
const video = document.querySelector('video');
if ('mediaSession' in navigator) {
    // Override play action
    navigator.mediaSession.setActionHandler('play', () => {
        // Custom play logic here
        video.play();
    });
    // Override pause action
    navigator.mediaSession.setActionHandler('pause', () => {
        // Custom pause logic here
        video.pause();
    });
    // Override seek actions
    navigator.mediaSession.setActionHandler('seekbackward', (details) => {
        // Custom seek logic here
        const skipTime = details.seekOffset || 10;
        video.currentTime = Math.max(video.currentTime - skipTime, 0);
    });
    navigator.mediaSession.setActionHandler('seekforward', (details) => {
        // Custom seek logic here
        const skipTime = details.seekOffset || 10;
        video.currentTime = Math.min(video.currentTime + skipTime, video.duration);
    });
}

// React Native App Code (to be implemented in your app)
return (
    <View style={styles.sectionContainer}>
      <WebView
        ref={webRef}
        hasTVPreferredFocus={true}
        allowsDefaultMediaControl={true}  // Required for navigator.mediaSession to work
        source={{
          uri: "https://example.com",  // Replace with your URL
        }}
        javaScriptEnabled={true}
      />
    </View>
);

​

Integration with VegaMediaControl interface in app

1. Configure the WebView Prop.
   • The default media control in WebView is disabled by default. To keep the controls disabled, either leave the prop unset or explicitly set allowsDefaultMediaControl to false. To use the VegaMediaControl integration, keep the default media control disabled.
2. Implement the VegaMediaControl Interface.
   • Add VegaMediaControl integration to your app
3. JavaScript Bridge Communication
   • Use injectJavaScript to control the web player according to VegaMediaControl handlers.

​

Example integrating VegaMediaControl in your app code

1. Add support for VegaMediaControl in manifest.toml. Update the manifest for KMC, along with other entries.
   [components]
   [[components.interactive]]
   categories = ["com.amazon.category.kepler.media"]
   
   [[extras]]
   key = "interface.provider"
   component-id = "com.amazondeveloper.keplerwebapp.main"
   
   [extras.value.application]
   [[extras.value.application.interface]]
   interface_name = "com.amazon.kepler.media.IMediaPlaybackServer"
   command_options = [
       "Play",
       "Pause",
       "SkipForward",
       "SkipBackward",
   ]
   
2. Add the following dependencies to package.json.
   "@amazon-devices/kepler-media-controls": "~1.0.0",
   "@amazon-devices/kepler-media-types": "~1.0.0",
   
3. The following app code example creates the KMC server and the associated handler. Those handlers can inject JavaScript into the webpage with custom behavior.
   import { WebView } from "@amazon-devices/webview";
   import { useEffect, useRef, useMemo } from "react";
   import { StyleSheet, View } from "react-native";
   import {
     Action,
     IMediaControlHandlerAsync,
     IMediaMetadata,
     IMediaSessionId,
     ITimeValue,
     ITrack,
     MediaControlServerComponentAsync,
     MediaSessionState,
     RepeatMode,
   } from "@amazon-devices/kepler-media-controls";
   import { IComponentInstance, useComponentInstance } from "@amazon-devices/react-native-kepler";
   
   export const App = () => {
     const webRef = useRef(null);
     const componentInstance: IComponentInstance = useComponentInstance();
   
     const mediaControlsHandler: IMediaControlHandlerAsync = useMemo(
       (): IMediaControlHandlerAsync => ({
         handlePlay: function (sessionId?: IMediaSessionId): Promise<void> {
           console.log("Media Controls", ["handlePlay"]);
           // update the JS script based on the webpage implementation.
           webRef.current?.injectJavaScript("document.querySelector('video')?.play();");
           return Promise.resolve();
         },
         handlePause: function (sessionId?: IMediaSessionId): Promise<void> {
           console.log("Media Controls", ["handlePause"]);
           // update the JS script based on the webpage implementation.
           webRef.current?.injectJavaScript("document.querySelector('video')?.pause();");
           return Promise.resolve();
         },
         handleTogglePlayPause: function (sessionId?: IMediaSessionId): Promise<void> {
           console.log("Media Controls", ["handleTogglePlayPause"]);
           // inject javascript based on the webpage implementation
           return Promise.resolve();
         },
         handleStop: function (sessionId?: IMediaSessionId): Promise<void> {
           console.log("Media Controls", ["handleStop"]);
           // inject javascript based on the webpage implementation
           return Promise.resolve();
         },
         handleStartOver: function (sessionId?: IMediaSessionId): Promise<void> {
           console.log("Media Controls", ["handleStartOver"]);
           // inject javascript based on the webpage implementation
           return Promise.resolve();
         },
         handleFastForward: function (sessionId?: IMediaSessionId): Promise<void> {
           console.log("Media Controls", ["handleFastForward"]);
           // inject javascript based on the webpage implementation
           return Promise.resolve();
         },
         handleRewind: function (sessionId?: IMediaSessionId): Promise<void> {
           console.log("Media Controls", ["handleRewind"]);
           // inject javascript based on the webpage implementation
           return Promise.resolve();
         },
         handleGetMetadataInfo: function (id: MediaId): Promise<IMediaMetadata> {
           console.log("Media Controls", ["handleGetMetadataInfo", id]);
           return Promise.resolve({
             mediaId: id.contentId,
             title: 'Sample Title',
             date: '2024-01-01',
             artwork: [
               {
                 url: 'https://example.com/artwork1.jpg',
                 sizeTag: 'medium',
                 id: 'sample artwork id1',
                 tag: 'fantastic',
               },
               {
                 url: 'https://example.com/artwork2.jpg',
                 sizeTag: 'large',
                 id: 'sample artwork id2',
                 tag: 'wonderful',
               },
             ],
           });
         },
         handleGetSessionState: function (sessionId?: IMediaSessionId): Promise<MediaSessionState[]> {
           console.log("Media Controls", ["handleGetSessionState"]);
           // inject javascript based on the webpage implementation
           return Promise.resolve([]);
         },
       }),
       []
     );
   
     useEffect(() => {
       const mediaControlServer = MediaControlServerComponentAsync.getOrMakeServer();
       mediaControlServer.setHandlerForComponent(mediaControlsHandler, componentInstance);
     }, [componentInstance, mediaControlsHandler]);
   
     const styles = StyleSheet.create({
       sectionContainer: {
         flex: 1,
       },
     });
   
     return (
       <View style={styles.sectionContainer}>
         <WebView
           ref={webRef}
           hasTVPreferredFocus={true}
           source={{
             // Replace with your URL.
             uri: "https://example.com",
           }}
           javaScriptEnabled={true}
         />
       </View>
     );
   };
   

​

Load a local file URL stored on the device into a WebView

• In the src/App.tsx, set the allowFileAccess property to true.

​

Example: Use WebView to load an HTML file from the assets directory

<View>
    <WebView
        source={{
            uri: "file:///pkg/assets/sample.html",
        }}
    />
</View>

​

Example: Use WebView to load an HTML file from the app data directory

<View>
    <WebView
        source={{
            uri: "file:///data/sample.html",
        }}
        allowFileAccess={true}
    />
</View>

​

D-Pad navigation in WebView

​

Prevent spatial navigation in WebView

​

How to prevent a flashing white screen before the page loads

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
        style={styles.webview}
        ref={webRef}
        hasTVPreferredFocus={true}
        source={{
          uri: "https://www.example.com",
        }}
        javaScriptEnabled={true}
        onLoadStart={(event) => {
          console.log("onLoadStart", event.nativeEvent.description)
        }}
        onLoad={(event) => {
          console.log("onLoad", event.nativeEvent.description)
        }}
        onError={(event) => {
          console.log("onError", event.nativeEvent.description)
        }}
      />
    </View>
  );
};

// Styles for layout and background color
const styles = StyleSheet.create({
  container: {
    flex: 1,
  },
  webview: {
    backgroundColor: "#000000"
  }
});

​

How to remove the remote playback icon at the top of the video playback screen

const obj = document.createElement("audio");
obj.disableRemotePlayback = true;

​

How to selectively allow or block HTTP

​

How it works

​

Common use cases

• Allow all HTTP except a few domains (blocklist). Example: Allow cleartext for the whole application except sensitive domains.
  [network-traffic-policy.cleartext]
  allowed-domains = ["*"]  # Allow all domains
  blocked-domains = [
      "sensitive-api.com",
      "*.bank.com",
      "payment.example.com"
  ]
  
• Block all HTTP except specific domains (allowlist). Example: Don’t enable cleartext for the whole application but trust specific domains.
  [network-traffic-policy.cleartext]
  allowed-domains = [
      "debug.myapp.com",
      "*.test.internal.com",
      "localhost"
  ]
  # blocked-domains omitted - not needed for allowlist
  
• Block all HTTP (no exceptions). Example: Don’t allow cleartext at all.
  [package]
  # network-traffic-policy.cleartext omitted
  # This is the default secure behavior
  
• Allow all HTTP (no restrictions). Example: Allow cleartext for all domains. Perhaps for a captive portal app, or network diagnostics.
  [network-traffic-policy.cleartext]
  allowed-domains = ["*"]  # Allow all domains
  

​

Related topics

• Overview of Vega Web Apps
• Performance Best Practices for Web Apps