AIR for TV Application Guide for Samsung TV[V1.10]

AIR for TV Application Guide for Samsung TVVersion 1.10

Samsung Smart TV@Samsung Electronics Copyright All Rights Reserved1

AIR for TV Application Guide for Samsung TV

1.

INTRODUCTION .................................................................................................................................................... 3 1.1. 1.2. PURPOSE OF DOCUMENT...................................................................................................................................... 3 AIR FOR TV APPLICATION DEVELOPMENT ........................................................................................................... 3

2.

PACKAGING AN AIR FOR TV APPLICATION ................................................................................................. 4 2.1. 2.2. STEPS FOR PACKAGING ........................................................................................................................................ 4 STRUCTURE OF APPLICATION PACKAGE ................................................................................................................ 5

3.

CONFIGURING AN AIR FOR TV APPLICATION ............................................................................................. 6 3.1. WRITING A CONFIG.XML....................................................................................................................................... 6

4.

UPLOADING AN AIR FOR TV APPLICATION TO TV .................................................................................. 10 4.1. SDK CONFIGURATION ....................................................................................................................................... 10 Web Server installation ............................................................................................................................. 10 Setting SDK Preferences ........................................................................................................................... 11 Preparing Applications for Upload ........................................................................................................... 12

4.1.1. 4.1.2. 4.1.3. 4.2.

TV CONFIGURATION .......................................................................................................................................... 14 Network Setup .......................................................................................................................................... 14 Developer Login ....................................................................................................................................... 14 Installing Applications .............................................................................................................................. 21 Deletion of User Application .................................................................................................................... 22

4.2.1. 4.2.2. 4.2.3. 4.2.4.

@Samsung Electronics Copyright All Rights Reserved2


1. Introduction1.1. Purpose of DocumentThis document is for explaining about the structure of Samsung SmartTV application that uses Adobe AIR for TV and how to package Adobe AIR application for Samsung SmartTV. Samsung TV Apps SDK does not provide the emulation of AIR for TV application.

1.2. AIR for TV application developmentAdobe AIR for TV application can be developed using Adobe Software. Samsung TV Apps SDK does not provide a method to develop Adobe AIR application or export as Adobe AIR format. We recommend the use of Adobe Software for developing Adobe AIR for TV application.

Recommended Tools for AIR application development :

Adobe Creative Suite, Adobe Flash Professional, Flash Builder, and so on With Adobe Creative Suite 5.5, user can author and emulate AIR for TV application.



2. Packaging an AIR for TV ApplicationCurrently, Samsung SmartTV does not support the installation and run of AIR application. Instead, AIR for TV application should be converted into Samsung SmartTV application format. Here, we describe how to package AIR for TV application for Samsung SmartTV and inside structure of that packaged application.

2.1.

Steps for packagingWe

In order to package an AIR for TV application as Samsung SmartTV application, developer should prepare AIR for TV application and put a proper configuration file (config.xml), and thumbnail images inside that AIR application. provide each step for that.

1.

Unzip an AIR application package (.air) into a folder. AIR_sample.air

Ex)

AIR_sample/.

2.

Write a Samsung SmartTV application configuration file (config.xml), and save it into the unzipped folder of AIR application. (Refer to Section 3.1 for writing a config.xml)

Ex)

AIR_sample/config.xml

3.

Prepare the thumbnail images of AIR application for Samsung SmartHub and TV Appstore, and save them into the unzipped folder of AIR application. (For the size and the use of each image, please refer to Table 1 in Section 3.1)

Ex)

AIR_sample/thumbnails/85.png /95.png /106.png /115.png

4.

Zip the AIR application folder into .zip file Ex) AIR_sample/. AIR_sample.zip



2.2. Structure of application packageHere is the brief description about each component in application package.

[Pic. 1] Inside of AIR for TV application for Samsung SmartTV config.xml

The config.xml file contains information about the applications execution, update, operating environment setting and other related issues. Developer should not change the name of config.xml.

-

Thumbnail images:

Developer should locate the images for icons shown in Samsung SmartHub. In config.xml, you can specify the path for thumbnail images. In the above example package, we put thumbnail images in thumbnail folder.

-

AIR for TV application

Developer should locate AIR for TV application executable, metadata and resources inside application package. Developer can specify the path for AIR for TV application in config.xml.



3. Configuring an AIR for TV Application3.1. Writing a config.xmlThe config.xml file contains the information about TV applications 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. The following is an example of config.xml for AIR for TV application.

user n others 1.000 13 ./ ./thumbnail/106.png ./thumbnail/115.png ./thumbnail/86.png ./thumbnail/95.png AIR_For_TV_Sample Samsung AIR for TV Application Sample 960 540

