top

Essentials for Beginner

Essentials for developing application on Samsung TV Tizen platform

Overview

This document is for SW developers who are planning to develop application on Samsung TV for Tizen platform.

This document is clearly dedicated for people with experiences in developing web application. To understand Tizen platform and develop web application, please refer tizen.org first.

And furthermore, this document builds on VOCs of whole development cycle and contains things which you can miss due to enumerative information.

This document includes installation of Samsung TV SDK, the structure of application, features of TV, helpful functions and useful APIs. In addition, it helps improving application performance and releasing of “Apps”. Therefore, you can nicely develop Samsung TV applications and easily release them.

Please note that some contents may not be latest. We strongly recommend checking the reference URLs provided in each chapter for the most actual information.

Getting Started

Installation of TV SDK

  • To develop application, you need to install SDK. You can download SDK on Download.

  • To install and use SDK, conditions required are:

    • SDK IDE requires Java Development Kit in version 1.8 or higher. Please install JDK.

    • Because emulator runs on virtual machine, you can’t use it in the following condition. (It is OK to use bootcamp.)

    Not Supported Virtualization Programs
    Remote Desktop
    Virtual Box
    VMWare
    Parallels(Mac PC)
  • If something is wrong and you can’t use your SDK, please post your questions on Community

Creating Certificates

All applications must be signed with certificate. It is used to identify application developer and protect applications from mixing and misusing. It is created by SDK installed on each PC. Please refer to Creating Certificates.

Important

After creating your author certificate, please be careful not to lose it. This is the unique proof for certifying application developer. For this reason, if you lose it, you can’t pass the process of Application Pre-Test. Ultimately you can’t version up your application.

Creating New Project

If SDK is installed successfully, you need creating new project. Please refer to Creating TV Application.
There are 4 ways to create a new project.

  • Basic
    It is the type of a sample application. You can figure out the structure of web application, key interaction and etc. We recommend checking and analyzing this application before you start developing your own one.

  • CAPH
    It is a project based on CAPH which is Web UI Framework offered from Samsung TV. On the following site, you can learn about CAPH.

  • Empty
    It is an empty project.

  • jQuery Mobile
    It is a project based on jQuery Mobile. You can refer to jQuery Mobile.

Using Emulator

  • Even if you have no Samsung TV for Tizen platform, you can run application by using emulator. Please note that emulator should run first before running application. It is different from other platforms (e.g. Android). You can refer to TV Emulator.

  • Run “Emulator Manager” on the bottom left side of an IDE.

  • After clicking “Create” > “Next” > “Next” > “HW Support”, check the values of CPU VT and GPU fields on the right. If these values are “OFF” or “Disable”, you can’t use emulator.
    If it is “Disable”, install Intel HAXM
    If it is “OFF”, turn on with clicking the button.

  • After clicking “Finish”, click ▶️ "Launch" for running emulator.

  • For running an app, on “Project Explorer” of IDE, open “Context Menu” of the project to want running.

  • Click “Run As” > “1 Tizen Web Application” to run the application.

  • If you click “Debug As”, you can use emulator with web inspector.

  • On the right of emulator, virtual remote controller can be used as real TV remote controller. However, “POINTER” of that isn’t supported. Instead, you can just use the mouse of your PC.

  • If you open “Context Menu” of emulator, you can control the size of emulator and etc.
    At “Advanced”, you can change the kind of remote controller or take screen shot.
    At “Control Panel”, you can manually make specific situations. You can make network disconnection, virtually access USB memory or change the kind of application server.

  • If entering “Menu” > “System” > “Accessibility” > “Caption”, you can set something about caption.

Differences between Emulator and Simulator for Usage

  • For usage, if you select emulator or simulator, it will help you develop efficiently. The following is differences between emulator and simulator.

    - Emulator Simulator
    Describe UI 🔵 🔵 (Faster)
    Support APIs 🔵 🔺 (Return value is dummy)
  • In case of developing UI, you can use simulator. After modifying HTML, CSS and etc files, you can check the UI of application lightly and quickly with clicking “Reload”.
    Please refer to TV Simulator.

  • In case of developing functions(APIs), you can use emulator. Emulator supports most of APIs and simulator doesn’t guarantee the result of APIs.

Structure of Application

Tizen Web application consists of HTML, CSS, JS and “config.xml”. (Please check basic type project.)

