Introduction of Client-Server based tvOS Application using TVML & TVJS

In September 2015 at WWDC event, Apple introduced the most powerful and advanced updates to the Apple TV set-up box. It provides simple, most effective and handy user interfaces to the users for navigating and viewing video content. It also supports other third-party applications and games named as tvOS applications. Apple’s 4th generation TV hardware includes:

  • 64-bit A8 processor
  • Siri enabled remote
  • HDMI
  • 1080p resolution
  • 32GB or 64GB of storage
  • 2GB RAM

Apple has provided two ways to develop tvOS app:

  • TVML Apps: Apple introduced new TVML framework which is a client-server based app that includes TVML, TVJS, and TVML kit.
  • Custom Apps: These custom apps are developed in the same manner as for iOS. Examples are Storyboard, UIKit, Outlets, Actions, etc.

It’s totally up to you while choosing the platform for your app. TVML Apps are client-server apps i.e., you have data on a server which you want to show to the users whereas Custom TV Apps are customizable as other iOS apps with impressive and sophisticated user interface, animations, auto layouts, navigations, etc.
In this blog, we are focusing on TVML framework. With the new TVML framework, the native tvOS app will access the main Javascript file(TVJS) on our server and display the pages in Television Markup Language (TVML). The architecture is shown below.


As mentioned, we can develop client-server based apps via TVML, TVJS, and TVMLKit.
TVML(Television Markup Language): As the name suggest, it’s a markup language, i.e., a form of XML. Apple provides various kind of premade templates which you can easily find on Apple’s developer website.
TVJS (Television Javascript): Its a set of javascript file which is responsible for fetching data from the server with various API’s and display content(created with TVML) on TV.
TVMLKit: It’s a framework that communicates between TVML, JavaScript, and your native tvOS application.

 We hope that now you would have gained enough idea to create your first app on tvOS but remember to always have Xcode 7.1 or later before starting the development work.
To do that, open your Xcode and select “Create a new Xcode project” or go to Xcode’s “File\New\Project” and select the “tvOS\Application\TVML Application” and click “Next” button.
For the Product Name, enter FirstTVDemo (anything you want to) and select Language ‘Swift’ and uncheck both boxes and click Next and choose any directory to save your project. After saving that project open AppDelegate file, you will find some additional code in didFinishLaunchingWithOptions method.


You will also find “application.js” file in your supporting file group. Just open this file, here you will find javascript methods hierarchy same as AppDelegate method hierarchy, i.e., App.onLaunch, App.onWillResignActive, App.onDidEnterBackground etc . It also contains a createAlert function in it which is an Apple predefined alertTemplate.

Screen Shot 2016-06-20 at 12.45.50 PM

After viewing this, the questions which should arise in your mind are:

  • If it is a client – server based app where we need to set up Server?
  • Where do we need to store TVML templates?
  • How can we access it using TVJS?

So, here are the answers, Open your AppDelegate file, you will find appController, tvBaseURL, and tvBootURL.


TVApplicationController is a class in TVMLKit framework that helps in your app in communicating with the server. TVBaseURL contains the base URL of our server and TVBootURL includes the path of our JavaScript file (in this case application.js on your local host server).

In didFinishLaunchingWithOptions method, It has TVApplicationControllerContext, which it will use to initialize your TVApplicationController i.e., you will need to set two paths: path of your server and path of your javascript files.


As you can see, its calling application.js javascript file to fetch data. It includes App.onLaunch method i.e., launch point of the javascript file. The TVApplicationController that was initialized in AppDelegate will pass on its TVApplicationControllerContext.

Here it is simply calling the createAlert method for showing simple alert to display on the screen.

createAlert is a function that returns a TVML document. It includes alertString TVML string (in this case we are using alertTemplate from premade templates provided by Apple) its same as UIAlertView.


Now, when I run application I got an error :


Now, If you read this error message carefully, you will find that its failed to load launch URL i.e., it’s a client-server based app, so we need a web server to host our javascript files and TVML files. So, a simple local server in Node.js or Python is also enough for this example. So, just open the Terminal app and enter the following:

cd ~/Desktop/FirstTVDemo/FirstTVDemo

python -m SimpleHTTPServer 9001

Just need to drag application.js parent folder path to the terminal and then start our SimpleHTTPServer server because it is a good option that is started by command and replace port with the real value you want. And now just run your app and you will find:


Cheers! You have made your first TV app. Its simply an alertTemplate template from 18 different kinds of templates provided by Apple. However, you can try different templates as well.



comments (2)

Leave a comment -