The Ultimate Guide to Samsung Tizen TV Web Development

Update January 2021: I have been receiving a lot of feedback on this article and some of the readers have reached out to me for advice, and I appreciate this a lot. Before I address the biggest question that I have received I would like to note that I am no longer working in this domain and therefore want to mark this article as being legacy and not maintained by the original author. If you have any questions, I would refer you to the experts in the domain, namely Norigin Media rather than contacting me directly.

The biggest question that has been asked is “how do I get a ReactJS app running”. The answer is surprising simple. React produces a build, which is the artefact of the application, this is the same as to whether or not you use a browser or not. In React, this build is normally included in an index.html file in the form of some JavaScript (normally <some abstractly named build file>.js). Instead of that build being included only in that HTML file native to React, include it in a file that in a HTML file in your Tizen app. This does mean, however, that you need to have some way of hosting that build file so that your Tizen app can have access to that resource, most likely via the internet.

I am a frontend developer at Norigin Media and I’m part of the team currently building our streaming apps SDK. Having built apps for many types of TVs before, our team has always found Samsung’s Tizen Smart TV to be particularly interesting to work on. If you are reading this and have worked with Tizen before then you’ve probably had some similar experiences.

Samsung Tizen holds a 23% share of the world TV market, coming only second to the coveted Android TV making it a prevalent operating system, especially in the Nordic/Scandinavian region with many people looking to take advantage of the hardware provided by their TV such as Tizen’s speech recognition from the remote control as well as some neat native tricks and integrations.

This article is designed to be a sort of condensed Wiki, some of it may also be just bullet points with things to note when working on a particular topic but the major point is to give you an explanation to problems. I’ll outline as many errors as possible and give some solutions that have worked for us in the past as well as links to some actually useful documentation from Samsung (I didn’t believe it existed either).

Background of Tizen

Tizen was released in 2015 after the Legacy Samsung TV Platform (formally Orsay) was deprecated. This brought a lot of challenges to TV developers which now must support two (very different) platforms as well as relearn another API for supporting them. Now, almost four years later, we have tools for dealing with this split as the Orsay market slowly begins to die out (check out TOAST API).

Getting Started with Tizen Studio

Tizen Studio is the IDE used for Tizen TV development. This is where you can connect to TVs, add your splash screen, create certificates, sign packages and run your app on the connected devices.

The IDE is based on Eclipse and therefore can be a bit tedious to run. A lot of the problems developers face when making Tizen applications can stem from some quirks in Tizen Studio. In this article, we will try and address some of the weird things that can happen when using this IDE.

For a detailed explanation of installing Tizen Studio check this out. https://developer.tizen.org/development/tizen-studio/download/installing-tizen-studio

Once you have it installed, you will be brought to the Package Manager. The package manager is where you will need to download your packages for Tizen Studio. For TV development, I would recommend downloading all the SDK packages as well as all the TV related packages. Then switch to the Extensions tab at the top of the Package Manager and also download all the TV extensions. Once that is done, you can close the Package Manager and you will be prompted to open Tizen Studio, why you can go ahead and do!

Importing/creating your project

Now that you have Tizen Studio up and ready, you need to import a project. To do this go to File > Import and >Tizen Project > Find Project locally > Import.

If you don’t already have a project, fear not. You can also create one: File > New > Tizen Project > Template. In the template screen, make sure you select the Custom section and in the drop down select TV-samsung 4.0.

Then on the next screen you should select the Web Application Option.

Once that is done, then select Basic Project on the next screen and name your project. Then you’re ready to go.

Connecting to your TV

Before connecting to your TV, you need to have a certificate. In order to create a certificate, you need to go to the Certificate Manager (in Tizen Studio) by going to Tools > Certificate Manager. Creating a certificate can be a bit of a pain but Samsung actually has some pretty good docs on it at this link.

Once you have your certificate, you then need to set up your TV to be able to connect to it. All Tizen TVs have the same flow for this. The first thing you should do is to make sure that you are on the same network as your TV. You also need to make sure there are no firewalls blocking you from making a connection to your TV. It is also worth noting that more often than not a wired connection seems to be more reliable than a wireless one, so make sure your TV is set up on a wired connection, if at all possible.

Once you’re both on the same network, you need to get your IPv4 address. With your IPv4 address in hand go to your TV and go to the Apps section (Found in the main menu when the home button is pressed) and then type in (using the remote or a keyboard) 12345. Once you have typed this a dialog will appear which will have two settings fields.

The first field will be a toggle for enabling Developer Mode — turn this on.

The second field is where you will need to enter your IP address. Enter this, and once it is done, select OK. A popup will then appear saying that it is recommended to turn off the TV, this, however, has never actually helped in connecting to the TV, so I tend to not do this.

Now your TV is ready to go. Next thing you need to do is get the IP address of the TV. To get this, you will need to find the Network Status section. The reason I don’t give the exact path to getting to is that it can be slightly different depending on the year of TV you have. It is either in Network Settings or it will be in the General settings of your TV.

Once you have the IP address of the TV,

you will need to go back to Tizen Studio and go to Tools > Device Manager. The Device Manager is where we, yes, manage the devices which our app will be running on. To add a device:

Click one the button circled in red in the above screenshot. This will then present you with the following popup:

Then click the + in the top left corner and begin to fill in the fields using the name of the device (just for display purposes for you), the IP you got from the TV and then leave the port as the default.

Once this is done then click the toggle button in the connection field. If it turns blue then you have successfully connected to the TV! Now simply go back to Tizen studio and right-click on your project in the project explorer and select Run As > Tizen Web Application to run without debug or Debug AS > Tizen Web Application to run with debug. The debugger will automatically display on your screen and you’re good to go, just get editing your application.

If you unfortunately got the following:

Then you have some options (In this example, I knew this IP wouldn’t work just to get the popup to show):

• You can turn off and on your WIFI connection if you’re using wireless. If you’re using wireless then I would recommend turning and then off again your WIFI connection, if you have one.
• You should repeat the steps above, this could be a typo in an IP address somewhere, which is common.
• Make sure you have set development mode to true in the popup that displays after typing 12345 in the app section on the TV.
• Ensure that you are on the same network as your TV and that you used the local network (Private) IP address and not the Public IP address.

Seven shades of debugger

Well, at the time of writing this it’s only 4 shades really but seven sounded a lot better. The Tizen debugger on a 2015 Tizen and on a 2018 Tizen are drastically different. You will have less capabilities on the 2015. I will list some of the things worth noting regarding debugging on a Tizen below.

• The debugger isn’t actually the debugger (lol) — It is just a frame which is mirroring the debugger from the TV. This doesn’t really make a lot of difference to you as a developer except for the fact that you won’t be able to add any of your favourite plugins to the debugger. This can be annoying when dealing with Redux state management for example.
• It will just randomly disconnect and crash the app and I’ve found that it happens a lot when back navigation occurs. It won’t happen when you just run the app without debug or from a USB — so just be aware of that and don’t blame all your crashes on it.
• The 2015/2016 debugger can really struggle with navigating to errors on specific lines and this can slow down development, so some healthy try/catch handling in your code can mitigate having to rely on the debugger too much in this scenario.

Running the App from a USB

In order to run your application from a USB key you need to have a Samsung Seller account. This can be obtained by going to this page. Once you have a Samsung Seller account, you can then login to your dashboard.

On the dashboard, you will see in the bottom left a button which looks like this:

Once you’ve clicked on this, a popup will appear (make sure your browser is allowing popups for this site). The popup asks you to upload a .wgt file, so this is what we need to go and create and it’s pretty simple.

To create the .wgt file, go back to Tizen Studio and right-click on your project and select Build Signed Package. This will then create a .wgt file in your project!

Then go back to the USB tool in the browser and upload your newly generated .wgt file. This will then create a .license file and a .tmg file. These two files are what will install the app on your TV.

The final step is to plug in your USB key and create a folder in the home directory of the USB key called ‘userwidget’, drop the two files in there, eject your USB key from your computer and then plug it into your TV. Your TV will then begin to automatically install the app and it will show up in the Downloaded Apps section of the Apps section of your Tizen.

It is worth noting that the installation process will fail if the .license or .tmg file name contains spaces or special characters. This can happen often if you’re installing a lot and your Downloads folder starts to rename the downloaded files (on a Mac YourApp (1).tmg, for example). When you want to replace the app, simply delete the contents of that folder on your USB and add the new .tmg and .license files (you will also see a res folder created by the TV, also delete this).

Useful documentation

• All things player.
• Develop homepage.

Errors and how to solve them

Tizen Studio errors are notoriously cryptic, so here are some of the tactics I have learned from development which I would have been glad to get an explanation of at the start.

• SDB Errors

step SDB shell handle failed

Failed to `step SDB shell handle ‘ls /usr/bin/xwalk-launcher > /tmp/eoinfalconer.deployer 2>&1; echo $? ‘ command` operation

sdb command rejected exception

The best way to handle above errors is to kill Tizen studio and restart. Tizen Studio is using SDB in order to connect to the TVs/devices. I’m sure sure exactly what is going wrong, but this has fixed the problem for me many times.

• Installation Errors

This error is pretty much always to do with your certificate setup:

• Go into Certificate Manager and try to reselect everything you have done and make sure the correct certificate has been selected using the ‘tick’ symbol.
• Not always necessary but sometimes helps if you go to the Device Manager and right-click on the device you are connected to and click Permit to install applications. If you receive a popup saying you have no certificate then you need to maybe make a new certificate and try again.
• Uninstallation Errors

Uninstallation errors generally occur most on the older models (2015 and 2016), although I have seen them on the newer models too. This is generally due to the fact that the TV didn’t have time to or was unable to delete the previous installation of the application to the TV because installing the new one.

The best thing to do here is to always manually delete the application from your TV by going to the application and long-pressing on it. You will then receive a menu in which you can delete the application. Then try and reinstall the application from Tizen Studio.

• Debugger Errors

Probably the worst error to get as sometimes you just need to close absolutely everything. It will basically state that the debugger can’t be opened, even though you have already killed all other debugger instances.

• Make sure you have all instances of the debugger closed.
• Ensure that you only have one debugger open in your instance of the browser of choice (Generally Chrome, for Tizen).

Conclusion & call for questions

This article is designed to be a starting point which we (the Samsung Tizen development community) can build on. If you have any adds/edits or removals for this article, do not hesitate to comment here or get in contact with me at eoin.falconer@noriginmedia.com.