Developing Applications Q&A

This topic provides answers to common questions related to developing Samsung Smart TV applications.

Application Installation

The following questions are related to installing and uninstalling applications.

For security reasons, ".wgt" application package files cannot be installed on a TV through USB.

However, you can use the USB Demo Packaging Tool, which allows you to create a ".tmg" package and license file that can be installed on a TV using a USB removable drive. The USB Demo Packaging Tool is available in the Samsung Apps TV Seller Office.

   #install    #usb    #usb demo packaging tool    #tv device

Consumer Samsung TVs do not support automatic launching for applications installed through USB.

Hotel TVs, however, support this use case. For information on Hotel TVs, see Samsung D Forum B2B Developers.

   #automatic launch    #hotel tv    #usb install

No. All application data is deleted when the application is uninstalled, and cannot be recovered.

   #application data    #uninstall    #reinstall

No. Preinstalled applications cannot be removed.

   #preinstall    #preinstalled application    #remove    #uninstall

Application Testing

The following questions are related to testing applications.

To test your application on a TV, you must use the Tizen Studio IDE. You can also use the USB Demo Packaging Tool, available in the Samsung Apps TV Seller Office.

You can test your application on the emulator without using the IDE. The Tizen Studio Command Line Interface (CLI) provides functionalities for installing, running, and uninstalling applications.

   #emulator    #command line interface    #cli    #tv device

To install and test your application on a TV, you must connect the TV and the Tizen Studio. For more information, see TV Device.

If you do not have access to an actual Samsung Smart TV, you can also test your application in the TV emulator.

   #tv device    #install    #tizen studio

Before connecting a Samsung Smart TV to the Tizen Studio, you must enable Developer Mode on the TV. For more information, see Connecting the TV and SDK.

Note If the TV has the "Samsung Instant On" feature enabled, you must power-cycle the TV (disconnect and reconnect the power source) at the reboot step.

   #developer mode    #tizen studio    #samsung instant on    #tv device

To connect a Smart TV to the Tizen Studio, you must enable Developer Mode on the TV, connect the TV and your computer to the same network, and launch the Remote Device Manager in the Tizen Studio. For more information, see TV Device.

   #tv device    #tizen studio    #connect

Make sure that you have connected the TV and computer to the same network, and enabled Developer Mode on the TV. For more information, see TV Device.

You can also try to connect the TV to the Tizen Studio without using the Remote Device Manager:

On the TV, enable Developer Mode.

In the Windows® command prompt, navigate to your "\tools" directory.

Enter the sdb connect command.

   #tizen studio    #connect    #tv device

The emulator and the TV environments are very similar, but there are some differences at the hardware level. For more information, see Emulator Limitations.

Make sure you perform the final testing of your application on the TV.

   #emulator    #limitations    #tv device    #different result

Applications installed to a TV through the Tizen Studio are uninstalled when the TV is switched off or disconnected from the Tizen Studio. This is the intended platform behavior.

   #tizen studio    #uninstall    #disconnect    #tv device

The TV emulator is a virtual machine that reduces the inconvenience of testing the application on a real device, by providing an environment similar to a real TV. For information about using the emulator, see TV Emulator.

   #emulator    #virtual machine

Prelaunching allows several applications to load in the background when the Samsung TV is switched on. When the user runs a prelaunched application, it launches immediately with no loading time. Prelaunching is supported on the TV emulator. For more information, see Prelaunching Applications.

   #prelaunching    #testing    #background loading

You can test DRM-protected content playback on an actual TV.

To test DRM-protected content playback on the emulator, you must be a member of a partner group. You can obtain the files needed to enable the feature on the emulator by contacting your Samsung Apps TV Seller Office Content Manager.

   #drm    #emulator    #multimedia    #playready    #verimatrix

You can use the Web Inspector to help you optimize your Web applications. It provides a debugging environment, and allows you to inspect the CSS and layout of HTML pages, and monitor resource and network usage.

   #web inspector    #performance    #analyze    #optimize

Select a model based on the media formats you want to support. For information on which TV models are included in each model group, see TV Model Groups.

   #model group    #tv model    #media format

For information about testing hosted applications on a TV, contact your Samsung Apps TV Seller Office Content Manager.

Note To create hosted applications, you must be a member of a Seller Office partner group.

   #hosted application    #cloud based application    #dynamic web page    #redirect application    #tv device

When no applications are running on the TV or emulator, the Web socket connection to the computer closes, disconnecting the Web Inspector. To prevent Web Inspector disconnection:

To install your application on the TV or emulator and launch the Web Inspector, run the application in debug mode from the Tizen Studio.

When the Web Inspector finishes loading, launch a different application from the Smart Hub.

Return to the Smart Hub and launch your application.

The first application remains running but hidden, and prevents the Web Inspector from disconnecting when you close your application.

   #web inspector    #disconnection    #web socket    #multitasking

No. Automated testing is not supported on Samsung TVs.

Additionally, the Automatic Testing Tools provided for Samsung Legacy Platform are no longer supported.

   #automated testing    #automatic testing tool    #samsung legacy platform    #web driver

TV applications do not support generating crash logs. However, you can detect when the application stops or closes unexpectedly, by implementing a software watchdog timer.

   #crash log    #watchdog timer

Yes. To test accessing content from another country or region, connect the TV to the Internet through a VPN.

   #vpn    #geolocation    #geo restricted    #geoblocking

You can view network traffic statistics in the Web Inspector. However, the Web Inspector detects only ordinary Web traffic. It does not detect network traffic from, for example, media playback using the AVPlay API.

   #network traffic    #statistics    #web inspector

The Web Inspector does not work properly with Samsung TVs on later versions of Google Chrome™. You can try using an older Google Chrome™ version.

   #web inspector    #google chrome    #older version

No. For security reasons, the Tizen Studio Dynamic Analyzer is not supported on Samsung TVs.

   #dynamic analyzer    #tizen studio    #memory profiling

No. It is not possible to obtain root access to the TV.

   #root access    #sdb tool

No. The sdb logging feature is not supported on Samsung TVs. It is not possible to retrieve system logs.

   #sdb tool    #system log

This error is related to a certificate issue. Try creating a new certificate profile, making sure you select the distributor certificate privilege level you need, then building the project with the new certificate profile.

   #distributor certificate    #privilege level    #tizen studio    #certificate profile    #error

If you have modified the content of a ".wgt" file after packaging it, it can no longer be installed. You must build the package again through the Tizen Studio.

   #wgt file    #packaging    #tizen studio    #error    #building

Samsung TVs support only Web applications (".wgt" files). They do not support native applications (".tpk" files).

   #tpk file    #native application    #wgt file    #web application

No. Testing by proxy is not supported on Samsung TVs.

   #proxy    #network traffic    #security certificate

No. To test Samsung TV applications, the device must have access to the Tizen and Samsung Product APIs. The Samsung Product API is only available on Samsung devices.

   #samsung product api    #raspberry pi    #hardware

Data and File Handling

The following questions are related to handling data and files on the TV.

You can use the FileSystem API to access external USB storage. For more information, see Handling USB Storages and Managing File Operations.

   #usb storage    #filesystem api

Application data is retained when the TV is switched off or the application is updated. All application data is deleted when the application is uninstalled.

   #application data    #update    #uninstall

When an installed application is updated, the local Web storage on the device is unaffected. The local Web storage data is only deleted when the application is uninstalled.

Note When updating an application test build through the Tizen Studio, the previous build is uninstalled before installing the new build. Consequently, the local Web storage data is deleted.

   #web storage    #uninstall    #tizen studio    #testing

No. The application cache is automatically managed by the platform.

   #application cache

Yes. By storing user login data in local Web storage, you can manage it in the same way as other Web storage data, including deleting it.

   #web storage    #user login data    #uninstall

No. For security reasons, this behavior cannot be modified. If you want to implement additional behavior when a USB storage is connected, use the Filesystem API. For more information, see Handling USB Storages.

   #file browser    #usb storage    #filesystem api

Make sure you have declared the "filesystem.write" privilege in your "config.xml" file. It is required for writing data to storage.

   #privilege    #config xml    #file system write

Device Information and Firmware

The following questions are related to accessing device information and managing device firmware.

On a Samsung Smart TV, you can find the DUID by selecting "Menu > Support > Contact Samsung".

