Application Development Guide for

(1)

Application Development Guide

for Internet@TV

Year 2010

Version 1.00

(2)

Application Development Guide for Internet@TV

1. Introduction ... 6 1.1. What is Internet@TV? ... 6 2. Samsung Internet@TV... 7 2.1. Operating principle ... 7 2.2. Operating environment ... 7 3. Applications ... 8

3.1. What are applications? ... 8

3.2. Structure of an application... 8

3.3. Display type of applications ... 9

3.4. Running an application ... 10

3.5. Application Manager ... 10

3.6. Features of Samsung applications ... 11

4. Creating an application ... 12

4.1. What you need to create an application ... 12

4.2. How to make an application ... 12

4.2.1. Writing config.xml ... 13

4.2.2. Writing index.html ... 14

4.2.3. Writing JavaScript ... 14

4.2.4. Writing a CSS ... 15

4.2.5. Use of the remote control ... 16

4.2.6. Complete your work & Sample code ... 18

4.3. config.xml ... 21

4.3.1. Tag information ... 21

4.3.2. Example ... 23

4.4. Single-Sign-On ... 25

4.4.1. What is Single-Sign-On ... 25

4.4.2. How Single-Sign-On works ... 25

4.4.3. Necessary Features Developers Should Realize ... 25

4.4.4. Guide for Config.xml ... 25

4.4.5. Guide for Module Realization ... 26

4.4.6. Return Value When Calling CallbackFunc ... 26

4.5. Reset ... 27

4.5.1. What is Reset? ... 27

4.5.2. How Reset Works? ... 27

(3)

Application Development Guide for Internet@TV

4.5.4. Guide for Config.xml Realization ... 27

4.5.5. Guide for Module Realization ... 27

4.6. Example for XHR communication ... 29

5. Common modules ... 32

5.1. Application Manager‟s common modules ... 32

5.2. How to use common modules... 32

5.3. TVKeyValue ... 32 5.4. Widget ... 35 5.4.1. sendReadyEvent()... 35 5.4.2. sendExitEvent() ... 36 5.4.3. sendReturnEvent() ... 36 5.4.4. blockNavigation() ... 36 5.4.5. putInnerHTML()... 37 5.5. Plugin ... 38 5.5.1. setOnWatchDog() ... 39 5.5.2. setOffWatchDog() ... 39 5.5.3. setOnOSDState() ... 40 5.5.4. setOffOSDState() ... 40 5.5.5. registKey() ... 41 5.5.6. unregistKey() ... 41 5.5.7. registIMEKey() ... 41 5.5.8. unregistIMEKey()... 42 5.5.9. registAllKey ... 42 5.5.10. unregistAllKey() ... 42 5.5.11. registFullWidgetKey() ... 43 5.5.12. registPartWidgetKey() ... 43 5.5.13. SetBannerState() ... 44 5.5.14. ShowTools() ... 44

6. Tips for application developers ... 46

6.1. Function necessary to be called when you open an application ... 46

6.2. Access point ... 46

6.3. Handling remote control key events ... 46

6.4. Remote control keys for applications ... 47

6.5. Closing an application ... 48

6.6. Prevention of closing the TV screen by the Return or Exit key ... 48

(4)

Application Development Guide for Internet@TV

6.8. What CSS need to contain ... 49

6.9. Loading images in advance ... 49

6.10. Character of the <input> tag ... 50

6.11. Scroll bar ... 50

6.12. Making dynamic web pages ... 50

6.13. Setting for letter-spacing ... 50

6.14. Memory management ... 51

6.14.1. Using XMLHttpRequest ... 51

6.14.2. Freeing up the memory ... 51

6.15. Watch Dog ... 51

6.16. Prevention for OSD distortion ... 52

6.17. Support CSS text-overflow ... 52

6.18. Directions for creating video application ... 52

6.19. Using IME ... 52

7. Maple browser ... 53

7.1. Maple? ... 53

7.2. Supported standard specifications ... 53

8. File API ... 54 8.1. File API? ... 54 8.2. API ... 54 8.2.1. FileSystem() ... 54 8.2.2. openCommonFile() ... 55 8.2.3. closeCommonFile() ... 55 8.2.4. deleteCommonFile() ... 56 8.2.5. createCommonDir()... 56 8.2.6. deleteCommonDir() ... 57 8.2.7. isValidCommonPath() ... 57 8.2.8. readLine() ... 57 8.2.9. writeLine() ... 58 8.2.10. readAll() ... 58 8.2.11. writeAll() ... 59 9. Appendix ... 60 9.1. Country Code ... 60 9.2. Language Code ... 61 9.3. Region Code ... 62

(5)

Application Development Guide for Internet@TV

Preface

 Purpose of Document

This document is written to help application developers who enjoy the Internet@TV service by providing an overview of the service and basic knowledge required to be obtained by application developers. Using this document, developers can develop and manage applications for digital TVs.

 Target Readers

This document is aimed at programmers who have used web development languages such as HTML, CSS and JavaScript. This document will be even more helpful for those who have web development experience.

(6)

Application Development Guide for Internet@TV

1. Introduction

This section describes what Internet@TV is, how it is configured and how it works.

1.1. What is Internet@TV?

SAMSUNG Internet@TV is a web-based application running on an application engine installed in digital TVs connected to the Internet. The Internet@TV service makes it possible to extend the functions of the TV by applying a variety of web functions to it, so that users can obtain useful information and interesting content on their TV screens. Users can check internet services such as news, weather, stock, UCC with simple operation.

With Internet@TV, digital TV users can not only download applications from HubSite and install them in their TVs but also personally develop applications tailored to their needs and install them in their TVs.

HubSite

PAVV

HubSite

(7)

Application Development Guide for Internet@TV

2. Samsung Internet@TV

This section describes the operating principle and environment of Samsung Internet@TV.

2.1. Operating principle

With Samsung Internet@TV installed in the TV, users can run Internet-based applications on the TV screen. An application is a special type of web page that is implemented on a web browser and runs on the TV screen. Viewing an application is very much like viewing web pages using a web browser on an ordinary PC. Differences between applications and web pages are made by screen resolution, hardware specifications and remote controller, the user interface for Internet@TV installed TVs.

2.2. Operating environment

Browser Maple 5.1