AIR for TV application for Samsung SmartTV should include the following tags in config.xml file. 13 : It specifies the application type. 13 means AIR for TV application. ./ : It specifies the path of AIR for TV application. Application manager reads the

path of AIR for TV application, and starts AIR for TV with that path. If config.xml is at the root folder of AIR for TV application, please set it as ./ .


AIR for TV Application Guide for Samsung TVThe following table describes other tags for Samsung SmartTV application.

[Table. 1] Description of tags in Configuration file

Element

DescriptionIndicates that the information is relevant to the application. An icon image displayed in the Application Manager.

ValueFile path

It is used in case of no focus and its size is 106 x 86pixel. 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. An icon image displayed in the Application Manager. The size is 85 x 70 pixel. An icon image displayed in the Application Manager. The size is 95 x 78 pixel. The category to distinguish applications, available items are video, sports, game, lifestyle, information, others. Decides whether to synchronize with hub site. The application which doesnt need synchronization chooses n. Shows information about application type Number 13: AIR for TV application Application Path root | child Application (Optional, Only when the channel bound service type is child.) ID When connected to more than one root, roots are distinguished by ::. 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.) 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.) information of application providers. This file has to be written in a Enter the application provider in this tag. The name of the JavaScript file that allows you to confirm account String String y|n String y|n String File path File path File path

File path at the initial execution of contents Limited to non-HTML based applications Channel Bound Service Type(optional) Confirms the relations with root-child clarifying root application ID.


AIR for TV Application Guide for Samsung TVdefined format. 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 tag value. Indicates the application version. Depending on that version information, the server computer updates the corresponding application. Indicates the Application Managers version that is required to run an application having the config.xml file. Indicates whether the application is a full-screen or a single-wide one. Display type affects the audio policy of the application when its run. Refer to Chapter. 6.4. Using Keys on Remote Control for details. If source conversion is needed, set this tag to y. 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. Determines whether to use the childLock function. This function enables the user to lock an application. 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. Turns on and off the video. If you select y, TV broadcasting is not on the screen when entering the application. 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 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. 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) y|n y|n y|n y|n y|n y|n y|n x.xxx x.xxx y|n


AIR for TV Application Guide for Samsung TVconverting sources, sounds can be mixed. 2. Sparkling at the entry for application 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. Enter a name of application. Enter a brief description of the application. Enter the screen area that the application will be occupying. Generally, it is recommended to enter 960 * 540 pixels. But AIR for TV support up to 1280*720 resolution. Enter a description of the author. This tag is used when needed to check network while operating an application. If the tag value is y and the network test result is fail, entry for the application can be blocked with a message indicating the failure. Without any set value, default is y. This tag is used when needed to check whether the hub-site has been authorized or not while operating an application. If the tag value is y, and the hub-site has not been authorized, entry for the application can be blocked with a message indicating the failure. Without any set value, default is n. Indicates whether the application provides Push Notification Service. Without any set value, default is n. This tag is reserved for former Push Notification Service. Without any set value, default is n. Indicates whether Push Notification Service is provided for specific user. Without any set value, default is n. y|n y|n y|n y|n y|n string Number String String



4. Uploading an AIR for TV Application to TVUsing the Samsung Smart TV SDK (SDK), it is very easy to test the basic functioning of a application using the emulator. This enables incremental development by quickly showing the results of a code change. But the emulator can never be an exact simulation of the TV, because it runs on different hardware. The only way to be sure of how application will behave on a Samsung TV set is to run it inside a Samsung TV set.

The TV environment is different from the PC environment in at least the following ways: 1. 2. Less memory is available - applications may run out of memory Response to remote control keys happens with different timing responsiveness to user key presses can be tested 3. 4. A real TV picture can be seen blending of App graphics over a TV picture can be evaluated Video and audio playback may behave differently due to using different hardware

The User Application feature of Smart Hub allows developers to upload applications from their own local server directly to the TV for testing, without affecting any other users of Samsung Smart TV. This section describes to set up the TV and a development PC so that the User Application feature will work correctly.

4.1. SDK Configuration4.1.1. Web Server installationDuring the installation of the SDK, there is an option to install the Apache web server. This document will assume that Apache being used. If the install of Apache was skipped during the SDK install, the user can either re-install the SDK choosing also to install Apache, or manually install Apache (version 2.2.11 is recommended for use with the SDK). When installing the Apache web server, it is recommended to choose all default installation options. It is also be possible to use a different web server if preferred.