To retrieve the DUID from within your application, use the getDuid() method of the ProductInfo API.

   #duid    #device id    #productinfo api

You can retrieve the TV language setting through the JavaScript navigator.language property.

   #language    #tv setting

The user agent string for Samsung TVs depends on the TV model year.

Table 1. User agent strings for Samsung TVs

Product

User Agent

2017 models

Mozilla/5.0 (SMART-TV; LINUX; Tizen 3.0) AppleWebKit/538.1 (KHTML, like Gecko) Version/3.0 TV Safari/538.1

2016 models

Mozilla/5.0 (SMART-TV; Linux; Tizen 2.4.0) AppleWebKit/538.1 (KHTML, like Gecko) Version/2.4.0 TV Safari/538.1

2015 models

Mozilla/5.0 (SMART-TV; Linux; Tizen 2.3) AppleWebkit/538.1 (KHTML, like Gecko) SamsungBrowser/1.0 TV Safari/538.1

2014 models

Mozilla/5.0 (SMART-TV; X11; Linux armv7l) AppleWebkit/537.42 (KHTML, like Gecko) Safari/537.42

2013 models

Mozilla/5.0 (SMART-TV;X11; Linux i686) AppleWebkit/535.20+ (KHTML, like Gecko) Version/5.0 Safari/535.20+

2012 models

Mozilla/5.0 (SMART-TV; X11; Linux i686) AppleWebKit/534.7 (KHTML, like Gecko) Version/5.0 Safari/534.7

2011 models

Mozilla/5.0 (SmartHub; SMART-TV; U; Linux/SmartTV) AppleWebKit/531.2 (KHTML, like Gecko) Web Browser/1.0 SmartTV Safari/531.2+

For more information, see Retrieving Platform Information.

   #user agent

To find the model code on the TV, in the Smart Hub, select "Settings > Support > About This TV". The model code is a string that specifies various TV characteristics.

The following table shows the information contained in the model code, and its sequence:

Table 1. Model code information

Screen Technology

Region

Screen Size

Model Year

Screen Matrix

Series and Model

"H" (DLP)"K" (OLED)"L" (LCD)"P" (Plasma)"Q" (QLED)"U" (LED)

"A" (Asia)"E" (Europe)"N" (North America)

Size in inches

"E" (2012)"F" (2013)"H" (2014)"J" (2015)"K" (2016)"L" (2017)"M" (2018)

None (FHD)"P" (Plasma)"Q" (QLED)"S" (SUHD)"U" (UHD)

Series and model number

For example, the "UN40MU9000" model code defines a TV with the following characteristics:

LED screen

North America region

40-inch screen

2018 model year

UHD screen matrix

Series 9 model

   #model code

To retrieve the MAC address of a Smart TV, use the getPropertyValue() method of the SystemInfo API with the applicable network adapter property:

For the Ethernet network adapter, use the ETHERNET_NETWORK property.

For the Wi-Fi network adapter, use the WIFI_NETWORK property.

   #ethernet    #wifi    #network adapter    #mac address    #systeminfo api

To retrive the Smart Hub country code, use the getSystemConfig() method of the ProductInfo API with the CONFIG_KEY_SERVICE_COUNTRY key.

   #smart hub    #country code    #productinfo api

To download the latest TV firmware, on the Samsung Web site, find your TV model. On the TV model page, select "User manual & Downloads". The "Upgrade File" contains the latest TV firmware.

   #firmware upgrade    #tv model

No, forcing firmware updates is not supported.

   #firmware update    #force update

No. For security reasons, downgrading the TV firmware is not supported.

   #firmware downgrade

Since 2016 models, to reset the TV to original factory settings, in the Smart Hub, select "Settings > Self Diagnosis > Reset". The reset changes the DUID.

Note The "Settings > Self Diagnosis > Reset Smart Hub" feature removes all Smart Hub and logged-in Samsung Account data from the TV. It does not change the DUID.

   #duid    #reset smart hub    #factory settings    #factory reset    #original settings

It is not possible to detect when the user has clicked the TV power key. However, you can implement application behavior for the following related scenarios:

To implement behavior when the application is closed, use the window.onUnload() event handler.

To implement behavior when the application is hidden, such as when another application is launched, create a listener for the visibilitychange event.

Since 2015 devices, if the user has switched on the "Instant On" TV feature, switching off the TV causes the application to hide, triggering the visibility change event listener.

For more information, see Monitoring Visibility Changes.

   #power key    #visibility change    #close application    #hide application

No. While an application is hidden, it is paused and cannot retrieve any information about the foreground application.

   #foreground application    #hidden    #paused    #background application

No. Retrieving the currently-active TV tuner is not supported, since it depends on the TV broadcaster.

   #tv tuner    #cable tv    #terrestrial tv    #broadcast signal

To retrieve the voice guide status:

On Tizen, check whether the voice guide is enabled using the getMenuValue() method with the TvInfoMenuKey.VOICE_GUIDE_KEY property:

// Returns "true" if voice guide is enabled

webapis.tvinfo.getMenuValue(webapis.tvinfo.TvInfoMenuKey.VOICE_GUIDE_KEY);

On Samsung Legacy Platform, check whether the voice guide is enabled with the IsTTSEngineEnabled property:

// Returns "true" if voice guide is enabled

webapis._plugin("RECOG", "IsTTSEngineEnabled")

   #voice guide    #samsung legacy platform    #tts    #text to speech

Since 2013 TV models, to change the Samsung Apps TV region:

Factory reset and restart the TV.

On the Terms and Conditions page, click the following key sequence on the remote control: "Mute, Back, Volume Up, Channel Up, Mute"

Select the region you want.

   #samsung apps tv    #region change    #app store    #store region

TV hardware is based on mobile technology, but for security reasons, the details are confidential.

   #hardware    #cpu    #processor

Extension Libraries

The following questions are related to implementing additional features with the available extension libraries.

Extension libraries contain additional features which are supported by Samsung Smart TVs. You can use them to further enhance your application.

The available extension libraries include Smart View SDK, Native Client (NaCl), CAPH, and TOAST.

   #library    #feature

The Smart View SDK allows you to integrate Android™ devices, iOS devices, and Web browsers with Samsung TV applications. For more information, see Smart View SDK.

Smart View-enabled applications are registered in the Samsung Apps TV Seller Office separately from other Samsung TV applications. For more information, see Smart View Enabled App Registration.

   #smart view sdk    #registration    #publication    #seller office

The Smart View SDK does not support smart watch applications.

However, you can use the Websocket API to implement communication between various Tizen devices, such as Samsung Smart TVs and Samsung Gear smart watches.

   #smart view sdk    #smart watch    #samsung gear    #websocket

To restore a hidden application to the foreground using the Smart View SDK, use the start(Result) method of the Application class. For more information, see the Smart View SDK API References.

   #smart view sdk    #restore    #foreground    #show

Yes, you can test your Smart View-enabled application before registering it in the Samsung Apps TV Seller Office. Implement the mobile application to launch the TV application using the TV application package ID. The package ID is defined in the TV application "config.xml" file, within the tizen:application element.

After you register the TV application in the Seller Office, in the mobile application, make sure you replace the TV application package ID with the application ID from the Seller Office. For more information, see How to manage multi app IDs.

   #smart view sdk    #application id    #testing

Check that the TV has not prevented your mobile device from connecting:

On the TV, open the mobile device manager:

For 2016 and later models, select "Menu > Network > Expert Settings > Mobile Device Manager > Mobile Device List"

For 2015 models, select "Menu > Network > Multimedia Device Manager"

If your mobile device appears on the device list, make sure its switch is set to "Allow".

If you are developing your mobile application in JavaScript, WebView does not support multicast requests, which are crucial for device discovery. As a workaround, the Smart View SDK performs device discovery by checking the IP host identifiers sequentially (from 1 to 255) for the first available network interface. Consequently, if the TV's IP address is near the end of the host range, the device discovery attempt can time out before reaching it. Alternatively, if device discovery is not the focus of your application, you can define the TV IP address using the msf.remote() method.

   #smart view sdk    #device discovery

SSDP is supported on 2012 to 2014 TV models. On 2015 and later models, use the Smart View SDK.

   #smart view sdk    #ssdp    #device discovery