TV screen resolution 960 Ⅹ 540 pixel

We will look at Maple, the browser dedicated to internet TVs manufactured by Samsung, in Chapter 7. Maple.

(8)

Application Development Guide for Internet@TV

3. Applications

This section looks at applications that we will develop for Samsung TVs.

3.1. What are applications?

Applications are web-based small

applications that are run in digital TVs connected to the internet. They are installed in TVs via the Internet and are run on Maple. It is safe to say that they are web pages displayed on the TV screen having the remote control as the only user interface. The Application

Manager (N.Navi.) controls installing and removing applications, and performing other works for them.

You can exploit the Software development kit (SDK) to develop new applications designed to be run on your TV screen.

3.2. Structure of an application

An application is a web page consisting of HTML, CSS and JavaScript, and for Samsung TVs it is run on Maple. The HTML page shows the structure of the application, the CSS file does the style, and the JavaScript file controls the behavior of the application. If you want to run an application on the TV screen, you have to create a config.xml file containing information on the operating environment and the version of the application. If you want to get more information about config.xml, see Ch. 4.3 config.xml.

(9)

Application Development Guide for Internet@TV

3.3. Display type of applications

Display type Description Screen layout

Full-screen application

Fills the entire screen with an application.

Single-wide application

Makes an application displayed only on part of the

screen.

Ticker

Keeps an application on the screen while you do other

things with your TV.

(10)

Application Development Guide for Internet@TV

3.4. Running an application

In order to start an application, you are required to follow the steps below:

Step Instruction description

Get the Application Manager started

Press the INTERNET(INFO.L) button on the remote control or go through Menu> Application>Internet@TV to open the application

Select an application

Press arrow button located in the center of the remote control to select an application.

Implement an application

Press the Enter button to implement an application. The Application Manager reads the information from the config.xml file of the currently running application to set an operating environment, and reads index.html to implement the application.

3.5. Application Manager

The Application Manager serves as a “manager” that has the authority to authenticate, install, delete, update, open and finish applications. With the Application Manager, users can install or delete applications, and also register applications they’ve developed and run them on the TV. The Application Manager is also an application that is continuously updated via the Internet.

(11)

Application Development Guide for Internet@TV

Settings

3.6. Features of Samsung applications

Applications for Samsung Internet@TV allow you to enjoy functions that only TVs have, unlike general web pages. For example, using plugins, you can volume up or down the application and play video other than broadcasting on the TV screen. In addition, you can use a file storage system. If you want to get detailed information on plug-ins and file storage system, refer to Ch. 7 and 8 File API.

The Application Manager provides several JavaScript modules used in applications. This enhances convenience of application development. If you want to get detailed information on use of a common module, see Ch. 5 Common modules.

(12)

Application Development Guide for Internet@TV

4. Creating an application

This section guides you to create a simple application.

4.1. What you need to create an application

Our final goal is to create applications and run them on the TV screen. To this end, you need a Samsung TV connected to the Internet and an SDK or a text editor with which you can write HTML, JavaScript and CSS files. The SDK is equipped with a simulator with which you can run an application you’ve created before actually installing it in your TV. So, if you use an SDK, you can make an application in a more convenient way.

4.2. How to make an application

An application should contain at least the following elements:

 An index.html file. The file serves as the access point of the application.

 An application configuration file. This is an XML file in the root of the application structure that

holds information about setting an application.

 JavaScript files. These are used for a preview of the application and for controlling the behavior of

the application.

 CSS files. The look of the application is determined by these files.

 Image files, which are used by your application.

Let’s make an application that displays text written in CSS and responds to remote control buttons events. The structure and look of an application we will make now are shown as below.

(13)

Application Development Guide for Internet@TV

4.2.1. Writing config.xml

The config.xml file is called first among all the files the application has in it. <ver> tag value decides whether to update the application and images designated in <ThumbIcon> tag are shown in thumbnail. For information about other tags, turn to Ch. 4.3. config.xml.

<?xml version="1.0" encoding="UTF-8"?> <widget>

<ThumbIcon>Resource/image/icon/picasa_106.png</ThumbIcon> <BigThumbIcon>Resource/image/icon/picasa_115.png</BigThumbIcon> <ListIcon>Resource/image/icon/picasa_85.png</BigThumbIcon> <BigListIcon>Resource/image/icon/picasa_95.png</BigThumbIcon> <category>lifestyle</category>

<autoUpdate>y</autoUpdate> <cpname>Junyoung</cpname> <cpauthjs></cpauthjs>

<widgetname>HelloWorld</widgetname> <description>Welcome!</description> <width>960</width>

<name>Samsung Electronics Co. Ltd.</name> <email></email>

<organization>Samsung Electronics Co. Ltd.</organization> </author>

(14)

Application Development Guide for Internet@TV

4.2.2. Writing index.html

What you have to do next is writing index.html which will be the access point of the application. The following example is about HTML code that includes the Main.js file under the JavaScript folder and calls the Main.onLoad() function when the document is loaded.

<!DOCTYPE html> <html>

<head>

<div>Welcome to Samsung application world!</div> </body>

</html>

4.2.3. Writing JavaScript

If the HTML document is loaded, the onLoad() function of the Main object is called, because you

registered the Main.onLoad() function in the onload property in the <body> tag. Make a Main object

and add the onload function.

var Main = { // Main object

}

Main.onLoad = function () { // called by <body>'s onload event alert("Main.onLoad()");

/**

*JavaScriptcodeHere! */

}

If you have done all the work, you will get a debug message of Main.onLoad(). But the ‘Welcome to Samsung application world!’ that you entered will not appear on the TV screen. If the application is successfully loaded, it has to ask the Application Manager to display itself on the screen using the common module provided by the Application Manager. The common module is a library containing essential functions provided by the Application Manager. For more information, refer to Ch. 5

(15)

Application Development Guide for Internet@TV

src="$MANAGER_WIDGET/Common/API/Widget.js"></script>

If the above code is added, a common module is available to use by JavaScript. Declare the common module as a global variable for Main.js you were working on and call the sendReadyEvent() function. By doing this, you can make the Application Manager display an application on the screen.

}

var widgetAPI = new Common.API.Widget(); // Create Common module

