Samsung Electronics logo

Samsung Web API: TVController


Introduction

This API allows developers to provide the generic remote key control and control TV browser on Samsung Smart TV.

TVController can remotely control the Samsung Smart TV manufactured since 2012.

Some APIs can be operated with the Samsung Smart TV manufactured since 2011. If your Smart TV does not support a particular feature, a NotSupportedError exception will be thrown.


Table of Contents


Summary of Interfaces and Methods

Interface Method
TVControllerSuccessCallback void onsuccess(DeviceId controllerId)
TVControllerGetBrowserModeSuccessCallback void onsuccess(TVControllerBrowserMode mode, DeviceId controllerId)
TVControllGetBrowserUrlSuccessCallback void onsuccess(DOMString url, DeviceId controllerId)
TVControllerErrorCallback void onerror(WebAPIError error, DeviceId controllerId)
TVControllerEventCallback void ondisconnected(DeviceId controllerId)
void onstringchanged(DOMString text, DeviceId controllerId)
TVController void connect(TVControllerSuccessCallback successCallback, TVControllerErrorCallback? errorCallback)
void disconnect(TVControllerSuccessCallback successCallback, TVControllerErrorCallback? errorCallback)
long addTVControllerEventListener(TVControllerEventCallback eventCallback)
void removeTVControllerEventListener(long eventListener)
void sendRemoteKey(RemoteKey key)
void sendKeyboardString(DOMString text)
void sendKeyboardEnd()
void sendTouchClick()
void sendTouchDown()
void sendTouchMove(long long dx, long long dy)
void sendTouchUp()
void setBrowserMode(TVControllerBrowserMode mode, TVControllerSuccessCallback successCallback, TVControllerErrorCallback? errorCallback)
void getBrowserMode(TVControllerGetBrowserModeSuccessCallback successCallback, TVControllerErrorCallback? errorCallback)
void scrollWebPage(BrowserScrollMode mode, TVControllerSuccessCallback successCallback, TVControllerErrorCallback? errorCallback)
void zoomWebPage(BrowserZoomMode mode, TVControllerSuccessCallback successCallback, TVControllerErrorCallback? errorCallback)
void getBrowserUrl(TVControllGetBrowserUrlSuccessCallback successCallback, TVControllerErrorCallback? errorCallback)
void goHomePage(TVControllerSuccessCallback successCallback, TVControllerErrorCallback? errorCallback)
void goNextWebPage(TVControllerSuccessCallback successCallback, TVControllerErrorCallback? errorCallback)
void goPreviousWebPage(TVControllerSuccessCallback successCallback, TVControllerErrorCallback? errorCallback)
void openWebPage(DOMString url, TVControllerSuccessCallback successCallback, TVControllerErrorCallback? errorCallback)
void closeWebPage(TVControllerSuccessCallback successCallback, TVControllerErrorCallback? errorCallback)
void refreshWebPage(TVControllerSuccessCallback successCallback, TVControllerErrorCallback? errorCallback)
void stopWebPageLoading(TVControllerSuccessCallback successCallback, TVControllerErrorCallback? errorCallback)

1. Type Definitions

1.1. RemoteKey

Specifies the TV remote controller keys.

    enum RemoteKey {
        "KEY_0", "KEY_1", "KEY_2", "KEY_3", "KEY_4", "KEY_5", "KEY_6", "KEY_7", "KEY_8", "KEY_9", 
        "KEY_BLUE", "KEY_CH_LIST", "KEY_CHDOWN", "KEY_CHUP", "KEY_CONTENTS", 
        "KEY_DASH", "KEY_DOWN", "KEY_ENTER", "KEY_EXIT", "KEY_FF", "KEY_GREEN", "KEY_INFO", "KEY_LEFT", 
        "KEY_MENU", "KEY_MUTE", "KEY_PAUSE", "KEY_PLAY", "KEY_POWEROFF", "KEY_PRECH", "KEY_REC", 
        "KEY_RED", "KEY_RETURN", "KEY_REWIND", "KEY_RIGHT", "KEY_SOURCE", "KEY_STOP", "KEY_TOOLS", 
        "KEY_UP", "KEY_VOLDOWN", "KEY_VOLUP", "KEY_YELLOW"
   };
  • KEY_0: The 'number 0' key.
  • KEY_1: The 'number 1' key.
  • KEY_2: The 'number 2' key.
  • KEY_3: The 'number 3' key.
  • KEY_4: The 'number 4' key.
  • KEY_5: The 'number 5' key.
  • KEY_6: The 'number 6' key.
  • KEY_7: The 'number 7' key.
  • KEY_8: The 'number 8' key.
  • KEY_9: The 'number 9' key.
  • KEY_BLUE: The 'blue' key.
  • KEY_CH_LIST: The 'channel list' key.
  • KEY_CHDOWN: The 'channel down' key.
  • KEY_CH_UP: The 'channel up' key.
  • KEY_CONTENTS: The 'SmartHub' key.
  • KEY_DASH: The 'dash (-)' key.
  • KEY_DOWN: The 'arrow down' key.
  • KEY_ENTER: The 'enter' key.
  • KEY_EXIT: The 'exit' key.
  • KEY_FF: The 'fast forward' key.
  • KEY_GREEN: The 'green' key.
  • KEY_INFO: The 'information' key.
  • KEY_LEFT: The 'arrow left' key.
  • KEY_MENU: The 'menu' key.
  • KEY_PAUSE: The 'pause' key.
  • KEY_PLAY: The 'play' key.
  • KEY_POWEROFF: The 'power off' key.
  • KEY_PRECH: The 'previous channel' key.
  • KEY_REC: The 'record' key.
  • KEY_RED: The 'red' key.
  • KEY_RETURN: The 'return' key.
  • KEY_REWIND: The 'rewind' key.
  • KEY_RIGHT: The 'arrow right' key.
  • KEY_SOURCE: The 'source' key.
  • KEY_STOP: The 'stop' key.
  • KEY_TOOLS: The 'tools' key.
  • KEY_UP: The 'arrow up' key.
  • KEY_VOLDOWN: The 'volume down' key.
  • KEY_VOLUP: The 'volume up' key.
  • KEY_YELLOW: The 'yellow' key.

