VoiceInteraction API

To use Samsung Product API,

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

Should be loaded in index.html

Samsung TVs allow developers to use voice commands such as Navigation, Search, Selection and Media Control to control their application.
The Voice Assistant in the TV can be Bixby or other assistants. Regardless of which assistant is used, the application will interact with it via the Voice Interaction APIs.
For best results, we recommend the application to be implemented with all the features that are described in this document.

Since : 6.0

Product : TV

Privilege Level : Public

Privilege : http://developer.samsung.com/privilege/voicecontrol

Summary of Interfaces and Methods

Interface

Method

VoiceInteractionManagerObject

VoiceInteractionCallback

optional VoiceApplicationState onupdatestate();
optional boolean onnavigation(VoiceNavigation voiceNavigation);
optional boolean onsearch(VoiceSearchTerm voiceSearchTerm);
optional boolean onplay();
optional boolean onstop();
optional boolean onpause();
optional boolean onexit();
optional boolean onselection(long voiceSelection);
optional boolean ontitleselection(DOMString title);
optional boolean onfastforward();
optional boolean onrewind();
optional DOMString onsearchcollection(VoiceSearchTerm voiceSearchTerm);
optional boolean onchangeappstate(VoiceApplicationState state);
optional boolean onchangeprevioustrack();
optional boolean onchangenexttrack();
optional boolean onrestart();
optional boolean onskipbackward(long offsetSeconds);
optional boolean onskipforward(long offsetSeconds);
optional boolean onsetplayposition(long position);
optional boolean onchangesubtitlemode(MediaFunctionMode mode);
optional boolean onchangeshufflemode(MediaFunctionMode mode);
optional boolean onchangescreenfitmode(MediaFunctionMode mode);
optional boolean onzoom(MediaZoomMode zoom);
optional boolean onrotate(MediaRotateMode direction);
optional boolean onchange360mode(MediaFunctionMode mode);
optional boolean onchangerepeatmode(MediaRepeatMode mode);
optional boolean oncontinuewatching();
optional boolean oncustom(DOMString jsonObjectString);
optional DOMString onrequestcontentcontext();
optional boolean onadditiontolist(ListItem list);
optional boolean onremovalfromlist(ListItem list);
optional boolean onplaylist(ListItem list);
optional boolean onbrowselist(ListItem list);
optional boolean onskipad();

VoiceSearchTerm

VoiceInteractionContentContext

VoiceInteractionManager

DOMString getVersion();
void setCallback(VoiceInteractionCallback callback);
void listen();
DOMString getDataFromSearchTerm(VoiceSearchTerm voiceSearchTerm, VoiceSearchTermField field);
DOMString buildCollectionDeeplinkData(DOMString appId, DOMString title, DOMString payload);
DOMString buildCollectionShowData(DOMString appId, DOMString title, DOMString payload, DOMString thumbnail);
VoiceInteractionContentContext buildVoiceInteractionContentContextItem(long positionX, long positionY, DOMString title, DOMString[] aliasArr, boolean bFocused);
DOMString buildVoiceInteractionContentContextResponse(VoiceInteractionContentContext[] contentContextArr);

1. Type Definitions

1.1 VoiceApplicationState

the application status handled via Voice Interaction.

enum VoiceApplicationState {
  "None",
  "Home",
  "List",
  "Player",
  "Setting",
  "Search",
  "Unknown"
};

The following values are supported

  • None : Application Default Status.
  • Home : The status of application's home.
  • List : The status of application showing something in list.
  • Player : The status of application playing something.
  • Setting : The status of application showing its setting.
  • Search : The status of application searching its content.
  • Unknown : The status of unknown.

1.2 VoiceNavigation

The navigation via Voice Interaction.

enum VoiceNavigation {
  "NAV_PREVIOUS",
  "NAV_NEXT",
  "NAV_LEFT",
  "NAV_RIGHT",
  "NAV_UP",
  "NAV_DOWN",
  "NAV_SHOW_MORE",
  "NAV_UNKNOWN"
};

The following values are supported

  • NAV_PREVIOUS : The navigation for the previous page.
  • NAV_NEXT : The navigation for the next page.
  • NAV_LEFT : The navigation for the left item.
  • NAV_RIGHT : The navigation for the right item.
  • NAV_UP : The navigation for the upper item.
  • NAV_DOWN : The navigation for the down item.
  • NAV_SHOW_MORE : The navigation for the detail page.
  • NAV_UNKNOWN : The navigation for unknown.

1.3 VoiceSearchTermField

Defines the fields which can be delivered via voice search.

enum VoiceSearchTermField {
  "SEARCH_TERM_UTTERANCE",
  "SEARCH_TERM_TITLE",
  "SEARCH_TERM_GENRE",
  "SEARCH_TERM_CAST",
  "SEARCH_TERM_CONTENT_TYPE",
  "SEARCH_TERM_RELEASE_DATE_FROM",
  "SEARCH_TERM_RELEASE_DATE_TO"
};

The following values are supported

  • SEARCH_TERM_UTTERANCE : The field for the full utterance.
  • SEARCH_TERM_TITLE : The field for the title.
  • SEARCH_TERM_GENRE : The field for the genre.
  • SEARCH_TERM_CAST : The field for the cast.
  • SEARCH_TERM_CONTENT_TYPE : The field for the content type (movie/tvshow).
  • SEARCH_TERM_RELEASE_DATE_FROM : The field for the start date time(ISO 8601).
  • SEARCH_TERM_RELEASE_DATE_TO : The field for the end date time(ISO 8601).

1.4 MediaFunctionMode

Enum for the param of Media Control function mode.

enum MediaFunctionMode {
  "MEDIA_FUNCTION_ON",
  "MEDIA_FUNCTION_OFF"
};

The following values are supported

  • MEDIA_FUNCTION_ON : Media Function Mode On.
  • MEDIA_FUNCTION_OFF : Media Function Mode Off.

1.5 MediaRotateMode

Enum for the param of Rotate.

enum MediaRotateMode {
  "MEDIA_ROTATE_LEFT",
  "MEDIA_ROTATE_RIGHT"
};

The following values are supported

  • MEDIA_ROTATE_LEFT : Media Rotate Mode Left.
  • MEDIA_ROTATE_RIGHT : Media Rotate Mode Right.

1.6 MediaZoomMode

Enum for the param of Zoom.

enum MediaZoomMode {
  "MEDIA_ZOOM_IN",
  "MEDIA_ZOOM_OUT"
};

The following values are supported

  • MEDIA_ZOOM_IN : Media Zoom Mode In.
  • MEDIA_ZOOM_OUT : Media Zoom Mode Out.

1.7 MediaRepeatMode

Enum for the param of Media Repeat.

enum MediaRepeatMode {
  "MEDIA_REPEAT_OFF",
  "MEDIA_REPEAT_ONE",
  "MEDIA_REPEAT_ALL"
};

The following values are supported

  • MEDIA_REPEAT_OFF : Media Repeat Mode Off.
  • MEDIA_REPEAT_ONE : Media Repeat Mode for One track.
  • MEDIA_REPEAT_ALL : Media Repeat Mode for All tracks.

1.8 ListItem

Enum for the param of List item.

enum ListItem {
  "LIST_BOOKMARKS",
  "LIST_WATCH_LATER",
  "LIST_UNKNOWN"
};

The following values are supported

  • LIST_BOOKMARKS : Bookmarks
  • LIST_WATCH_LATER : WatchLater
  • LIST_UNKNOWN : Unknown

2. Interfaces

2.1 VoiceInteractionManagerObject