Main.onLoad = function () { // called by <body>'s onload event alert("Main.onLoad()");

widgetAPI.sendReadyEvent(); // Send ready message to Application Manager /**

}

Ok, now run the application you‟ve just made. You will see the words “Welcome to Samsung application

world!” that you entered in the index.html file appearing on the screen. Maybe you don‟t like the look of the application because its font size is too small and font color is just simple black. You may want to make your application more stylish. Then, you can give the application a style using CSS.

4.2.4. Writing a CSS

Add the following string in

<

head

>

in the index.html file.

Assign an ID to

<

div

>

in the index.html file.

<div id='welcome'>Welcome to Samsung application world!</div>

Create a file in the CSS folder and enter text as you see in the below box to specify the style of the

„welcome‟ element.

body{

margin: 0; padding: 0;

(16)

Application Development Guide for Internet@TV

background-color:transparent; } #welcome{ position:absolute; left: 50px; top: 50px; width: 500px; height: 50px; background-color: #AFAFAF; color: #99FFFF; font-size: 30px; text-align:center; }

4.2.5. Use of the remote control

Now, we‟ll make your application respond to the remote control. By pressing any of the five buttons

located in the center of the remote control, you can change the words your application displays on the screen.

If a button on the remote control is pressed, a ‘keydown’ event occurs. An element having focus is required to receive the event to the index.html file. Add <a> element and Register a function that will

be executed when that event occurs in the onkeydown property. Place focus on <a> and press the

remote control key, the function registered previously is executed.

Add <a> which executes Main.keyDown() method when a ‘keydown’ event occurs.

<div id='welcome'>Welcome to Samsung application world!</div>

Write a keyDown() method bringing key code value when pressing the remote control key

Main.keyDown = function(){ // Key handler var keyCode = event.keyCode;

alert("Main Key code : " + keyCode); }

In a function processed by keys such as keydown(), each key has its own key code value.

(17)

Application Development Guide for Internet@TV

Add the below code to <head> in the index.html file to use a common module „TVKeyValue‟.

src="$MANAGER_WIDGET/Common/API/TVKeyValue.js"></script>

Modify Main.js in order to change the contents of „welcome‟ Div. This creates common module objects, classify keys in keydown() method, and define actions for each key. For detailed information on common modules and key code list, see Chapter 5. Common Modules.

}

var widgetAPI = new Common.API.Widget(); // Create Common module var tvKey = new Common.API.TVKeyValue();

Main.onLoad = function(){ // called by <body>'s onload event alert("Main.onLoad()");

widgetAPI.sendReadyEvent(); // Send ready message to Application Manager document.getElementById("anchor").focus(); // Focus to Anchor for handling key inputs

// from remote controller /**

}

alert("Main Key code : " + keyCode);

switch (keyCode) {

case tvKey.KEY_LEFT: alert("left");

document.getElementById("welcome").innerHTML = "Nice to meet you."; /**

*CodeforLeftkeyevent! */

break;

case tvKey.KEY_RIGHT: alert("right");

document.getElementById("welcome").innerHTML = "I'm so happy."; break;

case tvKey.KEY_UP: alert("up");

document.getElementById("welcome").innerHTML = "I Love you."; break;

case tvKey.KEY_DOWN: alert("down");

document.getElementById("welcome").innerHTML = "Good job."; break;

case tvKey.KEY_ENTER: alert("enter");

(18)

Application Development Guide for Internet@TV

break; case tvKey.KEY_RETURN: break; } }

You will see the value of the „welcome‟ Div tag change as you press the up, down, left or right button.

4.2.6. Complete your work & Sample code

With Samsung Internet@TV, you can do almost everything you do on a web page. You can create

“TV-oriented” applications with extended functions using many plugins.

The below are the codes we‟ve written until now.

4.2.6.1. config.xml

<previewjs>PreviewHelloWorld</previewjs> <cpname>Junyoung</cpname>

<cplogo>Resource/image/settings_logo.png</cplogo> <cpauthjs></cpauthjs> <ver>0.930</ver> <mgrver>1.000</mgrver> <fullwidget>n</fullwidget> <srcctl>n</srcctl> <ticker>n</ticker> <childlock>n</childlock> <audiomute>n</audiomute> <videomute>n</videomute> <dcont>y</dcont>

<widgetname>HelloWorld</widgetname> <description>Welcome!</description> <width>960</width>

<name>Samsung SDS</name> <email></email>

(19)

Application Development Guide for Internet@TV

4.2.6.2. index.html

<!DOCTYPE html> <html>

<head>

<div id='welcome'>Welcome to Samsung widget world!</div>

</html>

4.2.6.3. Main.js

}

var widgetAPI = new Common.API.Widget(); // Create Common module var tvKey = new Common.API.TVKeyValue();

Main.onLoad = function(){ // called by <body>'s onload event alert("Main.onLoad()");

widgetAPI.sendReadyEvent(); // Send ready message to Application Manager document.getElementById("anchor").focus(); // Focus to Anchor for handling key inputs

// from remote controller /**

}

alert("Main Key code : " + keyCode);

case tvKey.KEY_LEFT: alert("left");

document.getElementById("welcome").innerHTML = "Nice to meet you."; /**

*CodeforLeftkeyevent! */

(20)

Application Development Guide for Internet@TV

break;

case tvKey.KEY_RIGHT: alert("right");

document.getElementById("welcome").innerHTML = "I'm so happy."; break;

case tvKey.KEY_UP: alert("up");

document.getElementById("welcome").innerHTML = "I Love you."; break;

case tvKey.KEY_DOWN: alert("down");

document.getElementById("welcome").innerHTML = "Good job."; break; case tvKey.KEY_ENTER: alert("enter"); break; case tvKey.KEY_RETURN: break; } } 4.2.6.4. Main.css body{ margin: 0; padding: 0; background-color:transparent; } #welcome{ position:absolute; left: 50px; top: 50px; width: 500px; height: 50px; background-color: #AFAFAF; color: #99FFFF; font-size: 30px; text-align:center; }

(21)

Application Development Guide for Internet@TV

4.3. config.xml

The config.xml file contains information about the application’s execution, update, operating environment setting and other related issues. Depending on that information, the Application Manager controls the version of your application, sets an environment in which your application is run, and creates and manages user accounts. The config.xml file should be located in the directory in which the application is installed, and contain the following elements.