1.2. TVControllerBrowserMode

Specifies the Web browsing mode.

    enum TVControllerBrowserMode {
        "POINT_BROWSING", 
        "LINK_BROWSING",
        "UNKNOWN"
    };
  • POINT_BROWSING: Input mode using the mouse cursor
  • LINK_BROWSING: Input mode using the arrow keys
  • UNKNOWN: The unknown mode

1.3. BrowserScrollMode

Specifies the scroll direction in a browser.

    enum BrowserScrollMode {
        "SCROLL_UP", 
        "SCROLL_DOWN"
    };
  • UP: Scroll up
  • DOWN: Scroll down

1.4. BrowserZoomMode

Specifies the zoom mode in a browser.

    enum BrowserZoomMode {
        "ZOOM_IN", 
        "ZOOM_OUT", 
        "ZOOM_DEFAULT"
    };
  • ZOOM_IN: Set zoom in
  • ZOOM_OUT: Set zoom out
  • ZOOM_DEFAULT: Set the zoom ratio as default value, i.e 1.0x

2. Interfaces

2.1. TVControllerSuccessCallback

Provides generic interface for handling a response from TVController

    [Callback=FunctionOnly, NoInterfaceObject] interface TVControllerSuccessCallback {
    
        void onsuccess(DeviceId controllerId);
    };

METHODS

onsuccess

Invoked when the request is successful

Signature
void onsuccess(DeviceId controllerId);
Parameters
  • controllerId
    • Optional: No.
    • Nullable: No.
    • Type: DeviceId.
    • Description: The identifier of the TV Controller device which made a request

2.2. TVControllerGetBrowserModeSuccessCallback

Provides generic interface for getting TVController BrowserMode response.

    [Callback=FunctionOnly, NoInterfaceObject] interface TVControllerGetBrowserModeSuccessCallback {
    
        void onsuccess(TVControllerBrowserMode mode, 
                       DeviceId controllerId);
    };

METHODS

onsuccess

Invoked when the response arrives

Signature
void onsuccess(TVControllerBrowserMode mode, DeviceId controllerId);
Parameters
  • mode
    • Optional: No.
    • Nullable: No.
    • Type: TVControllerBrowserMode.
    • Description: Returned BrowserMode
  • controllerId
    • Optional: No.
    • Nullable: No.
    • Type: DeviceId.
    • Description: The identifier of the TV Controller device which was requested

2.3. TVControllGetBrowserUrlSuccessCallback

Provides generic interface for getting TVController browser URL response.

    [Callback=FunctionOnly, NoInterfaceObject] interface TVControllGetBrowserUrlSuccessCallback {
        
        void onsuccess(DOMString url, 
                       DeviceId controllerId);
    };

METHODS

onsuccess

Invoked when the response arrives

Signature
void onsuccess(DOMString url, DeviceId controllerId);
Parameters
  • url
    • Optional: No.
    • Nullable: No.
    • Type: DOMString.
    • Description: Returned browser URL
  • controllerId
    • Optional: No.
    • Nullable: No.
    • Type: DeviceId.
    • Description: The identifier of the TV Controller device which was requested

2.4. TVControllerErrorCallback

Provides generic interface for handling an error that occurred while performing operations with TVController

    [Callback=FunctionOnly, NoInterfaceObject] interface TVControllerErrorCallback {
    
        void onerror(WebAPIError error, 
                     DeviceId controllerId);
    };

METHODS

onerror

Invoked when an error occurs while performing operations related to TVController

Signature
void onerror(WebAPIError error, DeviceId controllerId);
Parameters
  • error
    • Optional: No.
    • Nullable: No.
    • Type: WebAPIError.
    • Description: The error that is raised
  • controllerId
    • Optional: No.
    • Nullable: No.
    • Type: DeviceId.
    • Description: The identifier of the TV Controller device which was requested

2.5. TVControllerEventCallback

Provides generic interface for getting TVController events.

    [Callback, NoInterfaceObject] interface TVControllerEventCallback {
        
        void ondisconnected (DeviceId controllerId);
        
        void onstringchanged (DOMString text, 
                              DeviceId controllerId);
    };

METHODS

ondisconnected

Invoked when the TVController has been disconnected