The VoiceInteractionManagerObject interface defines what is instantiated by the WebAPIs object from the Tizen Platform.
There will be a webapis.voiceinteraction object that allows access to the functionality of the Voice Interaction API.
To use the Voice Interaction API, the following privileges must be declared in the manifest file of the application.
If they are not declared, all usage of these APIs are blocked, and security exceptions are thrown. To use these privileges, the minimum ‘required_version’ is 6.0.

[NoInterfaceObject] interface VoiceInteractionManagerObject {
  readonly attribute VoiceInteractionManager voiceinteraction;
};
WebApi implements VoiceInteractionManagerObject;

Since : 6.0

Attributes

  • readonly VoiceInteractionManager voiceinteraction
    This attribute defines the namespace for voiceinteraction APIs.

2.2 VoiceInteractionCallback

Every voice interaction application should implement a callback function, so that the Assistant can operate the controls.
Your application can interact with voice assistant by passing the callbacks in webapis.voiceinteraction.setCallback and calling webapis.voiceinteraction.listen.
Except onupdatestate, onsearchcollection callbacks, the return value for the callback is the boolean flag for support or not.
If a callback returns the false/undefined value, or there is no callback implementation for the utterance, Samsung device may perform its basic function.

[Callback, NoInterfaceObject] interface VoiceInteractionCallback {
  optional VoiceApplicationState onupdatestate();
  optional boolean onnavigation(VoiceNavigation voiceNavigation);
  optional boolean onsearch(VoiceSearchTerm voiceSearchTerm);
  optional boolean onplay();
  optional boolean onstop();
  optional boolean onpause();
  optional boolean onexit();
  optional boolean onselection(long voiceSelection);
  optional boolean ontitleselection(DOMString title);
  optional boolean onfastforward();
  optional boolean onrewind();
  optional DOMString onsearchcollection(VoiceSearchTerm voiceSearchTerm);
  optional boolean onchangeappstate(VoiceApplicationState state);
  optional boolean onchangeprevioustrack();
  optional boolean onchangenexttrack();
  optional boolean onrestart();
  optional boolean onskipbackward(long offsetSeconds);
  optional boolean onskipforward(long offsetSeconds);
  optional boolean onsetplayposition(long position);
  optional boolean onchangesubtitlemode(MediaFunctionMode mode);
  optional boolean onchangeshufflemode(MediaFunctionMode mode);
  optional boolean onchangescreenfitmode(MediaFunctionMode mode);
  optional boolean onzoom(MediaZoomMode zoom);
  optional boolean onrotate(MediaRotateMode direction);
  optional boolean onchange360mode(MediaFunctionMode mode);
  optional boolean onchangerepeatmode(MediaRepeatMode mode);
  optional boolean oncontinuewatching();
  optional boolean oncustom(DOMString jsonObjectString);
  optional DOMString onrequestcontentcontext();
  optional boolean onadditiontolist(ListItem list);
  optional boolean onremovalfromlist(ListItem list);
  optional boolean onplaylist(ListItem list);
  optional boolean onbrowselist(ListItem list);
  optional boolean onskipad();
};

Since : 6.0

Methods

onupdatestate

Developers must specify the current application status to the onupdatestate function to get a proper voice control from the Voice Assistant.
This function is called right before processing every utterance, so that the Voice Assistant can be aware of the application status dynamically.
Depending on the status, the callback function called could be different. Therefore, it is important to return the real status of the application.

optional VoiceApplicationState onupdatestate();

Product : TV

Privilege Level : Public

Privilege : http://developer.samsung.com/privilege/voicecontrol

Return Value :

  • optional VoiceApplicationState : the status of the current application status.
    "None" : Application is in its default status. Same as "Player" status.
    "List" : The application is showing something in list.
    During this status, the utterances "Play this" or "Play" will call onselection(0).
    The utterance "Previous" will call onnavigation ("NAV_PREVIOUS").
    "Player" : The application is playing a piece of content.
    During this status, the utterance "Play this" will call onplay().

Since : 6.0

Code Example :

webapis.voiceinteraction.setCallback({
  onupdatestate : function () {
    console.log("Assistant tries to get app state");
    return "List";
  }
});

onnavigation

To support navigation controls via voice, the application should have the following callbacks. Otherwise, the Key Event will be generated.

optional boolean onnavigation(VoiceNavigation voiceNavigation);

Product : TV

Privilege Level : Public

Privilege : http://developer.samsung.com/privilege/voicecontrol

Parameters :

  • voiceNavigation : The navigation enumeration via Voice.

Return Value :

  • optional boolean : boolean value of whether the app supports this feature.
    If a callback returns the false/undefined value, or there is no callback implementation for the utterance, Samsung device may perform its basic function.

Since : 6.0

Code Example :

webapis.voiceinteraction.setCallback({
  onupdatestate : function () {
    console.log("Assistant tries to get app state");
    return "List";
  },
  onnavigation : function (voiceNavigation) {
    var bSupport = true;
    console.log("onnavigation : " + voiceNavigation);
    switch(voiceNavigation) {
      case "NAV_PREVIOUS ":
      // "Previous page"
      break;
      case "NAV_NEXT":
      // "Next page"
      break;
      case "NAV_LEFT":
      // "Go to left"
      break;
      case "NAV_RIGHT":
      // "Move to right"
      break;
      case "NAV_UP":
      // "Move up"
      break;
      case "NAV_DOWN":
      // "Go down"
      break;
      // If there is no callback implementation for these enums,
      // TV will Generate Remote Control Key Events: "ArrowRight", "ArrowLeft", "ArrowUp", "ArrowDown".
      case "NAV_SHOW_MORE":
      // "Show me more"
      break;
      default:
      bSupport = false;
      break;
    }
    return bSupport;
  }
});

onsearch

For a contents search provided by the application, it can receive a search utterance to show the search results.
In order to support the search via voice, the application must be registered to Samsung TV's companion search application and have the following callbacks.
The OnSearch parameter has a specific format. To learn more about it, please refer to the getDataFromSearchTerm.
Some callbacks are not called by default such as onsearch.
To receive all the callback signals on the development stage, request a key from Samsung and apply the key to the Manifest of your Tizen Application.
The following example shows how to add the "http://developer.samsung.com/tizen/metadata/support-vif-devfeature" key to the manifest file.

optional boolean onsearch(VoiceSearchTerm voiceSearchTerm);

Product : TV

Privilege Level : Public

Privilege : http://developer.samsung.com/privilege/voicecontrol

Parameters :

  • voiceSearchTerm : The Object contains the information via Voice.

Return Value :

  • optional boolean : boolean value of whether the app supports this feature.
    If a callback returns the false/undefined value, or there is no callback implementation for the utterance, Samsung device may perform its basic function.

Since : 6.0

Code Example :

<?xml version="1.0" encoding="UTF-8"?>
<widget xmlns="http://www.w3.org/ns/widgets" tizen="http://tizen.org/ns/widgets" id="http://yourdomain/VoiceInteractionWebSample" version="1.0.0" viewmodes="maximized">
<access origin="" subdomains="true"></access>
< application id="AbCDEfgHrJ.VoiceInteractionWebSample" package="AbCDEfgHrJ" required_version="6.0"/>
<content src="index.html"/>
<feature name="http://tizen.org/feature/screen.size.normal.1080.1920"/>
<icon src="icon.png"/>
< metadata key="http://developer.samsung.com/tizen/metadata/support-vif-dev-feature" value="true"/>
<name>VoiceInteractionWebSample</name>
< privilege name="http://developer.samsung.com/privilege/voicecontrol"/>
< privilege name="http://developer.samsung.com/privilege/microphone"/>
< profile name="tv-samsung"/>
</widget>
@endcode
@param voiceSearchTerm The Object contains the information via Voice.
@see getDataFromSearchTerm
@throw None N/A
@return boolean value of whether the app supports this feature.
If a callback returns the false/undefined value, or there is no callback implementation for the utterance, Samsung device may perform its basic function.
@code
webapis.voiceinteraction.setCallback({
  onupdatestate : function () {
    console.log("Assistant tries to get app state");
    return "Home";
  },
  onsearch : function (voiceSearchTerm) {
    console.log("OnSearch : " + JSON.stringify(voiceSearchTerm));
    var title = webapis.voiceinteraction.getDataFromSearchTerm(voiceSearchTerm, "SEARCH_TERM_TITLE");
    var genre = webapis.voiceinteraction.getDataFromSearchTerm(voiceSearchTerm, "SEARCH_TERM_GENRE");
    console.log("Request to search " + title + ", " + genre);
    return true;
  }
});

