Deploying and running Lightning 3 apps with Blits on SmartTV

Matthijs Langendijk
10 min readJul 26, 2024

--

Lightning 3 and Blits are out with their official v1 releases! Can you imagine it’s been a year since the first introduction? Now, with this official production-ready release, it means we can also start looking at using Lightning 3 and Blits on devices other than the typical RDK-based STBs. In this blog are some instructions for getting an app built with Blits to run on Smart TVs from the likes of Samsung, LG and AndroidTV/GoogleTV based devices from Sony, Philips, TCL and others.

This blog was previously created for Lightning 2, and has been adapted to fit the Lightning 3/Blits setup.

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 ‘basics of development with Blits’ blog.

With the introduction of Lightning 3 (and Blits), the bundler has moved over to a much easier (and much speedier) setup with Vite. Because of this, you can use most of the plugins that Vite has available out of the box. It also means generating a build is rather easy. You can run the npm run build script that is configured in your package.json , and underwater executes the build command on vite: vite build . Executing this command generates a dist with the following file structure (files differ depending on your project structure):

Example blits dist output

With the dist folder now available, you’re good to go for the next steps! What is important to note though, is the fact that Vite will generate a build of your Lightning 3 app with the latest javascript code. Sadly, not all televisions will support that, so you might need to enable some transpilation steps that ‘translate’ the code to older javascript versions. Luckily, a plugin already exists to handle all of that for you.

You can get the plugin installed with the following steps:

npm add -D @vitejs/plugin-legacy
npm add -D terser // is used by plugin-legacy

Then you simply enable the plugin and configure the browser support that you need for certain televisions. Certain functionality will not be available because of some requirements integral to Lightning 3, but you should be able to get as low as ~Chrome 38.

// vite.config.js
import legacy from '@vitejs/plugin-legacy'

export default {
plugins: [
legacy({
targets: ['Chrome 38'],
}),
],
}

After integrating the plugin, you can execute the build steps as usual — and you have a new dist folder with the correct javascript version. Ready for deploying to actual TVs!

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 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 3/Blits 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.

--

--

Matthijs Langendijk
Matthijs Langendijk

Written by Matthijs Langendijk

Developer from the Netherlands. Working as a Solution Architect at Triple. www.linkedin.com/in/matthijs-langendijk/

Responses (4)