Yes. To play multichannel streams with the NaCl Player, define the ChannelLayout property value in the AudioElementaryStream object. You can select from various multichannel layout values, such as CHANNEL_LAYOUT_5_1 and CHANNEL_LAYOUT_7_1.

   #native client    #nacl player    #elementary stream    #multichannel audio    #channel layout

You can try to export and reimport the project to the Tizen Studio:

In the Tizen Studio, build and export your NaCl project to a ".wgt" package.

Import the ".wgt" package as a Tizen project:

Since importing a project does not allow you to change the project name, rename the original project.

In the Tizen Studio menu, select "File > Import > Tizen > Tizen project".

Select "Select archive file" and navigate to the ".wgt" package.

Select the target TV platform, and click "Finish".

Launch the application on the TV from the new project.

   #native client    #nacl    #launch

Because a NaCl application is run in a sandbox environment, it can only access files that are within its own directory. NaCl applications cannot access the system certificates directory on the TV.

If you want to use CA certificates in a NaCl application, you must place the certificates in the application directory.

   #native client    #nacl    #ca certificate    #error

To improve your application UI, you can take advantage of CAPH 3.0, a Web UI framework, based on HTML5, that is optimized for Samsung TVs.

   #user interface    #ui    #caph

Although the CAPH Web UI framework is based on HTML5, it is only guaranteed to work with Samsung Smart TVs. For more information, see CAPH 3.0.

   #caph

Yes, you can implement scrollable lists using CAPH for AngularJS or CAPH for JQuery.

   #scrollable list    #ui    #caph    #user interface

It is not possible to create scrollable items directly using the CAPH library. However, since you can control CAPH UI elements using HTML and CSS, you can manually add the scrollable functionality with CSS. For more information, see CSS overflow property.

   #caph    #scrollable    #css

To make sure the scrollable list moves to show the focused item, you can trigger the "reload" event, which updates all item views.

You can also use the select() method instead of the focus() method, which selects the item in addition to moving focus to it.

   #caph    #focus    #scrollable    #angularjs

The icons defined in the "config.xml" file for a TOAST application have the following size requirements:

Table 1. TOAST application icon sizes IconSize ThumbIcon106x87 px

BigThumbIcon115x95 px

ListIcon85x70 px BigListIcon95x78 px

   #config xml    #toast    #application icon    #icon

Hosted Applications

The following questions are related to creating hosted applications.

In a hosted or cloud-based application, the application code is downloaded from your Web server at runtime, or the application simply loads a Web page at a specific URL.

Basically, hosted application is not allowed to submit due to security policy.

It can be acceptable for some special cases only.

You need to contact your Content Manager in advance.

   #cloud based application    #dynamic web page    #redirect application

No. For security reasons, Tizen APIs are not supported in hosted applications.

   #tizen api    #dynamic web page    #cloud based application    #redirect application

Yes, but you must be a member of a partner group to create hosted applications.

Simply convert your Web application to a hosted application, and submit an application update. You can also convert a hosted application to a Web application in the same way.

   #convert    #cloud based application    #dynamic web page    #migrate

To load external scripts in your application, you must obtain permission from your Samsung Apps TV Seller Office Content Manager.

Make sure you grant permission to access the external server in the application "config.xml" file, using the access element:

If your application needs to download content from multiple domains, in the "config.xml" file, define them in the tizen:allow-origin element.

   #external script    #external js    #dynamically loaded script

Yes. Make sure you grant permission to access the external server in the application "config.xml" file, using the access element:

   #external css    #config xml    #dynamically loaded css

Make sure your Content Security Policy header does not use the unsafe-inline or unsafe-eval policies. For security reasons, they must not be used.

   #content security policy    #csp    #unsafe inline    #unsafe eval    #error

Multimedia

The following questions are related to implementing multimedia playback features.

Video playback using the HTML video element supports external subtitles in WebVTT format. For more information, see Adding Captions and Subtitles.

The AVPlay API supports both internal and external subtitles in a variety of formats. For information on configuring subtitle tracks with the AVPlay API, see Subtitles.

Note To display internal subtitles, the user must switch on the "Caption" setting on the TV.

On some TV models, the "Caption" setting is available only when the TV input source is the broadcast signal.

   #subtitle    #video element    #avplay api    #caption

Yes. For implementation information, see Using Video Elements.

Alternatively, you can also implement video playback using the AVPlay API.

   #html    #video element

For information about implementing media playback with the AVPlay API, see Using AVPlay. The AVPlay API allows you to play media content with features not supported in HTML5, such as adaptive streaming, additional subtitle formats, and 4K UHD video.

   #avplay api    #adaptive streaming    #subtitle    #4k    #uhd

When implementing multitasking, if you use the AVPlay API to play media content, do not call the pause() and play() methods when the application is hidden and resumed. Instead, call the suspend() method to save the playback state, and the restore() method to restore it:

document.addEventListener('visibilitychange', function() {

if (document.hidden) {

// Behavior when the application is hidden

webapis.avplay.suspend();

} else {

// Behavior when the application is resumed

webapis.avplay.restore();

}

});

For more information, see Multitasking.

   #avplay api    #multitasking    #suspend    #restore

Yes, you can implement multiple audio tracks and multiple subtitle tracks using the AVPlay API.

If you are not using the AVPlay API, you can implement multiple subtitle tracks for an HTML5 video element. For more information, see Adding Captions and Subtitles.

   #subtitle    #audio track    #multiple tracks    #avplay api    #video element    #caption

No. A video element and an AVPlay instance cannot play content simultaneously.

   #video element    #avplay api

To check whether the TV supports 4K UHD resolution, use the isUdPanelSupported() method of the ProductInfo API.

   #uhd    #4k    #screen resolution    #productinfo api

To retrieve the current playback time, use the getCurrentTime() method. It returns the playback time in milliseconds.

   #avplay api    #playback time    #getcurrenttime    #timestamp

You can specify whether a video is displayed in fullscreen mode, letterbox mode, or the video's aspect ratio, using the setDisplayMethod() method of the AVPlay API.

Note Overriding the video's original aspect ratio can cause video image distortion.

   #aspect ratio    #fullscreen    #letterbox    #override    #display mode

No. The AVPlay API plays the video content as delivered. It does not support rotating or mirroring the video image.

   #avplay api    #rotate    #mirror    #video image    #flip    #reverse

No. Subtitle visibility can be controlled from within the application, but closed captioning must be enabled or disabled in the TV settings. If the media content has both closed captioning and subtitles, you can prompt the user to open the TV settings and disable captioning, or you can avoid implementing software subtitles.

   #caption    #subtitle    #tv setting

No, switching the TV audio mode is not supported by the API. The user must select the audio mode from the TV menu.

   #audio mode

Yes, the autoplay and loop attributes for the HTML video element are supported on Samsung Smart TVs.

   #html    #video element    #autoplay    #loop

No, the getVideoPlaybackQuality() method of the HTMLVideoElement interface is not supported.

   #html5    #html video element    #getvideoplaybackquality    #playback quality

No. Although allowing the user to jump backwards improves the user experience, it is not a required feature. When you submit the application for publishing, if it does not support backwards jump, make sure to mention it in your application UI description file.

   #jump    #backward    #rewind    #user experience    #ux    #application ui description

To implement launching another application, you need the other application's application ID. Since application IDs are confidential, you can only launch other applications that you have developed.

However, if the streaming service you want to use, such as YouTube, has an HTML embedding functionality, you can use it in your application to stream content from that service.

   #embedding    #html    #embedded content    #application launch

Make sure the video format is supported by the TV. For information on video format support, see Media Specifications. Implement checks to ensure that the video format is supported before you attempt playback.

   #video element    #video format

To handle AVPlay errors, implement the onerror() event handler, which returns the error code. For more information and error code definitions, see the AVPlay API.

   #avplay api    #error code    #onerror

Make sure the application is setting the correct subtitle track. To retrieve the list of tracks in a media stream:

var trackInfo = webapis.avplay.getTotalTrackInfo();

var text = 'type of track info: ' + typeof trackInfo + '';

text += 'length: ' + trackInfo.length + '';

for (var i = 0; i trackInfo.length; i++) {

text += 'index: ' + trackInfo[i].index + '';

text += 'type: ' + trackInfo[i].type + '';

text += 'extra_info: ' + trackInfo[i].extra_info + '';

}