4.3.1. Tag information

Element Description Value

<widget> Indicates that the information is relevant to the application. -

<ThumbIcon> An icon image displayed in the Application Manager.

It is used in case of no focus and its size is 106 x 87 pixel. File path

An icon image displayed in the Application Manager.

It is used in case that the focus is placed on an image and its size is 115 x 95 pixel.

File path

<ListIcon> An icon image displayed in the Application Manager.

The size is 85 x 70 pixel. File path

<BigListIcon> An icon image displayed in the Application Manager.

The size is 95 x 78 pixel. File path

<category> The category to distinguish applications, available items are video,

sports, game, lifestyle, information, others. String

<autoUpdate> Decides whether to synchronize with hub site. The

application which doesn’t need synchronization chooses ’n’. y | n

<apptype> Shows information on contents type.(11:javascript, 12: flash, 13:

game, …) Number

<contents> File route at the initial execution of contents (Limited to

non-Javascript based applications) File Path

<channelType> Channel Bound Service Type(optional) root | child

Confirms the relations with root-child clarifying root application ID. (Optional, Only when the channel bound service type is child.)

When connected to more than one root, roots are distinguished by ::.

Application ID

Channel information to be executed channel bound service (Distinguish each channel using :: Ex AAA::BBB::CCC)

(Optional, only if channel bound service type is root.)

(22)

Application Development Guide for Internet@TV

It decides whether the installed channelbound service is displayed on the first main screen or not.

(If you want to hide the service in the first main screen, select „n‟.)

y | n

<cpname> Enter the application provider in this tag. String

The name of the JavaScript file that allows you to confirm account information of application providers. This file has to be written in a defined format.

String

<login>

Decides a service is available to signin or not. If you select ‘y’, you can enter ID and password in Integrated Sign-in site of Application Manager for sign-in. Validity verification should be preceded in JavaScript file corresponding to <cpauthjs> tag value.

y | n

<ver>

Indicates the application version. Depending on that version information, the server computer updates the corresponding application.

x.xxx

<mgrver> Indicates the Application Manager’s version that is required to run an

application having the config.xml file. x.xxx

Indicates whether the application is a full-screen or a single-wide one. Display type affects the audio policy of the application when it’s run.

y | n

If source conversion is needed, set this tag to y. (ex. YouTube application).

If you select ‘y’, the TV source automatically switched from current TV channel or external input to the internal media player, and back again when the application is finished.

y | n

<childlock> Determines whether to use the childLock function. This function

enables the user to lock an application. y | n

Turns on and off the audio. If you select ‘y’, TV broadcasting sound is not outputted when entering the application. Set ‘y’ if the application occupies full screen and set ‘n’ if the application occupies parts of the screen.

y | n

<videomute> Turns on and off the video. If you select ‘y’, TV broadcasting is not

on the screen when entering the application. y | n

<dcont>

Sets the Disable dynamic contrast function.

Dynamic contrast is the function to adjust TV contrast ratio and brighten TV screen by darkening the dark screen and lightening the light screen. The screen might get lighter or darker when application

(23)

Application Development Guide for Internet@TV

is on with Dynamic contrast.

‘y’ turns off the Dynamic contrast, and ‘N’ turns on the Dynamic contrast. If the application is occupied on full screen, select ‘y’ to remove sparkling. If the application is partially occupied, select ‘n’.

<movie>

Application playing video files can bring problems as stated below. 1. If a video file is played in a device connected to HDMI port such as DVD Player when executing an application (ex. YouTube) converting sources, sounds can be mixed.

2. Sparkling at the entry for appliction due to the difference of Frame rate between the TV image and playing video file.

If you select ‘y’, you can prevent it from the problem above by ending operating the connected HDMI device when executing the application and fixing the Frame rate.

y | n

<widgetname> Enter a name of application. String

<description> Enter a brief description of the application. String

Enter the screen area that the application will be occupying. Generally, it is recommended to enter 960 * 540 pixels, digital TV specification.

Number

<author> Enter a description of the author. string

4.3.2. Example

<ThumbIcon>Resource/image/icon/picasa_106.png</ThumbIcon> <BigThumbIcon>Resource/image/icon/picasa_115.png</BigThumbIcon> <ListIcon>Resource/image/icon/picasa_85.png</ListIcon>

<BigListIcon>Resource/image/icon/picasa_95.png</BigListIcon> <category>lifestyle</category>

<autoUpdate>y</autoUpdate> <cpname>Picasa</cpname>

(24)

Application Development Guide for Internet@TV

<widgetname>Picasa Web Albums</widgetname> <description>View photo albums online</description> <width>960</width>

<name>Samsung Electronics Co. Ltd.</name> <email></email>

<organization>Samsung Electronics Co. Ltd.</organization> </author>

(25)

Application Development Guide for Internet@TV

4.4. Single-Sign-On

This section describes what the application needing to sign-in realizes.

4.4.1. What is Single-Sign-On

Single-Sign-On(hereinafter referred to as “SSO”) is the function to save ID/Password through one time ID/Password authorization process in the unit and enhance user convenience if sign-in application has been installed in ContentsHome.

4.4.2. How Single-Sign-On works

1. Once SSO starts to operate, ContentsHome brings information on config.xml of the all of installed applications.

2. ContentsHome decides the application is available to sign-in with certain information form Config.xml.

3. If the application is available to sign-in, it brings descriptions on authorization module of the application.

4. The module is executed according to the rules and ContentsHome received the result of authorization.

5. When the authorization has been completed as it should be, save the ID and Password used in the authorization in the TV unit.

6. Later, when operating the application, enter the saved ID and Password in the application

4.4.3. Necessary Features Developers Should Realize

1. Peculiar information in Config.xml(Refer to Chapter 4)

2. Module able to authorize ID and Password (Refer to Chapter 4)

4.4.4. Guide for Config.xml

(ex)

<cpname>YouTube</cpname> <cpauthjs>Youtube</cpauthjs>

Element

Form

Description

(26)

Application Development Guide for Internet@TV

selected to sign up for ID/Password in SSO.

<cpname> English Word Abbreviation for Contents Provider Name, the peculiar tag recognized in SSO should be unique and if there is an identical name, the last authorized module is mapped to the tag.

