Deploying and running Lightning apps on SmartTV

While Lightning is a framework made specifically for tv-applications running the Metrological Appstore (or RDK in general), it can certainly run on a subset of SmartTVs/devices from the likes of Samsung, LG, Sony (Android TV) and Amazon (FireTV). In this blog we’ll take a look at how we can build and run Lightning applications on these types of devices.

Generating a build of your app

This step assumes that you have already created an application. If you haven’t yet, please refer to this ‘getting started with LightningJS’ blog.

The Lightning CLI comes with several executable commands that you can use to generate builds. While for the Metrological Appstore you would normally execute lng build and lng upload to create and upload the build, we’ll use a different command (or rather, commands) here.

Commands we’ll execute

In the image above you’ll see two different commands that we’ll need to execute. These commands both execute the exact same thing, but there’s a slight difference. The ‘es5’ flag transpiles the code to an older version of javascript, which is needed to run on some ‘older’ televisions. Next to that, we will also create a ‘regular’ ES6 build that we could use on modern televisions.

Output of the two commands

The output of these commands is a dist folder that contains all of the files we will need to run on a television. These files comprise your actual Lightning application, and comes with an index.html that will be the entry-point of your application — similar to how normal websites are built.

Deploying to Samsung Tizen

There are several ways of deploying an application to Samsung Tizen. In both cases you’ll need to download tooling from Samsung, and obviously have access to a physical television*1. Before we move forward with these steps, I recommend you download and install Tizen Studio. This software comes bundled with the Samsung TV SDK, that also comes with an Emulator and debugging tooling.

Before we are able to push a build however, we need to create one first. I’m not going to go into too much detail, and would rather you follow the official guide from Samsung. The steps after you have your scaffolded app available, are what’s important to us. There are roughly two ways to include your application code into the Samsung-scaffolded project:

1. All application files included
2. A website redirect
3. A hybrid setup

1. Application files included

The first option is of course the easiest to execute. All you’ll have to do, is copy the files in the dist folder as generated by our earlier command, and place them into the scaffolded project. That’s all it takes. You’re now ready to either package the application for production, or deploy it to a TV or emulator for testing purposes. For instructions on installing on a physical television or emulator, please refer to the official Samsung documentation.

Pro’s of this approach:

• All your code is already downloaded to the device when installed

Con’s of this approach:

• You have no means of updating the application other than submitting a new version to Samsung

2. Website redirect

A different approach is to have your application available as a redirect. This requires for you to have your application code hosted on a publicly accessible domain (e.g. mylightningapp.mydomain.com). We can then instruct the Tizen package to immediately browse to the domain for loading the app. So in order to do that you’ll have to execute the following steps:

• Remove all of the un-used app-files from your scaffolded project (index.html has to stay)
• Implement a redirect in the index.html file (see image)
  There are different ways to redirect in javascript, you can use meta tags too, for example

index.html

Now, there is one detail with this approach that’s worth mentioning. Samsung Tizen has their own APIs that allow you to interact with the television itself (often available via the tizen and webapisobjects in code). They are however not available for hosted applications, unless you specifically ask Samsung Tizen for that permission. It is however only a permission that’s available to Samsung-registered partners.

Pro’s of this approach:

• You don’t have to submit applications to Samsung’s Appstore for each minor bugfix (still advised for each major update)

Con’s of this approach:

• The application is not downloaded to the device when the app is downloaded, rather it loads the website each time
• Requires Samsung partnership to access Tizen APIs

3. Hybrid setup

Last but not least, you can also achieve a somewhat ‘best of both worlds’ setup. The difference between a redirect and a hybrid setup, is the fact that you’ll instruct the index.html in the Tizen project to load the actual javascript files. By using this approach, you actually load the application from the device (rather than redirecting to the website). This means you’ll have access to the Tizen APIs without needing the partner permission.

It’s fairly easy to implement this functionality, and follows steps similar to the website redirect:

• Remove all of the un-used app-files from your scaffolded project (index.html has to stay)
• Copy the index.html from your dist folder into the Tizen project
• Adjust the javascript files to be retrieved from your website, rather than relative to the application path

Example of changes needed for Hybrid setup

Pro’s of this approach:

• You don’t have to submit applications to Samsung’s Appstore for each minor bugfix (still advised for each major update)
• You don’t need partnership status to apply this method

Con’s of this approach:

• The majority of your application is not downloaded to the device when the app is downloaded, rather it loads the javascript each time

Deploying your application to an Emulator or Samsung TV

Now that you have your application ready to use, you’ll need to try and see if it works on an actual device (or emulator). For that I would really recommend following the official documentation once more, since this step largely depends on whether you want to use the CLI or Tizen Studio; as well as deploying to an emulator or real device.