For more information on selecting a subtitle track, see Switching Subtitle Tracks.

   #avplay api    #subtitle track    #caption

Make sure you have set the appropriate display area for the content, using the setDisplayRect() method. For more information, see Using AVPlay.

If the media is 4K UHD content, you must also check that the TV supports it and implement its playback.

   #avplay api    #display area    #4k    #uhd    #no video

Captioning text is rendered with fixed-width (monospace) fonts, which can appear wider than variable-width (proportional) fonts.

   #caption    #subtitle    #font    #text    #font width

Closed captions are shown only when focus is on the TV broadcast window. To show closed captions in a PiP window, you must move focus to it.

   #captions    #subtitles    #picture in picture    #pip    #tv broadcast    #tvwindow api

The seekTo() method of the AVPlay API cannot be used to move to the video start time (0 milliseconds) or end time. To move to the beginning of a video, you can stop and restart the video, or move to a position close to the beginning, such as 1000 milliseconds.

   #seek    #jump    #avplay api    #seekto

The connection failed error occurs when the AVPlay instance is unable to access the media content. Make sure the URL is correct, the media server is accessible, and the connection uses the appropriate security settings and certificates.

   #network connection    #error    #url    #security certificate    #security setting    #server

When the media has multiple audio tracks, you must use the setSelectTrack() method to define the audio track to play. The method must be called when the AVPlay instance is in the playing state.

Note For Smooth Streaming only, the setSelectTrack() method can also be called during the ready state.

   #multiple audio tracks    #setselecttrack    #smooth streaming    #avplay api

Yes. The setVolume() method of the TVAudioControl API does not show the TV's built-in volume UI. You must implement your own volume UI.

   #volume level    #volume ui    #tvaudiocontrol api

Poor network connectivity can cause media to load slowly. To inform the user that content is still loading, implement a loading screen.

   #network connectivity    #black screen    #loading screen

Multimedia DRM

The following questions are related to implementing playback for media protected by digital rights management (DRM) technology.

Samsung TVs support playing media protected using the PlayReady, Widevine, and Verimatrix DRM technologies. For information on the supported media containers, streaming format and DRM combinations, and network protocols, see the General Specifications.

You can implement DRM-protected media playback by defining the DRM parameters with the setDrm() method of the AVPlay API. For implementation details, contact your Samsung Apps TV Seller Office Content Manager.

   #drm    #playready    #widevine    #verimatrix    #avplay api

You can define the HTTP header information in the DRM parameters, for example:

var drmParam = new Object();

drmParam.LicenseServer = "http://license.company.com";

drmParam.CustomData = "mycustomdata";

drmParam.HttpHeader = "header";

playerObj.setDrm("PLAYREADY", "SetProperties", JSON.stringify(drmParam));

   #drm    #http header    #license server request    #playready    #widevine

Check that the DRM configuration is set after opening the media file with open(), but before preparing it with prepare() or prepareAsync(). For more information, see the AVPlay API.

   #drm configuration    #avplay api

Yes. To delete the stored DRM license information, replace the DRM parameters with empty strings:

webapis.avplay.setDrm('', '', '');

   #license information    #avplay api    #setdrm    #delete

Samsung does not have documentation about PlayReady server communication details. You must contact Microsoft for this information.

   #playready    #public key    #server communication

When the application is hidden, the DRM session can be removed. To avoid the "PLAYER_ERROR_NONE" error when the application is resumed with the restore() method, you must also recreate the DRM session.

   #player error none    #drm session    #error    #restore    #multitasking    #avplay api

Make sure that all media segments begin with an instantaneous decoder refresh (IDR) frame. The codec information stored in the IDR frame is needed during playback to decode frames properly when the bandwidth changes.

   #verimatrix    #idr frame    #bandwidth change    #distortion    #stuttering

To avoid audio and video desynchronization, encode the video content at a constant frame rate (FPS). The other stream properties can be adaptive.

   #verimatrix    #audio sync    #frame rate    #fps

Multimedia Streaming

The following questions are related to streaming media in applications.

You can retrieve various stream property information, such as the current bandwidth, current bitrate, and available bitrates, using the getCurrentStreamInfo() and getStreamingProperty() methods of the AVPlay API.

Make sure playback is in progress before retrieving the current stream properties.

   #avplay api    #stream property    #bitrate    #bandwidth

By default, the AVPlay API implements a 10 second or 15 MB buffer.

You can define the buffer size, in seconds or bytes, using the setBufferingParam() method. While there is no maximum buffer size, it is not recommended to modify the default values.

   #buffer    #avplay api

Switching the audio quality or video resolution during playback is not supported. However, you can switch between audio tracks during playback.

   #audio quality    #video resolution    #switch    #audio bitrate    #change

Yes, you can implement adaptive streaming with the AVPlay API. For more information, see Adaptive Streaming.

   #adaptive streaming    #avplay api    #hls    #http live streaming    #smooth streaming    #mpeg dash

Adaptive streaming media playback is implemented using the AVPlay API in the same way as other media. For more information, see Adaptive Streaming.

To enable streaming 4K UHD video, use the setStreamingProperty() method to set the SET_MODE_4K property to TRUE. For more information, see 4K UHD Video.

If you implement adaptive streaming that can change the video resolution, make sure the SET_MODE_4K property is TRUE when the stream switches to 4K UHD resolution.

   #4k    #uhd    #adaptive streaming    #avplay api    #adaptive bitrate streaming

Cookies can be used if the DRM implementation requires them. However, cookie reception must be handled on the server side.

Whenever possible, use local storage instead of cookies, since the application is not a Web page on the Internet, and consequently does not have a domain name.

   #http live streaming    #hls    #cookie    #local storage    #drm

The seekTo(), jumpForward(), and jumpBackward() methods of the AVPlay API are supported for live HLS streams. If you want to use live seek, the streaming server must maintain past and future segments. The seekable range is limited to the segments maintained on the server.

Note To retrieve the live stream duration, use the getStreamingProperty("GET_LIVE_DURATION") method instead of the getDuration() method.

Live seek is supported for Verimatrix DRM-protected content since 2016 TV models.

   #http live streaming    #hls    #seeking    #avplay api

No. Samsung TVs do not support the UDP protocol.

Multicast streaming is supported on 2012 to 2015 models using Samsung Legacy Platform, but only through the HTTP and RTP protocols.

   #multicast    #udp    #samsung legacy platform

MPEG-DASH data can be specified in various ways, such as using a number-based or time-based segment template, or as a byte range. For more information, see the ISO/IEC 23009-1 specification.

   #mpeg dash    #segment template    #number based    #time based    #byte range

No. Samsung TVs do not support media up or down-scaling. The media content must follow the resolution and FPS specifications for the applicable video codec.

   #different resolution    #fps    #specification    #scaling    #video codec

To prevent audio sync issues, make sure that all video resolutions in the HLS content have the same frame rate (FPS).

   #http live streaming    #hls    #video resolution    #audio sync    #frame rate    #fps

Check that the TV supports the specified HLS tag version. For more information, see HLS Tag Support.

   #http live streaming    #corrupted    #hls tag version

Networking and Connectivity

The following questions are related to implementing networking and connectivity features.

Most Web applications use a network connection to, for example, play media and download files. Because the network connection can disconnect and reconnect unexpectedly, checking the network status regularly is very important for application stability. For information on how to monitor network status changes, see Checking Network Status.

   #network connection status    #disconnect    #reconnect    #network state change    #internet connection

To enable sending requests to external servers, you must add the following lines to your "config.xml" file:

To permit the application to access the Internet, include the following privilege:

To grant permission to access the external server, define the server URL using the access element:

   #config xml    #external server    #access origin    #ajax request

Yes. You can define the navigator.userAgent string directly.

   #user agent string    #http header

Since 2017 models, the Notifications API is supported on Samsung TVs.

Since 2018 models, the Web standard Push API is also supported.

   #notification    #notifications api    #push    #push api    #web standard

No. Samsung Smart TVs do not support XMPP messaging.

   #xmpp    #messaging

No. Retrieving details about the active Internet connection interface on the TV is not supported.

   #connection interface    #internet connection    #wifi connection

When the TV is switched on after being switched off, the network connection does not resume immediately. You can experience network errors, or the application plays the content still in the buffer and stops. To avoid these scenarios, when the application is resumed, make sure you check that the network connection is available before resuming media playback.

   #media playback    #resume    #error    #buffer    #streaming    #disconnect

