开发人员控制台

网页应用入门


网页应用入门

Amazon Fire TV(包括Fire TV和Fire TV Stick)支持HTML5网页应用。您可将网页应用移植到新平台,并可轻松提交至Amazon Appstore。

应用提交选项

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

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

打包应用的优势

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

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

托管应用的优势

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

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

混合应用的优势

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

有关提交网页应用的信息,请参阅《向Amazon Appstore提交或更新网页应用》

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>

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

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

使用网页应用测试器和DevTools

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

网页应用测试器还支持使用DevTools调试网页应用。有关获取和使用DevTools的信息,请参阅《调试网页应用》

在Fire TV上启用DevTools:

  1. 在网页应用测试器工具中,启动网页应用。
  2. 在Amazon Fire TV遥控器上,按菜单按钮。
  3. 选择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接口的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的游戏和其他应用静音。有关详细信息和代码示例,请参阅以下“焦点变化语音搜索中断”部分。 

焦点变化

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

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

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

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



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

自定义亚马逊事件

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

如需注册为pause事件侦听器,请使用以下格式:

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

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

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

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

对于所有类型的应用,当应用失去或获得焦点时,使用页面可见性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对象的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和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应用要求是,当用户按下遥控器上的“语音搜索”按钮时,这些应用必须停止或暂停音频播放。 目的是确保遥控器上的麦克风不会从系统中拾取音频并且性能不佳。应用可通过两种方式检测用户何时按下“语音搜索”按钮:

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

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

对于基于视频的媒体应用,网页应用平台自动处理视频暂停。只需确保当应用重新获得焦点时,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在网页应用中测试IAP v2.0 API。有关App Tester详细信息,请参阅安装和配置App Tester

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

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

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

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

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

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

提交网页应用时,在“App File(s)(应用文件)”选项卡上的Web App Features(网页应用功能)部分,选择Amazon Advertising(亚马逊广告)

在开发者控制台中提交应用时,选择“Amazon Advertising”
在开发者控制台中提交应用时,选择“Amazon Advertising”

Fire TV不具备的功能

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

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

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