onplay

Supports the media control to handle playback(Play).

optional boolean onplay();

Product : TV

Privilege Level : Public

Privilege : http://developer.samsung.com/privilege/voicecontrol

Return Value :

  • optional boolean : boolean value of whether the app supports this feature.
    If a callback returns the false/undefined value, or there is no callback implementation for the utterance, Samsung device may perform its basic function.

Since : 6.0

Code Example :

webapis.voiceinteraction.setCallback({
  onupdatestate : function () {
    console.log("Assistant tries to get app state");
    return "Player";
  },
  onplay : function () {
    // TV Default Action: Generates the Remote Control Key, "MediaPlay".
    console.log("OnPlay called");
    return true;
  }
});

onstop

Supports the media control to handle playback(Stop).

optional boolean onstop();

Product : TV

Privilege Level : Public

Privilege : http://developer.samsung.com/privilege/voicecontrol

Return Value :

  • optional boolean : boolean value of whether the app supports this feature.
    If a callback returns the false/undefined value, or there is no callback implementation for the utterance, Samsung device may perform its basic function.

Since : 6.0

Code Example :

webapis.voiceinteraction.setCallback({
  onupdatestate : function () {
    console.log("Assistant tries to get app state");
    return "Player";
  },
  onstop : function () {
    // TV Default Action: Generates the Remote Control Key, "MediaStop".
    console.log("OnStop called");
    return true;
  }
});

onpause

Supports the media control to handle playback(Pause).

optional boolean onpause();

Product : TV

Privilege Level : Public

Privilege : http://developer.samsung.com/privilege/voicecontrol

Return Value :

  • optional boolean : boolean value of whether the app supports this feature.
    If a callback returns the false/undefined value, or there is no callback implementation for the utterance, Samsung device may perform its basic function.

Since : 6.0

Code Example :

webapis.voiceinteraction.setCallback({
  onupdatestate : function () {
    console.log("Assistant tries to get app state");
    return "Player";
  },
  onpause : function () {
    // TV Default Action: Generates the Remote Control Key, "MediaPlayPause".
    console.log("OnPause called");
    return true;
  }
});

onexit

Supports the media control to handle playback(Exit).

optional boolean onexit();

Product : TV

Privilege Level : Public

Privilege : http://developer.samsung.com/privilege/voicecontrol

Return Value :

  • optional boolean : boolean value of whether the app supports this feature.
    If a callback returns the false/undefined value, or there is no callback implementation for the utterance, Samsung device may perform its basic function.

Since : 6.0

Code Example :

webapis.voiceinteraction.setCallback({
  onupdatestate : function () {
    console.log("Assistant tries to get app state");
    return "Player";
  },
  onexit : function () {
    // TV Default Action: Generates the Remote Control Key, "Exit".
    console.log("OnExit called");
    return true;
  }
});

onselection

To support selection controls via voice, the application should have the following callbacks.
This callback supports the ordinal, relative selection control.

optional boolean onselection(long voiceSelection);

Product : TV

Privilege Level : Public

Privilege : http://developer.samsung.com/privilege/voicecontrol

Parameters :

  • voiceSelection : The relative index via voice, (ex. the last item is -1, the current item is 0, the first item is 1).

Return Value :

  • optional boolean : boolean value of whether the app supports this feature.
    If a callback returns the false/undefined value, or there is no callback implementation for the utterance, Samsung device may perform its basic function.

Since : 6.0

Code Example :

webapis.voiceinteraction.setCallback({
  onupdatestate : function () {
    console.log("Assistant tries to get app state");
    return "List";
  },
  onselection : function (voiceSelection) {
    var bSupport = true;
    console.log("onselection : " + voiceSelection);
    switch(voiceSelection) {
      case -1 :
      // "Select the last one"
      break;
      case 0 :
      // "Select this"
      break;
      default:
      {
        if(voiceSelection >= 1)
        // "Select the first one"
        {
          // Select the (voiceSelection)th item
          // index of the first item is 1
          console.log("For Ordinal : " + voiceSelection);
        }
        else
        {
          bSupport = false;
        }
      }
      break;
    }
    return bSupport;
  }
});

ontitleselection

Title selection refers to an utterance in the format "Select {Title Name}".
To support the title selection via voice, the following two callbacks are required : onrequestcontentcontext and ontitleselection.
The onrequestcontentcontext callback provides the information regarding the content of the screen (such as title and position) to the Samsung TV.
This method will be invoked at the beginning of every utterance. The response consists of positionX(int), positionY(int), title(string), alias(string array) and bFocused(bool).
The title property is used for ASR conversion and the other properties are used to set the priority of each title.
The OnTitleSelection callback receives the title name from the utterance.

optional boolean ontitleselection(DOMString title);

Product : TV

Privilege Level : Public

Privilege : http://developer.samsung.com/privilege/voicecontrol

Parameters :

  • title : the string input via voice.

Return Value :

  • optional boolean : boolean value of whether the app supports this feature.
    If a callback returns the false/undefined value, or there is no callback implementation for the utterance, Samsung device may perform its basic function.

Since : 6.0

Code Example :

webapis.voiceinteraction.setCallback({
  onupdatestate : function () {
    console.log("Assistant tries to get app state");
    return "List";
  },
  onrequestcontentcontext : function () {
    console.log("onrequestcontentcontext ");
    var result = [];
    try {
      var item = {
        "positionX" : 0,
        "positionY" : 0,
        "title" : "Title Text1",
        "alias" : ["Title1", "My Text1"],
        "bFocused" : true
      };
      result.push(item);
      var item2 = {
        "positionX" : 1,
        "positionY" : 0,
        "title" : "Title Text2",
        "alias" : ["Title2", "My Text2"],
        "bFocused" : false
      };
      result.push(item2);
      result.push(webapis.voiceinteraction.buildVoiceInteractionContentContextItem(2,0,"Title Text3", ["Title3", "My Text3"], false));
    } catch (e) {
      console.log("exception [" + e.code + "] name: " + e.name + " message: " + e.message);
    }
    return webapis.voiceinteraction.buildVoiceInteractionContentContextResponse(result);
  },
  ontitleselection : function (title) {
    console.log("ontitleselection" + title);
    return true;
  }
});

onfastforward

Supports the media control to handle playback(FF).

optional boolean onfastforward();

Product : TV

Privilege Level : Public

Privilege : http://developer.samsung.com/privilege/voicecontrol

Return Value :

  • optional boolean : boolean value of whether the app supports this feature.
    If a callback returns the false/undefined value, or there is no callback implementation for the utterance, Samsung device may perform its basic function.

Since : 6.0

Code Example :

webapis.voiceinteraction.setCallback({
  onupdatestate : function () {
    console.log("Assistant tries to get app state");
    return "Player";
  },
  onfastforward : function () {
    // TV Default Action: Generates the Remote Control Key, "MediaFastForward".
    console.log("onfastforward called");
    return true;
  }
});

onrewind

Supports the media control to handle playback(Rewind).

optional boolean onrewind();

Product : TV

Privilege Level : Public

Privilege : http://developer.samsung.com/privilege/voicecontrol

