开始使用 Web 应用


开始使用 Web 应用

Amazon Fire TV(包括 Fire TV 和 Fire TV Stick)支持 HTML5 Web 应用。您可以将您的 Web 应用移植到新平台,并轻松地将其提交至亚马逊应用商店。

提交应用的选项

  • 打包应用:一个完备的客户端应用,基于 Web 标准,其资产一起打包到 ZIP 档案中以供分发。
  • 托管应用:其资产托管在 Web 服务器上的应用。客户端连接到主机并将应用资产下载到其设备上,然后才能运行应用。
  • HTML5 混合应用:为用户界面使用 Web 内容的平台原生应用。

对于混合应用,您可以使用 Cordova 构建自己的包装器,或创建自己的混合应用,并像任何其他原生应用一样提交它。有关 Cordova 的更多信息,请参阅 Apache Cordova。有关将 Cordova 与 Amazon WebView 结合使用的信息,请参阅 Apache Cordova API 主题 Fire OS 平台指南

打包应用的优势

与托管应用相比,打包应用有几个优势:

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

托管应用的优势

与打包应用相比,托管应用有几个优势:

  • 托管应用可以是具有服务器端和客户端代码的完整应用。
  • 托管应用可以立即更新。客户总是得到最新的代码。
  • 托管应用为客户提供与您网站上相同的体验(通常是相同的代码)。

混合应用的优势

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

有关提交 Web 应用的信息,请参阅向亚马逊应用商店提交或更新您的 Web 应用

Amazon WebView API 还支持创建混合 HTML5 应用。有关 Amazon WebView API 的更多信息,请参阅构建和测试您的 HTML5 混合应用

在为 Amazon Fire TV 开发 Web 应用时,请注意以下详细介绍的问题。

有关详细信息,还请参阅以下主题:

包括 Amazon API

如果您的 Web 应用使用亚马逊 API(如应用内购买 API),则需要包含亚马逊 API JavaScript 库。此库初始化所有亚马逊插件,并引发一个 amazonPlatformReady 事件,以发出 API 已准备就绪的信号。该库托管在网址 http://resources.amazonwebapps.com/v1/latest/Amazon-Web-App-API.min.js 处。要包括该库,请向您的 Web 应用添加以下 <script> 标签:

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

由于此库在初始化完成时引发 amazonPlatformReady 事件,因此在调用任何亚马逊 API 之前应等待 amazonPlatformReady 事件,如以下示例所示:

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

使用 Web App Tester 和 DevTools

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

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

要在 Fire TV 上启用 DevTools:

  1. 在 Web App Tester 工具中,启动您的 Web 应用。
  2. 在 Amazon Fire TV 遥控器上,按菜单按钮。
  3. 选择启用 Devtools 菜单项,然后按照出现的对话框中的说明操作。

分辨率和页面缩放

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

Web Audio API 支持

Amazon Fire TV 和 Fire TV Stick 都支持Web 应用的 Web Audio API。 它们还支持 AudioContext 接口的 suspendresume 方法。 这些方法允许应用在需要时暂停音频设备。暂停音频播放可降低 CPU 使用率并延长电池寿命。

 以下示例说明如何创建 AudioContext 对象以及调用 suspendresume 方法。 

// 创建上下文
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,suspendresume 提供了一种理想的方式,可在使用 Web Audio 的游戏和其他应用进入后台并且用户启动语音搜索时,将它们静音。有关详细信息和代码示例,请参阅以下焦点变化语音搜索中断部分。 

焦点变化

Web 应用可能需要跟踪它何时进入后台(就像用户按下主页按钮一样),以便应用可以在进入后台时保持其状态,并且可以在移到前台时恢复。下表显示了不同的方法及其行为。

方法 描述
自定义亚马逊事件:pauseresume 当应用发送到后台(应用完全隐藏)或部分模糊时(例如显示语音搜索对话框)时,触发 pause 事件。

