top

Smart Hub Preview

Samsung TV for Tizen platform supports Preview. There are two ways to implement Preview using server API and Background Service. This document covers the basic features of Preview, terminology and its implementation.

Overview

“Preview” is available since Tizen platform 2.4 or higher (Samsung TV 2016 models onwards).
Whenever user hovers application on “Smart Hub Launcher”, “Preview” is shown with “Launcher”.
On “Preview”, users can directly see contents and “Deep Link” into the contents of application.

Figure 1. Preview

Figure 1. Preview

According to our investigations, “Preview” helps to promote most interesting contents of application.
This catch-up contents help to drive more attention to application.

Dependencies

Depending on the model of Samsung TV, “Preview” can be supported or not.
Please refer to the following table.

Table 1. Dependencis
Product Support Model
Samsung TV All of 2016 Samsung TV models onwards
Samsung TV SDK Version 2.3.1 onwards

Terminology

Figure 2. Terminology Smart Hub Preview

Figure 2. Terminology Smart Hub Preview

  1. "Launcher"
    This is a quick access bar for common functions and applications.

  2. “Preview”
    “Preview” shows a list of “Section”.
    a. "Section"
    Tiles can be organized into different “sections” such as “Popular now” and “VOD recommended”.

    b. "Tile"
    This is a component of Section.

  3. "Deep Link"
    This means to jump from “Preview” to the specific detail page of application when user clicks “Tile”.

Adding Application to Launcher

“Preview” is shown only when an application is hovered on “Launcher”.
So, the application should be on “Launcher”. The following step is how to place the application on “Launcher”.

  • On “Launcher”, hover “APPS” icon and confirm application icon lists are shown on “Preview”.

  • Navigate to “Preview” and focus the application icon.

  • Click “Up” key and click “Add to Home”.

    Figure 3. Adding the application on “Launcher”

    Figure 3. Adding the application on “Launcher”

  • Place the application icon anywhere on “Launcher”.

    Figure 4. Placing the application on “Launcher”

    Figure 4. Placing the application on “Launcher”

  • After clicking “Enter” button, confirm “Preview” is shown.

Policy

It covers some regulations of “Preview”. Please refer to the following before making “Preview”.

All contents in “Preview” are owned by the application and are under contents provider’s responsibility.
But, Preview contents should comply the following things.

  • “Preview” should be used for following purpose:

    • Deep linking into playing contents such as movies, episodes, music or etc.

    • Deep linking into detail pages within application such as lists of episodes within seasons or etc.

    • Deep linking into the authenticate page of application such as account login screen.

    • If personal “Preview”, following purpose is also available.

      • Deep linking into personalized service if application is log-in based.

      • Deep linking into playing recent contents initiated by user.

  • It’s not allowed to use “Preview” for:

    • Displaying third party advertisements.

    • Displaying the features or capabilities of application.

  • Different kind of services can have different “Preview” contents, for example:

    • Video / Music service
      Ex) Popular videos / Top picks / Resume playing / My playlist

    • Sports
      Ex) Top games this week / My team

    • Lifestyle service
      Ex) Today’s news / My city’s weather / Hot topic

    • Game service
      Ex) Top games now / Recently played game

UX Guidelines

Section Requirements

  • The following table is “Section” requirements.

    Table 2. "Section" Requirements
    Requirements Description
    The number of Section 1 or more
    The number of Tile in a Section 1 or more
  • The following picture is “Section” image.

    Figure 5. "Section" Image

    Figure 5. “Section” Image

  • The following table is about Section elements.

    Table 3. "Section" Elements
    Element Description
    Title Optional
    (If “Title” text is too long, it is automatically scrolled.)
  • "Title" should be the same as system language.
    To support multiple language, please refer to it in chapter Configuring JSON File.

