top

Quick-start Guide

This topic is an introduction to developing Web applications for Samsung TV. It describes how to get started with the Samsung TV SDK, the characteristics and structure of TV Web applications, and some useful APIs and features. It also includes tips on how to optimize and test your application, and how to submit it for publishing.

This essentials topic is intended for developers with experience in creating Web applications. If you have not developed a Tizen Web application before, first familiarize yourself with Tizen Developers.

When developing a Web application for a Samsung TV, pay attention to the following application characteristics:

  • Remote control functionality
    The remote control is the main way for users to interact with the TV. For more information, see User Interaction.

  • Simple UI
    The TV has a simpler user interface (UI) than a mobile device. You must consider the user experience when designing the UI. For more information, see Design Principles.

  • Scalable application resolution
    On Samsung TV, the screen aspect ratio is 16:9. For the UHD TV model groups, the standard application resolution is 1920x1080 px, and for the FHD TV model groups, it is 1280x720 px.
    To prevent whitespace and scroll bars from appearing when the application screen is scaled, keep the aspect ratio at 16:9 even when the application resolution is different from the standard.

  • Common Web application features
    TV Web applications can have most of the same features as Web applications for other devices. You can use Web standard functions, such as mouse support, video elements, animations, and visibility change notifications. You can also use Tizen Web Device APIs and Samsung Product APIs supported by Samsung TV. For more information, see the API Reference.

  • TLS support
    To transmit encrypted information between Web browsers and Web servers, Samsung TV supports TLS (Transport Layer Security) versions 1.0, 1.1, and 1.2. SSL (Secure Sockets Layer) is not supported.

  • Multitasking
    When the user switches from your application to another application or TV channel, your application must save its current state to RAM and enter the hidden state. For more information, see Multitasking.

Getting Started

To begin application development with the Samsung TV SDK:

  • Install the Samsung TV SDK.

    Note

    The TV emulator runs as a virtual machine, so it cannot be used within the following virtualization environments:

    • Remote Desktop
    • Virtual Box
    • VMWare
    • Parallels (macOS)

    Using Boot Camp does not affect the emulator.

  • Create a certificate profile.
    According to the Tizen policy, all applications must be signed with valid certificates before they can be installed or run. The signature verifies the source of the application and makes sure it has not been tampered with since its publication.

    Important

    Keep your certificates backed up in a safe location. When you update your published applications, the update must be signed with the same author certificate as the original application. If the applications are signed with different author certificates, the update can be recognized as a different application and not an update.

  • Create a project.
    You can select from various predefined templates.

If you have questions about using the SDK, share them in the community forum.

Developing an Application

This section introduces the structure of a TV Web application, its configuration file, and some useful APIs and features for implementing TV functionalities.

Application Structure and Configuration

A Tizen Web application consists of HTML, CSS, and JS files, and a “config.xml” file.

Figure 1. Application structure

Figure 1. Application structure

The “config.xml” file contains the following information:

  • Application ID
    The Samsung TV SDK automatically creates an application ID, which uniquely identifies the application within the package.

    <tizen:application id='{Package}.{Project Name}' ... />
    
  • Application version
    The application version format is “x.y.z”.

    <widget … version='{0-255}.{0-255}.{0-65535}' ... />
    
  • Application icon
    File path for a launcher icon.

    <icon src='Icon Path' />
    
  • HTML content
    File path for the start-up file of the Web application. By default, it is the “index.html” file in the root directory.

    <content src='HTML Path' />
    
  • Privileges
    Tizen and Samsung TV APIs that handle platform and user-sensitive data require privileges that must be declared before the APIs can be used.

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

Other configuration information in the “config.xml” file includes the following:

  • Network access policy
    According to the W3C Access Requests Policy (WARP), you cannot access network resources by default.
    For more information, see Defining External Access Policies in the Policy Tab.

  • Application privileges
    To use APIs that handle sensitive data, you must declare the required privileges. For more information, see Security and API Privileges and Configuring TV Applications.

  • Meta data
    Some features are implemented by adding values to the metadata element. For more information, see Meta Data.

  • Prelaunching
    You can improve application launch time by launching the application in the background when the TV is switched on. For more information, see Prelaunching.

  • Mouse support
    Interaction with the application using a mouse, is enabled by default. If you want to disable it for your application, add the following line to the “config.xml” file:

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

