Chapter 15. Remote Device

Yahoo Connected TV's device communication model enables new and exciting TV-viewing experiences driven by the sophisticated controls available on today's mobile phones, tablets, and laptops. A new generation of TV App capabilities is now available to consumers, including gesture-based, multi-display, and multi-user features for intensive gaming, multimedia, and social applications.

The Yahoo Connected TV (YCTV) Device Communication platform provides two-way message-passing between Internet-enabled devices (such as AndroidOs & iOS mobile phones, tablets, and laptops) and consumer electronic devices (such as TVs, DVD/Blu-ray players, and DVRs) running the Yahoo Connected TV platform. These messages are communicated through a new protocol created by Yahoo using SSL-wrapped sockets over local TCP/IP. Message payloads can contain either JSON-encoded strings or predefined commands. Keyboard, navigation, media control, and app-specific messages are communicated using a publish/subscribe model and direct method calls.

The Device Communication model supports two types of application programming interfaces (APIs):

  • The Device Interface — The application developer uses this interface to write extensions to their own device applications to enable communication with apps and the Engine. This device communication protocol is versioned.

  • The KONtx Framework Remote Device Singleton — The app developer uses this JavaScript API to enable apps to communicate with applications on a remote device. The KONtx Application Framework is based on standard JavaScript and Yahoo JavaScript Extensions. The entire Remote Device JavaScript API is contained in the common namespace KONtx.remotedevice. The KONtx.remotedevice interface is only available when it is enabled on the Connected TV platform. Check that the Boolean system.features.devicecommunication is true in the config-oem.xml file. Event callbacks are use to relay messages from the device to the app via the Engine.

The following conventions are followed for this interface

  • The entire JavaScript API is contained in the common namespace: remoteDevice.
  • The remoteDevice Object will only be available if the feature is enabled on the platform. You can check this by looking at system.features.devicecommunication in the config-oem.xml file.
  • The device communication protocol is versioned.
  • Device communication event callbacks are messages from the remote device via the Engine.

In addtion to this JavaScript KONtx.remoteDevice interface for apps, you will also find device communication documentation here:

KONtx.remotedevice

remote device singleton

The KONtx.remotedevice singleton provides the interface for apps to communicate with remote devices, including mobile phones, tablets, and laptops.

Event Callbacks

The KONtx.remotedevice interface provides callbacks to handle events to and from the remote device.

 Callback 

 Type 

 Description 

 Device Protocol 

 onInstanceError 

 function 

  Callback function triggered when a remote device  
  encounters an error. The device sends a message to the app via this 
  onInstanceError event callback. Returns the instanceId  
  assigned to the device, a three digit error code string, 
  code, and an error description string,  
  message. Current error codes and messages are:  

  • 001 – Invalid Application Key
  • 002 – Invalid Instance ID
  • 003 – Invalid Signature
  • 101 – Unknown Message Type

  ERROR |  
  <code> |  
  <message> |  
  END  

 onKeyboardStateChanged 

 function 

  Callback function triggered when the remote  
  device’s keyboard state has changed. Returns the  
  instanceId assigned to the device  
  and an Object data containing  
  the device’s latest keyboard state. The  
  KONtx.remotedevice interface  
  receives a message from the remote device  
  and calls JSON.parse() to parse  
  the message string. If successful, a JSON  
  Object  is returned, otherwise  
  an error occurs.  

  PUBLISH |  
  INPUT |  
  keyboard |  
  {"totalValue": <total_value>,  
   "keyCode": <key_code>,  
   "cursorPosition":  
       <cursor_position>,  
   "isKeyboardOnScreen":  
       <keyboard_on_screen>,  
   "modifiers":  
       {"control": <control_state>,  
        "shift": <shift_state>,  
        "alt": <alt_state>},  
   "key": <last_key>,  
   "layoutType": <layout_type>} |  
  END  

 onKeyboardSubscribed 

 function 

  Callback function triggered when a remote device
  subscribes to keyboard input. Returns the remote 
  device’s assigned instanceId.  

  SUBSCRIBE |
  INPUT |
  keyboard |
  END  

 onKeyboardUnsubscribed 

 function 

  Callback function triggered when a remote device
  unsubscribes from keyboard input. Returns the remote
  device’s assigned instanceId.  

  UNSUBSCRIBE |  
  INPUT |  
  keyboard |  
  END  

 onMediaControlStateChanged 

 function 

  Callback function triggered when the remote  
  device’s media control state has changed. Returns  
  the instanceId assigned to the  
  device and a mixed type data containing  
  the device’s latest media control state. The  
  KONtx.remotedevice interface receives a  
  message from the remote device and attempts to call  
  JSON.parse() to parse the message  
  string. If successful, a JSON Object is  
  returned, otherwise an error occurs.  

  PUBLISH |  
  INPUT |  
  mediacontrol |  
  <data>  |
  END  

 onMediaControlSubscribed 

 function 

  Callback function triggered when a remote device
  subscribes to media control input. Returns the remote
  device’s assigned instanceId.  

  SUBSCRIBE |  
  INPUT |
  mediacontrol |
  END  

 onMediaControlUnsubscribed 

 function 

  Callback function triggered when a remote device  
  unsubscribes from media control input. Returns the  
  remote device’s assigned instanceId.  

  UNSUBSCRIBE |  
  INPUT |  
  mediacontrol |  
  END  

 onRemoteCall 

 function 

  Callback function triggered when the remote device  
  initiates a remote call. Returns an Object event  
  describing the remote call. The event Object  
  has the following properties:  

  • method – The name of the method being called.
  • widgetid – The unique identifier of the app implementing the method (if required).
  • instanceid – The unique identifier assigned to the remote device making the call.
  • callid – The unique identifier of this specific call, used to implement multiple pending calls.
  • data – The String data payload.

  CALL |  
  <method> |  
  <widgetId> |  
  <data> |  
  <callId> |  
  END  

  onRemoteEventReceived  

  function  

  Callback function triggered when the remote device  
  returns from a remote call initiated by the app.  
  Returns an Object event  
  describing the remote call. The event Object  
  has the following properties:

  • method – The name of the method being called.
  • widgetid – The unique identifier of the app implementing the method (if required).
  • instanceid – The unique identifier assigned to the remote device making the call.
  • callid – The unique identifier of this specific call, used to implement multiple pending calls.
  • result – The String result payload.

  RETURN |  
  <method> |  
  <widgetId> |  
  <result> |  
  <callId> |  
  END  

 onWidgetMessageReceived 

 function 

  Callback function triggered when a message is  
  received from a remote device. Returns the  
  instanceId assigned to the  
  device and a mixed type data containing the  
  device’s message. The data may be a JSON  
  Object or a String.  
  The KONtx.remotedevice interface  
  receives a message from the remote device and  
  attempts to call JSON.parse()  
  to parse the message string. If successful, a JSON  
  Object is returned. If the JSON.parse()  
  call fails, the message is passed through  
  to the app as a string.  

  PUBLISH |  
  WIDGET |  
  <widgetId> |  
  <data> |  
  END  

 onWidgetSubscribed 

 function 

  Callback function triggered when a remote device
  subscribes to your app. Returns the remote 
  device’s assigned instanceId.  

  SUBSCRIBE |
  WIDGET |
  <widgetId> |
  END  

 onWidgetUnsubscribed 

 function 

  Callback function triggered when a remote device
  unsubscribes from your app. Returns the remote
  device’s assigned instanceId.  

  UNSUBSCRIBE |  
  WIDGET |
  <widgetId> |
  END  