当应用被带到前台(应用完全可见),包括关闭语音搜索对话框时,触发 resume 事件。 
页面可见性 API  webkitvisibilitychange 事件被触发:

• 当应用被发送到后台时(完全隐藏)



• 当应用被带到前台时(完全可见) 

自定义亚马逊事件

要使用自定义亚马逊事件,您需要在您的应用中包含 Amazon WebApp API 脚本,并让您的应用侦听文档上触发的 pauseresume 事件。 

要注册为 pause 事件的侦听器,请使用以下语法:

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

当应用发送到后台(应用完全隐藏)或部分模糊时(例如显示语音搜索对话框)时,触发 pause 事件。当 amazonPlatformReady 事件触发时,应用应使用 document.addEventListener 来附加事件侦听器。

要注册为恢复事件的侦听器,请使用以下语法。

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

当应用被带到前台(应用完全可见),包括关闭“语音搜索”对话框时,触发 resume 事件。 当 amazonPlatformReady 事件触发时,应用应使用 document.addEventListener 来附加事件侦听器。

以下代码段说明了 pauseresume 事件的注册。

<!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

对于所有类型的应用,当应用失去或获得焦点时,Web 应用平台使用页面可见性 API 触发可见性更改事件。(有关检测失焦的更多信息,请参阅 Web 应用常见问题解答。)

对于视频播放应用,当应用失去焦点时,视频会自动暂停。但是,您必须确保您的 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 对象的 suspendresume 方法暂停和恢复音频播放,如以下示例所示。(有关 Web Audio 的详细信息,请参阅前面的 Web Audio 支持部分。)

// 创建上下文
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 and Firefox 18 and later support
        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 提交的应用的要求是,当用户按下遥控器上的语音搜索按钮时,这些应用必须停止或暂停音频播放。 这是为了确保遥控器上的麦克风不会从系统中拾取音频并表现不佳。您的应用可以通过两种方式检测用户何时按下语音搜索按钮:

  • 通过响应自定义亚马逊 pauseresume 事件
  • 通过使用页面可见性 API,如上一节所述(仅适用于平台版本 1.3)

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

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

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

仅音频应用还必须停止或暂停播放。当您使用 Web Audio 时,可以使用 AudioContext 对象的 suspendresume 方法来正确处理使用 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 在您的 Web 应用中测试 IAP v2.0 API。有关 App Tester 的更多信息,请参阅安装和配置 App Tester

检索广告 ID 和广告跟踪首选项

Web 应用可以检索广告 ID 和广告跟踪首选项(有关这些功能的详细信息,请参阅广告 ID)。在您包含 Web 应用 API 脚本(如上文包含亚马逊 API 中所述)后,AmazonAdvertising 对象会在您的 Web 应用中启用两个函数:getAdvertisingIdgetLimitAdTrackingPreference。这两个函数分别有两个参数 - 一个成功回调和一个错误回调。签名看起来类似如下:

AmazonAdvertising.getAdvertisingId(successCallback, errorCallback)
AmazonAdvertising.getLimitAdTrackingPreference(successCallback, errorCallback)

当您调用这些函数时,返回的值将传递给成功回调,如下所示:

  • getAdvertisingId 函数将广告 ID 传递给成功回调。
  • getLimitAdTrackingPreference 函数将 0(对于 false)或 1(对于 true)传递给成功回调。此值表示用户的广告跟踪首选项是什么。

如果在处理请求时发生错误,错误消息将传递给错误回调。您的 Web 应用应正常处理广告 ID 或限制广告追踪响应不可用的情况。

当您提交 Web 应用时,在“应用文件”选项卡“应用文件”选项卡上的 Web 应用功能部分,选择亚马逊广告

在开发者控制台中提交应用时,选择“亚马逊广告”
在开发者控制台中提交应用时,选择“亚马逊广告”

Fire TV 上不提供的功能

Amazon Fire TV 上不提供以下 Web 应用平台功能:

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

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