Tile Requirements

  • The following table is “Tile” requirements.

    Table 4. "Tile” Requirements
    Requirements Description
    Deep Link URL of Tile It should be different from each other.
    The number of Tile Maximum is 40.
  • The following table is “Tile” requirements for Size.

    Table 5. "Tile” Requirements for Size
    Size Description
    Tile height It is fixed at 250px.
    (Thumbnail height should be taller or equal than 250px. If it is taller than, it will be suitably shrunk.)
    Tile width It is 167px, 250px, 333px or 444px.
    Tile Ratio 16:9 (444 x 250px)
    4:3 (333 x 250px)
    1:1 (250 x 250px)
    2:3 (167 x 250px)

    Please refer to the following “Tile” ratio.

    Figure 6. "Tile" Ratio

    Figure 6. “Tile” Ratio

  • The following picture is “Tile” image.

    Figure 7. "Tile" Image

    Figure 7. “Tile” Image

  • The following table is about “Tile” elements.

    Table 6. "Tile" Elements
    Element Description
    Thumbnail PNG, JPG
    It should be suitable for viewers of all ages.
    It shouldn’t be broken, or won’t be displayed.
    Maximum image file size is 360KB.
    Title Optional
    It is displayed in bold.
    (If Title text is too long, it is automatically scrolled.)
    Subtitle Optional
    It is displayed below Title.
    (If Subtitle text is too long, it is automatically scrolled.)
    Playable Icon Optional
    It is displayed on upper-right corner.
    If Deep linking into playback, you can show it on Tile.
    Important

    “Title”, “Subtitle” and “Playable Icon” are displayed over hovered “Tile” only.

  • "Title" and “Subtitle” should be the same as system language.
    To support multiple language, please refer to it in chapter Configuring JSON File.

Return Scenario

After deep linking from “Preview” into the application,
if user clicks “Return” key, it should navigate back to the previous page within application.
And then, if user clicks on the home page within application, the application should be terminated without any confirmation.

Figure 8. Return Scenario

Figure 8. Return Scenario

Implementation

Implementation of “Preview” functionality is as easy as these three steps:

  • Gather requirements for the tiles and configuration

  • Prepare thumbnails and configuration JSON data

  • Implement “Deep Link” in application

Depend on application purpose, there are two ways to implement “Preview”.

  • Public "Preview"
    It has purpose to show same “Preview” for everyone.
    Application provides JSON file as URL type. Then “Preview” will be shown.

  • Personal "Preview"
    It has purpose to show personal suitable “Preview” for each users.
    Application provides JSON file as run background process. Then “Preview” will be shown.

Please note that you can’t use both ways at the same time.
The following table describes difference between public and personal “Preview”.

Table 7. Defference of "Preview"
Public Personal
Workload Server side > application side Server side < application side
Personalization X O
Expires option O X

Public Preview

Flow Chart

  1. JSON data is connected on “config.xml”.

  2. “Preview” is shown.

  3. If user clicks “Preview”, deep linking is occured.

  4. “action_data” in JSON data is sent to the application.

  5. In the application, “action_data” is parsed. Finally, the detail page is shown.

Figure 9. Flow Chart

Figure 9. Flow Chart

Configuring JSON File

For “Preview”, the data (“Thumbnail”, “Title”, “action_data” and etc) is needed.
The format of data model is JSON object. Only one JSON file is allowed per application.

