Apple TV TVML tvOS hello world app in Swift

Introduction

Table of Contents
So, you saw the shiny new AppleTV demo on the Apple Live Event. Finally we can write apps for the beast! Like most of you, I downloaded the Xcode 7.1 beta to jump in. Hey, there’s a project template! Let’s try that. Oh, that’s it? Looks like any other iOS app. Where’ the TV code? Sigh. I guess I’ll have to RTFM.

There are two types of app. One relies on “templates” written in XML called TVML (Television markup language). The other “low level” way is to write custom apps in Swift (or objc). Here is a list of iOS APIs that did or did not make it to tvOS. (Interesting that AudioToolbox made it but CoreMIDI didn’t – and no mention of Core Audio). In this post, I’ll talk about the TVML approach.

Apple has provided us with their usual almost-adequate tvOS documentation. After you get an idea of how it works, you get a “hello world” type page named Creating a Client-Server App.

Cool. The sample code is not downloadable, so you need to scrape the code off the page and fix the problems.
Not cool.

Here’s my attempt at being a bit more helpful.

Getting started

Table of Contents

Go ahead and read Creating a Client-Server App. This will give you a good conceptual overview. I’ll give you action items below.

Server

Table of Contents

Let’s start with the server side. For development, you will need to serve JavaScript and TV Markup (TVML) files. There are various ways to do this. You can use Python, but I don’t like snakes or syntactic whitespace (both will bite you). Since you’re hip and happenin’ you probably have Node.js installed. So, let’s bask in your grooviosity and use Node to serve your files.

You will need to install http-server via npm.

Easy.

Then to serve the files in a subdirectory named “public” you simply type

Or if your files are in a different directory

So, what’s in that directory?

Go ahead and create a tvOS “Single View Application” project. Now drop to a terminal and create a directory named public under your project. Then import that directory to your project. Wouldn’t it be nice if you could do this directly in Xcode?

Now, you need two files (to start) in this directory. First, the JavaScript. I created a file named tv.js. Name it what you’d like. Here is Apple’s code:

Don’t bother copying it, I’ll point you to a Github repo later.

The other file you need is a TVML file. Note that in the onLaunch function I referenced a file named yo.tvml. Go ahead and create it in the public directory.

This is Apple’s minimal example. In my next blog post, I’ll go into more details, but if you want more now, read about Templates.

In the terminal, start the http-server. In another terminal (or tab if you use iTerm) you can test it with curl. Or use your browser.

Yay. You’re serving if you see the file’s contents.

Swift

Table of Contents

Make these modifications to your app delegate. This is how your app finds the JavaScript you’re serving. If you named your JavaScript file differently, modify the name here.

That’s it for your Swift code.

Security

Table of Contents

If you run your app now, it will crash with a security problem. Apple says read the
App Transport Security Technote.

Here’s the tl;dr.

Open your Info.plist as source code and add this key.

While you’re in Info.plist, delete the storyboard reference. You won’t be using a storyboard. You can delete the ViewController.swift file too (as specified in Apple’s documentation).

Run it now.

That complicated TVML file we served looks like this:

Summary

 

Table of Contents

tvOS TVML apps use a client-server architecture. You need to serve a JavaScript file and TVML files from a web server. Your Swift code will reference this JavaScript file. Most of your UI will be written in TVML.

Update

Table of Contents

Since I wrote this, Apple has published some sample code that you can download as a project. Yay.

Here is their TVML example. As usual it’s a dog’s dinner rather than a tutorial.

Resources

Table of Contents