<cpauthjs> English Word If JavaScript file name and Class name is XXXX.js, the JavaScript class name should be XXXX.

4.4.5. Guide for Module Realization

1. File name and Class name should be identical.

2. Factor consists of ID, Password, and callback function.

3. Callback function should be called to close the module, unless, the result will not be the expected one.

(ex)

var Youtube = { …

}

Youtube.checkAccount = function(id, pw, callbackFunc) { ...

...

callbackFunc("TRUE"); }

4.4.6. Return Value When Calling CallbackFunc

CallbackFunc is able to be executed with the return value stated below.

Return value

Description

“TRUE” Authorization Completed. Saves ID and Password in SSO. “FALSE” Wrong ID and Password. Let the user enter them again.

“ERROR” Decided as Network errors in SSO. Later, let the user try again. Others The same as “ERROR”

(27)

Application Development Guide for Internet@TV

4.5. Reset

Reset describes functions to initialize the application.

4.5.1. What is Reset?

The function to execute initial modules realized by applications when deleting or initializing applications in Application Manager.

4.5.2. How Reset Works?

1. Application Manager brings information in config.xml of the installed application when deleting/initializing.

2. Check if the application needs a module which initializes through the information in config.xml. 3. If the application has the module that initializes, bring information on the module.

4. Execute the module in accordance with rules and try initializing.

* Application Manager does not obtain any return value but operate the module to initialize.

4.5.3. Necessary Features Developers Should Realize

1. Peculiar Information on config.xml(Refer to Chapter 4) 2. Initialization Module (Refer to Chapter 5)

4.5.4. Guide for Config.xml Realization

Add xml Element as shown below.

<deleteJS>MyReset</deleteJS>

* Without deleteJS Element, the application does not operate the initialization module.

4.5.5. Guide for Module Realization

1. The file name should be the same as class name. 2. No factor.

3. The name of function is “reset”.

(28)

Application Development Guide for Internet@TV

… } MyReset.reset = function() { ... ... alert("Reset Complete!"); }

(29)

Application Development Guide for Internet@TV

4.6. Example for XHR communication

In this section, we‟ll look at an example for XHR communication, which is a key factor comprising

AJAX technology.

The below example is HTML code that includes XHRExample.js, and executes the

XHRExample.onload() function when the „load‟ event occurs.

<!DOCTYPEhtml>

<metahttp-equiv="Content-Type"content="text/html; charset=utf-8"> <title>XHR Example</title>

<scripttype="text/javascript"language="javascript"

src="$MANAGER_WIDGET/Common/API/Widget.js"></script>

<scripttype="text/javascript"language="javascript"src="XHRExample.js"></script> </head>

<bodyonload="XHRExample.onload()">

<divid='intro'>XHR Example.</div>

</body> </html>

The below is JavaScript code. XHRExample is has been declared as an object and has the variable of XHRObj in it. If XHRObj already exists, XHRExample calls the destroy() method. We will look at this more specifically later in this chapter. If an XHR object has been successfully created, set it and

request data. If the state of XHR changes to 4, which means data reception is completed, recieveData()

that you registered in onreadystatechange is executed.

var XHRExample ={

XHRObj :null

}

var tvKey =new Common.API.TVKeyValue();

var widgetAPI =new Common.API.Widget();

XHRExample.onload =function(){

widgetAPI.sendReadyEvent();

(30)

Application Development Guide for Internet@TV

if(this.XHRObj !=null)

this.XHRObj.destroy();

this.XHRObj =new XMLHttpRequest();

if(this.XHRObj){

this.XHRObj.onreadystatechange =function(){

if(XHRExample.XHRObj.readyState ==4){

XHRExample.recieveData(); }

};

this.XHRObj.open("GET", URL,true);

this.XHRObj.send(null); }

}

XHRExample.recieveData =function(){

alert(this.XHRObj.responseText); }

The above example has two remarkable points. One is that the variable of XHRObj is in the XHRExample object. The other is that the destroy() method is called before an object is assigned to XHRObj.

With Samsung TVs, if you run out of the memory by continuing to create and use the XHR object, applications in your TV do not work anymore at a certain time. In order to avoid this kind of situation, you should delete objects you used in the past and assign new ones when you use XHR. To free up objects that had been used, the object pointer should be maintained. For this, developers should memorize and manage the variable dealing with XHR objects.

If you want to remove an XHR object from the memory, use the destroy() method of it, and this is the method that Maple provides to allow you to use the limited memory efficiently.

XHRObjet.destroy

Free up the XHR object you created from the memory.

Syntax XHRObject.destroy() Parameter none

(31)

Application Development Guide for Internet@TV

Remarks This function, which is executed to optimize the memory usage, is only provided by Maple for Samsung TV users.

Example

if(this.XHRObj !=null)

this.XHRObj.destroy();

this.XHRObj =new XMLHttpRequest();

In the above example, two common modules provided by the Application Manager are included. For more information, turn to Ch. 5 Common modules.

(32)

Application Development Guide for Internet@TV

5. Common modules

In this section, we will look at a library shared by all your applications.

5.1. Application Manager’s common modules

The Application Manager provides object modules that all your applications can use. Those common modules enable your applications to do basic work to be normally running on the screen. Also, using common modules, individual applications can recognize and identify remote control button events, use plugins, and communicate with the Application Manager in more convenient and simpler ways.

5.2. How to use common modules

 Include common modules you want to use in the index.html file. In order to prevent occurrence of any parsing order error, it is recommended that you include them at the top of the document.

„$MANAGER_WIDGET‟ allows your applications to access common modules provided by the

Application Manager.

* In SDK, „$MANAGER_WIDGET‟ points the „commonlib‟ folder that SDK installed in.

 Create an object.

 Use known member variable and method.

alert(tvKey.KEY_LEFT);

5.3. TVKeyValue

TVKeyValue

An object that defines TV key code.

(33)

Application Development Guide for Internet@TV

Syntax new Common.API.TVKeyValue()

Parameter none

Return Value TVKeyValue object

Remarks This is an object having key code used by the TV as a member variable, and identifies remote control keys pressed by the user by referring to member variables.

Example