Signature
void ondisconnected(DeviceId controllerId);
Parameters
  • controllerId
    • Optional: No.
    • Nullable: No.
    • Type: DeviceId.
    • Description: The identifier of TV Controller device which has been disconnected

onstringchanged

Invoked when the string change response arrives

Signature
void onstringchanged(DOMString text, DeviceId controllerId);
Parameters
  • text
    • Optional: No.
    • Nullable: No.
    • Type: DOMString.
    • Description: Returned new string
  • controllerId
    • Optional: No.
    • Nullable: No.
    • Type: DeviceId.
    • Description: The identifier of the TV Controller device in which the change was made

2.6. TVController

Provides the remote control for a Smart TV.

    [NoInterfaceObject] interface TVController : DeviceDevice {
    
        readonly attribute DOMString version;
        
        readonly attribute boolean isWebSharingSupported;
        
        readonly attribute boolean isConnected;
        
        void connect(TVControllerSuccessCallback successCallback, 
                     optional TVControllerErrorCallback? errorCallback);
        
        void disconnect(TVControllerSuccessCallback successCallback, 
                        optional TVControllerErrorCallback? errorCallback);
        
        long addTVControllerEventListener (TVControllerEventCallback eventCallback);
        
        void removeTVControllerEventListener (long eventListener);

        void sendRemoteKey(RemoteKey key);
        
        void sendKeyboardString(DOMString text);
        
        void sendKeyboardEnd(); 

        
        void sendTouchClick();
        
        void sendTouchDown();
        
        void sendTouchMove(long long dx,
                           long long dy);
        
        void sendTouchUp();

        void setBrowserMode(TVControllerBrowserMode mode, 
                            TVControllerSuccessCallback successCallback, 
                            optional TVControllerErrorCallback? errorCallback);
        
        void getBrowserMode(TVControllerGetBrowserModeSuccessCallback successCallback, 
                            optional TVControllerErrorCallback? errorCallback);

        void scrollWebPage(BrowserScrollMode mode,  TVControllerSuccessCallback successCallback, 
                               optional TVControllerErrorCallback? errorCallback);
        
        void zoomWebPage(BrowserZoomMode mode, 
                         TVControllerSuccessCallback successCallback, 
                         optional TVControllerErrorCallback? errorCallback);
        
        void getBrowserUrl(TVControllGetBrowserUrlSuccessCallback successCallback, 
                           optional TVControllerErrorCallback? errorCallback);
        
        void goHomePage(TVControllerSuccessCallback successCallback, 
                        optional TVControllerErrorCallback? errorCallback);
        
        void goNextWebPage(TVControllerSuccessCallback successCallback, 
                                       optional TVControllerErrorCallback? errorCallback);
        
        void goPreviousWebPage(TVControllerSuccessCallback successCallback, 
                                            optional TVControllerErrorCallback? errorCallback);
        
        void openWebPage(DOMString url, 
                         TVControllerSuccessCallback successCallback, 
                         optional TVControllerErrorCallback? errorCallback);

        void closeWebPage(TVControllerSuccessCallback successCallback, 
                          optional TVControllerErrorCallback? errorCallback);
        
        void refreshWebPage(TVControllerSuccessCallback successCallback, 
                                       optional TVControllerErrorCallback? errorCallback);

        
        void stopWebPageLoading(TVControllerSuccessCallback successCallback, 
                                optional TVControllerErrorCallback? errorCallback);    
    };
Code example
 
 var serviceProvider; // it is assumed that you obtained serviceProvider. For further details, see the creatServiceProvider(..).
 var deviceId;           // it is assumed that a TV controller's device Id has already been determined.
 
 try {
     var controller = serviceProvider.getDeviceFinder().getDevice("TVCONTROLLER", deviceId);

     // Print out the device's name
     console.log(controller.name);
     
 } catch(e) {
      console.log(e.name);
 }
 
 

ATTRIBUTES

readonly DOMString version

Version of TV Controller

This attribute is read-only.

readonly boolean isWebSharingSupported

Information on whether the Web sharing feature is supported

This attribute is read-only.

readonly boolean isConnected

Information about connection state

This attribute is read-only.

METHODS

connect

Establishes a connection to a Smart TV.

Signature
void connect(TVControllerSuccessCallback successCallback, optional TVControllerErrorCallback? errorCallback);

All the other APIs which TV controller provides can be used under the condition that the connection has been properly set. The error callback is launched with these error types:

  • UnknownError: In the case of any other error
Parameters
  • successCallback
    • Optional: No.
    • Nullable: No.
    • Type: TVControllerSuccessCallback.
    • Description: callback function called if the request is successful
  • errorCallback
    • Optional: Yes.
    • Nullable: Yes.
    • Type: TVControllerErrorCallback.
    • Description: callback function called if the request is fails
Exceptions
  • WebAPIException:

    with error type SecurityError, if this functionality is not allowed.

    with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.

Code example
 var controller; // it is assumed that a TV controller object is obtained.
 
 function connectCB(controllerId) {
     console.log("TV is successfully connected.");
 }

 function errorCB(error, controllerId) {
     console.log(error.name);
 }

 try {
     if (controller.isConnected == false) {
         controller.connect(connectCB, errorCB);
     }
 } catch (e) {
    console.log(e.name);
 }
 