“config.xml” has following items. (Please open “config.xml” and check “Source” Tab.)

  • Application ID / Package: It is the unique ID and Package of application. Package type is {Random 10 Characters} and ID type is {Package}.{Project Name}. It is automatically created when project is created.

    <tizen:application id='{Package}.{Project Name}' ... />
    
  • Application version: It is version information of application. Version type is {0-255}.{0-255}.{0-65535}.

    <widget … version='{0-255}.{0-255}.{0-65535}' ... />
    
  • Application icon: It is the icon of application which displays on emulator. It consists of the path of icon image.

    <icon src='Icon Path' />
    
  • HTML starting point: It consists of the path of HTML File to load first when running application. By default, it is the path of “index.html” file located in the root directory, but you can change it to any HTML file within application.

    <content src='HTML Path' />
    
  • Privilege: Because of Tizen Privilege policy, sensitive APIs of Tizen need privilege declaration. Also, sensitive APIs of Samsung TV for Tizen platform for need it.

    <tizen privilege name='http://tizen.org/privilege/Privilege Name' />
    <tizen privilege name='http://developer.samsung.com/privilege/Privilege Name' />
    

Features of Application for Samsung TV for Tizen Platform

  • Using remote controller
    TV application should support to interact remotly with user because it is too far from user to TV in comparison with mobile.

  • UI / UX requirements
    TV UI/ UX is simpler as compare to mobile,. For this reason, input process should be minimized and you should consider UI/UX. You can learn more about UX on Design Principles.

  • Application resolution
    On Samsung UHD TV, the standard of application resolution is 1920x1080px and the ratio of same is 16:9. (In case Samsung FHD TV, it is 1280x720px.)
    Even if resolution is different from the standard, the ratio should be kept constant. If you keep the ration fixed, whitespace and scrollbars will not appear on screen when the application is scaled up or down.

  • Common Features
    Application for Tizen Platform Samsung TV has most of the features which general web application has. You can use web standard functions: mouse, video tag, animation, VisibilityChange event and etc.
    In addition, you can use Tizen Web Device APIs and Samsung Product APIs supported by Samsung TV. You can learn more about APIs on API Reference

  • Supported TLS / SSL version
    Between web browsers and web servers, to transmit and receive encrypted information, Samsung TV supports TLS(Transport Layer Security).
    The version of TLS supported is 1.0/1.1/1.2. (SSL(Secure Sockets Layer) is not supported.)

Developing Application

Controlling Key

As mentioned in Features of Application for Samsung TV for Tizen Platform, TV application should support to interact remotly.
Please refer to User Interaction.

Setting config.xml for Application with Various Functions

  • Using network
    According to the W3C Access Requests Policy (WARP), you cannot access network resources by default.
    Please refer to Defining External Access Policies in the Policy Tab on Setting Project Properties.

  • Adding privilege
    As mentioned in Structure of Application, to use sensitive APIs, you should add privilege.
    Please refer to Security and API Privileges and Setting config.xml for TV for Samsung TV.

  • Adding meta data
    For applying some features, you should add meta data. Please refer to Setting config.xml for TV.

  • Prelaunching
    By making that platform previously loads application in background before running the application, you can improve initial application performance.
    You can refer to Prelaunching.

  • Multitasking
    During running application, users may switch to another application or TV channel. In this case, the application will be hidden.
    You can refer to Multitasking.

  • Multi Link Screen
    With dividing screen by 2, you can run multiple applications on 2015 Samsung TV. The following picture is the example of MLS function. The left side is a TV channel screen and the right side is an app.

    If you don’t want to support, you can declare as follows. Default value is true.

    <tizen:metadata key='http://samsung.com/tv/metadata/multiscreen.support' value='false' />
    
  • Pointing device function (mouse function)
    By default, application supports interaction by pointing devices.
    However, if you don’t want to support it, you can add as follows. Default value is enable.

    <tizen:setting pointing-device-support='disable' />
    

APIs for VOD Service

  • There are two ways to play VODs on application.

    • One way is using video tag which is HTML5 standard element.

    • Another way is using webapis.avplay which is product APIs supported by Samsung TV.

    The following is explanations about two ways and other functions to helpfully use in VODs service application.

  • video Element
    video element makes VODs playing easy by HTML5 standard element.
    If you can be enough to develop by using it only, we recommend to use it rather than webapis.avplay.
    Please refer to Using video Element.

  • webapis.avplay
    If you want to play VOD with several technologies such as DRM, you can use webapis.avplay.
    Please refer to Using AVPlay.

  • webapis.appcommon.setScreenSaver
    Screen saver is shown to prevent screen from burning when screen displays a still image for pre-set duration time.
    And when there is no any user input on application,
    screen saver is also shown because screen is regarded as displaying a still image.
    Please refer to Setting Screen Saver.

  • Controlling volume
    To control volume on playing VODs, if you use the volume key of remote controller, you can just use it without registering key. In this case, because platform handles the key, you can use it as the original role of the key. If you want to use Tizen API, please refer to APIs for TV Service.

  • “Play/Pause” key
    There is Play/Pause key in Smart Controller. This key is combined play key with pause key. Its “KeyName” is MediaPlayPause and “KeyCode” is 10252. VOD service applications must handle this key to toggle between play and pause mode.