Return Value :

  • optional boolean : boolean value of whether the app supports this feature.
    If a callback returns the false/undefined value, or there is no callback implementation for the utterance, Samsung device may perform its basic function.

Since : 6.0

Code Example :

webapis.voiceinteraction.setCallback({
  onupdatestate : function () {
    console.log("Assistant tries to get app state");
    return "Player";
  },
  onrewind : function () {
    // TV Default Action: Generates the Remote Control Key, "MediaRewind".
    console.log("onrewind called");
    return true;
  }
});

onsearchcollection

Supports the search utterance appending to the default search application. The value of the result for the search term.

optional DOMString onsearchcollection(VoiceSearchTerm voiceSearchTerm);

Product : TV

Privilege Level : Public

Privilege : http://developer.samsung.com/privilege/voicecontrol

Parameters :

  • voiceSearchTerm : The Object contains the information via Voice.

Return Value :

  • optional DOMString : the formatted value of the result for the search term.

Since : 6.0

Code Example :

webapis.voiceinteraction.setCallback({
  onupdatestate : function () {
    console.log("Assistant tries to get app state");
    return "None";
  },
  onsearchcollection : function (voiceSearchTerm) {
    Log("onsearchcollection : " + JSON.stringify(voiceSearchTerm));
    var result = [];
    //appName and appId are of the UI Application to get the payload on launch.
    result.push(webapis.voiceinteraction.buildCollectionDeeplinkData("a1b2c3d4ef.myTizenAppId", "myTizenApp", "page_id=123456&method=voice"));
    return JSON.stringify(result);
  }
});

onchangeappstate

To support the utterance of shortcut commands, the application must have the onchangeappstate callback.

optional boolean onchangeappstate(VoiceApplicationState state);

Product : TV

Privilege Level : Public

Privilege : http://developer.samsung.com/privilege/voicecontrol

Parameters :

  • state : The Application Context via Voice.

Return Value :

  • optional boolean : boolean value of whether the app supports this feature.
    If a callback returns the false/undefined value, or there is no callback implementation for the utterance, Samsung device may perform its basic function.

Since : 6.0

Code Example :

webapis.voiceinteraction.setCallback({
  onupdatestate : function () {
    console.log("Assistant tries to get app state");
    return "None";
  },
  onchangeappstate: function (state) {
    // TV Default Action: Launches the Samsung TV FirstScreen, Menu or Search application. Depending on the input parameter.
    // "Go to Home", "Go to Settings", "Go to Search".
    console.log("onchangeappstate : " + state);
    var bSupport = true;
    switch (state) {
      case "Home":
      // Go to App's Home
      break;
      default:
      bSupport = false;
      break;
    }
    return bSupport;
  }
});

onchangeprevioustrack

In order to handle requests to move to the previous track via voice, the application should override the onchangeprevioustrack callback.

optional boolean onchangeprevioustrack();

Product : TV

Privilege Level : Public

Privilege : http://developer.samsung.com/privilege/voicecontrol

Return Value :

  • optional boolean : boolean value of whether the app supports this feature.
    If a callback returns the false/undefined value, or there is no callback implementation for the utterance, Samsung device may perform its basic function.

Since : 6.0

Code Example :

webapis.voiceinteraction.setCallback({
  onupdatestate : function () {
    return "List";
  },
  onchangeprevioustrack : function () {
    console.log("onchangeprevioustrack");
    return true;
  }
});

onchangenexttrack

In order to handle requests to move to the next track via voice, the application should override the onchangenexttrack callback.

optional boolean onchangenexttrack();

Product : TV

Privilege Level : Public

Privilege : http://developer.samsung.com/privilege/voicecontrol

Return Value :

  • optional boolean : boolean value of whether the app supports this feature.
    If a callback returns the false/undefined value, or there is no callback implementation for the utterance, Samsung device may perform its basic function.

Since : 6.0

Code Example :

webapis.voiceinteraction.setCallback({
  onupdatestate : function () {
    return "List";
  },
  onchangenexttrack : function () {
    console.log("onchangenexttrack");
    return true;
  }
});

onrestart

In order to handle requests to restart to this track via voice, the application should override the onrestart callback.

optional boolean onrestart();

Product : TV

Privilege Level : Public

Privilege : http://developer.samsung.com/privilege/voicecontrol

Return Value :

  • optional boolean : boolean value of whether the app supports this feature.
    If a callback returns the false/undefined value, or there is no callback implementation for the utterance, Samsung device may perform its basic function.

Since : 6.0

Code Example :

webapis.voiceinteraction.setCallback({
  onupdatestate : function () {
    return "List";
  },
  onrestart : function () {
    console.log("onrestart");
    return true;
  }
});

onskipbackward

In order to handle requests to skip backward via voice, the application should override the onskipbackward callback.

optional boolean onskipbackward(long offsetSeconds);

Product : TV

Privilege Level : Public

Privilege : http://developer.samsung.com/privilege/voicecontrol

Parameters :

  • offsetSeconds : the relative position in seconds.

Return Value :

  • optional boolean : boolean value of whether the app supports this feature.
    If a callback returns the false/undefined value, or there is no callback implementation for the utterance, Samsung device may perform its basic function.

Since : 6.0

Code Example :

webapis.voiceinteraction.setCallback({
  onupdatestate : function () {
    return "List";
  },
  onskipbackward : function (offsetSeconds) {
    console.log("onskipbackward : " + offsetSeconds);
    return true;
  }
});

onskipforward

In order to handle requests to skip forward via voice, the application should override the onskipforward callback.

optional boolean onskipforward(long offsetSeconds);

Product : TV

Privilege Level : Public

Privilege : http://developer.samsung.com/privilege/voicecontrol

Parameters :

  • offsetSeconds : the relative position in seconds.

Return Value :

  • optional boolean : boolean value of whether the app supports this feature.
    If a callback returns the false/undefined value, or there is no callback implementation for the utterance, Samsung device may perform its basic function.

Since : 6.0

Code Example :

webapis.voiceinteraction.setCallback({
  onupdatestate : function () {
    return "List";
  },
  onskipforward : function (offsetSeconds) {
    console.log("onskipforward : " + offsetSeconds);
    return true;
  }
});

onsetplayposition

In order to handle requests to set play position via voice, the application should override the onsetplayposition callback.

optional boolean onsetplayposition(long position);

Product : TV

Privilege Level : Public

Privilege : http://developer.samsung.com/privilege/voicecontrol

Parameters :

  • position : the absolute position in seconds.

Return Value :

  • optional boolean : boolean value of whether the app supports this feature.
    If a callback returns the false/undefined value, or there is no callback implementation for the utterance, Samsung device may perform its basic function.

Since : 6.0

Code Example :

webapis.voiceinteraction.setCallback({
  onupdatestate : function () {
    return "List";
  },
  onsetplayposition : function (position) {
    console.log("onsetplayposition : " + position);
    return true;
  }
});

onchangesubtitlemode

In order to handle requests to turn the subtitle feature on/off via voice, the application should override the onchangesubtitlemode callback.

optional boolean onchangesubtitlemode(MediaFunctionMode mode);

Product : TV

Privilege Level : Public

Privilege : http://developer.samsung.com/privilege/voicecontrol

Parameters :

  • mode : MEDIA_FUNCTION_ON : Turning On / MEDIA_FUNCTION_OFF : Turning Off

Return Value :

  • optional boolean : boolean value of whether the app supports this feature.
    If a callback returns the false/undefined value, or there is no callback implementation for the utterance, Samsung device may perform its basic function.

Since : 6.0

Code Example :

webapis.voiceinteraction.setCallback({
  onupdatestate : function () {
    return "List";
  },
  onchangesubtitlemode : function (mode) {
    console.log("onchangesubtitlemode");
    switch(mode) {
      case "MEDIA_FUNCTION_ON" :
      console.log("Function ON");
      break;
      default :
      console.log("Function OFF");
      break;
    }
    return true;
  }
});

