网页应用入门

网页应用入门（Fire TV）

Amazon Fire TV（包括Fire TV和Fire TV Stick）支持HTML5网页应用。可将网页应用移植到新平台，并轻松提交至亚马逊应用商店。

应用提交选项
包括Amazon API
使用Web App Tester和DevTools
分辨率和页面缩放
Web Audio API支持
焦点变化
- 自定义亚马逊事件
- 页面可见性API
语音搜索中断
测试IAP
Fire TV不提供的功能

应用提交选项

打包应用：是基于Web标准的客户端应用，功能完备，其资产会打包成ZIP档案供分发。
托管应用：其资产托管在Web服务器上的应用。客户端只有在连接到主机并将应用资产下载到其设备上后才能运行应用。
HTML5混合应用：使用Web内容作为用户界面的平台原生应用。

对于混合应用，可用Cordova构建包装器，或创建混合应用，并像其他原生应用一样提交。有关Cordova的详情，请参阅Apache Cordova。有关如何将Cordova与Amazon WebView结合使用的信息，请参阅《Fire OS平台指南》中的“Apache Cordova API”主题。

打包应用的优势

与托管应用相比，打包应用有几个优势：

打包应用无需寻找应用的托管解决方案。
打包应用的性能可能更好，因为所有资产均存在本地文件系统中。
打包应用可更轻松地脱机工作。

托管应用的优势

与打包应用相比，托管应用有几个优势：

托管应用可以是具有服务器端和客户端代码的完整应用。
托管应用可立即更新。客户始终可以获得最新代码。
托管应用可让客户具有与网站上相同的体验（通常是相同的代码）。

混合应用的优势

更快、更高效的渲染，脚本性能和内存管理
支持最新Web标准（HTML5、CSS3和JavaScript）
CSS、画布和WebGL图形的硬件加速和GPU优化

有关提交网页应用的信息，请参阅提交应用。

Amazon WebView API还支持创建混合HTML5应用。有关Amazon WebView API的详细信息，请参阅构建和测试HTML5混合应用。

在开发适用于Amazon Fire TV的网页应用时，请注意下面详细介绍的问题。

有关详细信息，还请参阅以下主题：

包括Amazon API

若网页应用使用亚马逊API（如应用内购买API），需包含亚马逊API JavaScript库。该库初始化所有亚马逊插件，并发起一个amazonPlatformReady事件，发出API已准备就绪的信号。该库托管在URL http://resources.amazonwebapps.com/v1/latest/Amazon-Web-App-API.min.js中。要包含该库，请向网页应用添加以下<script>标签：

<script src="https://resources.amazonwebapps.com/v1/latest/Amazon-Web-App-API.min.js"></script>

注意： 仅在应用使用亚马逊API时，才需包含亚马逊API JavaScript库。

由于该库在初始化完成时发起amazonPlatformReady事件，在调用亚马逊API前应等待amazonPlatformReady事件，如以下示例所示：

document.addEventListener('amazonPlatformReady', function () {
    //此处使用API代码
});

使用Web App Tester和DevTools

Web App Tester是一个可用于在Amazon Fire TV设备上测试托管和打包应用的工具。

Web App Tester还支持使用DevTools调试网页应用。有关获取和使用DevTools的信息，请参阅调试网页应用。

在Fire TV上启用DevTools：

在Web App Tester工具中，启动网页应用。
在Amazon Fire TV遥控器上，按菜单按钮。
选择Enable Devtools（启用Devtools）菜单项，然后按照弹出对话框中的说明操作。

分辨率和页面缩放

为Amazon Fire TV的网页应用将分辨率定为1080p (1920x1080)。有关将应用从720p扩展到1080p的信息，请参阅《自定义Fire TV网页应用》。有关Fire TV网页应用设计指南的详细信息，请参阅设计和用户体验指南。

Web Audio API支持