• Deploying to a real device
• Deploying to an emulator

Deploying to LG WebOS

Luckily, LG actually follows a similar approach to what Samsung does. The three options I’ve mentioned (App files included, redirect and hybrid) are all available for LG, too. The only difference is in the tooling used to scaffold the application, and in the way it’s deployed to the device.

LG previously made use of their ‘WebOS IDE’, but this has since the start of 2022 been deprecated in favour of using a VS Code extension. For that extension to work, you’ll also need to install the WebOS CLI separately from the extension. I would gladly refer you to the official documentation for installing these two: CLI and VS Code extension.

Scaffolding and applying our application method of choice

First up you’ll again need to scaffold your application, for which you can find instructions here. What you’ll find after scaffolding is a similar setup to a Samsung-scaffolded application. There is an index.html which is the entry point of your application, and some other files explaining how the app behaves on TV (appinfo.json, certain logo images).

When you’ve scaffolded the app, the next step is as explained exactly the same as it is for Samsung. You can choose from the three options mentioned earlier, all which come with their own pro’s and con’s. After changing the application code to your preferred method, you can move on to the next step.

Note: The ‘website redirect’ method does not require any specific permissions for LG WebOS, and can be used without problems.

Deploying your application to an Emulator or LG TV

Once you’ve made your application files ready for use, you can start deploying your Lightning application to a TV or emulator*1. I would gladly refer you to the official documentation for this again, which can be found on this website from LG.

Deploying to AndroidTV and FireTV

While LG and Samsung both offer ‘native’ support for running web-based applications, it’s not that easy for AndroidTV (and FireTV). One of the major aspects you’ll have to do is implement a Webview that’s going to load our application. Now, before we get started, you’ll need to install ‘AndroidTV Studio’. This is the IDE of choice for Android development, and comes with all the tools we’ll need to scaffold, build and deploy our application.

Scaffold your application

There are many steps required for scaffolding an application for AndroidTV. As you might have noticed for most of this, I’ll always refer to the official documentation. That way I can guarantee the information on scaffolding (as well as deploying) stays up to date for future iterations of Android Studio. Please refer to the scaffolding and setup documentation here.

Implementing a Webview

You might have heard of tools like Apache Cordova or Capacitor before. They are tools that allow you to run a website inside a mobile application, often leveraging native APIs to access the camera and native components. In this case we’ll be implementing our Webview, since we have a fairly simple ask from the device: just load the url.

First you’ll need to add a webview to your application. You can either choose to add it to your so-called app layout, or programatically add it when the application is created (you’ll find all code in the image below). Then all we have to do is instruct that webview to load the website where we’ve hosted our URL, and we’re off to the races. But, before we do, we have to make sure that the webview has the option to run Javascript. This functionality is disabled by default. In the end you’ll get the following code:

Example code for AndroidTV webview implementation

Deploying to emulator or physical Android (/Fire)TV device

Now that you have your webview implemented, you can test out the application. I’m starting to feel like a guitar with just one string here, but once again, I’ll gladly refer you to the official documentation on deploying your application. It’s the easiest and most well-documented way to get you going. There are other, and in my eyes, better ways to specifically work with Android TV devices. If you’re interested in learning more about that, please drop me a message!

Next steps

With all the above information, you should have been able to run your Lightning application on various TV brands from LG, Samsung, and any running Android TV or Fire TV. There are of course still some steps to take in order to make this a production-ready application, to name a few:

• Correct tv-remote key-mapping
  You might have noticed that not all keys will work on all devices. This is because Lightning comes with a default mapping of keys, that doesn’t match with the keys on the tv-remote. For example, the ‘back’ button is keycode ‘8’ by default, while it is keycode ‘10009’ on Samsung.
• App-package Logo’s and other metadata
  There is a world of options available in the various app files for the various brands. You’ll need to update the logo images that are referenced, but also look at language support, device-orientation support, and a whole lot more.
• Implementing device-specific behaviour
  While your application may run well now, there are things you’ll need to handle that are specific to the device in question. Samsung and LG have different ways of exiting out the application, for example, and you’ll need to handle both of them. This might apply to network-loss, video playback and others.

Conclusion

As you can tell from the above, it’s definitely possible (and fairly easy) to implement and run a Lightning application on a subset of SmartTVs. There are definitely some things you’ll have to handle for everything to work properly, like the key codes. But with relatively little effort, it’s possible to run your application on several SmartTVs. Where in another situation it might not have been that easy. And, even more importantly, Lightning applications perform incredibly well on SmartTV devices, even low-end ones. And that’s something you definitely cannot say from most other web-based solutions.

*1 It is also possible to run your application in an emulator for Samsung, LG or AndroidTV, but not all functionality of your app (mainly video playback) is expected to work.