Privileges

The following questions are related to application privileges.

To use security-sensitive APIs, you must declare the required privileges and sign your application with a certificate for the appropriate privilege level. For more information, see Configuring TV Applications.

   #security    #certificate    #configuration    #config xml

To publish applications that use partner privileges, you must be a member of a Seller Office partner group. For more information, see Partnership Request.

   #publish    #partnership

To use partner-level privileges during testing, you must create a partner-level distributor certificate and sign the application with it. When you create the partner-level distributor certificate, you must enter the DUID of the test device. For more information, see Creating Certificates.

   #partner    #testing    #distributor certificate    #partnership

Samsung Legacy Platform

The following questions are related to developing applications for Samsung Legacy Platform.

Tizen applications are not compatible with Samsung Legacy Platform devices. However, you can migrate your application to TOAST, which allows the application to support both platforms. For more information, see Migrating Tizen to TOAST.

   #compatible    #tizen    #toast    #migrate    #compatibility    #hybrid

Samsung Legacy Platform applications are not compatible with Tizen devices. However, you can migrate the application to Tizen.

Alternatively, you can migrate your application to TOAST, which allows the application to support both platforms. For more information, see Migrating Legacy Platform to TOAST.

   #compatible    #tizen    #toast    #migrate    #compatibility    #hybrid

For Samsung Legacy Platform developer documentation, see Samsung Legacy Platform.

   #documentation    #api reference

For information on platform features, such as supported streaming and DRM protocols, see Samsung Legacy Platform (2010 ~ 2014). For detailed information on the supported video codecs, see Player Specification.

   #streaming protocol    #drm    #specification    #media format    #codec    #feature support    #media playback

To develop and test Samsung Legacy Platform applications, use the Samsung TV SDK for Legacy Platform.

   #samsung tv sdk    #test    #debug    #emulator

No. The Tizen Studio does not support creating Samsung Legacy Platform application packages. You must use the Samsung TV SDK for Legacy Platform.

   #application package    #tizen studio    #zip package

To test your Samsung Legacy Platform application on a TV through a USB removable drive, you must obtain a ".sig" signature file from the Samsung Apps TV Seller Office:

Retrieve the device ID (DUID) for the device on which you want to test the application.

On the Smart Hub screen, click the following remote control key sequence: "Fast Forward, 2, 8, 9, 2"Note On 2013 models, you must instead click the key sequence on the "Store > More Apps" screen.

To request the ".sig" file, create a Seller Office "1:1 Q&A" support ticket and provide the DUID information.

The signature file and application package must be placed in the USB removable drive root directory.

   #testing    #signature file    #sig file    #usb

To test applications on a Samsung Legacy Platform TV, log in to the "develop" account on the TV.

   #developer mode    #testing    #developer account

Copy the "CPDeveloper.sig" file to the root directory of the external USB drive containing the application package you want to test on the TV. You must keep the USB drive connected to the TV while you test the application.

Note On some TV models, the "CPDeveloper.sig" file must be renamed to "Developer.sig".

   #testing    #signature file    #sig file    #usb

The IME enables text input in the applcation. For information on how to implement it, see How To Use IME (Input Method Editor).

   #input method editor    #ime    #on screen keyboard

To retrieve the TV model code, use the GetProductCode() method of the TV class.

   #model code    #tv class    #getproductcode    #device information

You can retrieve various network information using the Network API. However, retrieving the Wi-Fi security mode and encryption type is not supported.

   #network information    #wifi connection    #wifi security    #wifi encryption    #network api

Samsung Legacy Platform supports the CEA-708, SMPTE-TT, and SAMI subtitle formats. For information on implementing subtitles, see Subtitle (Closed Caption).

   #subtitle    #closed caption    #captioning

On Samsung Legacy Platform, the external subtitle URL cannot be changed during playback. To implement switching subtitle URLs, you must destroy the video player object and recreate it with the new URL, resuming playback from the same position. For more information on implementing subtitles, see Subtitle (Closed Caption).

   #subtitle    #external subtitle url    #closed caption

To enable automatic updates for a Samsung Legacy Platform application, add the following code to the "config.xml" file:

y

The specific automatic update behavior depends on the TV model year. On 2013 and later models, the user can enable or disable automatic updates, which overrides the automatic update behavior defined by the application.

Note If you do not enable automatic updates in your application, the user must uninstall and reinstall the application to get the latest version.

   #automatic update    #config xml    #auto update

On Samsung Legacy Platform, to determine whether the voice guide is enabled, check the IsTTSEngineEnabled property:

// Returns "true" if voice guide is enabled

webapis._plugin("RECOG", "IsTTSEngineEnabled")

   #voice guide    #tts    #text to speech

To calculate the time in a specific time zone, you must retrieve the time zone information with the getTimeZone() method of the tv.info class, and convert the time manually from UTC time.

   #tv info class    #time zone    #time conversion

The icons for a Samsung Legacy Platform application have the following size requirements:

Table 1. Samsung Legacy Platform application icon sizes IconSize ThumbIcon106x86 px BigThumbIcon115x95 px ListIcon85x70 px BigListIcon95x78 px

   #icon    #application icon

The Convergence feature is supported on 2012 to 2014 TV models. It allows users to communicate with and transfer files between the TV and mobile devices or computers. For 2015 and later models, you can implement similar functionality using the Smart View SDK.

   #convergence    #mobile integration    #smart view sdk

No. The Samsung Legacy Platform player supports only ".ism" and ".isml" manifest files for Smooth Streaming. It does not support ".ismc" manifest files. For more information on implementing Smooth Streaming, see Guideline for Smooth Streaming Application Developers.

   #multimedia    #media playback    #smooth streaming    #manifest file    #ismc file

Streaming over RTMP is supported on 2012 to 2014 TVs only. For information on the supported network protocols, see General Specifications.

   #rtmp    #streaming    #samsung legacy platform    #network protocol

No. Samsung Legacy Platform does not support hosted applications.

   #hosted application    #cloud based application    #dynamic web page    #redirect application

No. Samsung TVs do not support the UDP protocol.

Multicast streaming is supported on 2012 to 2015 models using Samsung Legacy Platform, but only through the HTTP and RTP protocols.

   #multicast    #udp

No. Automated testing is not supported on Samsung TVs.

Additionally, the Automatic Testing Tools provided for Samsung Legacy Platform are no longer supported.

   #automated testing    #automatic testing tools    #web driver

The "Network Error Handling" warnings are shown when your application does not use the CheckPhysicalConnection() or CheckHTTP() methods of the Network class to check network connectivity. Implementing the missing checks is recommended, but the warnings are not critical and do not prevent your application from being submitted.

   #pre test    #network error    #warning    #network class    #connectivity

Security

The following questions are related to implementing security protocols in TV applications.

To transmit encrypted information between Web browsers and Web servers, Samsung Smart TVs support TLS (Transport Layer Security) versions 1.0, 1.1, and 1.2.

A TV firmware upgrade can be required to patch the POODLE attack vulnerability. Consequently, SSL (Secure Sockets Layer) is no longer supported.

   #tls    #transport layer security    #ssl    #secure sockets layer

Since 2017 models, the Web Cryptography API is supported on Samsung Smart TVs.

   #web cryptography api    #webcrypto api

The Cross-Origin Resource Sharing (CORS) "Origin" request header is not supported on Samsung Smart TVs.

   #cors    #cross origin resource sharing    #request header    #error    #http header

SNI certificates for TLS are supported on Samsung Smart TVs since 2017 models.

   #server name indication    #sni    #tls    #transport layer security    #ssl certificate

Yes. Smart TVs support handling JSON feeds through HTTPS.

   #json    #https

Make sure the TV Web engine supports the child-src directive, which was introduced in the Content Security Policy Level 2 (CSP2) specification. CSP2 is supported on Samsung TVs since 2017 models.

   #content security policy    #csp    #child src    #error

Smart Hub Preview

The following questions are related to implementing the Smart Hub Preview feature.

Smart Hub Preview is a feature for Samsung Smart TVs that allows you to show content when the user hovers over your application icon in the launcher. The user can click the preview tile to open the content directly within the application. You can use the preview to promote new or personalized content to the user. For more information, see Smart Hub Preview.

   #preview    #launcher    #personalized content