APIs for TV Service

  • tizen.tvwindow
    By using Tizen APIs, you can develop PiP(Picture in Picture). TV channel screen or external inputs can be shown on application by setting source.
    As follows, you can use the show API of tvwindow. Please refer to Implementing PiP

    tizen.tvwindow.show(function(){}, null, ['0', '0', '50%', '50%'], 'MAIN');
    
  • tizen.tvchannel
    When channel screen is shown, you can just use the channel key of remote controller without registering key. If you want to use Tizen API, you can control channel which is from the getChannelList API of tvchannel. Please refer to TVChannel API.

    tizen.tvchannel.getChannelList(
    	function(channelList){
    		...
    	},
    	null, 'ALL', 0, 10
    );
    
    tizen.tvchannel.tune(
    	{
    		major:channelList[0].major
    	},
    	function(){
    		...
    	}
    );
    
  • tizen.tvaudiocontrol
    In case of volume, you use it as mentioned APIs for TV Service or tvaudiocontrol API. And then you can control volume or mute status. The following is the guide of this.

    tizen.tvaudiocontrol.setMute(true);
    tizen.tvaudiocontrol.setVolume(10);
    

Other Instructions & Functions

  • WebAPI
    WebAPI, the product API of Samsung TV is used to get the information of platform, set subtitle, play VODs and etc. It can offer firmware version, DUID, ModelCode, CaptionChange and some APIs of webapis.avplay as mentioned above. You can refer to API Reference.

  • IME(Input Method Editor)
    If input or textarea element is focused, IME (virtual keyboard) is shown.
    (If you connect external keyboard and click any character key, IME is automatically hidden.)
    Please refer to Keyboard / IME.

  • visibilitychange event
    visibilitychange event is fired when application is shown or hidden. You can handle each operation by registering this event in an app. In this event callback, you can check whether an application is shown or hidden. The following is how it is implemented.

    document.addEventListener(
    	'visibilitychange',
    	function() {
    		if(document.hidden) {
    			...
    		}
    		else {
    			...
    		}
    	}
    );
    
  • viewport
    As mentioned in Features of Application for Samsung TV for Tizen Platform, the standard of application resolution is 1920x1080px on Samsung UHD TV. (In case Samsung FHD TV, it is 1280x720px.)
    If you create smaller or bigger application than the standard, you can scale up and down size of application by using viewport meta tag.

    Please refer to Application Resolution.

  • iframe Element
    You can use iframe for inserting remote page.
    Because it is web standard, you can get more information on iframe Element.

    <iframe width='960px' height='540' src='https://www.youtube.com/embed/7xBT-UDAHX8'></iframe>
    

    The following is limitations fot using iframe. Please note that.

    • For sandbox attributes, only 4 attributes are available. allow-same-origin, allow-scripts, allow-forms, allow-top-navigation

    • If using Tizen and Samsung Porduct APIs on iframe, it doesn’t work.

    • “Frame Flattening” of Tizen mobile is not applied to TV.

    • SDK Emulator have bug on header value of iframe networking, so iframe for remote source doesn’t work properly as expected.