JSON File URL should be connected on “config.xml”. Please refer to it in chapter Setting config.xml.

  • The following table is properties.

    Table 8. Properties
    Name Type Required
    expires UTC timestamp Optional
    sections Array Mandatory
    • "expires"
      Public “Preview” only.
      By default, “Preview” is refreshed every 10 minutes and when a TV turns on.
      However, if you include “expires” information in JSON data, “Preview” doesn’t update until the expiration time.
      Please note that you cannot set “expires” to be longer than 1 week.

    • "sections"
      The list of “sections” in “Preview”.

  • The following table is “sections” properties.

    Table 9. "sections” Properties
    Name Type Required
    title String Optional
    position integer optional
    tiles Array Mandatory
    • "title"
      It is “Section”'s “Title”.

    • "position"
      If you include it in JSON data, “sections” is in ascending order of position.

    • "tiles"
      The list of Tiles in the “Section”.

  • The following table is “Tiles” properties.

    Table 10. “Tiles” Properties
    Name Type Required
    title String Optional
    subtitle String Optional
    image_url String Mandatory
    image_ratio String Mandatory
    action_data String Mandatory
    is_playable Boolean Mandatory
    display_from UTC timestamp Optional
    display_until UTC timestamp Optional
    position Integer Optional
    • "title"
      It is “Tile”'s “Title”.

    • "subtitle"
      It is “Tile”'s “Subtitle”.

    • "image_url"
      It is “Thumbnail”'s URL.

    • "image_ratio"
      Such as: ‘16by9’, ‘4by3’, ‘1by1’ or ‘2by3’

    • “action_data”

      • “action_data” is data sent to an application when deep linking.
        Therefore, information should be contained in “action_data”, which is needed for deep linking into the specific page.
        The application receives the data and then can display the suitable page.

      • When deep linking, “action_data” is converted to ApplicationControlData as below.
        Therefore, the application can receive it by using tizen.application.getCurrentApplication().getRequestedAppControl method.
        For more detail, refer to it in chapter Get “action_data”.

        {
        	"key": "PAYLOAD",
        	"value": ["{\"values\": \"{\\\"videoIdx\\\": 1}\"}"]
        }
        

        action_data is contained under “PAYLOAD” key.
        For more ApplicationControlData, refer to Application API.

    • "is_playable"
      If this value is true, “Playable Icon” is shown.

    • "display_from"
      If you include it in JSON data, “Tile” is shown from the specified time.

    • "display_until"
      If you include it in JSON data, “Tile” is shown until the specified time.

    • "position"
      If you include it in JSON data, “Tile” is in ascending order of position.

  • The following is sample JSON data.
    You can see this sample on the sampleJSON.
{
	"sections": [{
		"title": "Popular VOD",
		"tiles": [{
			"title": "Funny",
			"subtitle": "Birthday Party",
			"image_ratio": "16by9",
			"image_url": "https://developer.samsung.com/onlinedocs/tv/Preview/1.jpg",
			"action_data": "{\"videoIdx\": 1}",
			"is_playable": true
		}]
	},
	{
		"title": "VOD recommended",
		"tiles": [{
			"title": "Living",
			"image_ratio": "1by1",
			"image_url": "https://developer.samsung.com/onlinedocs/tv/Preview/2.jpg",
			"action_data": "{\"videoIdx\": 2}",
			"is_playable": true
		},
		{
			"title": "Cooking",
			"subtitle": "Season 1",
			"image_ratio": "16by9",
			"image_url": "https://developer.samsung.com/onlinedocs/tv/Preview/3.jpg",
			"action_data": "{\"pictureIdx\": 3}",
			"is_playable": false
		},
		{
			"title": "Party",
			"image_ratio": "16by9",
			"image_url": "https://developer.samsung.com/onlinedocs/tv/Preview/4.jpg",
			"action_data": "{\"pictureIdx\": 4}",
			"is_playable": false
		},
		{
			"title": "Animal",
			"image_ratio": "16by9",
			"image_url": "https://developer.samsung.com/onlinedocs/tv/Preview/5.jpg",
			"action_data": "{\"pictureIdx\": 5}",
			"is_playable": false
		}]
	}]
}
  • How to send different JSON data base on TV information
    There are several parameters which an application can receive when “Preview” system requests JSON data.
    These parameters have TV information, which are sent into HTTP headers.
    The application receives these information and send the suitable JSON data to response.
    The following table describes the kind of HTTP headers.

    Table 11. Description of HTTP Header
    HTTP Header Description
    ACCEPT-LANGUAGE Standard HTTP header such as ‘en-US’
    X-SAMSUNG-COUNTRY ISO 3166-1 alpha2 format such as ‘US’
    X-SAMSUNG-APP-VERSION The application version. It maybe used to display different contents based on the application version.

Setting config.xml

Please declare the following metadata tag on “config.xml” for making “Preview”.

  • Connect JSON file URL (maybe on your server) at the following tag and declare it.

    <tizen:metadata key='http://samsung.com/tv/metadata/use.preview' value='endpoint_URL=http://yourServer/JSONfile.json'></tizen:metadata>
    
  • As mentioned above, in case the application has already run in foreground or background, “action_data” should be sent to application without reloading.
    So, you should declare the following tag.

    <tizen:app-control>
    	<tizen:src name='index.html' reload='disable'></tizen:src>
    	<tizen:operation name='http://samsung.com/appcontrol/operation/eden_resume'></tizen:operation>
    </tizen:app-control>
    

    The main HTML page of application should be connected in the name of tizen:src tag.
    If you don’t declare this tag, the application is reloaded although it has already run.
    For the application receives it, appcontrol event should be added. Plese refer to it in chapter Get “action_data”.

  • If you have plan to release the application on both 2015 and 2016 models, you should check Tizen platform version.
    The version of 2015 models is 2.3 and 2016 is 2.4.
    So, you should configure required_version to 2.3 and devel.api.verson to 2.4.

    <tizen:application ... required_version='2.3'></tizen:application>
    <tizen:metadata key='http://samsung.com/tv/metadata/devel.api.version' value='2.4'></tizen:metadata>
    