disconnect

Break off the connection to a Smart TV.

Signature
void disconnect(TVControllerSuccessCallback successCallback, optional TVControllerErrorCallback? errorCallback);

After this API is invoked properly, all the other APIs except connect() will be disabled. The error callback is launched with these error types:

  • UnknownError: In the case of any other error
Parameters
  • successCallback
    • Optional: No.
    • Nullable: No.
    • Type: TVControllerSuccessCallback.
    • Description: callback function called if the request is successful
  • errorCallback
    • Optional: Yes.
    • Nullable: Yes.
    • Type: TVControllerErrorCallback.
    • Description: callback function called if the request is fails
Exceptions
  • WebAPIException:

    with error type SecurityError, if this functionality is not allowed.

    with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.

Code example
 var controller; // it is assumed that a TV controller object is obtained.
 
 function disconnectCB(controllerId) {
     console.log("TV is successfully disconnected.");
 }

 function errorCB(error, controllerId) {
     console.log(error.name);
 }

 try {
     if (controller.isConnected) {
         controller.disconnect(disconnectCB, errorCB);
     }
 } catch (e) {
    console.log(e.name);
 }
 

addTVControllerEventListener

Registers the TV Controller event listener

Signature
long addTVControllerEventListener(TVControllerEventCallback eventCallback);
Parameters
  • eventCallback
    • Optional: No.
    • Nullable: No.
    • Type: TVControllerEventCallback.
    • Description: Callback function called if the event occured
Return value
listener handle
Exceptions
  • WebAPIException:

    with error type SecurityError, if this functionality is not allowed.

    with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.

Code example
 var controller; // it is assumed that a TV controller object is obtained.
 
 var eventCB =  {
     ondisconnected : function (controllerId) { console.log("TV is disconnected"); }, 
     onstringchanged : function (text, controllerId) { console.log("string " + text + " is changed"); }  
 };

 try {
     var handle = controller.addTVControllerEventListener(eventCB);
 } catch (e) {
    console.log(e.name);
 }

 

removeTVControllerEventListener

Clears the TV Controller event listener

Signature
void removeTVControllerEventListener(long eventListener);
Parameters
  • eventListener
    • Optional: No.
    • Nullable: No.
    • Type: long.
    • Description: Event listener id
Exceptions
  • WebAPIException:

    with error type SecurityError, if this functionality is not allowed.

    with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.

Code example
 var controller; // it is assumed that a TV controller object is obtained.
 var handle; // it is assumed that the event handle is stored
 
 try {
     controller.removeTVControllerEventListener(handle);
 } catch (e) {
    console.log(e.name);
 }

 

sendRemoteKey

Send the TV remote control key input.

Signature
void sendRemoteKey(RemoteKey key);
Parameters
  • key
    • Optional: No.
    • Nullable: No.
    • Type: RemoteKey.
    • Description: The value of remote key input
Exceptions
  • WebAPIException:

    with error type UnknownError, if any other error case.

    with error type SecurityError, if this functionality is not allowed.

    with error type NotSupportedError, if this feature is not supported.

    with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.

Code example
 var controller; // it is assumed that a TV controller object.
 
 try {
     if (controller.isConnected) {
         controller.sendRemoteKey("KEY_UP");
     }
 } catch (e) {
    console.log(e.name);
 }

 

sendKeyboardString

Send the TV keyboard string input.

Signature
void sendKeyboardString(DOMString text);

This API is valid when the controlled TV is displaying an on-screen keyboard. Otherwise it will be ignored.

Parameters
  • text
    • Optional: No.
    • Nullable: No.
    • Type: DOMString.
    • Description: The value of TV keyboard string
Exceptions
  • WebAPIException:

    with error type UnknownError, if any other error case.

    with error type NotSupportedError, if this feature is not supported.

    with error type SecurityError, if this functionality is not allowed.

    with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.

Code example
 var controller; //  it is assumed that a TV controller object has been obtained.
 
 // assume that an on-screen keyboard is displayed by selecting an input box. 
 try {
     if (controller.isConnected) {
         controller.sendKeyboardString("hello");
     }
 } catch (e) {
    console.log(e.name);
 }

 

sendKeyboardEnd

Send the end of the TV keyboard string input.

Signature
void sendKeyboardEnd();

This API is valid when the controlled TV is displaying an on-screen keyboard. Otherwise it will be ignored.

Exceptions
  • WebAPIException:

    with error type UnknownError, if any other error case.

    with error type NotSupportedError, if this feature is not supported.

    with error type SecurityError, if this functionality is not allowed.

Code example
 var controller; // it is assumed that a TV controller object has been obtained.

 // assume that an on-screen keyboard is displayed by selecting an input box. 
 try {
     if (controller.isConnected) {
         controller.sendKeyboardString("hello");
         controller.sendKeyboardEnd();
     }
 } catch (e) {
    console.log(e.name);
 }

 

sendTouchClick

Send the touch click of the TV mouse input.

Signature
void sendTouchClick();

This API is valid if the controlled TV has launched a TV browser with POINT_BROWSING mode or an application which supports touch event handling. Otherwise, it is ignored. It is supported on all Samsung Smart TVs manufactured since 2012.