Make sure your JSON file URL and the defined tile image URLs are valid. Invalid tile image URLs can cause unexpected Smart Hub Preview behavior.

   #tile image    #preview tile

Smart Hub Preview is supported since 2016 TV models. It is also supported on the TV emulator since Tizen TV Extension 2.3.1.

   #tv model    #emulator    #feature support

When implementing a personal preview, the background service application is required. While the foreground application performs the main application tasks, such as showing content, the background service application serves information to show in the preview. For more information on implementing a personal preview, including the background service application, see Implementing Personal Preview.

   #personal preview    #background service application

Smart Hub Preview tile images must be at least 250 px tall, with an aspect ratio of 16:9, 4:3, 1:1, or 2:3. Larger images are reduced to fit the specified aspect ratio. For more information, see Tile Element Specifications.

   #tile    #size    #image    #aspect ratio

Since languages can have different display character widths, there is no defined text length limit. However, long titles or subtitles can cause unintended Smart Hub Preview behavior.

   #section title    #tile title    #tile subtitle    #title length

The title and subtitle are only shown when the tile has focus. If you want to show text on the tile image even when it does not have focus, you can implement the text in the tile image itself.

   #tile title    #tile subtitle

You can define the JSON file as either "text/plain" or "application/json" type.

   #json file    #media type    #mime type    #content type

By default, the preview content is updated every 10 minutes and whenever the TV is switched on.

You can also define a specific update time with the expires property, and define a new update time in the updated feed. The minimum time between updates is 10 minutes. After the feed updates at the defined time, if no new expires property is specified, the preview content is updated every 10 minutes.

   #feed update    #update interval    #refresh interval

To show different content on Smart Hub Preview for specific model groups, such as 4K UHD video content on UHD TVs, you can implement a public preview. Create a separate application version that shows preview content from a different JSON file URL, and submit it for the applicable model groups.

Alternatively, you can implement a personal preview, which allows you to customize the preview content for the user. Use the ProductInfo API to retrieve the model information from the TV, and use the background service application to serve content based on the model information retrieved.

   #public preview    #private preview    #model group    #4k    #uhd    #productinfo api

If the application is installed from a USB removable drive on a 2017 or later TV model, Smart Hub Preview does not work. This is a known limitation.

   #install    #usb    #missing tile    #testing

The preview content is updated in the following scenarios:

When the application is added to the launcher.

When the TV is switched on, after being fully powered off.

Every 10 minutes.

For a public preview, at the time defined by the expires parameter in the JSON file. The expires parameter value must be a time no more than 1 week into the future.

For a private preview, at a frequency defined by the background service application, based on the timestamp of the current JSON content. You can store the JSON content and timestamp in local storage using the Filesystem API.

To implement preview content updates:

For a public preview, you must request the JSON file from the external URL defined in the use.preview metadata key of the config.xml file.

If the public preview does not refresh properly:

Make sure that the JSON data received is valid.

Check that the expires parameter is correctly defined.

For a private preview, you must launch the background service application as a node module, and trigger the ON-START() and onRequest() event handlers.

If the private preview does not refresh properly:

Make sure the background service application is running without errors.

If the background service application encounters an issue and must close, check that it is terminated properly using the getCurrentApplication().exit() method. If the background service application is not properly terminated, it cannot be relaunched at the next 10 minute interval.

   #background service application    #application api    #private preview    #public preview

Before launching the background service application, make sure the TV supports it:

tizen.systeminfo.getCapability("http://tizen.org/feature/web.service");

When you use the launchControl() method to launch a background service application on a TV that does not support service applications, it causes unexpected behavior in the foreground application, such as missing images and corrupted video playback.

   #background service application    #launchcontrol    #missing image    #feature support

Specifications and Feature Support

The following questions are related to the specifications for and the features supported by Samsung Smart TVs.

For the mapping of Samsung Smart TV product year and lineup with the model groups at the Samsung Apps TV Seller Office, see TV Model Groups.

   #model group    #tv model    #product year    #model lineup

2016 and later Samsung Smart TVs are distributed with and can run Tizen applications only.

2015 models are distributed with Tizen applications, but for backward compatibility, can run Samsung Legacy Platform applications.

2010 to 2014 models are distributed with and can run Samsung Legacy Platform applications only.

   #platform    #tizen    #samsung legacy platform    #compatibility

For detailed information on the supported music, picture, and video formats and decoders, see Media Specifications.

   #media specifications    #media format    #music    #picture    #audio decoder    #video decoder    #codec

The Samsung Product API is supported on 2012 and later Samsung Smart TV models.

   #samsung product api    #tv model

All Samsung TVs since 2015 support multitasking, except the "15TV_STANDARD2" model group. Multitasking is also supported on the TV emulator since Tizen TV Extension 2.1.2.

   #multitasking    #tv model    #emulator    #model group

Not all Samsung TVs support HDR video. To determine whether the TV supports HDR content, use the isHdrTvSupport() method of the AVInfo API.

   #hdr    #high dynamic range    #avinfo api

For information on the supported Web engine features, see Web Engine Specifications.

   #web engine

Samsung TVs partially support ES6 JavaScript. For a list of supported ES6 features, see Web Engine Specifications.

   #javascript    #es6    #web engine

Make sure the Web engine used by the TV supports the feature. For information on the TV Web engine version and the supported features, see Web Engine Specifications.

   #web engine    #webkit

Support for PlayReady and Widevine depends on the TV model year. For information on the supported versions, see MSE/ESE.

   #playready    #widevine    #encrypted media extensions    #eme    #drm    #digital rights management

The PlayReady DRM support depends on the TV model year:

2012 to 2013 models support PlayReady 1.2

2014 to 2017 models support PlayReady 2.5

2018 and later models support PlayReady 3.3

For more information, see MSE/ESE.

   #playready    #drm

Widevine Modular is supported since 2017 TV models. For 2016 and older models, use Widevine Classic.

   #widevine modular    #widevine classic    #drm

In the "config.xml" file, define the minimum required platform version for your application in the required_version attribute of the tizen:application element. You must also specify the API version used for the application, by defining the value of the "'http://samsung.com/tv/metadata/devel.api.version" key within a tizen:metadata element.

If the API version is greater than the minimum required platform version, the application launches on devices using lower platform versions, but unsupported API features do not work.

   #platform version    #api version    #config xml    #meta data    #required version

Since 2017 models, you can implement text-to-speech (TTS) functionality using the Web Speech API. For information on supporting TTS in your application, see Text to Speech.

   #text to speech    #tts    #web speech api    #accessibility

Since 2016 TV models, ID3 tags containing timed meta data are supported for HTTP Live Streaming (HLS) media.

   #http live streaming    #hls    #id3 tag    #timed meta data

When implementing Smooth Streaming, you can use TTML, DFXP, and SMPTE-TT internal subtitles or captions.

   #smooth streaming    #caption    #internal subtitle    #ttml    #dfxp    #smpte tt

Streaming over RTMP is supported on 2012 to 2014 TVs only. For information on the supported network protocols, see General Specifications.

   #rtmp    #streaming    #samsung legacy platform    #network protocol

Unicast streaming over RTP is not supported. For information on the supported network protocols, see General Specifications.

   #streaming    #rtp    #unicast    #network protocol

No. Because SVG images are not supported, they can display incorrectly on Samsung TVs. Using JPG and PNG images is recommended.

   #svg    #scalable vector graphic    #image format    #vector image

No. Customizing the UI sound effects is not supported on Samsung TVs.

   #ui    #user interface    #sound effect    #click sound

Since 2014 TV models, custom fonts are supported.

Custom Arabic fonts are not supported on 2013 and older TV models.

   #font    #arabic

You can use iframe elements in your application, but they can only display content. They do not support user interaction with the content, nor the Tizen or Samsung Product APIs.

When the user clicks an iframe element, the content opens in the Web browser. This behavior cannot be disabled.

   #iframe

No, Samsung Smart TVs do not support Java applications.

   #java

No, Samsung Smart TVs do not support HbbTV.

   #hbbtv    #hybrid broadcast broadband tv    #hybrid digital tv

Third-party Features

The following questions are related to features provided by third parties, such as Google or YouTube.