Amazon Fire TV和Fire TV Stick均支持网页应用的Web Audio API。它们还支持AudioContext接口的suspend和resume方法。必要时，应用可使用这些方法暂停音频设备。暂停音频播放可降低CPU使用率并延长电池寿命。

以下示例说明创建AudioContext对象以及调用suspend和resume方法。

//创建上下文
var context = new(window.AudioContext || window.webkitAudioContext)();

//启动上下文
var oscillator = context.createOscillator();
oscillator.connect(context.destination);
oscillator[oscillator.start ? 'start' : 'noteOn'](0);

// 暂停
context.suspend();
// 恢复
context.resume();

// 由于暂停和恢复均返回一个承诺，因此可确定是成功还是失败
context.suspend().then(function() {
   alert('success!');
    },
    function() {
     alert('failure!');
     });
   context.resume().then(function() {
      alert('success!');
       },
       function() {
        alert('failure!');
        });

结合页面可见性API，suspend和resume提供理想的静音方式，在进入后台和用户启用语音搜索时，将使用Web Audio的游戏和其他应用静音。有关详细信息和代码示例，请参阅以下“焦点变化和语音搜索中断”部分。

焦点变化

网页应用可能需跟踪何时进入后台（正如用户按下主页按钮时），以便应用可以保持其在进入后台那一刻的状态，并可在移到前台时恢复。下表显示不同的方法及其行为。

方法	描述
自定义亚马逊事件：`pause`和`resume`	当应用发送到后台（应用完全隐藏）或部分被遮住（例如显示语音搜索对话框）时，触发`pause`事件。当应用调到前台（应用完全可见），包括关闭语音搜索对话框时，触发`resume`事件。
页面可见性API	触发`webkitvisibilitychange`事件： • 当应用发送到后台时（完全隐藏） • 当应用调到到前台时（完全可见）

自定义亚马逊事件

如需使用自定义亚马逊事件，需在应用中包含Amazon Webapp API脚本，并让应用侦听触发的pause和resume事件。

要注册为pause事件侦听器，请使用以下语法：

document.addEventListener("pause", yourCallbackFunction, false);

当应用发送到后台（应用完全隐藏）或部分被遮挡（例如显示“语音搜索”对话框）时，触发pause事件。触发amazonPlatformReady事件后，该应用应使用document.addEventListener附加事件侦听器。

如需注册为resume事件的侦听器，请使用以下格式。

document.addEventListener("resume", yourCallbackFunction, false);

当应用调到前台（应用完全可见），包括关闭“语音搜索”对话框时，触发resume事件。触发amazonPlatformReady事件后，该应用应使用document.addEventListener附加事件侦听器。

以下代码段说明pause和resume事件的注册。

<!DOCTYPE html>
<html>
<head>
    <title>Page Visibility Test Page</title>
</head>
<body>
<h2> Visibility : </h2>
<div id="appstate"> Visible </div>
<script src="https://resources.amazonwebapps.com/v1/latest/Amazon-Web-App-API.min.js"></script>
<script>
    var visibility =  document.getElementById("appstate");

    function onPause() {
        visibility.innerHTML = 'Hidden';
    }

    function onResume() {
        visibility.innerHTML = 'Visible';
    }

    function onAmazonPlatformReady() {
        document.addEventListener("pause" , onPause, false);
        document.addEventListener("resume" , onResume, false);
    }

    document.addEventListener("amazonPlatformReady" , onAmazonPlatformReady, false);
</script>
</body>
</html>

页面可见性API

对于所有类型的应用，当应用失去或获得焦点时，使用页面可见性API，网页应用平台触发可见性更改事件。（有关检测失焦详细信息，请参阅《网页应用常见问题解答》。）

对于视频播放应用，当应用失去焦点时，视频会自动暂停。但必须确保UI在应用重新获得焦点时处于正确的状态。例如，最好调出媒体控件，以便用户可看到播放状态，并确保应用响应播放/暂停按钮。或可能希望自动恢复视频。

但对于音频应用，应用本身必须暂停音频播放。该点尤其重要，因为当应用位于后台时，按下媒体按钮不会传递给应用，因此用户无法暂停音频播放。