Improving Application Performance

  • This chapter contains how to start an application quickly, optimize JS and improve performance while application runs. You can expect excellent performance application, if you follow this.

  • JavaScript basic tips

    • We recommend using local variables instead of global variables. If you store the value of global variables in local variables, you can improve processing performance.

      var doc = document;
      var a = doc.getElementById('aaa');
      var b = doc.getElementById('bbb');
      
    • If frequently used HTML elements should be assigned to variables, you can improve processing performance.

      var trash = document.getElementById('trash');
      var forms = document.getElementsByTagName('form');
      
    • for in loops and with statements are not recommended.

    • Closure is very useful, but it is one of causes for reducing performance. We recommend using it only where necessary.

  • Improving application launch speed

    • To reduce initial start time, it is important to minimize the number of JS files loaded in HTML on application launch. If you don’t load files which are unnecessary for first screen, you can reduce time for showing first screen.

    • While communicating with servers or loading JS files, please display the background of first screen and then fill all contents brick by brick. If so, users can feel less stuffy. If you make the speed of loading images fast, the speed of loading application looks quick.

    • Minifying JavaScript files can make to reduce loading time.

    • If using Image Lazy Loading, you can avoid loading images which will not be shown on screen. If so, you can reduce loading time. You can easily develop by using jQuery as follows. You can refer to Image Lazy Loading.

      <script type='text/JavaScript' src='jquery.js'></script>
      <script type='text/JavaScript' src='jquery.lazyload.js'></script>
      <script>
      	function onLoad() {
      		$('img.lazy').lazyload();
      	}
      </script>
      
      <body>
      	<img class='lazy' data-original='img/example.jpg' width='765' height='574'>
      
    • You need to reduce total time spent on communication with server as much as possible. To achieve this, it is important to start sending requests as soon as possible and process independent data in parallel communications.

  • Improving performance during running application

    • You can improve performance as changing CSS classes instead of the changing style of an HTMLElement.

      .elm {
      	background-color: #fff;
      	padding-left: 0px;
      }
      
      <div class='elm'>...</div>
      
    • You can improve rendering performance by using GPU accelerator. Simply changing top and left value will be occurred reflow. If you use -webkit-transform, it will be renderd by GPU accelerator.

      @-webkit-keyframes 'move' {
      		from {-webkit-transform:translateX(0px);}
      		to {-webkit-transform:translateX(200px);}
      }
      

Releasing Application

Procedure of Release

After completing your application development, you can publish your application on “Apps”. To publish, the following procedure is required.
Please refer to Distribute.

  • Visit Seller Office site and sign up.
    Seller Office is system on which you can accomplish whole process for releasing application.

  • Select sequentially “Application Registration” and “Samsung Tizen TV SDK”.

  • Fill in an application name and check availability.

  • Fill in Basic Information: developer information, application information, country for release and etc.

  • Fill in Test Information: TV model for release, application document and etc.

  • Progress Pre-Test: Refer to Application Pre-Test.

  • Complete to register the application.

  • After checking whether your application is proper, you can confirm your application on TV.

Materials for Register Application

  • As preparing the below things, you can easily progress registering your application.

    - Application Code Application Picture
    Count 1 1
    Size - 1280x720px or 1920x1080px
    Format WGT JPG
    Max Volume - 500 KB

    Application icon is defferent from year.

    Application Icon 2015 2016
    Count 1 2 (Foreground / Background)
    Size 512x423px 1920x1080px / 1920x1080px
    Format JPG, PNG PNG / JPG, PNG
    Max Volume 300 KB 300 KB
  • Also, you need to prepare application name and description in the language of each country for releasing.

Application Pre-Test

  • After registering your application information and application code, system progresses Pre-Test. It essentially checks whether required information are missed and it has security issues and common defects. The following things are the list of checking during Pre-Test. If you don’t keep the rules, Pre-Test will be failed. In such case, you should review and fix problems and resubmit your application code.
  • Check file to submitted

    File Check
    Format WGT
    Name No special characters except for underscore (_).
    Below 100 Bytes
    Compression ZIP (Able to decompress)
  • Check “config.xml”

    config.xml Check
    Mandatory items “config.xml” File
    application ID
    application Version
    Feature
    Application ID For new application, check if your application ID is not used by other applications.
    For version up, check if the application ID is same as previous one.
    Application Version Check if format is {0-255}.{0-255}.{0-65535}
    For version up, check if the version is higher than previous one.
    Required_version Check if format is {number}.{number}
  • Check “author-signature.xml”

    author-signature.xml Check
    Mandatory items “author-signature.xml” File
    Author Certificate For new application, check if the certificate is proper format.
    For version up, check if the author is same as previous one.

Completing

  • After passing Pre-Test and completing your application register, our system starts real an application test. If there are no defects, your application is released on “Apps”. Then you can check your application on TVs.

  • If your application has defects, you should review and fix it. Then you should resubmit new version application. Otherwise the application will not be published. The detailed defect list can be found on Seller Office. On “Applications” menu, click “Defect Resolution”.

  • For version up, you can similarly process with registering application. On “Applications” menu, click “Management” and then click the application. you can process to upgrade your application by clicking “Version Up” on “Application Information”.

  • In case of any questions about release process, defects or system features, you can contect managers on Seller Office. On “Support” menu, click “1:1 Q&A”.