APIs for VOD Services

You can implement VOD playback in 2 ways:

  • Using video elements
    You can use the HTML5 standard video element. For more information, see Using Video Elements.

  • Using the AVPlay API
    VOD playback can be implemented using the AVPlay API, which has additional features, such as support for DRM technologies. For more information, see Using AVPlay.

The following remote control keys are needed to control VOD playback:

  • Volume control
    To control VOD playback volume levels, you can use the volume keys of the remote control without registering them, because they are handled at the platform level. Volume control can also be implemented using the Tizen API. For more information, see TVAudioControl API.

  • “Play/Pause” key
    The Smart Control “Play/Pause” key combines the functions of the “Play” and the “Pause” keys. Its KeyName is MediaPlayPause and the KeyCode is “10252”. VOD service applications must handle this key to toggle between play and pause modes.

APIs for TV Service

The following are Tizen APIs that are useful for TV service applications:

  • TVWindow API
    You can use Tizen Web Device APIs to show the TV channel screen or external inputs in an application. For example, you can implement picture-in-picture (PiP) using the show() function of the TVWindow API:

    tizen.tvwindow.show(function(){}, null, ['0', '0', '50%', '50%'], 'MAIN');
    

    For more information, see Implementing PiP.

  • TVChannel API
    When the channel screen is shown, you can simply use the remote controller channel keys without registering the keys. You can also control channel changes and retrieve TV program information using the TVChannel API. For example, you can use the getChannelList() function to retrieve the channel list:

    tizen.tvchannel.getChannelList(
      function(channelList){
       ...
     },
     null, 'ALL', 0, 10
    );
    
    tizen.tvchannel.tune(
     {
       major:channelList[0].major
     },
     function(){
       ...
     }
    );
    
  • TVAudioControl API
    You can control the volume level or mute status of the TV, using the TVAudioControl API:

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

Other Useful Features

  • WebAPI
    WebAPI is a Samsung Product API that has functionalities, such as retrieving information about the device and platform, displaying subtitles, and playing VODs. For more information, see the API Reference.

  • Screensaver
    To prevent screen burn, the screensaver is shown after a defined amount of time, if the TV screen has been displaying a still image or if there has been no user input. For more information, see Setting Screensaver.

  • Input method editor (IME)
    When an input or textarea element is focused, the virtual keyboard is shown. The virtual keyboard is automatically hidden when a key on a connected external keyboard is pressed. For more information, see Keyboard / IME.

  • Visibility change notifications
    You can receive notifications when an application is shown or hidden by registering a callback for the visibilitychange event:

    document.addEventListener(
      'visibilitychange',
      function() {
        if (document.hidden) {
          ...
        }
        else {
          ...
        }
      }
    );
    
  • Viewport scaling
    If you create an application for resolutions different than the standard resolutions, you can scale the resolution up or down, using the viewport meta element. For more information, see Managing Screen Resolution.

  • iframe elements
    You can insert remote pages into your application using the Web standard iframe element. For more information, see the W3C recommendation for HTML5.

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

When using iframe elements in TV applications, the following limitations apply:

  • Only the following sandbox attributes are available: allow-same-origin, allow-scripts, allow-forms, allow-top-navigation
  • Tizen and Samsung Product APIs cannot be used in iframe elements.
  • The “frame flattening” feature, supported in Tizen mobile Web applications, is not supported in TV applications.
  • On the emulator, iframe elements for remote sources do not work as expected.

Improving Application Performance

