Options for Submitting Apps

Packaged app: is a full-fledged client-side web standards-based application whose assets are bundled together in a ZIP archive for distribution.

Hosted app: is an application whose assets are hosted on a web server. Clients connect to the host and download the app's assets to their device before being able to run the app.

HTML5 hybrid apps: are platform-native apps that use web content for the user interface.

For hybrid apps, you can build your own wrapper with Cordova or create your own hybrid app and submit it like any other native app. For more information on Cordova, see Apache Cordova. For information on using Cordova with Amazon WebView, see the Apache Cordova API topic, Fire OS Platform Guide.

Advantages of Packaged Apps

Packaged apps have several advantages over hosted apps:

Packaged apps do not require you to find a hosting solution for your app.

Packaged app performance can be better because all of the assets are present on the local filesystem.

Packaged apps can work more easily offline.

Advantages of Hosted Apps

Hosted apps have several advantages over packaged apps:

Hosted apps can be complete applications with server-side and client-side code.

Hosted apps can be updated immediately. Customers always get the latest code.

Hosted apps provide the same experience (and typically the same code) for customers as on your web site.

Including the Amazon APIs

If your web app uses Amazon APIs, such as the In-App Purchasing API, you need to include the Amazon API JavaScript library. This library initializes any Amazon plugins and raises an amazonPlatformReady event to to signal that the APIs are ready for use. The library is hosted at the URL http://resources.amazonwebapps.com/v1/latest/Amazon-Web-App-API.min.js. To include this library, add the following <script> tag to your web app:

Web Audio API Support

Amazon Fire TV and Fire TV Stick both support the Web Audio Api for web apps. They also support the suspend and resume methods of the AudioContext interface. These methods allow applications to pause the audio device when needed. Suspending audio playback reduces CPU usage and prolongs battery life.

The following example illustrates creating an AudioContext object and calling the suspend and resume methods.

// Create contextvarcontext=new(window.AudioContext||window.webkitAudioContext)();// Start contextvaroscillator=context.createOscillator();oscillator.connect(context.destination);oscillator[oscillator.start?'start':'noteOn'](0);// Suspendcontext.suspend();// Resumecontext.resume();// Since both suspend and resume return a promise, their success/failure can be determinedcontext.suspend().then(function(){alert('success!');},function(){alert('failure!');});context.resume().then(function(){alert('success!');},function(){alert('failure!');});

Coupled with the page visibility API, suspend and resume provides an ideal way to silence games and other applications that use Web Audio when they go into the background and when the user initiate a voice search. For more information and code examples, see the following Focus Changes and Voice Search Interruption sections.

Focus Changes

A web app may need to track when it is moved to the background (as when the user presses the Home button) so that the app can preserve its state at the moment when it is moved to the background and can resume when it is brought to the foreground. The following table shows the different methods and their behavior.

Method

Description

Custom Amazon events: pause and resume

pause event is fired when the app is sent to the background (app completely hidden) or when its partially obscured (for example, when the Voice Search dialog box is displayed)

resume event is fired when the app is brought to the foreground (app completely visible) including when the Voice Search dialog box is dismissed.

Page Visibility API

webkitvisibilitychange event is fired:

• when the app is sent to the background (completely hidden)

• when the app is brought to the foreground (completely visible)

Custom Amazon Events

To use the custom Amazon events, you need to include the Amazon Webapp API script in your app and have your app listen for pause and resume events fired on the document.

To register as a listener for the pause event, use the following syntax:

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

The pause event is fired when the app is sent to the background (app completely hidden) or when it's partially obscured (e.x Voice Search Dialog is displayed). The app should use document.addEventListener to attach an event listener once the amazonPlatformReady event fires.

To register as a listener for the resume event, use the following syntax.

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

The resume event is fired when the app is brought to the foreground (app completely visible) including when the Voice Search Dialog is dismissed. The app should use document.addEventListener to attach an event listener once the amazonPlatformReady event fires.

The following code snippet illustrates registering for the pause and resume events.

The Page Visibility API