4.1.2. Setting SDK PreferencesThe SDK must be configured correctly to set the correct location for uploading applications. Firstly, the emulator must be closed before preferences can be set. Then select the Preferences option from the Tools menu. This gives several further tabs listed on the left of a dialogue box. On the Package Settings tab, selecting the option Use the Apache (2.2.11) installation folder will set the location for uploading Apps to the default Apache installation folder. This is the recommended option for those using Apache with a default configuration.

It is also possible to choose a different folder for uploading applications. This is done by selecting the option Use the virtual directory root folder. When this option is selected, the user may use the Browse button to select a directory. This can either be a directory that is directly accessed by a web server or another directory where files can be stored for later upload (for example by FTP)


AIR for TV Application Guide for Samsung TV 4.1.3. Preparing Applications for UploadThis section assumes that a application is already developed and tested using the emulator. Applications uploaded directly from the development PC to a TV set are known as User Application. Firstly the application configuration must indicate that it is a User Application. This is done by adding a line to the config.xml file, between the and tags, as follows: user To package the User Application for uploading to a TV, right-click on the App name in the Project Explorer window and select Package.

A Packaging area will be shown. Enter the application name and version number, select a region where the application is to be used, and entering the package date (the default is todays date). These settings determine the file name that is used for the package. Then select Update the packaged files on the server, and enter a title and description for the App. The language file settings are used for language translation when developing a multi-lingual application - they are not described by this document.



After pressing OK, the message Packaging complete should be displayed. If using Apache with the default configuration, and the package settings set to use the default installation folder, the packaged application is now available on the Apache web server. If a different folder was configured, the packaged application is now available in the configured folder. The file widgetlist.xml, the folder widget and its contents must be transferred to the web server so that can be accessed by: http:///widgetlist.xml http:///widget/ Please note multiple applications can be packaged and stored on the web server for upload together. Each one will be given a description in the file widgetlist.xml and the files for each will be stored in the widget folder.



4.2. TV Configuration4.2.1. Network SetupFirstly, the TV must be connected to a network and configured with an IP address. If this is already done, please move to the next section. Connect the TV by Ethernet cable to an IP network that has access to the web server where the packaged application is stored. In the TV Settings menu, select Network, and enter Network Setup. Choose either Automatic configuration (for DHCP) or Manual configuration (for fixed IP address). For manual configuration, enter IP address, subnet mask, gate-way and DNS servers. To check that the network is functioning correctly, select Network Test. If this fails, please contact your network administrator; if it succeeds, the TV is correctly connected to the network. Press the Return key to go back to the menu.

4.2.2. Developer Login

Firstly ensure that the TV country is set to a location where Samsung applications on Samsung Smart TV are used. Then press



Then press the Samsung Smart TV button. The Samsung Smart Hub should be displayed. Enter the Login.

To activate the User Application feature, the login name must be set to develop. Select the Create Account button.



Enter the name develop using the numeric keys on the remote controller (in the same style as a mobile telephone) and press select



Choose a 6~12 password (anything is OK). Please press the "Create Account" button.



Next, log in to the develop account.

If this is successful, the name develop should be displayed at the bottom-left corner of the screen. Next enter the Settings.



A new option, Development, should have appeared at the end of the menu.

Select it and choose the option Setting Server IP.



In the boxes, enter the IP address of the web server that contains the packaged application. When this is finished, press the return button on the remote controller. The information entered in these steps is saved in the TV memory. After switching the TV power off and back on, press the Samsung Smart TV button. Then, Smart Hub should be displayed again. All that is needed is to log in to the develop account again by pressing the red button from Smart Hub display. Select the develop account and enter the 6~12 digit password.


AIR for TV Application Guide for Samsung TV 4.2.3. Installing Applications

From the Development menu in the Settings, select User Application Synchronization.

The TV should indicate that it is installing a new service, and will display the name of the user App.



When the install is finished, select Complete and press the Return key on the remote controller two times to exit the Settings.

If this was successful, a new application will be available in Smart Hub. It will have the text USER on a red background at the bottom, and it will display the icon of App.

4.2.4. Deletion of User ApplicationSometimes, on TV, User Application can bring some troubles because there are many errors. On this time, you can delete the User Applications at one time. First, connect the Ethernet cable, and when you start Samsung Smart TV, you can see the Settings. Second, you login with develop id and password and enter the Settings. Third, you can see the Edit Mode menu at the below, and then push the yellow button. Lastly, choose the User Application that you want to delete and press the enter button. After these steps, you can delete User Application on TV.


Documents

AIR for TV Application Guide for Samsung TV[V1.10]