Service Types

This section describes the syntax of the three categories of messages and their payloads. For sample message interactions, see the Sequence Diagrams section.

Input Service

The service type INPUT is used to publish messages related to user inputs, for example keyboard, navigation, and media controls, to the device or TV.

Keyboard Service

The keyboard service is designed to support On Screen Keyboards (OSK) on the device display and the connected TV display. When the consumer opens an OSK on the connected TV display, the device receives a publish event. The complete state of the keyboard is passed as the event payload.

When the consumer edits the OSK on the device the Engine receives a publish event which causes the Framework to trigger the onKeyboardStateChanged() callback function with the complete keyboard state.

Every keystroke generates an event. Keyboard events must be sent in full every time any value changes. The goal is to emulate every movement from one device’s OSK on the other device’s OSK and vice versa. For JavaScript API details, see the KONtx Framework Remote Device Singleton.

Device Request: SUBSCRIBE|INPUT|keyboard|END

Engine Response : SUBSCRIBED|INPUT|keyboard|END

In the keyboard event, the message payload contains the full state of the keyboard as a JSON string.

Device or Engine::

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 

  • <total_value>: string, complete value of the string on screen
  • <key_code>: integer, special key codes including:
    • BACKSPACE : 8
    • TAB : 9
    • RETURN : 13
    • CAPS_LOCK : 20
    • ESCAPE : 27
    • PAGE_UP : 33
    • PAGE_DOWN : 34
    • END : 35
    • HOME : 36
    • PRINTSCREEN : 44
    • INSERT : 45
    • DELETE : 46
    • F10 : 121
    • NUM_LOCK : 144
    • SCROLL_LOCK : 145
  • <cursor_position>: integer, zero-based offset of the cursor into the total string
  • <keyboard_on_screen>: Boolean, true if the keyboard is currently on the connected TV display. This is only sent by the Engine and ignored if received from the device.
  • <control_state>: Boolean, true if control key is pressed
  • <shift_state>: Boolean, true if shift key is pressed
  • <alt_state>: Boolean, true if the alt key is pressed
  • <last_key>: character, the last character hit. If the last key hit was not a character, then <last_key> should be null or an empty string. In this case, <key_code> should be populated.
  • <layout_type>: integer, 0 - QWERTY keyboard; 1 - PIN-entry keyboard

The navigation service has set entry points to emulate remote control keys. These events are not passed to the JavaScript contexts. If simulating a prolonged key press, multiple key down events must be sent.

Device Request: SUBSCRIBE|INPUT|navigation|END

Engine Response: SUBSCRIBED|INPUT|navigation|END

The navigation event's message payload contains the action/key name and is not a JSON string.

Device or Engine: PUBLISH|INPUT|navigation|<action>|END

The parameter <action> is defined as follows:

  • press_<key>: full press-release key hit
  • down_<key>: on key down

Where the parameter <key> is one of the following: [a to z], [A to Z], [0 to 9], up, down, left, right, enter, yahoo (Yahoo! TV Key), back, backspace, red, green, yellow, blue, play, pause, stop, forward, rewind, skip_forward, skip_backward, and info.

Media Control Service

The media control service supports interactive media controls, such as scrub bars and metadata passing. When the message is sent from the device to the Engine, only the timeIndex payload property is read and acted upon.

Device Request: SUBSCRIBE|INPUT|mediacontrol|END

Engine Response: SUBSCRIBED|INPUT|mediacontrol|END

The media control event message payload contains the state of the media transport controls and is a JSON string.

Device or Engine:

PUBLISH|INPUT|mediacontrol|{
  "state": <state>, 
  "timeindex": <timeindex>, 
  "duration": <duration>, 
  "humanDuration": <humanDuration>, 
  "isControlOnScreen": <isControlOnScreen>
}|END

  • <state>: An integer constant corresponding to the following KONtx.mediaplayer.constants.states:
    • INIT : -1
    • PLAY : 0
    • PAUSE : 1
    • FASTFORWARD : 2
    • REWIND : 3
    • STOP : 4
    • BUFFERING : 5
    • BUFFEREMPTY : 6
    • INFOLOADED : 7
    • EOF : 8
    • UNKNOWN : 9
    • ERROR : 10
  • <timeindex>: An integer representing the current time index in seconds.
  • <duration>: An integer representing the total duration of the current clip in seconds.
  • <humanDuration>: A String that is the total duration matching the onscreen duration display.
  • <isControlOnScreen>: A Boolean that is true if the overlay controls are currently onscreen, and false otherwise.

Service Type

The service type SERVICE is used to support advanced services such as media launching, app listing, and others to be specified (TBS).

Media Launch Service

The media launching service allows an app to broadcast a media type to be opened by any device. This message is sent to the device only, media launch messages sent to the Engine are ignored.

Device Request: SUBSCRIBE|SERVICE|medialaunch|END

Engine Response: SUBSCRIBED|SERVICE|medialaunch|END

The media launch message payload contains the URL to launch and its metadata and is a JSON string.

Engine:

PUBLISH|SERVICE|medialaunch|{
  "mimetype": <mimetype>, 
  "name": <name>, 
  "url": <url>
}|END 

  • <mimetype>: A String representing the MIME type of the media.
  • <name>: A String for the name or title of the media.
  • <url>: A String for the URL of the media.
TV App List Service

The app listing service allows devices to receive a list of all currently installed apps (formerly called widgets) for the profile. Events continue to fire as app installations change.

Device Request: SUBSCRIBE|SERVICE|widgetlist|END

Engine Response: SUBSCRIBED|SERVICE|widgetlist|END

The app list message payload contains the TV App ID and metadata of an installed app and is a JSON string.

Engine:

PUBLISH|SERVICE|widgetlist|{
  "id": <id>, 
  "name": <name>, 
  "iconURL": 
  <iconURL>
}|END 

  • <id>: The String TV App ID.
  • <name>: The String name of the app.
  • <iconURL>: The String URL for the app's icon. See the section on Creating Icon Images.

Widget Type

The service type WIDGET is used for device-app communication and enables apps and devices to pass JSON strings to one another. When a device connects to the Device Communication module of the Engine it can request to receive all messages from a specific app. The app sends publish events to any devices subscribed to its message interface. This service enables special keyboards, game keyboards, and other unique user interfaces to communicate with the app.

Device Request: SUBSCRIBE|WIDGET|<tv_app_id>|END

Engine Response: SUBSCRIBED|WIDGET|<tv_app_id>|END

The app message payload is defined by the app and is a JSON string.

Device or Engine: PUBLISH|WIDGET|<tv_app_id>|<json_string>|END

  • The <tv_app_id> is the TV App ID that is the unique identifier of the app (formerly called widget)
  • The <json_string> is the message payload passed as a JSON string

Table of Contents