Exceptions
  • WebAPIException:

    with error type UnknownError, if any other error case.

    with error type NotSupportedError, if this feature is not supported.

    with error type SecurityError, if this functionality is not allowed.

Code example
 var controller; // it is assumed that a TV controller object with POINT_BROWSING mode has been obtained.
 
 try {
     if (controller.isConnected) {
         // click the position where the cursor is pointed
         controller.sendTouchClick();
     }
 } catch (e) {
    console.log(e.name);
 }

 

sendTouchDown

Send the touch down of the TV mouse input.

Signature
void sendTouchDown();

This API is valid if the controlled TV has launched a TV browser with POINT_BROWSING mode or an application which supports touch event handling. Otherwise, it is ignored. It is supported on all Samsung Smart TVs manufactured since 2012.

Exceptions
  • WebAPIException:

    with error type UnknownError, if any other error case.

    with error type NotSupportedError, if this feature is not supported.

    with error type SecurityError, if this functionality is not allowed.

Code example
 var controller; // it is assumed that a TV controller object with POINT_BROWSING mode has been obtained.
 

 try {
     if (controller.isConnected) {
         // emulate a vertical drag operation 
         controller.sendTouchDown();
         controller.sendTouchMove(0, 100);
         controller.sendTouchUp(); 
     }
 } catch (e) {
    console.log(e.name);
 }

 

sendTouchMove

Send the touch move of the TV mouse input.

Signature
void sendTouchMove(long long dx, long long dy);

This API is valid if the controlled TV has launched a TV browser with POINT_BROWSING mode or an application which supports touch event handling. Otherwise, it is ignored.

Parameters
  • dx
    • Optional: No.
    • Nullable: No.
    • Type: long long.
    • Description: Move across x-axis
  • dy
    • Optional: No.
    • Nullable: No.
    • Type: long long.
    • Description: Move across y-axis
Exceptions
  • WebAPIException:

    with error type UnknownError, if any other error case.

    with error type NotSupportedError, if this feature is not supported.

    with error type SecurityError, if this functionality is not allowed.

    with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.

sendTouchUp

Send the touch up of the TV mouse input.

Signature
void sendTouchUp();

This API is valid if the controlled TV has launched a TV browser with POINT_BROWSING mode or an application which supports touch event handling. Otherwise, it is ignored.

Exceptions
  • WebAPIException:

    with error type UnknownError, if any other error case.

    with error type NotSupportedError, if this feature is not supported.

    with error type SecurityError, if this functionality is not allowed.

setBrowserMode

Sets the input mode of the web browser.

Signature
void setBrowserMode(TVControllerBrowserMode mode, TVControllerSuccessCallback successCallback, optional TVControllerErrorCallback? errorCallback);

This API is valid if the controlled TV has launched a TV browser. Otherwise, it is ignored. It is supported on the Samsung Smart TVs manufactured since 2012.

The error callback is launched with these error types:

  • UnknownError: In the case of any other error
Parameters
  • mode
    • Optional: No.
    • Nullable: No.
    • Type: TVControllerBrowserMode.
    • Description: Desired browser mode
  • successCallback
    • Optional: No.
    • Nullable: No.
    • Type: TVControllerSuccessCallback.
    • Description: Callback function called if the request is successful
  • errorCallback
    • Optional: Yes.
    • Nullable: Yes.
    • Type: TVControllerErrorCallback.
    • Description: Callback function called if the request is fails
Exceptions
  • WebAPIException:

    with error type NotSupportedError, if this feature is not supported.

    with error type SecurityError, if this functionality is not allowed.

    with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.

Code example
 var controller; // it is assumed that a TV controller object is obtained.
 
 function successCB(controllerId) {
     console.log("TV browser mode is successfully set.");
 }

 function errorCB(error, controllerId) {
     console.log(error.name);
 }

 try {
     if (controller.isConnected) {
         controller.setBrowserMode("LINK_BROWSING", successCB, errorCB);
     }
 } catch (e) {
    console.log(e.name);
 }

 

getBrowserMode

Gets the input mode of the web browser.

Signature
void getBrowserMode(TVControllerGetBrowserModeSuccessCallback successCallback, optional TVControllerErrorCallback? errorCallback);

This API is valid if the controlled TV has launched a TV browser. Otherwise, it is ignored. It is supported on the Samsung Smart TVs manufactured since 2012.

The error callback is launched with these error types:

  • UnknownError: In the case of any other error
Parameters
  • successCallback
    • Optional: No.
    • Nullable: No.
    • Type: TVControllerGetBrowserModeSuccessCallback.
    • Description: Callback function called if the request is successful
  • errorCallback
    • Optional: Yes.
    • Nullable: Yes.
    • Type: TVControllerErrorCallback.
    • Description: Callback function called if the request is fails
Exceptions
  • WebAPIException:

    with error type NotSupportedError, if this feature is not supported.

    with error type SecurityError, if this functionality is not allowed.

    with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.

Code example
 var controller; // it is assumed that a TV controller object has been obtained.
 
 function successCB(mode, controllerId) {
     console.log("TV browser mode is " + mode);
 }

 function errorCB(error, controllerId) {
     console.log(error.name);
 }

 try {
     if (controller.isConnected) {
         var mode = controller.getBrowserMode(successCB, errorCB);
     }
 } catch (e) {
    console.log(e.name);
 }

 