onchangeshufflemode

In order to handle requests to turn the shuffle feature on/off via voice, the application should override the onchangeshufflemode callback.

optional boolean onchangeshufflemode(MediaFunctionMode mode);

Product : TV

Privilege Level : Public

Privilege : http://developer.samsung.com/privilege/voicecontrol

Parameters :

  • mode : MEDIA_FUNCTION_ON : Turning On / MEDIA_FUNCTION_OFF : Turning Off

Return Value :

  • optional boolean : boolean value of whether the app supports this feature.
    If a callback returns the false/undefined value, or there is no callback implementation for the utterance, Samsung device may perform its basic function.

Since : 6.0

Code Example :

webapis.voiceinteraction.setCallback({
  onupdatestate : function () {
    return "List";
  },
  onchangeshufflemode : function (mode) {
    console.log("onchangeshufflemode");
    switch(mode) {
      case "MEDIA_FUNCTION_ON" :
      console.log("Function ON");
      break;
      default :
      console.log("Function OFF");
      break;
    }
    return true;
  }
});

onchangescreenfitmode

In order to handle requests to turn the screen fit feature on/off via voice, the application should override the onchangescreenfitmode callback.

optional boolean onchangescreenfitmode(MediaFunctionMode mode);

Product : TV

Privilege Level : Public

Privilege : http://developer.samsung.com/privilege/voicecontrol

Parameters :

  • mode : MEDIA_FUNCTION_ON : Turning On / MEDIA_FUNCTION_OFF : Turning Off

Return Value :

  • optional boolean : boolean value of whether the app supports this feature.
    If a callback returns the false/undefined value, or there is no callback implementation for the utterance, Samsung device may perform its basic function.

Since : 6.0

Code Example :

webapis.voiceinteraction.setCallback({
  onupdatestate : function () {
    return "List";
  },
  onchangescreenfitmode : function (mode) {
    console.log("onchangescreenfitmode");
    switch(mode) {
      case "MEDIA_FUNCTION_ON" :
      console.log("Function ON");
      break;
      default :
      console.log("Function OFF");
      break;
    }
    return true;
  }
});

onzoom

In order to handle requests to zoom in/out via voice, the application should override the onzoom callback.

optional boolean onzoom(MediaZoomMode zoom);

Product : TV

Privilege Level : Public

Privilege : http://developer.samsung.com/privilege/voicecontrol

Parameters :

  • zoom : MEDIA_ZOOM_IN : zoom in / MEDIA_ZOOM_OUT : zoom out

Return Value :

  • optional boolean : boolean value of whether the app supports this feature.
    If a callback returns the false/undefined value, or there is no callback implementation for the utterance, Samsung device may perform its basic function.

Since : 6.0

Code Example :

webapis.voiceinteraction.setCallback({
  onupdatestate : function () {
    return "List";
  },
  onzoom : function (zoom) {
    console.log("onzoom");
    switch(zoom) {
      case "MEDIA_ZOOM_IN" :
      console.log("Zoom IN");
      break;
      default :
      console.log("Zoom OUT");
      break;
    }
    return true;
  }
});

onrotate

In order to handle requests to rotate left/right via voice, the application should override the onrotate callback.

optional boolean onrotate(MediaRotateMode direction);

Product : TV

Privilege Level : Public

Privilege : http://developer.samsung.com/privilege/voicecontrol

Parameters :

  • direction : MEDIA_ROTATE_LEFT : rotate left / MEDIA_ROTATE_RIGHT : rotate right

Return Value :

  • optional boolean : boolean value of whether the app supports this feature.
    If a callback returns the false/undefined value, or there is no callback implementation for the utterance, Samsung device may perform its basic function.

Since : 6.0

Code Example :

webapis.voiceinteraction.setCallback({
  onupdatestate : function () {
    return "List";
  },
  onrotate : function (direction) {
    console.log("onrotate");
    switch(direction) {
      case "MEDIA_ROTATE_LEFT" :
      console.log("Rotate Left");
      break;
      default :
      console.log("Rotate Right");
      break;
    }
    return true;
  }
});

onchange360mode

In order to handle requests to turn the 360 feature on/off via voice, the application should override the onchange360mode callback.

optional boolean onchange360mode(MediaFunctionMode mode);

Product : TV

Privilege Level : Public

Privilege : http://developer.samsung.com/privilege/voicecontrol

Parameters :

  • mode : MEDIA_FUNCTION_ON : Turning On / MEDIA_FUNCTION_OFF : Turning Off

Return Value :

  • optional boolean : boolean value of whether the app supports this feature.
    If a callback returns the false/undefined value, or there is no callback implementation for the utterance, Samsung device may perform its basic function.

Since : 6.0

Code Example :

webapis.voiceinteraction.setCallback({
  onupdatestate : function () {
    return "List";
  },
  onchange360mode : function (mode) {
    console.log("onchange360mode");
    switch(mode) {
      case "MEDIA_FUNCTION_ON" :
      console.log("Function ON");
      break;
      default :
      console.log("Function OFF");
      break;
    }
    return true;
  }
});

onchangerepeatmode

In order to handle requests to change the repeat mode via voice, the application should override the onchangerepeatmode callback.

optional boolean onchangerepeatmode(MediaRepeatMode mode);

Product : TV

Privilege Level : Public

Privilege : http://developer.samsung.com/privilege/voicecontrol

Parameters :

  • mode : MEDIA_REPEAT_OFF : repeat mode off / MEDIA_REPEAT_ONE : repeat this track / MEDIA_REPEAT_ALL : repeat all tracks

Return Value :

  • optional boolean : boolean value of whether the app supports this feature.
    If a callback returns the false/undefined value, or there is no callback implementation for the utterance, Samsung device may perform its basic function.

Since : 6.0

Code Example :

webapis.voiceinteraction.setCallback({
  onupdatestate : function () {
    return "List";
  },
  onchangerepeatmode : function (mode) {
    console.log("onchangerepeatmode");
    switch(mode) {
      case "MEDIA_REPEAT_ONE" :
      console.log("ONE");
      break;
      case "MEDIA_REPEAT_ALL" :
      console.log("ALL");
      break;
      default :
      console.log("OFF");
      break;
    }
    return true;
  }
});

oncontinuewatching

In order to handle requests to launch the application with playing the history track via voice, the application should override the oncontinuewatching callback to play the history track.
This callback will be called after launching the application.

optional boolean oncontinuewatching();

Product : TV

Privilege Level : Public

Privilege : http://developer.samsung.com/privilege/voicecontrol

Return Value :

  • optional boolean : boolean value of whether the app supports this feature.
    If a callback returns the false/undefined value, or there is no callback implementation for the utterance, Samsung device may perform its basic function.

Since : 6.0

Code Example :

webapis.voiceinteraction.setCallback({
  onupdatestate : function () {
    return "List";
  },
  oncontinuewatching : function () {
    console.log("oncontinuewatching");
    return true;
  }
});

oncustom

Supports the custom voice assistant action.

optional boolean oncustom(DOMString jsonObjectString);

Product : TV

Privilege Level : Public

Privilege : http://developer.samsung.com/privilege/voicecontrol

Parameters :

  • jsonObjectString : the string stringified json object.

Return Value :

  • optional boolean : boolean value of whether the app supports this feature.
    Voice Assistant Action will get the response "{"result_code":"SUCCESS"}" for true, "{"result_code":"FAILURE"}" for false/undefined.

Since : 6.0

Code Example :

