Samsung Electronics logo

Create TV application



The MultiScreen API allows you to create an application that runs on a Samsung SmartTV. The mobile applications can find compatibled TV via the pincode, and can communicate with each other with the channel opened by the TV application.

The Main features of MultiScreen API’s include:


TV Application Setup

In order to use Multiscreen API, you must add below script tag to your project with its referencing file. File can be found at following path. DTV Web Project > DTV Sample Application > MultiScreen Demo > js folder.


  <script type="text/javascript" src="js/multiscreen-smarttv-1.1.11.min.js"</script>;

getCurrentDevice

In order to start or join a MultiScreen experience, application that runs on the TV must get a reference to a device instance. In this case, the TV application needs to get the “current” device by calling getCurrent(), the "current" device will be asynchronously returned.

/**
  *Getting current TV device in TV application.
  */
function onGetCurrentSuccess(device) {
  console.log("connected to device : " + device.id);
}

try {
  webapis.multiscreen.Device.getCurrent(onGetCurrentSuccess);
} catch(e) {
  console.log("Error exception, error code: " + e.code + ", error message : " + e.message);
}

After getting the device instance, the TV application can retrieve the pin code information associated with cloud discovery, can open channel for other clients to connect, then can send to or receive messages from other clients, and monitor the channel by add listener.

Communicate

When the clients communicate with each other, channel is required. A Channel is simply a communication channel that clients connect to, and provides capabilities to send and receive messages to/from any client. Once the TV application has got a reference to a device instance, it should "open" a channel.

openChannel

Only TV Application can “open” a channel, mobiles devices can connect to the channel by calling method connectToChannel(). The channel instance will be asynchronously returned.

/**
  *Opening channel from a TV application.
  */
function onOpenChannelSuccess(channel){
  console.log("channel opened " + channel.id);
}

function onGetCurrentSuccess(device) {
  device.openChannel("com.mydomain.myapp.chat",{name:"Host"}, onOpenChannelSuccess);        
}

try {
  webapis.multiscreen.Device.getCurrent(onGetCurrentSuccess);
} catch(e) {
  console.log("Error exception, error code: " + e.code + ", error message : " + e.message);
}

Once connected, each device has awareness of all other devices connected. This allows TV to send messages to any other device, or group of devices, or receive messages from other devices.

send

Once the clients connect to the channel, TV can freely exchange messages between the clients. TV can send a message to a single client, a list of clients, or all clients in several ways.


/**
 * Sending message to other clients
 */
function onOpenChannelSuccess(channel){
  channel.send("Hello", "all");      //send message using send()
  channel.broadcast("hello", true); //send message using broadcast()
}

function onGetCurrentSuccess(device) {
  device.openChannel("com.mydomain.myapp.chat",{name:"Host"}, onOpenChannelSuccess);        
}

try {
  webapis.multiscreen.Device.getCurrent(onGetCurrentSuccess);
} catch(e) {
  console.log("Error exception, error code: " + e.code + ", error message : " + e.message);
}

Besides calling send() or broadcast() provided by channel interface, TV application can also send message to other clients by getting the releated channelclient, then calling send() method of that interface.

addListener

In order to be notified when other clients connect or disconnect, when itself connects or disconnects to the channel, and when a message is received, TV application need to addListener().

/**
  *Receiving Messages and events via the Channel
  */
 var channelEventCallback = {
	clientconnected : function(client){
		console.log("clientconnected"); // client connected
	},
	clientdisconnected : function(){
		console.log("clientdisconnected"); // client disconnected
	},
	connected : function(){
		console.log("connected");  
	},
	disconnected : function(){
		console.log("disconnected");
	},
	onerror : function(error){
		console.log("onerror");
	},
	onmessage : function(message, client) {
		console.log("onmessage"); // message received from a client
	}
}

function onOpenChannelSuccess(channel){
  channel.addListener(channelEventCallback);
}

function onGetCurrentSuccess(device) {
  device.openChannel("com.mydomain.myapp.chat",{name:"Host"}, onOpenChannelSuccess);        
}

try {
  webapis.multiscreen.Device.getCurrent(onGetCurrentSuccess);
} catch(e) {
   console.log("Error exception, error code: " + e.code + ", error message : " + e.message);
}