Callback Examples

The KONtx.remotedevice interface provides callbacks to handle events to and from the remote device. The following example shows how to register and unregister callback handlers for remote device callback events.

Property

  Property  

  Type  

  Description  

  isEnabled  

  Boolean  

  If isEnabled is true, then the partner's device supports remote device 
  communication. If isEnabled is false,  then remote device communication is not 
  supported. This Boolean points to system.features.remoteDevice.  

Methods

Array<String> findKeyboardSubscribers()

Finds all subscribers to keyboard state changes.

Array<String> findMediaControlSubscribers()

Finds all subscribers to media control state changes.

Array<String> findSubscribers(String type, String subject)

Finds all subscribers for a given type and subject.

Array<String> findWidgetSubscribers()

Finds all subscribers for the current app.

RemoteDeviceInfo getInstance(String instanceId)

Gets metadata about a particular instanceId identifying a remote device.

Array<RemoteDeviceInfo> getInstances(Array<String> instanceIds)

Gets metadata about the remote device(s) identified by an array of String instanceIds.

Boolean publishKeyboardMessage(Object data, [Array<String> instanceIds])

Publishes a keyboard message. The Object data parameter is the keyboard state payload sent to remote device(s).

Boolean publishMediaControlMessage(Object data, [Array<String> instanceIds])

Publishes a media control message. The Object data parameter is the transport control state payload sent to remote device(s).

Boolean publishMediaLaunchMessage(Object data, [Array<String> instanceIds])

Publishes a message to devices identifying media to be launched. The Object data parameter is the media metadata payload sent to remote device(s).

Boolean publishMediaLaunchUrlMessage(String title, String url, [Array<String> instanceIds])

Publishes a message to devices identifying media to be launched by URL.

Boolean publishMessage(Object payload)

Publishes a given message. The parameter Object payload contains the message string as well as message metadata.

Boolean publishWidgetMessage(String data, [Array<String> instanceIds])

Publishes a app message. Publishes the given JSON-encoded string message data to identified listeners.

Boolean returnRemoteCall(RemoteDeviceEvent event)

Respond to an incoming call from a remote device by replying to the device with the original RemoteDeviceEvent event Object received, with return data populated in the event.result property.

Boolean sendRemoteCall(RemoteDeviceEvent event)

Initiate a remote call by sending a RemoteDeviceEvent event to a remote device.

Table of Contents