webapis.voiceinteraction.setCallback({
  onupdatestate : function () {
    console.log("Assistant tries to get app state");
    return "List";
  },
  oncustom : function (jsonObjectString) {
    console.log("oncustom : " + jsonObjectString);
    try {
      var customObject = JSON.parse(jsonObjectString);
      for (var key in customObject) {
        if(customObject.hasOwnProperty(key)) {
          console.log("Key : " + key + ", Value : " + customObject[key]);
        }
      }
    } catch (e) {
      console.log("exception [" + e.code + "] name: " + e.name + " message: " + e.message);
      return false;
    }
    return true;
  }
});

onrequestcontentcontext

In order to support the voice title selection via voice, the application should override the onrequestcontentcontext callback, return the JsonObject string for the current content context list showing.

optional DOMString onrequestcontentcontext();

Product : TV

Privilege Level : Public

Privilege : http://developer.samsung.com/privilege/voicecontrol

Return Value :

  • optional DOMString : DOMString containing JsonObject string for the content context list.

Since : 6.0

Code Example :

webapis.voiceinteraction.setCallback({
  onupdatestate : function () {
    console.log("Assistant tries to get app state");
    return "List";
  },
  onrequestcontentcontext : function () {
    Log("onrequestcontentcontext ");
    var result = [];
    try {
      var item = webapis.voiceinteraction.buildVoiceInteractionContentContextItem(1,1,"test", ["test set", "test title"], true);
      result.push(item);
      var item2 = webapis.voiceinteraction.buildVoiceInteractionContentContextItem(2,1,"test2", ["test set 2", "test title 2"], false);
      result.push(item2);
    } catch (e) {
      console.log("exception [" + e.code + "] name: " + e.name + " message: " + e.message);
    }
    return webapis.voiceinteraction.buildVoiceInteractionContentContextResponse(result);
  }
});

onadditiontolist

In order to handle requests to add this context to list via voice, the application should override the onadditiontolist callback.

optional boolean onadditiontolist(ListItem list);

Product : TV

Privilege Level : Public

Privilege : http://developer.samsung.com/privilege/voicecontrol

Parameters :

  • list : LIST_BOOKMARKS : bookmarks / LIST_WATCH_LATER : watch later / LIST_PREFERENCE : preference / LIST_SUBSCRIPTION : subscription

Return Value :

  • optional boolean : boolean value of whether the app supports this feature.
    If a callback returns the false/undefined value, or there is no callback implementation for the utterance, Samsung TV may perform its basic function.

Since : 6.5

Code Example :

webapis.voiceinteraction.setCallback({
  onupdatestate : function () {
    return "List";
  },
  onadditiontolist : function (list) {
    console.log("onadditiontolist");
    switch(list) {
      case "LIST_BOOKMARKS" :
      console.log("Add this context to Bookmarks");
      break;
      case "LIST_WATCH_LATER" :
      console.log("Add this context to Watch later");
      break;
      case "LIST_PREFERENCE" :
      console.log("Like this context");
      break;
      case "LIST_SUBSCRIPTION" :
      console.log("Subscribe to context");
      break;
      default :
      break;
    }
    return true;
  }
});

onremovalfromlist

In order to handle requests to remove this context from list via voice, the application should override the onremovalfromlist callback.

optional boolean onremovalfromlist(ListItem list);

Product : TV

Privilege Level : Public

Privilege : http://developer.samsung.com/privilege/voicecontrol

Parameters :

  • list : LIST_BOOKMARKS : bookmarks / LIST_WATCH_LATER : watch later / LIST_PREFERENCE : preference / LIST_SUBSCRIPTION : subscription

Return Value :

  • optional boolean : boolean value of whether the app supports this feature.
    If a callback returns the false/undefined value, or there is no callback implementation for the utterance, Samsung TV may perform its basic function.

Since : 6.5

Code Example :

webapis.voiceinteraction.setCallback({
  onupdatestate : function () {
    return "List";
  },
  onremovalfromlist : function (list) {
    console.log("onremovalfromlist");
    switch(list) {
      case "LIST_BOOKMARKS" :
      console.log("Remove this context from Bookmarks");
      break;
      case "LIST_WATCH_LATER" :
      console.log("Remove this context from Watch later");
      break;
      case "LIST_PREFERENCE" :
      console.log("Dislike this context");
      break;
      case "LIST_SUBSCRIPTION" :
      console.log("Unsubscribe from this context");
      break;
      default :
      break;
    }
    return true;
  }
});

onplaylist

In order to handle requests to play this context from list via voice, the application should override the onplaylist callback.

optional boolean onplaylist(ListItem list);

Product : TV

Privilege Level : Public

Privilege : http://developer.samsung.com/privilege/voicecontrol

Parameters :

  • list : LIST_PREFERENCE : preference / LIST_SUBSCRIPTION : subscription / LIST_WATCH_LATER : watch later

Return Value :

  • optional boolean : boolean value of whether the app supports this feature.
    If a callback returns the false/undefined value, or there is no callback implementation for the utterance, Samsung TV may perform its basic function.

Since : 6.5

Code Example :

webapis.voiceinteraction.setCallback({
  onupdatestate : function () {
    return "List";
  },
  onplaylist : function (list) {
    console.log("onplaylist");
    switch(list) {
      case "LIST_PREFERENCE" :
      console.log("Play liked content");
      break;
      case "LIST_SUBSCRIPTION" :
      console.log("Play subscription content");
      break;
      case "LIST_WATCH_LATER" :
      console.log("Play watch later content");
      break;
      default :
      break;
    }
    return true;
  }
});

onbrowselist

In order to handle requests to browse this context from list via voice, the application should override the onbrowselist callback.

optional boolean onbrowselist(ListItem list);

Product : TV

Privilege Level : Public

Privilege : http://developer.samsung.com/privilege/voicecontrol

Parameters :

  • list : LIST_PREFERENCE : preference / LIST_SUBSCRIPTION : subscription / LIST_WATCH_LATER : watch later

Return Value :

  • optional boolean : boolean value of whether the app supports this feature.
    If a callback returns the false/undefined value, or there is no callback implementation for the utterance, Samsung TV may perform its basic function.

Since : 6.5

Code Example :

webapis.voiceinteraction.setCallback({
  onupdatestate : function () {
    return "List";
  },
  onbrowselist : function (list) {
    console.log("onbrowselist");
    switch(list) {
      case "LIST_PREFERENCE" :
      console.log("Browse liked content");
      break;
      case "LIST_SUBSCRIPTION" :
      console.log("Browse subscription content");
      break;
      case "LIST_WATCH_LATER" :
      console.log("Browse watch later content");
      break;
      default :
      break;
    }
    return true;
  }
});

onskipad

In order to handle requests to skip ad content via voice, the application should override the onskipad callback.

optional boolean onskipad();

Product : TV

Privilege Level : Public

Privilege : http://developer.samsung.com/privilege/voicecontrol

Return Value :

  • optional boolean : boolean value of whether the app supports this feature.
    If a callback returns the false/undefined value, or there is no callback implementation for the utterance, Samsung TV may perform its basic function.

Since : 6.5

Code Example :

webapis.voiceinteraction.setCallback({
  onupdatestate : function () {
    return "Player";
  },
  onskipad : function () {
    console.log("onskipad");
    return true;
  }
});

2.3 VoiceSearchTerm

This interface represents information about the voice search term.

[NoInterfaceObject] interface VoiceSearchTerm {
  readonly attribute DOMString? utterance;
  readonly attribute DOMString? title;
  readonly attribute DOMString? genre;
  readonly attribute DOMString? cast;
  readonly attribute DOMString? contentType;
  readonly attribute DOMString? from;
  readonly attribute DOMString? to;
};

