• Preview Content Policy

  • Section Element Specifications

  • Tile Element Specifications

• Deep-link Return Key Policy

• Public Preview

  • Prerequisites

  • Configuring Public Preview Data

  • Implementing Public Preview Deep Links

• Personal Preview

  • Prerequisites

  • Configuring Private Preview Data

  • Implementing the Background Service Application

  • Implementing Private Preview Deep Links

• Application API

• Messageport API

• Preview API

• Personal Preview: Background Service using Local JSON File

• Personal Preview: Background Service using Server JSON File

• Public Preview: Server API

• Sample JSON File

The Smart Hub Preview feature allows you to show content when the user hovers over your application icon in the launcher. The user can click the preview tile to open the content directly within the application. You can use the preview to promote new or personalized content to the user.

All Samsung TVs since 2016 support Smart Hub Preview. It is also supported on the TV emulator since Tizen TV Extension 2.3.1.

Figure 1. Preview panel

There are 2 kinds of previews. You can select 1 of them for your application:

• Public preview shows the same preview content to all users. The preview content is defined by a remotely-hosted JSON file. You can configure the JSON file to expire and refresh at a specific time.
• Personal preview shows preview content personalized for the user. The preview content is defined by a JSON file managed by a background service application running on the TV.

You can implement the preview to suit the content of the application. For example:

• A video application can have sections for "Popular videos", "Resume playing", and "My playlists".
• A sports application can have sections for "Top games this week" and "My team".
• A news application can have sections for "Today's headlines" and "Local weather".
• A games application can have sections for "Top games now" and "Recently played games".

The following figure illustrates the parts of the preview feature.

Figure 2. Preview parts

1. The launcher contains icons for quick access to common functions and applications.
2. When the user hovers over the application icon in the launcher, the preview panel is shown.
   1. The preview panel can have multiple sections.
   2. Each section can have multiple tiles.
3. Each tile deep-links directly to content within an application. When the user clicks a tile, the application opens to the deep-linked content.

Preview Content Policy

The Samsung Apps TV policy defines requirements for the content shown in Smart Hub Preview. You can use the preview to:

• Link directly to media content, such as movies and music.
• Link directly to detail pages in an application, such as an episode list.
• Link to an authentication or account login screen.

In addition, the personal preview can be used to:

• Link to personalized content, if the application is login-based.
• Link to the user's recently played content in the application.

Important

The preview must not be used to display third-party advertising or to advertise application features or capabilities.

Content shown in Smart Hub Preview belongs to the application and is the responsibility of the content provider.

Section Element Specifications

The following table defines the section element requirements.

Figure 3. Section element with a section title

Tile Element Specifications

The following table defines the tile element requirements.

Figure 4. Thumbnail image aspect ratios

Optional elements can be shown when the user hovers on the tile:

• Title
  The title is shown in bold. Long title text automatically scrolls across the tile. The title must be in the system language.
• Subtitle
  The subtitle is shown below the title. Long subtitle text automatically scrolls across the tile. The subtitle must be in the system language.
• "Play" icon
  To indicate a deep link to media playback, you can show a "play" icon in the upper-right corner of the tile.

The following figure shows a tile with a title, a subtitle, and the "play" icon.

Figure 5. Tile with optional elements

Deep-link Return Key Policy

After the user enters the application through a deep link, the “Return/Exit” key click must be implemented to perform the following actions:

• From a detail page within an application, clicking the “Return/Exit” key must display the previous page in the application.
• From the home page of an application, clicking the “Return/Exit” key must terminate the application without any confirmation popup. The user is returned to Smart Hub Preview.

Figure 6. Deep-link return key policy

Public Preview

The public preview generation process is shown in the following figure.

Figure 7. Public preview generation process

1. The URL to the remote JSON file is defined in the application's "config.xml" file.
2. The preview is generated and shown based on the JSON data.
3. The user clicks a preview tile.
4. The tile's corresponding JSON "action_data" value is sent to the application.
5. The application parses the "action_data" value and shows the detail page.

Prerequisites

To enable your application to use the public preview functionality:

1. Define the remote JSON file URL in the "config.xml" file:

   <tizen:metadata key='http://samsung.com/tv/metadata/use.preview' value='endpoint_URL=http://yourServer/JSONfile.json'></tizen:metadata> 
   

2. Disable reloading the application main page when it receives an application control request.
   This allows your application, if it is already running, to receive the "action_data" information without reloading.

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