scrollWebPage

Scrolls the current web page up or down.

Signature
void scrollWebPage(BrowserScrollMode mode, TVControllerSuccessCallback successCallback, optional TVControllerErrorCallback? errorCallback);

This API is valid if the controlled TV has launched a TV browser. Otherwise, it is ignored. It is supported on the Samsung Smart TVs manufactured since 2012.

The error callback is launched with these error types:

  • UnknownError: In the case of any other error
Parameters
  • mode
    • Optional: No.
    • Nullable: No.
    • Type: BrowserScrollMode.
    • Description: The direction of scrolling on the current Web page
  • successCallback
    • Optional: No.
    • Nullable: No.
    • Type: TVControllerSuccessCallback.
    • Description: Callback function called if the request is successful
  • errorCallback
    • Optional: Yes.
    • Nullable: Yes.
    • Type: TVControllerErrorCallback.
    • Description: Callback function called if the request is fails
Exceptions
  • WebAPIException:

    with error type NotSupportedError, if this feature is not supported.

    with error type SecurityError, if this functionality is not allowed.

    with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.

Code example
 var controller; // assumed to be a TV controller object.
 
 function successCB(controllerId) {
     console.log("The web page is scrolling properly.");
 
 }

 function errorCB(error, controllerId) {
     console.log(error.name);
 }

 try {
     if (controller.isConnected) {
         controller.scrollWebPage("SCROLL_DOWN", successCB, errorCB);
     }
 } catch (e) {
    console.log(e.name);
 }

 

zoomWebPage

Set the zoom rate on the current web page.

Signature
void zoomWebPage(BrowserZoomMode mode, TVControllerSuccessCallback successCallback, optional TVControllerErrorCallback? errorCallback);

This API is valid if the controlled TV has launched a TV browser. Otherwise, it is ignored. It is supported on the Samsung Smart TVs manufactured since 2012.

The error callback is launched with these error types:

  • UnknownError: In the case of any other error
Parameters
  • mode
    • Optional: No.
    • Nullable: No.
    • Type: BrowserZoomMode.
    • Description: The zoom mode on the current page
  • successCallback
    • Optional: No.
    • Nullable: No.
    • Type: TVControllerSuccessCallback.
    • Description: Callback function called if the request is successful
  • errorCallback
    • Optional: Yes.
    • Nullable: Yes.
    • Type: TVControllerErrorCallback.
    • Description: Callback function called if the request is fails
Exceptions
  • WebAPIException:

    with error type NotSupportedError, if this feature is not supported.

    with error type SecurityError, if this functionality is not allowed.

    with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.

Code example
 var controller; // assumed to be a TV controller object.
 
 function successCB(controllerId) {
     console.log("The web page is zoomed properly.");
 
 }

 function errorCB(error, controllerId) {
     console.log(error.name);
 }

 try {
     if (controller.isConnected) {
         controller.zoomWebPage("ZOOM_IN", successCB, errorCB);
     }
 } catch (e) {
    console.log(e.name);
 }

 

getBrowserUrl

Get the current web page URL

Signature
void getBrowserUrl(TVControllGetBrowserUrlSuccessCallback successCallback, optional TVControllerErrorCallback? errorCallback);

This API is valid if the controlled TV has launched a TV browser. Otherwise, it is ignored. It is supported on the Samsung Smart TVs manufactured since 2012.

The error callback is launched with these error types:

  • UnknownError: In the case of any other error
Parameters
  • successCallback
    • Optional: No.
    • Nullable: No.
    • Type: TVControllGetBrowserUrlSuccessCallback.
    • Description: Callback function called if the request is successful
  • errorCallback
    • Optional: Yes.
    • Nullable: Yes.
    • Type: TVControllerErrorCallback.
    • Description: Callback function called if the request is fails
Exceptions
  • WebAPIException:

    with error type NotSupportedError, if this feature is not supported.

    with error type SecurityError, if this functionality is not allowed.

    with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.

goHomePage

Go to the home page.

Signature
void goHomePage(TVControllerSuccessCallback successCallback, optional TVControllerErrorCallback? errorCallback);

This API is valid if the controlled TV has launched a TV browser. Otherwise, it is ignored. It is supported on the Samsung Smart TVs manufactured since 2012.

The error callback is launched with these error types:

  • UnknownError: In the case of any other error
Parameters
  • successCallback
    • Optional: No.
    • Nullable: No.
    • Type: TVControllerSuccessCallback.
    • Description: Callback function called if the request is successful
  • errorCallback
    • Optional: Yes.
    • Nullable: Yes.
    • Type: TVControllerErrorCallback.
    • Description: Callback function called if the request is fails
Exceptions
  • WebAPIException:

    with error type NotSupportedError, if this feature is not supported.

    with error type SecurityError, if this functionality is not allowed.

    with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.

goNextWebPage

Go to the next page.

Signature
void goNextWebPage(TVControllerSuccessCallback successCallback, optional TVControllerErrorCallback? errorCallback);

This API is valid if the controlled TV has launched a TV browser. Otherwise, it is ignored. It is supported on the Samsung Smart TVs manufactured since 2012.

