How to Build a tvOS Application for Apple TV Tutorial

9 min readOct 11, 2015

TL;DR: Tutorial on building a “Hello World” tvOS application for Apple TV using Javascript and Apple’s Markup language.

Apple recently announced the new AppleTV will be launching with an operating system called tvOS, and it will include an app store! This will will allow developers to build tvOS apps using Javascript, TVML (Apple’s templating language), and Swift.

The best part? You don’t need to know Swift in order to build an app for the tvOS.

Using Javascript to handle the application logic and Apple’s very own TVML templating language for UI will let you build robust front-end applications in no time.

I sat down this weekend to build a simple application and was able to be up and running within an hour. This is huge because it didn’t require any Swift knowledge to get running, most of the application logic was in Javascript.

In this tutorial, we are going to build a simple “Hello World” TVML app. You will learn how to setup a Xcode project, use Apple’s TVML templates, TVJS, TVMLKit, and build an app for the Apple TV!

What is tvOS?

tvOS is Apple’s new operating system for the Apple TV, which will now allow developers to build applications and games for it. tvOS includes an app store making it easy for end users to download your app or game. There is a great write up about it here.

tvOS is built upon iOS and uses a lot of the same frameworks. You can build TVML apps, which are applications that use TVML, TVJS, and TVMLKit. You can custom apps if you have experience with iOS development too. TVML apps leverage Javascript and the templating language Apple offers where custom apps are like a blank canvas.

What is TVML, TVJS, and TVMLKit?

TVML

TVML, which stands for “Television Markup Language”, was created by Apple and it’s a form of XML. This is what creates the User interface for your application. Apple defines TVML as:

“Every page in a client-server app is built on a TVML template. TVML templates define what elements can be used and in what order. Each template is designed to display information in a specific way.
For example, the loadingTemplate shows a spinner and a quick description of what is happening, while the ratingTemplate shows the rating for a product. You create a new TVML file that contains a single template for each page in a client-server app. Each template page occupies the entire TV screen. Each template page uses compound and simple elements. Compound elements contain other elements, while simple elements are single lines of TVML. Elements contain the information and images that are displayed on the screen.”

Apple also includes predefined templates that you can use for your application. I have included a list of them below with links to the templates and a brief description from Apple.

alertTemplate — Display important information, such as a message telling the user to perform an action before continuing.
catalogTemplate — Display information about groups of like products.
compilationTemplate — Display information about one product that is made up of several distinct pieces.
descriptiveAlertTemplate — Display a significant amount of important information, such as a Terms of Service page
divTemplate — Use this template to create pages that do not conform to a layout defined by another template.
formTemplate — Use this template to gather information from the user.
listTemplate — Display a list of items; for example, a list of the user’s favorite movies.
loadingTemplate — Display a spinner and description of why the spinner is being displayed
mainTemplate — Display options to the user; for example, the main page for a movie with options to play the movie, see extra content, and jump to specific scenes.
menuBarTemplate — Display a list of selectable items across the top of the screen.
oneupTemplate — Display a single, full-screen image. Users can navigate left or right on the remote to select another image. Activating an up action on the remote will shrink the image and allow a description to be displayed.
paradeTemplate — Display a list of automatically scrolling, static images on the left that are associated with a selected image category on the right.
productBundleTemplate — Display detailed information about a product bundle; for example, a page that describes a television series, including information about the actors, ratings, and series episodes.
productTemplate — Display detailed information about a product; for example, a page that describes a movie, including information about the actors, ratings, and like movies.
ratingTemplate — Display a rating for an item.
searchTemplate — Display a text field that takes user input in order to search for a specific item.
showcaseTemplate — Display a row of images with descriptions associated with each image; for example, displaying a set of screenshots to promote a movie.
stackTemplate — Display groups of products; for example, displaying different genres of movies.

Apple offers a sample app that shows all of its templates, you can check it out here. Running this sample app will let you navigate through the templates in the Xcode Simulator.

Here are the steps you need in order to run the sample project:

Download the file and unzip it.
Open the Xcode Project file in Xcode 7.1 or later.
Open your Terminal application and change your directory to downloaded app. Then change directory into the folder called “client”.
Run the command ‘python -m SimpleHTTPServer 9001’, without single quotes. This will start up a mini server so that your app can call the JS files. Note: 9001 is defined as the localhost port in the `TVBaseURL` variable.
Build the application and voala!

TVJS

TVJS is a framework of JavaScript APIs for creating client-server apps using TVMLKit. Apple defines TVJS as:

The TVJS framework provides you with the means to display client-server apps created with the Apple TV Markup Language (TVML) on the new Apple TV. You use other classes in the framework to stream media and respond to events.

TVMLKit

TVMLKit is a framework that provides the ability to incorporate JavaScript and TVML files to create client-server apps.

How the tvOS app infrastructure works

[caption id=”attachment_279" align=”aligncenter” width=”300"]

Diagram from Apple.com[/caption]

Client-server apps using JavaScript and TVML are different from traditional apps. The purpose of the project you create in Xcode is to access a main JavaScript file and present pages created from TVML files on the screen.

[caption id=”attachment_280" align=”aligncenter” width=”300"]

Diagram from Apple.com[/caption]

For example, you open your application on tvOS and the TVMLKit calls to the Javascript file. The Javascript file then responds with a TVML template to load on your screen. If the user does an interaction with the TVML file, then calls the Javascript file again and decides what to do next.

Please note that each app on the Apple TV is limited to a maximum of 200MB. Due to this limit, you must use an asset server to host content files and data. ie: videos, images, etc. Read more about it here and here.

Getting Started, Let’s Start Building!

Now that you have a basic understanding of tvOS, TVML, and TVJS let’s start building!

If you haven’t done so, make sure you are using Xcode 7.1 or later. As of this writing Xcode 7.1 Beta was available here.

Start by creating a new project in Xcode and using the tvOS “Single View Application” template.

Once you click “Next”, fill out the options for your project. You do not need to have “Use Core Data” checked. Upon completing that page, save your project to your desktop.

Delete the files “ViewController.swift” and “Main.storyboard”. When prompted, click “Move files to trash”. You won’t be using these files since we are build a simple TVML application.

Open the “Info.plist” file and remove the entry line “Main storyboard file base name”. Now, add `App Transport Security Settings` then add a child to it called `Allow Arbitrary Loads` and set it to `YES`. Remember to save the file. The `Allow Arbitrary Loads` row allows you to load the local client files without forcing HTTPS.

Now open the file called “AppDelegate.swift” and make the following changes:

Import TVMLKit to your app.
Add `TVApplicationControllerDelegate` to the end of the class declaration “AppDelegate”
Delete all of the methods in the AppDelgate class
A method begins with “func” then the name of the method and parameters after that. The code is within the curly braces.

Now, add the following code to your AppDelegate Class, below var window: UIWindow?:

Your AppDelegrate.swift file should look something like this:

Javascript to the rescue!

Create a folder in your app directory called “client” with a sub folder called “js”. The “js” folder is where your Javascript files live.

Within the “js” folder, create a file called application.js and add the following code:

[Note: I use Sublime Text as my text editor for when I’m not coding in Swift]

Once you complete the previous steps, set up your local server. We previously touched based about it, but here are the steps:

Open your Terminal application and change into your app directory and the “client” folder. Here is a gist of the commands you need to run if your directory is on the desktop and the folder is called `hello world`.
Run the command ‘python -m SimpleHTTPServer 9001’, without single quotes. This will start up a mini server so that your app can call the JS files. Note: 9001 is defined as the localhost port in the `TVBaseURL` variable.

Build the application and voala! You have just created your first tvOS app!

Quick Recap

So far you have created a simple alert that says “Hello World” in this tutorial. You’ve managed to create a barebones Xcode project, added Javascript, TVML and set up a simple server.. congrats! Great job, you just built a tvOS application for the Apple TV! You can download the project on Github here. This is a great foundation for building more robust applications for the Apple TV.