Attributes

  • readonly DOMString utterance [nullable]
    The field for the full utterance.
  • readonly DOMString title [nullable]
    The field for the title.
  • readonly DOMString genre [nullable]
    The field for the genre.
  • readonly DOMString cast [nullable]
    The field for the cast.
  • readonly DOMString contentType [nullable]
    The field for the content type (movie/tvshow).
  • readonly DOMString from [nullable]
    The field for the start date time(ISO 8601).
  • readonly DOMString to [nullable]
    The field for the end date time(ISO 8601).

2.4 VoiceInteractionContentContext

This interface represents information about the content context for an item.

[NoInterfaceObject] interface VoiceInteractionContentContext {
  attribute long positionX;
  attribute long positionY;
  attribute DOMString title;
  attribute boolean bFocused;
};

Attributes

  • long positionX
    The field for x-axis position of the item.
  • long positionY
    The field for y-axis position of the item.
  • DOMString title
    The field for the title of the item.
  • boolean bFocused
    The field for whether this item has a focus.

2.5 VoiceInteractionManager

The VoiceInteractionManager interface is the top-level interface for the VoiceInteractionManager API that provides access to the module functionalities.

[NoInterfaceObject] interface VoiceInteractionManager {
  DOMString getVersion();
  void setCallback(VoiceInteractionCallback callback);
  void listen();
  DOMString getDataFromSearchTerm(VoiceSearchTerm voiceSearchTerm, VoiceSearchTermField field);
  DOMString buildCollectionDeeplinkData(DOMString appId, DOMString title, DOMString payload);
  DOMString buildCollectionShowData(DOMString appId, DOMString title, DOMString payload, DOMString thumbnail);
  VoiceInteractionContentContext buildVoiceInteractionContentContextItem(long positionX, long positionY, DOMString title, DOMString[] aliasArr, boolean bFocused);
  DOMString buildVoiceInteractionContentContextResponse(VoiceInteractionContentContext[] contentContextArr);
};

Methods

getVersion

This method gets the plugin's version number.

DOMString getVersion();

Product : TV

Privilege Level : Public

Privilege : http://developer.samsung.com/privilege/voicecontrol

Return Value :

  • DOMString : DOMString return value of plugin's version.

Exceptions :

  • WebAPIException
    • with error type UnknownError in any other error case.
    • with error type SecurityError, if the application does not have the privilege to call this method.

Since : 6.0

Code Example :

try {
  var version = webapis.voiceinteraction.getVersion();
  console.log("works with voiceinteraction [" + version + "]");
} catch (e) {
  console.log("exception [" + e.code + "] name: " + e.name + " message: " + e.message);
}

setCallback

API to define callback functions for the voice interaction commands.

void setCallback(VoiceInteractionCallback callback);

Product : TV

Privilege Level : Public

Privilege : http://developer.samsung.com/privilege/voicecontrol

Parameters :

  • callback : composing the functions to be called for the voice interaction commands.

Exceptions :

  • WebAPIException
    • with error type UnknownError in any other error case.
    • with error type TypeMismatchError, if an input parameter is not compatible with its expected type.
    • with error type SecurityError, if the application does not have the privilege to call this method.

Since : 6.0

Code Example :

try {
  webapis.voiceinteraction.setCallback({
    onupdatestate : function () {
      return "List";
    },
    onnavigation : function (vn) {
      console.log("onnavigation" + vn);
      return true;
    },
    onselection : function (voiceSelection) {
      console.log("OnSelection" + voiceSelection);
      return true;
    }
  });
} catch (e) {
  console.log("exception [" + e.code + "] name: " + e.name + " message: " + e.message);
}

listen

API to start listening the voice interaction commands after setting callbacks by setCallback.

void listen();

Product : TV

Privilege Level : Public

Privilege : http://developer.samsung.com/privilege/voicecontrol

Exceptions :

  • WebAPIException
    • with error type UnknownError in any other error case.
    • with error type SecurityError, if the application does not have the privilege to call this method.

Since : 6.0

Code Example :

try {
  webapis.voiceinteraction.listen();
} catch (e) {
  console.log("exception [" + e.code + "] name: " + e.name + " message: " + e.message);
}

getDataFromSearchTerm

API to parse the searchTerm from samsung side.

DOMString getDataFromSearchTerm(VoiceSearchTerm voiceSearchTerm, VoiceSearchTermField field);

Product : TV

Privilege Level : Public

Privilege : http://developer.samsung.com/privilege/voicecontrol

Parameters :

  • voiceSearchTerm : The VoiceSearchTerm from samsung side as search term.
  • field : The field enum to get the value.

Return Value :

  • DOMString : The result string formatted.

Exceptions :

  • WebAPIException
    • with error type UnknownError in any other error case.
    • with error type SecurityError, if the application does not have the privilege to call this method.
    • with error type InvalidValuesError, if any input parameter contains an invalid value.
    • with error type TypeMismatchError, if an input parameter is not compatible with its expected type.

Since : 6.0

Code Example :

var title = webapis.voiceinteraction.getDataFromSearchTerm(voiceSearchTerm, "SEARCH_TERM_TITLE");
var genre = webapis.voiceinteraction.getDataFromSearchTerm(voiceSearchTerm, "SEARCH_TERM_GENRE");

buildCollectionDeeplinkData

API to build data for search collection easily.

DOMString buildCollectionDeeplinkData(DOMString appId, DOMString title, DOMString payload);

Product : TV

Privilege Level : Public

Privilege : http://developer.samsung.com/privilege/voicecontrol

Parameters :

  • appId : The app id to be shown in the search application, and to launch the payload.
  • title : The title to be shown in the search application.
  • payload : The payload value to be passed with application launch request.

Return Value :

  • DOMString : The result string formatted.

Exceptions :

  • WebAPIException
    • with error type UnknownError in any other error case.
    • with error type TypeMismatchError, if any input parameter is not DOMString type.
    • with error type SecurityError, if the application does not have the privilege to call this method.

Since : 6.0

Code Example :

webapis.voiceinteraction.setCallback({
  onupdatestate : function () {
    console.log("Assistant tries to get app state");
    return "None";
  },
  onsearchcollection : function (voiceSearchTerm) {
    Log("OnSearchCollection : " + JSON.stringify(voiceSearchTerm));
    var result = [];
    // appName and appId are of the UI Application to get the payload on launch.
    try {
      result.push(webapis.voiceinteraction.buildCollectionDeeplinkData("a1b2c3d4ef.myTizenAppId", "myTizenApp", "page_id=123456&method=voice"));
    } catch (e) {
      console.log("exception [" + e.code + "] name: " + e.name + " message: " + e.message);
    }
    return JSON.stringify(result);
  }
});

buildCollectionShowData

API to build data for search collection easily.

DOMString buildCollectionShowData(DOMString appId, DOMString title, DOMString payload, DOMString thumbnail);

Product : TV

Privilege Level : Public

Privilege : http://developer.samsung.com/privilege/voicecontrol

Parameters :

  • appId : The app id to be shown in the search application, and to launch the payload.
  • title : The title to be shown in the search application.
  • payload : The payload value to be passed with application launch request.
  • thumbnail : The thumbnail url, path to be shown in the search application.

Return Value :

  • DOMString : The result string formatted.

Exceptions :

  • WebAPIException
    • with error type UnknownError in any other error case.
    • with error type TypeMismatchError, if any input parameter is not DOMString type.
    • with error type SecurityError, if the application does not have the privilege to call this method.

Since : 6.0

Code Example :

webapis.voiceinteraction.setCallback({
  onupdatestate : function () {
    console.log("Assistant tries to get app state");
    return "None";
  },
  onsearchcollection : function (voiceSearchTerm) {
    Log("OnSearchCollection : " + JSON.stringify(voiceSearchTerm));
    var result = [];
    // appName and appId are of the UI Application to get the payload on launch.
    try {
      result.push(webapis.voiceinteraction.buildCollectionShowData("a1b2c3d4ef.myTizenAppId", "myTizenApp", "page_id=123456&method=voice", "http://myservice.com/content/123456.png"));
    } catch (e) {
      console.log("exception [" + e.code + "] name: " + e.name + " message: " + e.message);
    }
    return JSON.stringify(result);
  }
});

