Samsung Electronics logo

Create Mobile application



The MultiScreen API allows you to create a mobile application, which can control the app on the compatibled TV discovered, and communicate with other mobile devices and tv connectting to the same channel.

The Main features of MultiScreen API’s include:


Discover

In order to start or join a MultiScreen experience, a mobile device must be able to discover a compatible TV. Mobile application can discover a compatible SmartTV by calling search method or using the pin code provided by the TV.

findByCode

Besides the search() method, mobile applications can also get a single device instance via the method findByCode().findByCode() requires pincode as the input parameter, which can be optionally displayed by the TV application. If the pincode is valid, the device instance required will be asynchronously returned.


/**
 * Getting a single device instance via a pin code.
 * It is assumed that the mobile app has already known the pin code of the device.
 */
 function onFindByCodeSuccess(device) {
     console.log("connected to device : " + device.id);
 }
 
  function onFindByCodeError(e) {
     console.log("error callback invoked, error code: " + e.code + ", error message : " + e.message);
 }
 
 try {
     var pinCode; // assume that the TV application has already displayed the pin code to the mobile.
     webapis.multiscreen.Device.findByCode(pinCode,onFindByCodeSuccess,onFindByCodeError);
 } catch(e) {
     console.log("Error exception, error code: " + e.code + ", error message : " + e.message);
 }

Application Management

Once a TV is discovered, the TV must load the public view of the experience. Mobile devices can instruct a TV to load either an installed app on the TV, or a web application hosted in the cloud, get the application's status and terminate the application on the TV.

1.getApplication

In order to manage the TV application, you should get a reference to the application first. "runTitle" which is a special id of the application is required when you calling getApplication(), the corresponding application reference will be asynchronously returned.

/**
  *Getting a reference to a TV Application from a mobile application.
  */
//Define callback functions for getApplication. 
function onGetApplicationSuccess(application){
 console.log("application title : " + application.runTitle);
}

function onSearchSuccess(devices) {
  var device = devices[0]; 
  device.getApplication("DemoApp", onGetApplicationSuccess);
}

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

2.launch

Once you have a reference to a TV application, you can launch it on the TV. You can also pass parameters to the TV app during the launch phase. These parameters will be available to the TV app on the URL.


/**
 * Launching a TV application from the mobile API
 */
function onLaunchSuccess(status){
  console.log("launch success, status : " + status);
}

function onGetApplicationSuccess(application){
  application.launch({launchedBy:"mobile"},onLaunchSuccess);
}

function onSearchSuccess(devices) {
  var device = devices[0]; 
  device.getApplication("DemoApp", onGetApplicationSuccess);
}

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

3.updateStatus

Mobile devices can also get the latest status of a TV application to determine if the TV application is running. The Application's status will be asynchronously returned.


/**
 * Getting the status of a TV Application
 */
function onUpdateStatusSuccess(status){
  console.log("updateStatus success, status : " + status);
}

function onGetApplicationSuccess(application){
  application.updateStatus(onUpdateStatusSuccess);
}

function onSearchSuccess(devices) {
  var device = devices[0]; 
  device.getApplication("DemoApp", onGetApplicationSuccess);
}

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

4.terminate

Mobile devices can terminate the application on the host device by calling terminate(), the Application's status will be asynchronously returned.


/**
 *  Terminating the application on the host Device 
 */
function onTerminateSuccess(status){
  console.log("terminate success, status : " + status);
}

function onGetApplicationSuccess(application){
  application.terminate(onTerminateSuccess);
}

function onSearchSuccess(devices) {
  var device = devices[0];
  device.getApplication("DemoApp", onGetApplicationSuccess);
}

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

Communicate

Channel is the key concept of the Multiscreen, once the mobile device has a reference to a device instance, it should "connnect" to a channel which is "opened" by the TV application in order to communicate with other devices. All the clients connected to the channel can freely exchange messages to each other, clients can also receive events that notify them when other clients connect or disconnect. The client that connects to the channel is represented as a “ChannelClient”. By the channel, mobile device can get a list of channelclients or a certain channelclient needed, and send message to the channelclient.

connectToChannel

Mobile device can connect to the channel by calling method connectToChannel(), the channelId must be the same as the one opened in the TV application. The channel instance will be asynchronously returned.

/**
  *Connecting to channel from a mobile application.
  */
function onConnectionSuccess(channel){
  console.log("connected to " + channel.id);
}

function onSearchSuccess(devices) {
  var device = devices[0]; // Assuming for this example there is only one
  // Assuming device has already opened channel named "com.mydomain.myapp.chat"
  device.connectToChannel("com.mydomain.myapp.chat",{name:"MobileClient"}, onConnectionSuccess);        
}

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

After the client connecting to the channel successfully, the channel instance will be returned asynchronously, with which, the mobile client can communicate with other clients freely, and connect or disconnect to the channel as well.

send

Once connecting to a channel, clients can freely exchange messages. Clients can send a message to a single client, a list of clients, or all clients in several ways.


/**
 * Sending message to other clients
 */
 function onConnectionSuccess(channel){
  channel.broadcast("hello", true); // Sends a message to all clients connected to the channel excluding the sender 
  channel.send("Hello", "host"); //Sends to the host client (the TV client)
}

function onSearchSuccess(devices) {
  var device = devices[0];
 // Assuming device has already opened channel named "com.mydomain.myapp.chat"
  device.connectToChannel("com.mydomain.myapp.chat",{name:"MobileClient"}, onConnectionSuccess);        
}

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

Besides using send() of channel interface, client can also send message to other client by get the releated channelclient, then calling send() method of that interface.

addListener

Clients can receive messages from any other client after calling addListener(). In addition, clients can also receive events that notify them when other clients connect or disconnect or when itself connects or disconnects from the channel.

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

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

function onSearchSuccess(devices) {
  var device = devices[0]; 
 // Assuming device has already opened channel named "com.mydomain.myapp.chat"
  device.connectToChannel("com.mydomain.myapp.chat",{name:"MobileClient"}, onConnectionSuccess);        
}

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