You can use third-party data management and analytics solutions, such as mParticle and GoogIe Analytics, in the application, but you must contact the provider for support.

Samsung does not provide support for third-party features.

   #google analytics    #data management    #mparticle    #statistics    #analysis    #data collection

You can use YouTube API features, but they are not guaranteed to work properly.

Samsung does not provide support for third-party features.

   #youtube

You can use third-party ad-serving platforms, such as Google AdSense, but the advertisements are not guaranteed to work properly.

Samsung does not provide support for third-party features.

Note In-app advertising must only be shown within your application, and must not intrude on the user experience.

   #ad serving platform    #google adsense    #in app advertising    #advertisement    #ad framework

Facebook Login is not supported on Samsung TVs.

However, in a Samsung TV application, you can implement the Single Sign-On (SSO) feature (for Tizen and Samsung Legacy Platform applications), which allows the user to save login information to their TV.

   #facebook login    #single sign on    #sso    #user login    #user account

In general, external libraries are not supported and not guaranteed to work.

   #external library    #jsonrpc

Samsung does not provide support for third-party features, such as JW Player. To ensure compatibility, use HTML audio and video elements or the AVPlay API for media playback.

   #jw player    #streaming    #media playback    #avplay api    #audio element    #video element

Tizen Studio

The following questions are related to developing applications with the Tizen Studio.

If you are unable to test your application on your TV through the Tizen Studio, try the following actions:

In the Tizen Studio Package Manager, make sure the Samsung TV Extension is installed.

Create a new certificate profile, making sure you select the distributor certificate privilege level you need, then build the project with the new certificate profile.

Make sure installing your application on the device is allowed. In the Tizen Studio Device Manager, right-click on a folder of the connected device filesystem and select "Permit to install applications" in the context menu.

Export and reimport the project to the Tizen Studio:

In the Tizen Studio, build your project as a signed ".wgt" package.

Import the ".wgt" package as a new Tizen project:

Since importing a project does not allow you to change the project name, rename the original project.

In the Tizen Studio menu, select "File > Import > Tizen > Tizen project".

Select "Select archive file" and navigate to the ".wgt" package.

Select the target TV platform, and click "Finish".

Launch the application on the TV from the new project.

   #testing    #troubleshooting    #tv device

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. A certificate profile is a combination of the certificates used for signing, and it can be created using the Certificate Manager.

   #certificate profile    #signing    #certificate manager    #signature

To work with the Samsung TV SDK, download and install the Tizen Studio, Samsung TV Extension, and Samsung Certificate Extension.

   #samsung tv sdk    #samsung certificate extension    #samsung tv extension    #sdk access

It is easy to create an application for a Samsung TV. For an overview of the TV Web application features and development process, from creating a project to publishing it on Samsung Apps TV, see Quick-start Guide.

   #quick start guide    #getting started    #beginner    #application creation

To avoid the warning, you can import the application package as a new project in the Tizen Studio:

In the Tizen Studio menu, select "File > Import > Tizen > Tizen project".

Select "Select archive file" and navigate to the ".wgt" package.

Select your TV's platform version, and click "Finish".Note Since Tizen Studio 1.1.1, the Tizen Studio supports creating Tizen 3.0 and higher TV applications only. However, the "Platform not supported" warning does not affect application functionality when testing on TVs running older Tizen versions.

   #warning    #testing    #unsupported platform    #deprecated platform

Make sure you are using the latest Tizen Studio version. For the Tizen Studio release notes and a list of known issues, see Tizen Studio Release Notes on the Tizen Developers Web site.

   #release note    #known issue    #troubleshooting

To sign application packages with your author certificate, the certificate must be valid.

To renew an existing author certificate, in the Tizen Studio Certificate Manager, create a new certificate profile with it. In the "Author Certificate" step, select the "Select an existing author certificate" option, and enter your existing author certificate and password.

   #author certificate    #certificate profile    #certificate manager    #renew certificate    #signature

To import an existing author certificate to the Tizen Studio Certificate Manager, create a new certificate profile. In the "Author Certificate" step, select the "Select an existing author certificate" option, and enter your existing author certificate and password.

   #author certificate    #certificate profile    #certificate manager    #import certificate    #signature

If you prefer a command line interface to the graphical Tizen Studio window, you can use the Tizen Studio Command Line Interface (CLI) tool throughout the development process.

When testing your application, you can also use various SDB shell commands.

   #command line tool    #command line interface    #cli    #sdb shell

When you package an application with the Tizen Studio, all JavaScript code files in the "js" directory are validated. If the JavaScript code has been minified, it can cause significant delays in the validation process. However, JavaScript libraries in the "lib" directory are not validated. To avoid JavaScript validation delays, you can place the minified JavaScript code files in the "lib" directory.

   #js validation    #javascript validation    #application packaging    #minification    #javascript library

Check that your environment variables are configured for Tizen Studio use. On your computer, make sure the "\tools\ide\bin" directory is defined in the PATH environment variable.

   #wgt file    #package    #build    #path    #environment variable

Yes, you can use CSS preprocessors, such as Sass and Less, as Eclipse plugins within the Tizen Studio. However, Samsung does not provide support for third-party tools.

   #css preprocessor    #eclipse plugin    #sass    #less

User Interaction

The following questions are related to user interaction features provided by a keyboard, mouse, or pointer.

To disable the pointer and mouse functionality in your application, make sure the "config.xml" file contains the following elements:

For more information, see Mouse.

   #pointer    #mouse    #disable    #air pointer    #pointing device

Even if your application does not support a keyboard, there are some hidden keys that work with a keyboard. The following hidden keys must be mapped to the remote control keys.

Table 1. Hidden key mapping

Hidden Key

Remote Control Key

Hidden Key

Remote Control Key

Esc

Return

F5

Smart Hub

Number keys

Channel number

F6

Source

Windows key

Menu

F7

Channel List

Arrow keys

Move focus (cursor)

F8

Volume Mute

Enter

Enter

F9

Volume Down

F1

Color Key A

F10

Volume Up

F2

Color Key B

F11

Channel Down

F3

Color Key C

F12

Channel Up

F4

Color Key D

Number pad input

Channel number

   #key    #mapping    #remote control    #hidden key    #keyboard event

No, it is not possible to disable the keyboard.

Since some keyboard keys have the same code as the remote controls key, they cannot be disabled. For other keyboard keys, implement a default action to make sure the application does not respond when they are pressed. For more information, see Keyboard/IME.

   #disable    #keyboard    #key    #ime

The Samsung policy requires that the "Exit" key allows the user to exit the application and return to the live broadcast channel immediately from anywhere within the application.

However, there is no Samsung API method that you can use to manually implement this behavior for the "Exit" key. To follow the policy, unregister the "Exit" key and do not handle it in your application. The key's default behavior implements the policy.

In contexts other than the "Exit" key click, you can close the application and all its content by calling the getCurrentApplication().exit() method. For example, a "Return" key click opens a popup with "Yes" and "No" buttons, and selecting the "Yes" button calls the getCurrentApplication().exit() method.

Note Do not open a popup after the "Exit" key click. The "Exit" key click must immediately exit the application, and any other behavior causes your application to fail its certification checks.

   #exit key    #broadcast channel    #show channel    #application exit    #closing application

To customize the IME to show the number pad only, in the input element, set the type attribute to number. This disables all the letter keys and prediction in the IME.

Note On 2015 TV models, this works correctly. However, the 2016 and 2017 TV models do not show the IME correctly. The issue will be fixed in a future firmware release.

For more information on the IME, see Keyboard/IME.

   #IME    #customize    #keyboard    #number pad    #number input type    #num pad

To block a key event, register the key:

tizen.tvinputdevice.registerKey(keys[i]);

The registration blocks the key's default functionality.

   #block    #key    #register    #event    #disable    #prevent

If you register an event for a function key but do not add code to handle the event, the key no longer works. The default function of the key stops working when you register the key event in your application.

Note Do not register keys that are supposed to be handled by the platform, and only register keys that the application uses.

   #smart hub    #power    #key    #broken    #not working

Some Samsung TV remote control keys have separate functionalities for normal and long presses, while others only recognize a normal key press. For information on which keys support long presses, see Remote Control.

   #long press    #key    #remote control    #different key function    #smart remote

