• Overview

• Dependencies

• Terminology

• Adding Application to Launcher

• Policy

• UX Guidelines

  • Section Requirements

  • Tile Requirements

  • Return Scenario

• Implementation

  • Public Preview

  • Personal Preview

• Sample Application

• Application API

• sampleJSON

• Service Application

• Preview API

• Message Port API

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

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.

Terminology

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”

• Place the application icon anywhere 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

• 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

• The following picture is “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

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”.

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

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
  expires_only	Boolean	Optional
  sections	Array	Mandatory

  • "expires"
    Public “Preview” only.
    By default, “Preview” is updated every 10 minutes, when a TV turns on, and JSON data is changed.
    However, if you include “expires” information in JSON data, “Preview” is also updated at expiration time.
    Please note that you cannot set “expires” to be longer than 1 week.

  • "expires_only"
    Public “Preview” only.
    If this value is true, “Preview” is strictly updated dependent only on expiration time.
    If this value is false or not set,
    “Preview” is updated every 10 minutes, when a TV turns on, JSON data is changed and at the expiration time.
    Default value is false.

  • "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

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>
  

  Note

  This configuration does not work on the application which adopts background service application.

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

• Public "Preview"
  Sample App for Server API

• Persocal “Preview”

  • Background Service using Local Json

  • Background Service using Server Json