For all types of apps, the web app platform fires a visibility changed event, using the Page Visibility API, when the app loses or gains focus. (For more information on detecting loss of focus, see the Web Apps FAQ.)

For video-playback apps, the video is paused automatically when the app loses focus. However, you must ensure that your UI is in the proper state when the app regains focus. For example, it is a good idea to bring up the media controls so the user can see the state of the playback, and to ensure the app responds to Play/Pause button. Alternatively, you may want to resume the video automatically.

However, for audio apps, the app itself must pause the audio playback. This is especially important because presses on the media buttons are not passed to an app when it is in the background, so the user has no way to pause audio playback.

The following code shows how to detect changes in focus. Note that these events use the "webkit" prefix.

If you are using Web Audio, you can use the Page Visibility API to detect changes in focus and use the suspend and resume methods of the AudioContext object to pause and resume audio playback, as illustrated in the following example. (For more information on Web Audio, see the preceding Web Audio Support section.)

// Create contextvarcontext=new(window.AudioContext||window.webkitAudioContext)();// Start contextvaroscillator=context.createOscillator();oscillator.connect(context.destination);oscillator[oscillator.start?'start':'noteOn'](0);// Determine the correct visibility api names.varhidden,visibilityChange;if(typeofdocument.hidden!=="undefined"){// Opera 12.10 and Firefox 18 and later supporthidden="hidden";visibilityChange="visibilitychange";}elseif(typeofdocument.webkitHidden!=="undefined"){hidden="webkitHidden";visibilityChange="webkitvisibilitychange";}// Page visibility listener.functionhandleVisibilityChange(){if(document[hidden]){if(context.suspend){context.suspend();}else{// Browser does not support suspend()}}else{if(context.resume){context.resume();}else{// Browser does not support resume()}}}document.addEventListener(visibilityChange,handleVisibilityChange,false);

Voice Search Interruption

A requirement for applications submitted for Amazon Fire TV is that they stop or pause audio playback when the user presses the Voice Search button on the remote. This is to ensure that the microphone on the remote does not pick up audio from the system and perform poorly. Your app can detect when the user presses the Voice Search button in two ways:

By responding to the custom Amazon pause and resume events

By using the Page Visibility API, as explained in the previous section (for platform version 1.3 only)

For more information and codes examples, see the preceding Focus Changes section.

For video-based media applications, the web app platform will automatically handle pausing the video. You only need to ensure that your UI is in the proper state when your app regains focus. For example, ensure that the Play/Pause button is correctly set, or you may decide to bring up the video control overlay.

For games, you must also ensure that audio playback is muted or paused. A common solution in this situation is to put the game in a paused state.

Audio-only apps must also stop or pause playback. When you use Web Audio, you can use the suspend and resume methods of the AudioContext object to properly handle voice search requests when using WebAudio. (For more information on Web Audio, see the preceding Web Audio Support section.)

Testing IAP

Retrieving the Advertising ID and Ad Tracking Preference

Web apps can retrieve the advertising ID and the ad tracking preference (see Advertising ID for details about these features). After you include the Web App API script (as described above in Including the Amazon APIs), an AmazonAdvertising object enables two functions in your web app: getAdvertisingId and getLimitAdTrackingPreference. Both functions have two parameters each — a success callback and an error callback. The signatures look like this:

When you call these functions, the returned value is passed to the success callback as follows:

The getAdvertisingId function passes the advertising ID to the success callback.

The getLimitAdTrackingPreference function passes either a 0 (for false) or 1 (for true) to the success callback. This value indicates what the user's ad tracking preference is.

If an error occurs when processing the request, the error message will be passed to the error callback. Your web app should gracefully handle situations when the advertising ID or limit ad tracking responses are not available.

When you submit your web app, on the App File(s) tab in the App File(s) tab, in the Web App Features section, select Amazon Advertising.

Select Amazon Advertising when you submit your app in the Developer Console

Features Not Available on Fire TV

The following web application platform features are not available on Amazon Fire TV:

Geolocation (GPS)

Popup windows

Multiline text boxes

Launching an app to an external browser

Uploading files

Downloading files

WebGL is supported on Fire TV, but not supported on the Fire TV stick.