3. If you want the application to support 2015 TV models, in the "config.xml" file, set the required_version attribute to "2.3" and the development API version meta data 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>
   

Configuring Public Preview Data

The preview content is defined in JSON format. The application can only use 1 preview content JSON file at a time.

The following table lists the structure and parameters for the preview content JSON data.

For an example of a preview content JSON file, see sampleJSON.

When the preview system requests JSON data from your server, TV information is sent in the HTTP header. You can serve different preview content depending on TV information, such as the country, language, or application version.

The following table lists the HTTP header fields that contain TV information.

Implementing Public Preview Deep Links

When a tile is clicked, its associated "action_data" value is converted to an ApplicationControlData object with the "PAYLOAD" key:

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

For more information on ApplicationControlData objects, see the Application API.

To implement deep-linking:

1. To receive "action_data" information when the application is already running, add an event listener for the appcontrol event to the onload property:

   window.addEventListener('appcontrol', deepLink); 
   

2. In the onload property, receive and parse the "PAYLOAD" key value, using the getCurrentApplication().getRequestedAppControl() method:

   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");
     }
   }
   

Personal Preview

To implement a personal preview, you need to develop a foreground application and a background service application. The foreground application performs the main application tasks, such as showing content, while the background application serves information to show in the preview. Personalized preview content is implemented by sharing data between the foreground and background applications. For example, the foreground application can share user-entered information with the background service, which queries for personalized recommendations.

The personal preview generation process is shown in the following figure.

Figure 8. Personal preview generation process

1. Launching the foreground application also launches the background service application.
2. The JSON data is set by the background service application.
3. The preview is generated and shown based on the JSON data.
4. The user clicks a preview tile.
5. The tile’s corresponding JSON “action_data” value is sent to the application.
6. The foreground application parses the “action_data” value and shows the detail page.

Prerequisites

To enable your application to use the private preview functionality, you must modify the foreground application's "config.xml" file:

1. Define the JSON source as a background application:

   <tizen:metadata key='http://samsung.com/tv/metadata/use.preview' value='bg_service'></tizen:metadata> 
   

2. To add the service application to the foreground application, add the following code inside the widget element.
   The id attribute of the tizen:service element is in the format [application ID].[service name], and the src attribute of the tizen:content element is the path to the service application code.

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

3. Disable reloading the application main page when it receives an application control request.
   This allows your application, if it is already running, to receive the "action_data" information without reloading.

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

4. If you want the application to support 2015 TV models, set the required_version attribute to "2.3" and the development API version meta data 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> 
   

Configuring Private Preview Data

The structure and parameters of the preview content JSON file are the same as for public preview, except that the "expires" and "expires_only" properties are not supported.

You can provide the JSON data as a variable, a local file, or a file at a remote URL. If you want to retrieve JSON data using HTTP requests, you must implement them using NodeJS.

The following example provides the JSON data as a 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
    }]
  }]
};

Implementing the Background Service Application

To implement the background service application:

1. In the foreground application, launch the background service using the Application API in the window.onload method:

   var serviceId = 'g3rAasdgsM.service'; //Application ID for 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));
     }
   );
   

2. In the "service/[service name].js" file, develop the background service application using NodeJS:

   1. Define the onStart() callback.
      When the background service application is launched, this callback is the start point.

      module.exports.onStart = function() {
        console.log("Start Callback");
      }
      

   2. In the onRequest() callback, implement the background application logic, such as HTTP networking, generating preview data, and communication with the foreground application:

      • Use the setPreviewData() method of the Preview API to set the JSON data for the preview.
      • Use the Messageport API to share data between the foreground application and the background service application.

      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() {
                // Terminate service after setting preview data
                tizen.application.getCurrentApplication().exit();
              },
              function(e) {
                console.log('setPreviewData failed : ' + e.message);
              }
            );
          }
        }
      }
      

      Note

      In the success callback for the setPreviewData() method, you must terminate the background service application using the getCurrentApplication().exit() method.

      The Samsung Apps TV policy defines that, if the background service application is not terminated in this way, it is automatically terminated after 5 minutes.

   3. Define the onExit() callback.
      This callback is invoked when the background service application is terminated.

      module.exports.onExit = function() {
        console.log("Exit Callback");
      }
      

Implementing Private Preview Deep Links

Private preview deep links are implemented in the same way as public preview deep links.