The error callback is launched with these error types:

  • UnknownError: In the case of any other error
Parameters
  • successCallback
    • Optional: No.
    • Nullable: No.
    • Type: TVControllerSuccessCallback.
    • Description: Callback function called if the request is successful
  • errorCallback
    • Optional: Yes.
    • Nullable: Yes.
    • Type: TVControllerErrorCallback.
    • Description: Callback function called if the request is fails
Exceptions
  • WebAPIException:

    with error type NotSupportedError, if this feature is not supported.

    with error type SecurityError, if this functionality is not allowed.

    with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.

goPreviousWebPage

Go to the previous page.

Signature
void goPreviousWebPage(TVControllerSuccessCallback successCallback, optional TVControllerErrorCallback? errorCallback);

This API is valid if the controlled TV has launched a TV browser. Otherwise, it is ignored. It is supported on the Samsung Smart TVs manufactured since 2012.

The error callback is launched with these error types:

  • UnknownError: In the case of any other error
Parameters
  • successCallback
    • Optional: No.
    • Nullable: No.
    • Type: TVControllerSuccessCallback.
    • Description: Callback function called if the request is successful
  • errorCallback
    • Optional: Yes.
    • Nullable: Yes.
    • Type: TVControllerErrorCallback.
    • Description: Callback function called if the request is fails
Exceptions
  • WebAPIException:

    with error type NotSupportedError, if this feature is not supported.

    with error type SecurityError, if this functionality is not allowed.

    with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.

openWebPage

Open the web page.

Signature
void openWebPage(DOMString url, TVControllerSuccessCallback successCallback, optional TVControllerErrorCallback? errorCallback);

This API is valid if the controlled TV has launched a TV browser. Otherwise, it is ignored. It is supported on the Samsung Smart TVs manufactured since 2012.

The error callback is launched with these error types:

  • UnknownError: In the case of any other error
Parameters
  • url
    • Optional: No.
    • Nullable: No.
    • Type: DOMString.
    • Description: The web page URL
  • successCallback
    • Optional: No.
    • Nullable: No.
    • Type: TVControllerSuccessCallback.
    • Description: Callback function called if the request is successful
  • errorCallback
    • Optional: Yes.
    • Nullable: Yes.
    • Type: TVControllerErrorCallback.
    • Description: Callback function called if the request is fails
Exceptions
  • WebAPIException:

    with error type NotSupportedError, if this feature is not supported.

    with error type SecurityError, if this functionality is not allowed.

    with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.

closeWebPage

Close the current web page.

Signature
void closeWebPage(TVControllerSuccessCallback successCallback, optional TVControllerErrorCallback? errorCallback);

This API is valid if the controlled TV has launched a TV browser. Otherwise, it is ignored. It is supported on the Samsung Smart TVs manufactured since 2012.

The error callback is launched with these error types:

  • UnknownError: In the case of any other error
Parameters
  • successCallback
    • Optional: No.
    • Nullable: No.
    • Type: TVControllerSuccessCallback.
    • Description: Callback function called if the request is successful
  • errorCallback
    • Optional: Yes.
    • Nullable: Yes.
    • Type: TVControllerErrorCallback.
    • Description: Callback function called if the request is fails
Exceptions
  • WebAPIException:

    with error type NotSupportedError, if this feature is not supported.

    with error type SecurityError, if this functionality is not allowed.

    with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.

refreshWebPage

Refresh the current web page.

Signature
void refreshWebPage(TVControllerSuccessCallback successCallback, optional TVControllerErrorCallback? errorCallback);

This API is valid if the controlled TV has launched a TV browser. Otherwise, it is ignored. It is supported on the Samsung Smart TVs manufactured since 2012.

The error callback is launched with these error types:

  • UnknownError: In the case of any other error
Parameters
  • successCallback
    • Optional: No.
    • Nullable: No.
    • Type: TVControllerSuccessCallback.
    • Description: Callback function called if the request is successful
  • errorCallback
    • Optional: Yes.
    • Nullable: Yes.
    • Type: TVControllerErrorCallback.
    • Description: Callback function called if the request is fails
Exceptions
  • WebAPIException:

    with error type NotSupportedError, if this feature is not supported.

    with error type SecurityError, if this functionality is not allowed.

    with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.

stopWebPageLoading

Stop the current Web page from loading

Signature
void stopWebPageLoading(TVControllerSuccessCallback successCallback, optional TVControllerErrorCallback? errorCallback);

This API is valid if the controlled TV has launched a TV browser. Otherwise, it is ignored. It is supported on the Samsung Smart TVs manufactured since 2012.

The error callback is launched with these error types:

  • UnknownError: In the case of any other error
Parameters
  • successCallback
    • Optional: No.
    • Nullable: No.
    • Type: TVControllerSuccessCallback.
    • Description: Callback function called if the request is successful
  • errorCallback
    • Optional: Yes.
    • Nullable: Yes.
    • Type: TVControllerErrorCallback.
    • Description: Callback function called if the request is fails
Exceptions
  • WebAPIException:

    with error type SecurityError, if this functionality is not allowed.

    with error type NotSupportedError, if this feature is not supported.

    with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.

3. Full WebIDL