buildVoiceInteractionContentContextItem

API to build the VoiceInteractionContentContext of an item.

VoiceInteractionContentContext buildVoiceInteractionContentContextItem(long positionX, long positionY, DOMString title, DOMString[] aliasArr, boolean bFocused);

Product : TV

Privilege Level : Public

Privilege : http://developer.samsung.com/privilege/voicecontrol

Parameters :

  • positionX : x-axis position of the item.
  • positionY : y-axis position of the item.
  • title : The title of the item.
  • aliasArr : The alias titles of the item.
  • bFocused : Whether this item has a focus.

Return Value :

Exceptions :

  • WebAPIException
    • with error type UnknownError in any other error case.
    • with error type TypeMismatchError, if any input parameters are not compatible with its expected type.

Since : 6.0

Code Example :

onrequestcontentcontext : function () {
  console.log("onrequestcontentcontext ");
  var result = [];
  try {
    var item = webapis.voiceinteraction.buildVoiceInteractionContentContextItem(1,1,"test", ["test set", "test title"], true);
    result.push(item);
  } catch (e) {
    console.log("exception [" + e.code + "] name: " + e.name + " message: " + e.message);
  }
  return webapis.voiceinteraction.buildVoiceInteractionContentContextResponse(result);
}

buildVoiceInteractionContentContextResponse

API to build the response of onrequestcontentcontext callback function from VoiceInteractionContentContext.

DOMString buildVoiceInteractionContentContextResponse(VoiceInteractionContentContext[] contentContextArr);

Product : TV

Privilege Level : Public

Privilege : http://developer.samsung.com/privilege/voicecontrol

Parameters :

  • contentContextArr : VoiceInteractionContentContext objects of the items showing.

Return Value :

  • DOMString : The DOMString of JsonObject string containing the items showing.

Exceptions :

  • WebAPIException
    • with error type UnknownError in any other error case.
    • with error type TypeMismatchError, if any input parameters are not compatible with its expected type.

Since : 6.0

Code Example :

onrequestcontentcontext : function () {
  console.log("onrequestcontentcontext ");
  var result = [];
  try {
    var item = webapis.voiceinteraction.buildVoiceInteractionContentContextItem(1,1,"test", ["test set", "test title"], true);
    result.push(item);
  } catch (e) {
    console.log("exception [" + e.code + "] name: " + e.name + " message: " + e.message);
  }
  return webapis.voiceinteraction.buildVoiceInteractionContentContextResponse(result);
}

3. Full WebIDL

module VoiceInteraction {
  enum VoiceApplicationState {
    "None",
    "Home",
    "List",
    "Player",
    "Setting",
    "Search",
    "Unknown"
  };

  enum VoiceNavigation {
    "NAV_PREVIOUS",
    "NAV_NEXT",
    "NAV_LEFT",
    "NAV_RIGHT",
    "NAV_UP",
    "NAV_DOWN",
    "NAV_SHOW_MORE",
    "NAV_UNKNOWN"
  };

  enum VoiceSearchTermField {
    "SEARCH_TERM_UTTERANCE",
    "SEARCH_TERM_TITLE",
    "SEARCH_TERM_GENRE",
    "SEARCH_TERM_CAST",
    "SEARCH_TERM_CONTENT_TYPE",
    "SEARCH_TERM_RELEASE_DATE_FROM",
    "SEARCH_TERM_RELEASE_DATE_TO"
  };

  enum MediaFunctionMode {
    "MEDIA_FUNCTION_ON",
    "MEDIA_FUNCTION_OFF"
  };

  enum MediaRotateMode {
    "MEDIA_ROTATE_LEFT",
    "MEDIA_ROTATE_RIGHT"
  };

  enum MediaZoomMode {
    "MEDIA_ZOOM_IN",
    "MEDIA_ZOOM_OUT"
  };

  enum MediaRepeatMode {
    "MEDIA_REPEAT_OFF",
    "MEDIA_REPEAT_ONE",
    "MEDIA_REPEAT_ALL"
  };

  enum ListItem {
    "LIST_BOOKMARKS",
    "LIST_WATCH_LATER",
    "LIST_UNKNOWN"
  };

  [NoInterfaceObject] interface VoiceInteractionManagerObject {
    readonly attribute VoiceInteractionManager voiceinteraction;
  };

  WebApi implements VoiceInteractionManagerObject;

  [Callback, NoInterfaceObject] interface VoiceInteractionCallback {
    optional VoiceApplicationState onupdatestate();
    optional boolean onnavigation(VoiceNavigation voiceNavigation);
    optional boolean onsearch(VoiceSearchTerm voiceSearchTerm);
    optional boolean onplay();
    optional boolean onstop();
    optional boolean onpause();
    optional boolean onexit();
    optional boolean onselection(long voiceSelection);
    optional boolean ontitleselection(DOMString title);
    optional boolean onfastforward();
    optional boolean onrewind();
    optional DOMString onsearchcollection(VoiceSearchTerm voiceSearchTerm);
    optional boolean onchangeappstate(VoiceApplicationState state);
    optional boolean onchangeprevioustrack();
    optional boolean onchangenexttrack();
    optional boolean onrestart();
    optional boolean onskipbackward(long offsetSeconds);
    optional boolean onskipforward(long offsetSeconds);
    optional boolean onsetplayposition(long position);
    optional boolean onchangesubtitlemode(MediaFunctionMode mode);
    optional boolean onchangeshufflemode(MediaFunctionMode mode);
    optional boolean onchangescreenfitmode(MediaFunctionMode mode);
    optional boolean onzoom(MediaZoomMode zoom);
    optional boolean onrotate(MediaRotateMode direction);
    optional boolean onchange360mode(MediaFunctionMode mode);
    optional boolean onchangerepeatmode(MediaRepeatMode mode);
    optional boolean oncontinuewatching();
    optional boolean oncustom(DOMString jsonObjectString);
    optional DOMString onrequestcontentcontext();
    optional boolean onadditiontolist(ListItem list);
    optional boolean onremovalfromlist(ListItem list);
    optional boolean onplaylist(ListItem list);
    optional boolean onbrowselist(ListItem list);
    optional boolean onskipad();
  };

  [NoInterfaceObject] interface VoiceSearchTerm {
    readonly attribute DOMString? utterance;
    readonly attribute DOMString? title;
    readonly attribute DOMString? genre;
    readonly attribute DOMString? cast;
    readonly attribute DOMString? contentType;
    readonly attribute DOMString? from;
    readonly attribute DOMString? to;
  };

  [NoInterfaceObject] interface VoiceInteractionContentContext {
    attribute long positionX;
    attribute long positionY;
    attribute DOMString title;
    attribute boolean bFocused;
  };

  [NoInterfaceObject] interface VoiceInteractionManager {
    DOMString getVersion();
    void setCallback(VoiceInteractionCallback callback);
    void listen();
    DOMString getDataFromSearchTerm(VoiceSearchTerm voiceSearchTerm, VoiceSearchTermField field);
    DOMString buildCollectionDeeplinkData(DOMString appId, DOMString title, DOMString payload);
    DOMString buildCollectionShowData(DOMString appId, DOMString title, DOMString payload, DOMString thumbnail);
    VoiceInteractionContentContext buildVoiceInteractionContentContextItem(long positionX, long positionY, DOMString title, DOMString[] aliasArr, boolean bFocused);
    DOMString buildVoiceInteractionContentContextResponse(VoiceInteractionContentContext[] contentContextArr);
  };

};