Amazon Fire TV, including both the Fire TV and Fire TV Stick, now supports HTML5 web apps. The Web App Starter Kit for Fire TV is a new open source project intended to help developers get up to speed quickly creating a simple media-oriented app for this exciting new web platform. Features of the project include an example user interface designed for the 10-foot user experience, support for the Fire TV remote control, and sample components to create and customize a media app. You can find this project on its GitHub project page here.
Here's an example of a media app using video content from the recent AWS re:Invent conference:
Over the summer of 2014, we ran an early-access beta program with a dozen or so web app developers who were interested in collaborating with us to bring their HTML5 media apps to Fire TV. The program was a huge success, pinpointing technical issues that needed to be resolved before we opened access to web apps to the larger developer community. One of the most important pieces of beta feedback was the request for some sort of template to target the "10-foot Experience" on Fire TV. Though web browsers have been on TVs since the mid 90s, developers have never really targeted big screens and thus there is a notable vacuum of examples, guides or code available that web app developers can use to get started.
To address this need, we decided to create an open source HTML5 web app "starter kit" that developers can use to quickly create a simple media app, ready to be customized and published in the Amazon Appstore. The project contains code developers can re-use in their apps, as well as a design template for the couch-focused user experience as well. Interacting with HTML5 via a remote control is a very different experience than that of a mouse or touch screen.
Create TV-Based Web Apps
The project is written as a simplified MVC-based web app with few external dependencies. It's been componentized so that developers can pull functionality into in their own app, such as support for the Fire TV remote, or they can decide to simply use the code "as-is" and only customize the existing app by modifying the style and image files.
Baked into the starter kit is the code needed to both provide the large screen experience consumers expect, as well as to pass Amazon Appstore testing during the app submission process. This includes support for remote control key codes, warnings before quitting the app, handlers for when the app is backgrounded, full-screen media playback, and more. At the bare minimum, the developer only needs to provide access to their media sources as a JSON document that includes a list of media files, thumbnail images, titles, descriptions and categories. The app then uses that data to display the media as a selectable list of categories and a rotating carousel of media content.
We've included documentation covering all aspects of the starter kit: A ReadMe document introduces the project, and architecture and styling guides walk developers through the options they have to use or customize the app for their needs.
Being on GitHub also opens the opportunity to both improve the documentation as time goes on, as well as receiving "pull requests" from those in the developer community who wish to help improve the starter kit in the future.
Let's run through the basic steps in getting a media web app up and running using the starter kit. (See the documentation on GitHub for full details.) For an introduction to Web Apps on Fire TV be sure to read our other blog post, Publishing HTML5 Apps to the Fire TV.
First, you'll need to grab the code from the Amazon GitHub repository using git - the open source version control system. (If you haven't learned how to use git yet, GitHub has a great online tutorial which will walk you through the basic steps, or you can download one of their easy to use GUI clients.)
Local Web Server. Once you've cloned the repository to your system, you'll need to launch a local development web server to test it out. This can be done through various means, including using either Python or Node.js. Open a terminal or command line, and change into the base directory of the project, and use one of the following methods to create a local web server:
Using Python, create a simple HTTP server with this command:
Using Node and NPM, install the Serve package, then create the server:
Web App Tester. Though we can do development using our desktop browser by navigating to http://localhost:3000, you'll want to see what the app looks like on a big screen powered by a Fire TV device. To do that, we'll be using the Web App Tester to view the content. The Tester is an app provided by Amazon which you can install on your Fire TV. It lets you test your web app on a real-world big screen before you submit the app to the Amazon Appstore.
Once you've installed the app, note the IP address of your computer where you are serving the starter kit's content, then navigate to http://your-local-ip:3000, highlight the Test button and press select and the sample app will be displayed .
Customize Your App
Now that you have the starter kit installed and running, you will want to customize the look and feel of the app as well as provide your own content to populate the video list and category list. Below are the files you'll need to change.
Logo. To modify the logo, use your favorite text editor to open the index.html file found in the root of the project and search for the "app-logo" class. This is where you will add the URL to your new logo.
Later, once you are familiar with the design of the web app, you can modify more of the HTML to better reflect your content or brand. Again, the documentation provided with the starter kit will point out the overall architecture of the project.
Look and Feel. The project's CSS file is automatically generated from a Sass template found in the root of the project called firetv.scss. Check out the Sass website for info on how to install and use sass templates. Rather than needing to go through the entire CSS file looking for things to change, there is a variable file called _variables.scss which allows you to change the fonts, colors, etc. of the app by simply changing the values used in the main Sass file. Once you have modified the variables, you'll need to generate a new CSS file to be used by using Sass from the command line:
You can find more details on how to style an app in the project's documentation.
Content. The last step to creating your first big screen web app for the Fire TV is to create a JSON file with the details of your media content, providing the file names, URLs and meta data needed. A sample JSON file can be found in the ./assets folder of the project and can be modified, or the URL can be changed completely by editing the index.html page to change the settings.dataURL value.
The JSON file contains an array of these basic fields:
- The URL fields (imgURL and videoURL) can be local files or external resources.
- The categories field is an array of topics used for filtering videos, which will be automatically grouped and displayed in the main menu of the app.
For more information about the JSON format and other architectural questions, check out the project's documentation. To find out more about developing web apps from scratch for the Fire TV, check out the Developer Portal's Getting Started with Web Apps for Fire TV, which has lots of useful information and notes you should be aware of.
Submitting your app to the Amazon Appstore
Once you've customized the Starter Kit and have your Fire TV web app created, you can publish it to the Amazon Appstore within minutes - without having to do any native development. Developers have a choice of either hosting the app's asset files on their own web server and submitting just the URL, or uploading the assets to Amazon's servers, where it will be bundled into a standalone packaged app.
Follow the steps below to submit your web app:
1. Create a Free Amazon Developer account.
2. Go to the New Web App Submission page and provide details about your Fire TV web app:
- General Information (title, category, support details, privacy URL)
- Availability and Pricing (release date and base list price)
- Images and Multimedia (screen shots, icons)
- Content rating
3. Choose whether or not to submit a hosted web app or a packaged web app. (In this case, the latter).
5. Choose both the Fire TV and Fire TV Stick in the Device Support section.
For information on submitting both hosted and packaged apps, see Submitting or Updating Your Web App to the Amazon Appstore.
The Web App Starter Kit for Fire TV is just in its beginning stages, so if you have any questions, suggestions, or (most importantly) pull requests, please use the Amazon GitHub project page to send them to us. We really look forward to seeing all the cool new media apps created by web developers!