module TVController {

    enum RemoteKey {
        "KEY_0", "KEY_1", "KEY_2", "KEY_3", "KEY_4", "KEY_5", "KEY_6", "KEY_7", "KEY_8", "KEY_9", 
        "KEY_BLUE", "KEY_CH_LIST", "KEY_CHDOWN", "KEY_CHUP", "KEY_CONTENTS", 
        "KEY_DASH", "KEY_DOWN", "KEY_ENTER", "KEY_EXIT", "KEY_FF", "KEY_GREEN", "KEY_INFO", "KEY_LEFT", 
        "KEY_MENU", "KEY_MUTE", "KEY_PAUSE", "KEY_PLAY", "KEY_POWEROFF", "KEY_PRECH", "KEY_REC", 
        "KEY_RED", "KEY_RETURN", "KEY_REWIND", "KEY_RIGHT", "KEY_SOURCE", "KEY_STOP", "KEY_TOOLS", 
        "KEY_UP", "KEY_VOLDOWN", "KEY_VOLUP", "KEY_YELLOW"
   };
    
    
    enum TVControllerBrowserMode {
        "POINT_BROWSING", 
        "LINK_BROWSING",
        "UNKNOWN"
    };

    enum BrowserScrollMode {
        "SCROLL_UP", 
        "SCROLL_DOWN"
    };

    enum BrowserZoomMode {
        "ZOOM_IN", 
        "ZOOM_OUT", 
        "ZOOM_DEFAULT"
    };

    [Callback=FunctionOnly, NoInterfaceObject] interface TVControllerSuccessCallback {
    
        void onsuccess(DeviceId controllerId);
    };    
  
    [Callback=FunctionOnly, NoInterfaceObject] interface TVControllerGetBrowserModeSuccessCallback {
    
        void onsuccess(TVControllerBrowserMode mode, 
                       DeviceId controllerId);
    };
    
    [Callback=FunctionOnly, NoInterfaceObject] interface TVControllGetBrowserUrlSuccessCallback {
        
        void onsuccess(DOMString url, 
                       DeviceId controllerId);
    };

    [Callback=FunctionOnly, NoInterfaceObject] interface TVControllerErrorCallback {
    
        void onerror(WebAPIError error, 
                     DeviceId controllerId);
    };
      
    [Callback, NoInterfaceObject] interface TVControllerEventCallback {
        
        void ondisconnected (DeviceId controllerId);
        
        void onstringchanged (DOMString text, 
                              DeviceId controllerId);
    };
    
    [NoInterfaceObject] interface TVController : DeviceDevice {
    
        readonly attribute DOMString version;
        
        readonly attribute boolean isWebSharingSupported;
        
        readonly attribute boolean isConnected;
        
        void connect(TVControllerSuccessCallback successCallback, 
                     optional TVControllerErrorCallback? errorCallback);
        
        void disconnect(TVControllerSuccessCallback successCallback, 
                        optional TVControllerErrorCallback? errorCallback);
        
        long addTVControllerEventListener (TVControllerEventCallback eventCallback);
        
        void removeTVControllerEventListener (long eventListener);

        void sendRemoteKey(RemoteKey key);
        
        void sendKeyboardString(DOMString text);
        
        void sendKeyboardEnd(); 

        
        void sendTouchClick();
        
        void sendTouchDown();
        
        void sendTouchMove(long long dx,
                           long long dy);
        
        void sendTouchUp();

        void setBrowserMode(TVControllerBrowserMode mode, 
                            TVControllerSuccessCallback successCallback, 
                            optional TVControllerErrorCallback? errorCallback);
        
        void getBrowserMode(TVControllerGetBrowserModeSuccessCallback successCallback, 
                            optional TVControllerErrorCallback? errorCallback);

        void scrollWebPage(BrowserScrollMode mode,  TVControllerSuccessCallback successCallback, 
                               optional TVControllerErrorCallback? errorCallback);
        
        void zoomWebPage(BrowserZoomMode mode, 
                         TVControllerSuccessCallback successCallback, 
                         optional TVControllerErrorCallback? errorCallback);
        
        void getBrowserUrl(TVControllGetBrowserUrlSuccessCallback successCallback, 
                           optional TVControllerErrorCallback? errorCallback);
        
        void goHomePage(TVControllerSuccessCallback successCallback, 
                        optional TVControllerErrorCallback? errorCallback);
        
        void goNextWebPage(TVControllerSuccessCallback successCallback, 
                                       optional TVControllerErrorCallback? errorCallback);
        
        void goPreviousWebPage(TVControllerSuccessCallback successCallback, 
                                            optional TVControllerErrorCallback? errorCallback);
        
        void openWebPage(DOMString url, 
                         TVControllerSuccessCallback successCallback, 
                         optional TVControllerErrorCallback? errorCallback);

        void closeWebPage(TVControllerSuccessCallback successCallback, 
                          optional TVControllerErrorCallback? errorCallback);
        
        void refreshWebPage(TVControllerSuccessCallback successCallback, 
                                       optional TVControllerErrorCallback? errorCallback);

        
        void stopWebPageLoading(TVControllerSuccessCallback successCallback, 
                                optional TVControllerErrorCallback? errorCallback);    
    };
};