Getting action_data

  • When deep linking, as mentioned in caption Configuriung JSON File, the application should receive “action_data” by using tizen.application.getCurrentApplication().getRequestedAppControl method.
    You should call the following function on onload.
    (action_data is contained under “PAYLOAD” key.)

    function deepLink() {
    	var requestedAppControl = tizen.application.getCurrentApplication().getRequestedAppControl();
    	var appControlData;
    	var actionData;
    
    	var videoIdx;
    	var pictureIdx;
    
    	if(requestedAppControl) {
    		appControlData = requestedAppControl.appControl.data;
    		
    		for(var i = 0; i < appControlData.length; i++) {
    			if(appControlData[i].key == 'PAYLOAD') {
    				actionData = JSON.parse(appControlData[i].value[0]).values;
    
    				if(JSON.parse(actionData).videoIdx) {
    					videoIdx = JSON.parse(actionData).videoIdx
    
    					console.log(videoIdx);
    				}
    				else if(JSON.parse(actionData).pictureIdx) {
    					pictureIdx = JSON.parse(actionData).pictureIdx
    
    					console.log(pictureIdx);
    				}
    			}
    		}
    	} else {
    		console.log("no req app control");
    	}
    }
    

    For more detail code, refer to it in chapter Sample application.
    For more RequestedApplicationControl, refer to Application API.

  • As mentioned in chapter Setting config.xml, the application can receive “action_data”, when the application has already run.
    You should add the following event on onload.
    (deepLink is function name, as mentioned above.)

    window.addEventListener('appcontrol', deepLink);
    

Personal Preview

First, you need to develop 1 foreground application and 1 background service application.

  • Foreground application is for foreground task such as showing main or detail page.

  • Background service application is for showing “Preview”.
    If you want more details about service application, please refer to Service Application.

Personalization is available by using sharing data between foreground application and background service application.
For example, account data, device information and so on.

Flow Chart

  1. Foreground application launch background service application.

  2. JSON data is set by calling webapis.preview.setPreviewData method on background service application.

  3. “Preview” is shown.

  4. If user clicks “Preview”, deep linking is occured.

  5. “action_data” in JSON data is sent to foreground application.

  6. On foreground application, “action_data” is parsed. Finally, the detail page is shown.

Figure 10. Flow Chart for Personal Preview

Figure 10. Flow Chart for Personal Preview

Configuring JSON File

Configuring JSON File is same with Public “Preview”.
Please refer to that.

Note

Please note that “expires” property in JSON data will be not supported unlike Public “Preview”.

JSON data is available to use as variable, local or remote URL file.
If you want to configure JSON data with HTTP request, It is required to use HTTP request using NodeJS.

The following is sample JSON as variable.

// Sample user data for personalization
var user = {
	id : "Rozanne",
	age : 27
}

var previewData = {
	"sections" : [{
		"title" : user.id + "'s recommended",
		"tiles" : [{
			"title" : "Funny",
			"subtitle" : user.age + "th Birthday Party",
			"image_ratio" : "16by9",
			"image_url" : "https://developer.samsung.com/onlinedocs/tv/Preview/1.jpg",
			"action_data" : "{\"videoIdx\": 1}",
			"is_playable" : true
		}]
	}, {
		"title" : user.age + "'s choice",
		"tiles" : [{
			"title" : user.id + "'s Living",
			"image_ratio" : "1by1",
			"image_url" : "https://developer.samsung.com/onlinedocs/tv/Preview/2.jpg",
			"action_data" : "{\"videoIdx\": 2}",
			"is_playable" : true
		}, {
			"title" : "Cooking",
			"subtitle" : "Season 1",
			"image_ratio" : "16by9",
			"image_url" : "https://developer.samsung.com/onlinedocs/tv/Preview/3.jpg",
			"action_data" : "{\"pictureIdx\": 3}",
			"is_playable" : false
		}, {
			"title" : user.id + "'s " + user.age + "th Party",
			"image_ratio" : "16by9",
			"image_url" : "https://developer.samsung.com/onlinedocs/tv/Preview/4.jpg",
			"action_data" : "{\"pictureIdx\": 4}",
			"is_playable" : false
		}, {
			"title" : user.id + "'s Animal",
			"image_ratio" : "16by9",
			"image_url" : "https://developer.samsung.com/onlinedocs/tv/Preview/5.jpg",
			"action_data" : "{\"pictureIdx\": 5}",
			"is_playable" : false
		}]
	}]
};

Running Background Service Application

