Create and Host tvOS TVML Apps with Azure and Xamarin

Creating amazing tvOS TVML apps doesn’t have to be hard. In this blog post, I’ll go over the many similarities tvOS has to iOS and show you how to create a sample quiz app using UIKit that harnesses the power of Azure and Xamarin. We can create wonderful apps for the Apple TV, but what if you want a super dynamic app, such as those used for video streaming services or podcasts?

Typically, one can update UIKit based apps via the App Store at any time, or include logic that retrieves, like a json file with updated data. However, this is complicated in comparison to utilizing TVML, which does all of the heavy lifting for you. TVML makes creating dynamic, content-based apps a breeze by keeping all the app logic and layout on the server-side, while providing great native interfaces that conform to the Human Interface Guidelines, not just a WebView.

To provide some general background on TVOS apps, check out our previous tvOS blog post, Introduction to tvOS.

Introduction to TVML

TVML allows developers to serve apps from a server, while still providing a native interface that conforms to Apple’s user interface guidelines. The advantage of keeping the app’s content on a server is that updates can be made, and dynamic content utilized, without having to update the app on the device itself. TVML provides developers with a number of templates that make it easy to create great looking apps and customize templates as required. These templates will allow TVMLKit on the device to display truly native views that aren’t just displayed from a WebView.

A TVML app is made up of three distinct parts:

1. A simple tvOS app created in Visual Studio, which generates a controller that loads and processes the remote TVMLKit JS and TVML files.
2. The TVMLKit JS files, which comprise the main code of the app and contain all the logic.
3. Lastly, the TVML templates, which the app will use for the layout to be displayed on a screen (akin to HTML).

Getting Started

Let’s create a very simple “Hello World” app to demonstrate how to deliver a TVML based app from Azure. Since TVML relies heavily on the client-server infrastructure, using an Azure Web App is a great choice, because we both enjoy great uptime and can also scale on demand.

First, we need to create the app (client). Open Visual Studio, and create a new tvOS app. We won’t be using a storyboard, so we can safely delete this from the project and remove the reference to it in Main Interface within info.plist. Now, go to AppDelegate.cs, where we’re going to write just a few lines to bootstrap the client.

At the top of the file, we want to include TVMLKit by adding using TVMLKit, so we need a few variables:

public TVApplicationController TVAppController;

string AzureJS = "";
string AzureBase = "";

We’ll populate the Azure strings with the URLs of our web service once we have set it up.

Finally, we need to add the following code in FinishedLaunching:

public override bool FinishedLaunching(UIApplication application, NSDictionary launchOptions)
{
Window = new UIWindow(UIScreen.MainScreen.Bounds);

var ControllerContext = new TVApplicationControllerContext();

var JSUrl = new NSUrl(AzureJS);

ControllerContext.JavaScriptApplicationUrl = JSUrl;
ControllerContext.LaunchOptions = new NSDictionary(new NSString("BASEURL"), new NSString(AzureBase));

TVAppController = new TVApplicationController(ControllerContext, Window, new TVAppDelegate());

return true;
}

The code creates a new TVApplicationController, which acts as a bridge between the server hosting our TVML and the app running on the Apple TV. Apart from filling in the two Azure URLs later, this is all the code we need to get a TVML app up and running!

Hosting with Azure

It’s important that a reliable hosting method is used. Without access to the server, the TV app will not function. For this reason, creating an Azure Web App is a perfect fit, since we can achieve great availability and there are many options for scaling for future demand.

To proceed with the next part of the project, you need to create a free Azure account. Click here to get started.

Once you create your free Azure account, go to Create Resource and search for “Web App”. Once you find it, click Create. Now it’s time to fill out some details, like a web app name. In this case, we’ll use “XamarinTV” and create a new resource group for it. Here, you can also decide on which OS you want to host it on. For this project, we’ve chosen Windows. You also need to create an App Service Plan, which lets Azure know where you want to host the Web App and what pricing tier to use. Select the free F1 tier and a region that is located near you. Once the Web App has been deployed, click on it to open it in the portal.

Creating TVML Code

There are a few ways we can upload the files to the Web App, such as FTP. For ease of use, we’ll use the built-in App Service Editor under Development Tools in the sidebar.

Create a new folder called js, a new file called application.js, and add the following code. The file should automatically be saved after a few seconds:

App.onLaunch = function(options) {
  var alert = createAlert("Hello, Xamarin!", "Greetings from Azure");
  navigationDocument.presentModal(alert);
}

var createAlert = function(title, description) {

    var alertString = `
        
          
            
            ${description}
          
        `

    var parser = new DOMParser();

    var alertDoc = parser.parseFromString(alertString, "application/xml");

    return alertDoc
}

The code here will create a basic alert using the alertTemplate. TVMLKit on the device will process this and display the alert the same as a native alert (UIAlertController). Presentation is handled by the NavigationDocument, which is essentially the same as a UINavigationController. This will also allow you to push and pop your TVML templates on the navigation stack.

Bringing it Together

Finally, we just need to fill in the URLs in our tvOS app code. In the Azure portal, go to “Overview” for the Web App and copy the URL; it should be in the format of https://example.azurewebsites.net:

string AzureJS = "https://example.azurewebsites.net/js/application.js";
string AzureBase = "https://example.azurewebsites.net";

Now, if you run the app in the simulator you should see the following:

Congratulations! You now have a working TVML app hosted on Azure.

Round Up

You’ve successfully written and deployed a TVML based app using Azure and Xamarin! By using TVML instead of UIKit, we can create dynamic apps on the server side, while still retaining the look and feel of a native tvOS app. Additionally, we can expect great uptime and the ability to scale on demand by using Azure and Xamarin.

Look for the next blog post in this series, where we’ll discuss how to compliment our use of Azure for the hosting of the app by integrating Azure Media Services (video streaming). To view the code used in this blog post, head to the GitHub repository here. For more information on tvOS with Xamarin, browse through our Introduction Documentation.

Discuss this post on the Xamarin Forums!