switch(KEY_CODE){

case tvKey.KEY_LEFT:

// Do something

break;

case tvKey.KEY_RIGHT:

// Do something break; default: break; } Members  KEY_TOOLS  KEY_MUTE  KEY_RETURN  KEY_UP  KEY_DOWN  KEY_LEFT  KEY_RIGHT  KEY_WHEELDOWN  KEY_WHEELUP  KEY_ENTER  KEY_INFO  KEY_EXIT  KEY_RED  KEY_GREEN  KEY_YELLOW  KEY_BLUE  KEY_INFOLINK  KEY_RW  KEY_PAUSE  KEY_FF  KEY_PLAY  KEY_STOP

(34)

Application Development Guide for Internet@TV

 KEY_1  KEY_2  KEY_3  KEY_4  KEY_5  KEY_6  KEY_7  KEY_8  KEY_9  KEY_0  KEY_EMPTY  KEY_PRECH  KEY_SOURCE  KEY_CHLIST  KEY_MENU  KEY_WLINK  KEY_CC  KEY_CONTENT  KEY_FAVCH  KEY_REC  KEY_EMODE  KEY_DMA  KEY_PANEL_CH_UP  KEY_PANEL_CH_DOWN  KEY_PANEL_VOL_UP  KEY_PANEL_VOL_DOWN  KEY_PANEL_ENTER  KEY_PANEL_SOURCE  KEY_PANEL_MENU  KEY_PANEL_POWER Methods none

(35)

Application Development Guide for Internet@TV

5.4. Widget

This is an object that has functions needed for desirable operation of an application. A method that notifies the Application Manager of starting of an application, a method that registers and frees up keys users want to use, and other methods are contained in this object.

Widget

Object having functions needed for desirable operation of an application

Library path $MANAGER_WIDGET/Common/API/Widget.js Syntax new Common.API.Widget()

Parameter none

Return Value Widget object Remarks none

Example var widgetAPI =new Common.API.Widget(); widgetAPI. sendReadyEvent(); Members none Methods  sendReadyEvent  sendExitEvent  sendReturnEvent  blockNavigation  putInnerHTML

5.4.1. sendReadyEvent()

sendReadyEvent

Notifies the Application Manager that the application is ready to be displayed. This event should be passed to display and run the application on the screen.

Syntax sendReadyEvent() Parameter none

Return Value none Remarks none

Example var widgetAPI =new Common.API.Widget(); widgetAPI.sendReadyEvent();

(36)

Application Development Guide for Internet@TV

Enumeration none

5.4.2. sendExitEvent()

sendExitEvent

Brings the same effect as pressing the exit key. Stops the application and goes back to the TV screen.

Syntax sendExitEvent() Parameter none

Example var widgetAPI =new Common.API.Widget(); widgetAPI.sendExitEvent ();

5.4.3. sendReturnEvent()

sendReturnEvent

Brings the same effect of pressing the Return key. Finishes the application and takes you to the Application Manager.

Syntax sendReturnEvent() Parameter none

Example var widgetAPI =new Common.API.Widget(); widgetAPI.sendReturnEvent ();

5.4.4. blockNavigation()

blockNavigation

Key event cannot be forced to return.

(37)

Application Development Guide for Internet@TV

Parameter keyEvent: Key event

Return Value none

Remarks KEY_RETURN and KEY_EXIT events forcibly close the operating application. The func prevents forced closure and keep being executing.

Example

function keyDown () {

switch(event.keyCode) {

casethis.tvKey.KEY_LEFT: // Do something break;

casethis.tvKey.KEY_RIGHT: // Do something break;

casethis.tvKey.KEY_RETURN:

widgetAPI.blockNavigation(event); // Not terminated

break;

casethis.tvKey.KEY_EXIT: // Terminated by force break; default: break; } } Enumeration none

5.4.5. putInnerHTML()

putInnerHTML

innerHTML method to fix memory issues.

Syntax putInnerHTML(div, contents)

Parameter div: Div Element to use innerHTML contents: Things to insert in innerHTML Return Value none

Remarks Required to use this method because repetitive use of innerHTML can occur memory issues.

Example

var widgetAPI = new Common.API.Widget();

var divElement = document.getElementById("divID"); var contents = "Text to change";

widgetAPI.putInnerHTML(divElement, contents); Enumeration none

(38)

Application Development Guide for Internet@TV

5.5. Plugin

The Application Manager provides a wrapper class that allows you to use some plugin functions in more convenient ways. If you want to take advantage of this class, just insert objects needed for use of plugins in the index.html document. Then, the Application Manager will give you an appropriate class method.

Plugin

Object that is wrapped for convenient use of plugins

Library path $MANAGER_WIDGET/Common/API/Plugin.js Syntax new Common.API.Plugin()

Parameter none

Return Value Plugin object Remarks none

Example var pluginAPI =new Common.API.Plugin(); pluginAPI.setOnWatchDog(); Members None Methods Object ID : pluginObjectTVMW  setOnWatchDog  setOffWatchDog  registKey  unregistKey  registIMEKey  unregistIMEKey  registAllKey  unregistAllKey  registFullWidgetKey  registPartWidgetKey Object ID : pluginObjectVideo  setOnOSDState  setOffOSDState Object ID : pluginObjectVideo  setOnOSDState  setOffOSDState

(39)

Application Development Guide for Internet@TV

Object ID : pluginObjectNNavi  SetBannerState  ShowTools Object list  pluginObjectTVMW

<OBJECT id='pluginObjectTVMW' border=0 classid='clsid:SAMSUNG-INFOLINK-TVMW' style='opacity:0.0;background-color:#000000;width:0px;height:0px;'></OBJECT>  pluginObjectVideo

 pluginObjectNNavi

<OBJECT id='pluginObjectNNavi' classid='clsid:SAMSUNG-INFOLINK-NNAVI'

style='opacity:0.0;background-color:#000000;width:0px;height:0px;'></OBJECT>

5.5.1. setOnWatchDog()

setOnWatchDog

Turns on the Watch dog function. Syntax setOnWatchDog() Parameter none

Example var pluginAPI = new Common.API.Plugin(); pluginAPI.setOnWatchDog();

5.5.2. setOffWatchDog()

setOffWatchDog

Turns off the Watch dog function.

Syntax setOffWatchDog() Parameter none

(40)

Application Development Guide for Internet@TV

Example var pluginAPI = new Common.API.Plugin(); pluginAPI.setOffWatchDog();

5.5.3. setOnOSDState()

setOnOSDState

Sets the area where OSD is protected.

Syntax setOnOSDState(left, top, width, height)

Parameter

left : left coordinate of the area top : top coordinate of the area width : width of the area height : height of the area Return Value none

Remarks none

Example var pluginAPI = new Common.API.Plugin(); pluginAPI.setOnOSDState(0,0, 330, 540); Enumeration none

5.5.4. setOffOSDState()

setOffOSDState

Cancels the previously set OSD area.

Syntax setOffOSDState(left, top, width, height)

Parameter

left : left coordinate of the area top : top coordinate of the area width : width of the area

height : height of the area Return Value None

Remarks none

Example var pluginAPI = new Common.API.Plugin(); pluginAPI.setOffOSDState(0,0, 330, 540); Enumeration none

(41)

Application Development Guide for Internet@TV

5.5.5. registKey()

registKey

Let the Application Manager register specific key Syntax registKey(pNumKeyCode) Parameter pNumKeyCode: key code Return Value none

Remarks none

Example var pluginAPI = new Common.API.Plugin(); pluginAPI.registKey(tvKey.KEY_ TOOLS); Enumeration none

5.5.6. unregistKey()

unregistKey

Let the Application Manager unregister specific key Syntax unregistKey(pNumKeyCode) Parameter pNumKeyCode: key code Return Value none

Remarks none

Example var pluginAPI = new Common.API.Plugin(); pluginAPI.unregistKey(tvKey.KEY_ TOOLS);

5.5.7. registIMEKey()

registIMEKey

Let the Application Manager register IME key Syntax registIMEKey()

Parameter none Return Value none

(42)

Application Development Guide for Internet@TV

Example var pluginAPI = new Common.API.Plugin(); pluginAPI.registIMEKey();

5.5.8. unregistIMEKey()

unregistIMEKey

Let the Application Manager unregister IME key Syntax unregistIMEKey()

Remarks Frees up the 0~9, -, PRE-CH keys that are used when entering IME.

Example var pluginAPI = new Common.API.Plugin(); pluginAPI.unregistIMEKey();

5.5.9. registAllKey

registAllKey

Let the Application Manager register all keys Syntax registAllKey()

Remarks Register all the keys.

Example var pluginAPI = new Common.API.Plugin(); pluginAPI.registAllKey();

5.5.10. unregistAllKey()

unregistAllKey

(43)

Application Development Guide for Internet@TV

Syntax unregistAllKey()

Remarks Close all the keys.

Example var pluginAPI = new Common.API.Plugin(); pluginAPI.unregistAllKey();

5.5.11. registFullWidgetKey()

registFullWidgetKey

Let the Application Manager register specific key group Syntax registFullWidgetKey()

Remarks Register keys for full-screen applications. Example var pluginAPI = new Common.API.Plugin();

pluginAPI.registFullWidgetKey(); Enumeration none

5.5.12. registPartWidgetKey()

registPartWidgetKey

Let the Application Manager register specific key group Syntax registPartWidgetKey ()

Remarks Register keys for single-wide applications.

Example var pluginAPI = new Common.API.Plugin(); pluginAPI. registPartWidgetKey ();

(44)

Application Development Guide for Internet@TV

5.5.13. SetBannerState()

SetBannerState

A function using when you want to put volume and channel OSD with the application. Syntax SetBannerState (nState)

Parameter

nState : Defined value on OSD you want to bring with the application. PL_NNAVI_STATE_BANNER_NONE = 0;

PL_NNAVI_STATE_BANNER_VOL = 1; PL_NNAVI_STATE_BANNER_VOL_CH = 2; Return Value None

Remarks When you intend to bring up volume OSD on the screen, volume key value should be registered. So does channels. See an example.

Example

var PL_NNAVI_STATE_BANNER_NONE = 0; var PL_NNAVI_STATE_BANNER_VOL = 1; var PL_NNAVI_STATE_BANNER_VOL_CH = 2;

var pluginAPI = new Common.API.Plugin(); var tvKey = new Common.API.TVKeyValue();

pluginAPI.unregistKey(tvKey.KEY_VOL_UP); pluginAPI.unregistKey(tvKey.KEY_VOL_DOWN); pluginAPI.SetBannerState(PL_NNAVI_STATE_BANNER_VOL); Enumeration none

5.5.14. ShowTools()

ShowTools

A function to bring popup windows for screen and sound adjustment. Syntax ShowTools (nTool)

Parameter

nTool: Defined value on a popup window you want to bring. 0 : Sound Setting popup

1 : Picture Setting popup Return Value None

(45)

Application Development Guide for Internet@TV

Remarks You can see the point when the popup window is closed by signing up for curWidget.onWidgetEvent.

Example

curWidget.onWidgetEvent = function(){

// a code that will be executed after closing the popup window }

var pluginAPI = new Common.API.Plugin(); pluginAPI.ShowTools(1);

(46)

Application Development Guide for Internet@TV

6. Tips for application developers

This section describes several pieces of information that are useful for application developers.

6.1. Function necessary to be called when you open an application

For an application to be run, it should ask the Application Manager to display itself on the screen. Only when the Application Manager is requested to do so, it displays the corresponding application on the screen. Any request should be made through a common module. Call the sendReadyEvent() method of the Widget object in the common module.

var widgetAPI = new Common.API.Widget(); // Create Common module widgetAPI.sendReadyEvent(); // Send ready message to Application Manager

6.2. Access point

Whenever you open an application, the Maple browser reads the index.html document. If you implement an application by selecting an application and clicking Enter in the Application Manager,

the browser starts to read the index.html document. Register a JavaScript function in the „onload‟

property so that when the <body> load event occurs, the application is started. The application must

calls sendReadyEvent() of the Widget object in the common module.

6.3. Handling remote control key events

If any button on the remote control is pressed, the „keydown‟ event occurs. This event is passed to an

element receiving focus at the point of time when the event occurs. If the element has registered a

function in the „onkeydown‟ property, that function is executed. The function identifies which button is

pressed using event.keyCode.

You should note that an element that is supposed to respond to the „keydown‟ event should be

receiving focus. If there‟s no element receiving focus, there will be no relation on the TV screen even

though you press a remote control button.

(47)

Application Development Guide for Internet@TV

Look at the example below. Insert an element that will have focus in index.html.

Create a function that will be registered in the „onkeydown‟ property.

Main.keyDown = function(){ // Key handler

var keyCode = event.keyCode; alert("Main Key code : " + keyCode);

case tvKey.KEY_LEFT: /**

*CodeforLeftkeyevent! */ break; case tvKey.KEY_RIGHT: break; case tvKey.KEY_UP: break; case tvKey.KEY_DOWN: break; case tvKey.KEY_ENTER: break; case tvKey.KEY_RETURN: break; } }

6.4. Remote control keys for applications

If you access an application, the Application Manager registers basic keys relevant to it. The Manager

depends on the <fullwidget> tag in the config.xml file to determine whether the keys are for

full-screen or single-wide applications.

Full-screen application

Single-wide application

KEY_VOL_UP KEY_VOL_DOWN KEY_MUTE KEY_TOOLS KEY_INFO KEY_EMODE KEY_DMA KEY_MENU KEY_SOURCE KEY_PRECH KEY_FAVCH KEY_CHLIST KEY_1 KEY_2 KEY_3 KEY_4 KEY_5 KEY_6 KEY_7 KEY_8 KEY_9 KEY_0 KEY_WHEELDOWN KEY_WHEELUP KEY_WHEELDOWN KEY_WHEELUP KEY_RED KEY_GREEN KEY_YELLOW KEY_BLUE KEY_RW KEY_PAUSE KEY_FF KEY_PLAY KEY_STOP KEY_ENTER

(48)

Application Development Guide for Internet@TV

KEY_DMA KEY_TTX_MIX KEY_GUIDE KEY_SUBTITLE KEY_ASPECT KEY_DOLBY_SRR KEY_MTS KEY_PANEL_CH_UP KEY_PANEL_CH_DOWN KEY_PANEL_VOL_UP KEY_PANEL_VOL_DOWN KEY_PANEL_ENTER KEY_PANEL_SOURCE KEY_PANEL_MENU KEY_RED KEY_GREEN KEY_YELLOW KEY_BLUE KEY_RW KEY_PAUSE KEY_FF KEY_PLAY KEY_STOP KEY_ENTER KEY_RETURN KEY_EXIT KEY_RETURN KEY_EXIT

Individual applications can register or delete keys they want to use by utilizing the method of the

Widget object in the common module. For detailed information, refer to Ch. 5 Common module.

6.5. Closing an application

There are two ways to close your application working on the screen: pressing the Return or Exit button on the remote control or sending an event to the Application Manager. For the latter way, you use the sendExitEvent() and sendReturnEvent() functions of the Widget which is the common module. For more information, see Ch.5 Common module.

6.6. Prevention of closing the TV screen by the Return or Exit key

Using the Return or Exit key on the remote control, you can close applications. If you press the Return key, you will be taken to the Application Manager, and if you press the Exit key, you will be taken to the TV screen. In order to prevent this from happening, when either Return or Exit is pressed, the blockNavigation() function of the Widget which is the common module has to be executed. For more information, see Ch.5 Common modules.

6.7. Additional information available when applications are implemented

When an application is run, the Application Manager gives you additional information. The application

gets such information by referring to window.location.search. The below is an example.

?country=US&language=1&modelid=Valencia&server=development&remocon=2_35_259&area=USA&id=ori59 [email protected]&pw=pxxxx

(49)

Application Development Guide for Internet@TV

Attribute Value Description

country Country code Country code that has already been assigned. Refer to Chapter 9.1.

language Language code Language code that has already been assigned. Refer to Chapter 9.2.

modelid Digital TV Model ID Digital TV Model ID

server development | operating server type: Development Server or Operating Server

remocon - No use

area Region Code Region code that has already been assigned. Refer to chapter9.3.

Id string Id inputted in SSO. It is passed only when entering application after sign-in.

pw string Pw inputted in SSO. It is passed only when entering application after sign-in.

6.8. What CSS need to contain

The element created in the margin beyond the maximum TV resolution(960 x 540 pixel) can cause the display to scroll. All the element margins and paddings in the index.html document should be defaulted to 0 to prevent the matter resulted from going beyond the area. Your CSS should contain the following strings.

body{

margin: 0; padding: 0;

background-color:transparent; }

6.9. Loading images in advance

The Maple browser decodes images to make them displayed normally on your screen. If the browser continues to change images that are displayed at a high speed, it may fail to display images on the screen due to unfinished decoding process. To avoid this, you can load and keep images before you actually use them. By doing this, you can save the time for image decoding.

var imagePreloading = new Image();

(50)

Application Development Guide for Internet@TV

By doing the above work, you can make the Maple browser decode images. For images that have

been decoded once by the browser, they don‟t have to be decoded again later when they are used

elsewhere, so that your TV can display them faster.

6.10. Character of the <input> tag

On Maple, an object that is created by the <input> tag is not overlapped by other objects. Even if you use z-index, the <input> object is always over other objects.

6.11. Scroll bar

Maple provides a scrolling function, but you cannot see the actual scroll bar on the screen. You can scroll up or down the content on the screen with buttons on the remote control when the content needs a larger area than that you specified before. If you want to see the actual scroll bar on your TV screen, you should use scrollHeight, scrollTop and offsetHeight to make an actual scrollbar appear on the screen.

Put an anchor (‘<a>’) in the content you want to scroll up and down, give it focus and click the up or down button

on the remote control, then you can scroll up or down the content.

(Picture Source: http://sevencapitalsins.wordpress.com/2007/07/04/javascript-smooth-scroll/)

6.12. Making dynamic web pages

If you want to make dynamic web pages, you can use createElement and innerHTML. The createElement function is the standard method dealing with HTML DOM, but its disadvantage is lower operating speed, compared with innerHTML. It is recommended to use innerHTML because your applications are run in TVs, which provide a less optimized operating environment than personal computers.

6.13. Setting for letter-spacing

The value of letter-spacing in Maple browser is defaulted ‘-1’. In case of Thai language, letters happen to be overlapped when the value is ‘-1’. Set the value ‘0’ to prevent this from happening.