Developing a TVML App for The Apple TV (Part 1)
Since the 4th generation Apple TV was announced it was pretty clear for everyone in the app development business that a new Pandora’s box had been opened. The new Apple TV opened the way for millions of iOS and Web developers to the big screen, once again making possibilities endless. Three main factors contribute to make this new platform a success. First, Apple’s chance to reuse the experience of its already existing army of developers. Secondly, the new tvOS App Store that allows users to buy apps and content in the same way they already do with their iOS devices, and thirdly, the device’s technical features that make it far superior to the competition. As tvOS 10 gets nearer, we explore a little bit of what this platform has to offer us, the developers.
The problem with the Web
The web as we know it does not work well on TVs. At least that’s what Apple believes and, to be honest, it’s difficult to disagree. Nowadays the web has become really complex. Even a basic webpage has a structure that would be difficult to browse comfortably without depending on a mouse cursor or a touchscreen interface. That’s why Apple made it a big no-no to use UIWebView components in tvOS: they don’t want you to display HTML webpages on screen! So, what’s left for those people who want to provide a TV experience without falling into the complexities of native app development? The answer to that question is TVML.
Think about TVML as a special kind of HTML which allows you to present your website’s information using a series of predefined templates. There are over 18 templates available, all of them with perfect, Apple-certified navigability using the Siri Remote. It just works great with the new focus engine and behaves just like the Apple TV users expect to behave. And just like you can join forces between HTML and JavaScript, you can do the same with TVML.
Like in web development, you just need to start a local web server hosting your files. The app will first look for the application.js file which will serve as the entry point of your app. It will load all the necessary scripts that will feed data into your controllers, receive user input and interface with remote services — just like it happens in a standard Web client!
The Template Catalog
As starting point you can download and try the TVML Catalog App which will allow you to try out and understand the different templates available to you. If you are the usual Apple TV user you will quickly recognize most of them.
If you are used to working with HTML and your project is not complex enough to justify a native app, then move ahead and try TVML. Keep in mind that your project would need to adapt to the available templates. While there are many of them, if you aim to create a groundbreaking new interface you will probably have to work on a native app instead.
What is truly great about TVML is that with just a little training you can quickly turn a web developer into an tvOS developer without incurring into big performance penalties. Also, the tvOS App Store is still a fertile, almost unexplored ground when compared to its big iOS brother, so reaching visibility is easier. I deeply encourage you to build something nice and get it published!
Getting technical
My first experience with TVML was an attempt to use the iFixIt API to retrieve and display their guides. I had a fuzzy idea of what I had to do: simply download the JSON response from the API, then somehow connect one of the templates to it. I thought it would be like filling out the methods of the well known UITableViewDataSource protocol. I was wrong.
First I created a brand new TVML project. The empty template includes a JavaScript file called application.js which, as I previously mentioned, is the entry point of the app. What is not that clear from a newbie’s point of view is that this file won’t actually be included in the binary but it actually must be served by a web server. What is interesting about this is that since the binary doesn’t change, you can modify the files provided by your server and change your users’ experience without resubmitting the app to the store!
Following the TVML Catalog app as an example, I recreated the same folder structure and ended up with something like this:
Once the structure was ready it was time to get that server running so we could enjoy the sight of a Hello World on the big screen. But where and how should that server run? The answer was in this single line of the AppDelegate file:
static let TVBaseURL = “http://localhost:9001/"So I needed a local web server running in port 9001, pointing to the Server folder that I just created on the base directory of my project. To do that, the easiest way was simply firing up a Terminal window, moving to the base directory, then using a single Python sentence:
$ cd ~/Desktop/iFixIt/Server/
$ python -m SimpleHTTPServer 9001
Serving HTTP on 0.0.0.0 port 9001 ...Since I was using the tvOS Simulator using localhost was enough, but if I had wanted to use a real Apple TV I would have needed to change the TVBaseURL host to my own IP address or Bonjour name. In my case that would have looked like something like this:
static let TVBaseURL = “http://leanmac.local:9001/"This should be enough to get the app running, right? Wrong. The web server we’re using works with http (plain text) requests. Those requests are automatically denied by default due to ATS. To be able to use my test server I had to temporarily disable it by editing my Info.plist file:
Finally the app was ready to run! If you did everything right this should appear in your simulator window
So this took a little bit more work than I anticipated, and the steps to be followed weren’t that clear to start with, but once you learn it, it is really easy to replicate. Now it was the time to start messing with the JavaScript code and get those iFixIt guides on the screen! This was the moment when I fell in the sad realization that I haven’t done any JavaScript coding in two years and my abilities were beyond rusty. I sighed, rolled up my sleeves and started coding.
JavaScript time
A programmer’s best friend is always a good debugger. I use console outputs a lot in order to understand what’s going on during the execution of my scripts. Once I was able to start writing some JS I learned to recognize two different kinds of errors and how to deal with them.
Compilation-time errors often happened due to a typo or a missing semicolon. When you are developing for TVML, those kind of errors appear in the Xcode console. For instance:
Runtime errors, on the other hand, are debugged pretty much in the same way people do it on the web. Problem is, where are our developer tools? Our console? The answer is Safari.
Yep. Safari is capable to interact with the tvOS Simulator in such a way that it allows you to inspect objects, see the output console and do pretty much anything. To do that, first you need to enable the Developer menu by going to Preferences > Advanced and ticking the last option on the list. Then you will find out that connecting to the simulator is really easy:
Once you learn how to effectively debug your JavaScript code it’s just a matter of doing the actual coding!
Did I finally get the app up and running? Did I find my way through JavaScript compile errors and strange new XML controllers? Join us in the next episode in this exciting series and find out!