No, it is not possible to make the remote control special keys, such as the color or playback control keys, work in the Web browser. The Web browser does not have access to the Samsung Product and Tizen APIs.

   #remote control    #special key    #color key    #playback control key    #web browser    #key mapping

Yes. To set the maximum length for an input element, define the length in characters using the maxlength attribute.

   #html    #input element    #maximum length    #text entry

From your application home screen, you can implement the "Return" key to terminate or hide the application. For more information, see Terminating Applications.

   #return key    #hide    #terminate    #policy    #key mapping    #exit

The Samsung IME supports the standard keyboard characters, such as upper and lower case letters, numbers, punctuation, and symbols.

   #input method editor    #ime    #character    #number    #letter    #punctuation    #symbol    #keyboard

Each remote control key has a key name and corresponding numerical code value. Since keyCode values can differ depending on the TV model and platform version, it is recommended to implement key input using the key names whenever possible.

If you implement keyboard input, the keyboard keys also have key codes.

   #remote control    #key name    #key code    #keyboard    #key mapping

The IME does not display correctly in the emulator. This is a known issue.

   #input method editor    #ime    #emulator    #keyboard    #tv device

The getCurrentApplication().exit() method of the Application API closes the application and all its content. For example, a "Return" key click opens a popup with "Yes" and "No" buttons, and selecting the "Yes" button calls the getCurrentApplication().exit() method. For more information, see Terminating Applications.

Use the getCurrentApplication().hide() method when you do not want to close the application, but only hide it in the background. For more information, see Multitasking.

   #return key    #hide    #exit    #terminate    #multitasking    #application api

To avoid issues with keyboard key presses preventing HTML input elements from working properly, do not implement the preventDefault() method within your keydown and keypress event listeners.

   #html    #input element    #keyboard    #preventdefault    #keydown    #keypress    #no input

The pointer is a feature on the remote control included with 2015 Samsung Smart TV models. The feature allows the user to move the mouse cursor by gesturing with the remote control. To enable pointer support in your application, implement mouse support.

   #pointer    #gesture    #remote control    #mouse    #air pointer

No. Since keyCode values for keyboard keys can differ depending on the TV model and platform version, event handling for specific letter keys is not supported. For more information on handling keyboard and IME input, see Keyboard/IME.

   #ime    #input method editor    #keyboard    #keycode    #letter key    #key event

Other Features

The following questions are related to various TV application features.

Multitasking allows you to save the application state when the user launches another application or TV channel, and restore it when the application is resumed.

To be published on Samsung Apps TV, your application must implement multitasking. For more information, see Multitasking.

Note Applications for the following model groups do not require multitasking:

15_STANDARD2

15_ENTRY

15_BD

All 2014 and older model groups

   #multitasking    #save    #application state

Yes. To offer in-app purchases, you can implement Samsung Checkout in your application. It allows any user with a Samsung Account to register a payment method and use it to make payments on the TV. In addition, Samsung Checkout provides a comprehensive global monetization platform, which allows you to integrate various business models and promotional campaigns into your services. For more information, see Samsung Checkout.

   #samsung checkout    #monetization    #in app purchase    #payment

Samsung Smart TVs support the accessibility toolkit (ATK) as part of the Web engine. If the user has activated the voice guide feature, the text-to-speech (TTS) engine can read HTML elements on the application screen.

Since 2016 models, the voice guide also supports various roles and descriptions based on the WAI-ARIA (Web Accessibility Initiative - Accessible Rich Internet Applications) standard for Web content accessibility.

For information on implementing voice guide support, see Text To Speech.

   #text to speech    #tts    #accessibility    #voice guide

No. Voice control is supported only for TV features, such as opening the search panel or adjusting the volume level. It is not supported within applications.

   #voice control    #voice search    #speech to text

The standard screen resolution for Samsung Smart TV applications is 1920x1080 px for UHD models, and 1280x720 px for FHD models. For information on implementing your application to fit TV screens, see Managing Screen Resolution.

   #screen resolution    #screen size

You can use the AppCommon API to enable and disable the screensaver. For more information, see Setting Screensaver.

   #screensaver    #appcommon api

When an application is hidden, JavaScript execution is paused, which can affect time calculations. To avoid problems, retrieve the time from a server. For more information, see Special Multitasking Scenarios.

   #time    #multitasking

Since 2017 model groups, Samsung TVs have a stability-monitoring feature that automatically terminates processes to free up system memory.

Applications installed through the Tizen Studio for testing can use a maximum 120 MB of memory.

   #system memory    #memory usage    #memory management    #ram usage

Since 2015 models, you can enable or disable the auto update feature for your application, which automatically updates it during regularly-scheduled updates.

On 2015 and 2016 TV models, you can also enable or disable the force update feature for your application, which automatically updates the application when a new version is available, even outside regularly-scheduled updates.

These features are configured in the "config.xml" file. For implementation details, see Meta Data.

   #update    #config xml    #auto update    #force update

No. Overlay applications are not supported on Samsung TVs.

   #overlay

Picture-in-picture (PiP) allows you to display TV source video, such as a TV channel or HDMI input, through a cutout in your application screen. You can implement it using the TVWindow API.

   #picture in picture    #pip    #tvwindow api    #tv source    #tv channel

Yes. To hide the application and move directly to the TV live signal screen, use the launch() method of the Application API to launch the "org.tizen.tv-viewer" application.

   #live signal    #tv channel    #tv broadcast

No. Detecting the attached audio devices is not supported. The user must select the active audio device from the TV menu.

By default, the remote control volume keys adjust only the TV volume, but you can use the TVAudioControl API to control the volume level in your application.

   #audio device    #tvaudiocontrol api    #volume    #speaker    #sound bar

The SSO feature allows users to save login information to their Samsung Account on the device.

To enable SSO in your application, you must add the following code to your "config.xml" file:

y

For information on implementing the SSO feature, see Sso API.

   #single sign on    #sso    #samsung account    #config xml    #sso api    #user login

MLS is a feature on 2014 and 2015 TV models that allows the user to divide the TV screen into 2 parts, showing the TV broadcast signal in 1 part and a running application in the other part.

This feature is enabled by default. If you want to disable it for your Tizen application, add the following line to your "config.xml" file:

   #multi link screen    #mls    #split screen

The Ticker feature, which allowed an application to run as an overlay, is no longer supported. Do not use ticker elements in your "config.xml" file.

Since 2015 TV models, you can implement similar PiP (Picture in Picture) functionality, to show the TV source through a cut-out in the application screen.

   #picture in picture    #pip    #config xml    #ticker    #overlay

The live signal is the broadcast received by the TV, such as through cable or satellite reception.

   #live signal    #broadcast    #cable tv    #satellite tv    #tv channel    #tv source

No. Screen capture is not supported in Samsung TV applications.

   #screen capture    #screenshot

Samsung TVs do not include a built-in parental control solution. You must implement your own in the application.

   #parental control    #age limit    #young audience    #child mode

In general, the serviceName property represents a TV broadcast service, which can have multiple channels defined by channelName properties. The encoding used for these properties depends on the broadcaster.

The sourceID property uniquely identifies a source for scheduled TV programming.

   #tv broadcast    #servicename    #channelname    #sourceid    #tv channel    #tv program

The value of the "'http://samsung.com/tv/metadata/devel.api.version" key within the tizen:metadata element defines the API version used in the application. For compatibility reasons, it is not required to be the latest API version; you can specify the minimum version needed to use all application features.

   #meta data    #api version    #compatibility

No. Since 2015 TV models, applications are automatically paused when they are hidden. For compatibility reasons, in the "config.xml" file, the background-support attribute must be set to "disable". Do not modify it.

   #background support    #config xml    #pause    #multitasking

Make sure that your application is loading the CSS file. Check that your HTML code is valid and that your stylesheet link element is in the following format:

   #css    #stylesheet

The Family Hub platform is not fully compatible with that of Samsung Smart TVs. To enable a Family Hub application to run on a Samsung TV, you must modify the application to meet TV application specifications.

   #family hub    #smart refrigerator

For information on developing applications for Samsung professional display solutions, such as digital signage and hotel TVs, see Samsung D Forum B2B Developers.

   #digital signage    #hotel tv    #professional display    #professional panel

The Samsung D Forum content has been migrated to the Samsung Developers Smart TV site.

   #samsung d forum    #samsung developers    #developer site