以下代码演示了如何探测焦点变化。请注意，这些事件使用“webkit”前缀。

var handleVisibilityChange = function() {
    if (document.hidden || document.webkitHidden) {
        // 暂停音频/视频播放，暂停游戏，调整视频控制UI等
    } else {
        // 恢复播放，调整UI等
    }
}

document.addEventListener('webkitvisibilitychange', handleVisibilityChange);
document.addEventListener('visibilitychange', handleVisibilityChange);

若使用Web Audio，则可使用页面可见性API检测焦点更改，并使用AudioContext对象的suspend和resume方法暂停和恢复音频播放，如以下示例所示。（有关Web Audio详细信息，请参阅前面的Web Audio API支持部分。）

//创建上下文
var context = new (window.AudioContext || window.webkitAudioContext)();

//启动上下文
var oscillator = context.createOscillator(); oscillator.connect(context.destination); oscillator[oscillator.start ? 'start' : 'noteOn'](0);

// 确定正确的可见性API名称。
var hidden, visibilityChange;
if (typeof document.hidden !== "undefined") { // 支持Opera 12.10和Firefox 18及更高版本
        hidden = "hidden";
        visibilityChange = "visibilitychange"; }
else if (typeof document.webkitHidden !== "undefined") {
        hidden = "webkitHidden";
        visibilityChange = "webkitvisibilitychange"; }

// 页面可见性侦听器。
function handleVisibilityChange() {
   if (document[hidden]) {
     if (context.suspend) {
       context.suspend();
     } else {
       // 浏览器不支持suspend()
     }
   } else {
     if (context.resume) {
        context.resume();
     } else {
          // 浏览器不支持resume()
     }
   }
}
document.addEventListener(visibilityChange, handleVisibilityChange, false);

语音搜索中断

对于所提交的Amazon Fire TV应用，有一项要求是：当用户按下遥控器上的语音搜索按钮时，这些应用必须停止或暂停音频播放。目的是确保遥控器上的麦克风不会出现从系统中拾取音频，从而表现不佳的情况。应用可通过两种方式检测用户何时按下“语音搜索”按钮：

通过响应自定义亚马逊pause和resume事件
通过使用页面可见性API，如上一节所述（仅适用于平台版本1.3）

有关详细信息和代码示例，请参阅上文的“焦点变化”部分。

对于基于视频的媒体应用，网页应用平台自动处理视频暂停。只需确保当应用重新获得焦点时，UI处于正确状态。例如，请确保正确设置播放/暂停按钮，或可决定调用视频控制叠加层。

对于游戏，还必须确保音频播放处于静音或暂停状态。在这种情况下，一个常见的解决方案是将游戏置于暂停状态。

仅音频应用也必须停止或暂停播放。当使用Web Audio时，可使用AudioContext对象的suspend和resume方法正确处理使用WebAudio时的语音搜索请求。（有关Web Audio详细信息，请参阅前面的“Web Audio支持”部分。）

<script src="https://resources.amazonwebapps.com/v1/latest/Amazon-Web-App-API.min.js"></script>

<script>
var context = new (window.AudioContext || window.webkitAudioContext)();

function onPause() {
    context.suspend();
}

function onResume() {
    context.resume();
}

function onAmazonPlatformReady() {
    document.addEventListener("pause" , onPause, false);
    document.addEventListener("resume" , onResume, false); }

document.addEventListener("amazonPlatformReady" , onAmazonPlatformReady, false);
</script>

测试IAP

使用App Tester测试网页应用中的IAP v2.0 API。有关App Tester的详细信息，请参阅安装并配置App Tester。

Fire TV不提供的功能

Amazon Fire TV不提供以下网页应用平台功能：

地理定位(GPS)
弹出窗口
多行文本框
在外部浏览器启动应用
上传文件
下载文件

Fire TV支持WebGL，但Fire TV Stick不支持。

Last updated: 2023年8月30日