Background service application is composed by NodeJS.
And it is required to launch from foreground application by using Application API.

  • Foreground application side
    Foreground application make background service application launch.
    You should add this mehod in window.onload function.

    var serviceId = 'g3rAasdgsM.service'; //App ID of background service application
    
    tizen.application.launchAppControl(
    	new tizen.ApplicationControl(
    		'http://tizen.org/appcontrol/operation/pick', null, 'imag/jpeg',null,
    		[new tizen.ApplicationControlData('caller', ['ForegroundApp'])]
    	),
    	serviceId,
    	function() {
    		console.log('Launch success: ' + serviceId);
    	},
    	function(error) {
    		console.log(JSON.stringify(error));
    	}
    );
    
  • Background service application side
    After launching service application from foreground application,
    “service/[service name].js” file is run. And it should contain the following method.

    • onStart()
      This callback function is start point when background service application is launched.
    module.exports.onStart = function() {
    	console.log("Start Callback");
    }
    
    • onRequest()
      This callback function is called after onStart callback function.
      And it is main logic such as HTTP networking, communication with foreground application or setPreviewData and so on.

      In this function, you can set JSON data to show “Preview” by calling webapis.preview.setPreviewData method.
      Please refer to Preview API.

    module.exports.onRequest = function() {
    	console.log("Request Callback");
    
    	var reqAppControl = tizen.application.getCurrentApplication().getRequestedAppControl();
    	if(reqAppControl && reqAppControl.appControl.operation == "http://tizen.org/appcontrol/operation/pick") {
    		var data = reqAppControl.appControl.data;
    
    		if(data[0].value[0] == 'ForegroundApp') {
    			webapis.preview.setPreviewData(
    				JSON.stringify(previewData),
    				function() {
    					// Should terminate service after setting preview data
    					tizen.application.getCurrentApplication().exit();
    				},
    				function(e) {
    					console.log('setPreviewData failed : ' + e.message);
    				}
    			);
    		}
    	}
    }
    
    Important

    In success callback of webapis.preview.setPreviewData method,
    you should terminate background service application by calling tizen.application.getCurrentApplication().exit.

    Note

    As “APPS” policy, although background service application is not terminated in this callback function,
    background service application will be terminated after 5 minutes.

    • onExit()
      This callback function is called when background service application is terminated.
    module.exports.onExit = function() {
    	console.log("Exit Callback");
    }
    

Setting config.xml

Please declare the following tag on “config.xml” for making “Preview”.

  • Add metadata.

    <tizen:metadata key='http://samsung.com/tv/metadata/use.preview' value='bg_service'></tizen:metadata>
    
  • Add the following to your “config.xml” under the widget to add service to application.

    <tizen:service id='g3rAasdgsM.service'>
    	<tizen:content src='service/service.js'></tizen:content>
    	<tizen:name>service</tizen:name>
    	<tizen:icon src='service/service_icon.png'></tizen:icon>
    	<tizen:description>Service Application</tizen:description>
    	<tizen:metadata key='meta-key' value='meta-value'></tizen:metadata>
    	<tizen:category name='http://tizen.org/category/service'></tizen:category>
    </tizen:service>
    
    • id of tizen:service
      Combination of you application ID and the service name in the format of [application ID].[service name]

    • src of tizen:content
      Point to the file containing the service code

  • As mentioned above, in case the application has already run in foreground or background, “action_data” should be sent to application without reloading.
    So, you should declare the following tag.

    <tizen:app-control>
    	<tizen:src name="index.html" reload="disable"></tizen:src>
    	<tizen:operation name="http://samsung.com/appcontrol/operation/eden_resume"></tizen:operation>
    </tizen:app-control>
    

    The main HTML page of application should be connected in the name of tizen:src tag.
    If you don’t declare this tag, the application is reloaded although it has already run.
    For the application receives it, appcontrol event should be added. Plese refer to it in chapter Get “action_data”.

  • If you have plan to release the application on both 2015 and 2016 models, you should check Tizen platform version.
    The version of 2015 models is 2.3 and 2016 is 2.4.
    So, you should configure required_version to 2.3 and devel.api.verson to 2.4.

    <tizen:application ... required_version='2.3'></tizen:application>
    <tizen:metadata key="http://samsung.com/tv/metadata/devel.api.version" value="2.4"></tizen:metadata>
    

Getting action_data

Getting action_data is same with Public “Preview”.
Please refer to that.

Sharing data between Foreground and Background Service Application

You can use MessagePort API to share data between foreground application and background service application.
For instance sharing account information entered by the user in the foreground application with the background service querying for personalized recommendations.

For more details, please refer to MessagePort API.

Sample Application