To improve the performance of your application, learn how to optimize your JavaScript code, start the application quickly, and run the application efficiently.

  • Basic JavaScript tips:

    • Use local variables instead of global variables. You can improve processing performance by storing the value of global variables in local variables.
    var doc = document;
    var a = doc.getElementById('aaa');
    var b = doc.getElementById('bbb');
    
    • Improve processing performance by assigning frequently-used HTML elements to variables:
    var trash = document.getElementById('trash');
    var forms = document.getElementsByTagName('form');
    
    • Do not use for in loops and with statements.

    • Closure is very useful, but can reduce performance. Use it only when necessary.

  • To improve application launch speed:

    • Minimize the number of JS files loaded in HTML on application launch. You can reduce the time it takes to load the first screen by loading only the files required for it.

    • While communicating with servers or loading JS files, first display the background of the first screen, then load the content incrementally. By loading images quickly, the application appears to launch faster and more smoothly.

    • Reduce loading time by minifying JavaScript files.

    • Use Lazy Load to avoid loading images which are not shown on screen, reducing loading time. Lazy Load can be implemented using jQuery:

      <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'>
      

      For more information, see Lazy Load.

    • Reduce the total time spent communicating with the server as much as possible. Start sending requests as soon as possible and process independent data in parallel communications.

  • To improve performance of the running application:

    • Change CSS classes instead of changing HTML element styles:
    .elm {
      background-color: #fff;
      padding-left: 0px;
    }
    
    <div class='elm'>...</div>
    
    • Use GPU acceleration to improve rendering performance. Simply changing the top and left value causes reflow. If you use -webkit-transform, it is rendered through GPU acceleration.
    @-webkit-keyframes 'move' {
      from {-webkit-transform:translateX(0px);}
      to {-webkit-transform:translateX(200px);}
    }
    

Testing the Application

The Samsung TV SDK provides the TV simulator and TV emulator tools to help you test your application during development:

  • TV Simulator
    The TV simulator is a light-weight tool that simulates Samsung TV APIs using a JavaScript backend. The simulator is useful when quick prototype development is required, such as when developing the UI. You can modify the HTML5, JS, and CSS code, and quickly reload the simulator to view your changes.
    API support on the simulator is limited; the simulator does not support any features that have strict dependencies on TV hardware or core Tizen modules. Some API functions return dummy values.
    For more information, see TV Simulator.

  • TV Emulator
    The TV emulator is a tool that provides an environment similar to a real device. If you do not have the real device, you can test on a virtual device with similar features. The emulator supports most of the device APIs, so it is useful when implementing the features of your application.
    For more information, see TV Emulator.

Publishing the Application

After completing your application development, you can publish your application on Samsung Apps TV. For more information, see Distribute.

To publish a new application:

  1. Prepare the following files before submitting your application.
    Table 1. Files required for application registration in TV Seller Office
    ElementDimensionsFormatMaximum Size
    Application package-WGT-
    Application image1280x720 px or 1920x1080 pxJPG 500 KB
    Application icons2015 TV models512x423 pxJPG, PNG300 KB
    2016 and later TV modelsForeground1920x1080 pxPNG
    BackgroundJPG, PNG

    You must also prepare the application name and description in the language of each country you want to release the application in.

  2. Go to the Samsung Apps TV Seller Office and log in to your account.

    The application publishing process is managed through the TV Seller Office.

  3. Select "Application Registration > Samsung Tizen TV SDK".
  4. Enter the required information:
    • Application name

      The availability of the application name is checked.

    • Basic Information, such as developer information, application information, and country for release
    • Test Information, such as TV model groups for release and application files
  5. Complete the pre-test.

    The pre-test checks the application package to make sure that all required information is present, and also checks for common security issues and defects. Your application must pass the pre-test before you can proceed with registration.

    The following table lists the items checked by the pre-test.

    Table 2. Pre-test check items
    FileItemRequirement
    Application packageFormatWGT
    NameNo special characters except underscore (_)
    Length below 100 bytes
    CompressionZIP (decompressible)
    "config.xml" fileApplication IDNew application: Application ID is unique
    Application update: Application ID is the same as previous version
    Application versionFormat is {0-255}.{0-255}.{0-65535}
    Application update: Version number is higher than previous version
    required_versionFormat is {number}.{number}
    "author-signature.xml" fileAuthor certificateNew application: Certificate is valid
    Application update: Certificate is the same as in previous version
  6. Register the application.

    After passing the pre-test and completing the application registration, the Samsung Apps TV Seller Office tests your application:

    • If there are no defects, your application is published on Samsung Apps TV.
    • If your application has defects, you must correct them and submit a new version of your application. At the Samsung Apps TV Seller Office, select "Applications > Defect Resolution" to view the detailed defect list.

To update your application:

  1. At the Samsung Apps TV Seller Office, go to “Applications > Management” and select the application you want to update.
  2. In the “Application Information” tab, click “Version Up”.
    The process is similar to publishing a new application.
    Figure 2. App Information tab

    Figure 2. App Information tab

If you have questions about the release process, defects, or system features, you can contact the TV Seller Office by selecting “Support > 1:1 Q&A”.