Preview API

To use Samsung Product API,

<script type="text/javascript" src="$WEBAPIS/webapis/webapis.js"></script>

Should be loaded in index.html

This module defines the Preview functionalities provided by the Tizen Samsung Product API.

Since : 2.3

Product : TV, AV, B2B(HTV)

Summary of Interfaces and Methods

Interface Method
PreviewManagerObject

PreviewManager

void setPreviewData(DOMString previewData_JSON, optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback);
DOMString getVersion();
bool setActionDataEventListener(DeeplinkCallback deeplinkCallback);
void unActionDataEventListener();

1. Interfaces

1.1 PreviewManagerObject

Defines a WebApi object instance of the Tizen Samsung Product API.
The webapis.preview object enables access to Preview API functionality.

[NoInterfaceObject] interface PreviewManagerObject {
  readonly attribute PreviewManager preview;
};
WebApi implements PreviewManagerObject;

Attributes

1.2 PreviewManager

Provides methods for Preview functionalities.

[NoInterfaceObject] interface PreviewManager {
  void setPreviewData(DOMString previewData_JSON, optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback);
  DOMString getVersion();
  bool setActionDataEventListener(DeeplinkCallback deeplinkCallback);
  void unActionDataEventListener();
};

Methods

setPreviewData

Sets the preview data. Each application can have 1 preview. The preview consists of at least 1 section, which contains at least 1 tile.

Prerequisites

  • using tag in config.xml
    For example, <tizen:metadata key="http://samsung.com/tv/metadata/use.preview" value="bg_service"/>
void setPreviewData(DOMString previewData_JSON, optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback);

Parameters :

  • previewData_JSON : Preview properties
    sections Mandatory object properties array :
    • title Optional string shown at the top of the section
    • position Optional number defining the position of the section within the preview panel. Sections are shown in ascending position order.
    • tiles Mandatory tile object properties array:
    • title Optional string shown on a highlighted tile
    • subtitle Optional string shown below the title
    • image_url Mandatory string with the thumbnail image URL. The supported formats are PNG and JPG.
    • image_ratio Mandatory string defining the thumbnail image aspect ratio. The valid strings are: "16by9", "4by3", "1by1" (default), and "2by3". The thumbnail height is fixed at 250 px.
    • action_data Mandatory string defining the data to be passed to the application when it is launched from this tile
    • is_playable Mandatory boolean defining whether selecting the tile starts media playback. If "true", a "Play" button icon is shown over the thumbnail image.
    • display_from Optional timestamp defining the time to begin showing the tile
    • display_until Optional timestamp defining the time to stop showing the tile
    • position Optional number defining the position of the tile within the section. Tiles are shown in ascending position order.
  • successCallback [optional][nullable] : Callback method to invoke when the call is successful
  • errorCallback [optional][nullable] : Callback method to invoke if the request fails

Exceptions :

  • WebAPIException
    • with error type InvalidValuesError, if any input parameter contains an invalid value.
    • with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.
    • with error type UnknownError, for any other error.

Code Example :

var previewData = {
  "sections": [{
    "title": "Popular Now",
    "tiles": [{
      "title": "Parks and Recreation",
      "subtitle": "Pawnee Pony",
      "display_from": 1422766800,
      "display_until": 1441937400,
      "image_url": "http://yourserver.com/image.jpg",
      "action_url": "myapp://playVideo?videoId=185595-0324",
      "is_playable": true
    }]
  }]
}

function successCallback() {
  console.log("success");
}

function errorCallback(error) {
  console.log(error.message);
}

try {
  webapis.preview.setPreviewData(JSON.stringify(previewData), successCallback, errorCallback);
} catch(ex) {
  console.log(ex.message);
}

getVersion

Retrieves the Preview API version.

DOMString getVersion();

Return Value :

  • DOMString : Plugin version

Exceptions :

  • WebAPIException
    • with error type UnknownError, for any error.

Code Example :

try {
  var result = webapis.preview.getVersion();
  console.log(result);
} catch(ex) {
  console.log(ex.message);
}

setActionDataEventListener

Register callback function which is called when the preview tiles are clicked.

bool setActionDataEventListener(DeeplinkCallback deeplinkCallback);

Parameters :

  • deeplinkCallback : callback method to invoke when action event is occured.

Return Value :

  • bool : Output of callback registeration

Exceptions :

  • WebAPIException
    • with error type UnknownError, for any error.

Deprecated : 4.0

Code Example :

This method doesnot have  sample code because of @deprecated 4.0.

unActionDataEventListener

Unregister callback function which is called when the preview tiles are clicked.

void unActionDataEventListener();

Exceptions :

  • WebAPIException
    • with error type UnknownError, for any error.

Deprecated : 4.0

Code Example :

This method doesnot have  sample code because of @deprecated 4.0.

2. Full WebIDL

module Preview {
  [NoInterfaceObject] interface PreviewManagerObject {
    readonly attribute PreviewManager preview;
  };

  WebApi implements PreviewManagerObject;

  [NoInterfaceObject] interface PreviewManager {
    void setPreviewData(DOMString previewData_JSON, optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback);
    DOMString getVersion();
    bool setActionDataEventListener(DeeplinkCallback deeplinkCallback);
    void unActionDataEventListener();
  };

};