Samsung Electronics logo

Create N-Service Host Application

The N-Service API allows you to create a convergence application which runs on Samsung Smart TV working with the client application runs on mobile devices.

Using the N-Service API capabilities, your applications can:


Prerequisite

The N-Service Host API provides access to connectivity through N-Service functionality on Samsung Smart TV provides. When the application is launched, a nservice object is instantiated automatically in the webapis object. The webapis.nservice object is an instance of the NServiceManager interface, which provides N-Service connectivity features.

Adding the webapis JavaScript file in your application is required to invoke this API properly. Please refer to the script code below to add the webapis file:

<head>
    <script type="text/javascript" src="$MANAGER_WIDGET/Common/API/CImageViewer.js"></script>
    <script type="text/javascript" src="$MANAGER_WIDGET/Common/API/TVKeyValue.js"></script>
    <script type="text/javascript" src="$MANAGER_WIDGET/Common/API/Widget.js"></script>

     <!-- including the JavaScript file which supports Samsung Web API -->   
    <script type="text/javascript" src="$MANAGER_WIDGET/Common/webapi/1.0/webapis.js"></script>
</head>

Handle N-Service Device Changes

The webapis.nservice.registerManagerCallback method lets you register an event listener that handles changes when a N-Service client device has attached or detached to the N-Service host application.

The event listener can receive following events:

  • webapis.nservice.MGR_EVENT_DEV_CONNECT as a value of eventType attribute : A N-Service client device has been joined.
  • webapis.nservice.MGR_EVENT_DEV_DISCONNECT as a value of eventType attribute: A N-Service client device has been leaved.

You can retrieve the information about the device name and the device ID which sent this event.

Handling N-Service Device changes MUST be proceeded during the application intialization phase. Without invoking registerManagerCallback() properly, The client application COULD NOT connect TV application.

The following example illustrates how to handle events which a N-Service client device has joined or leaved.

function managerCallback(event) {
      switch (event.eventType) {
          webapis.nservice.MGR_EVENT_DEV_CONNECT:
              alert(event.deviceName + " with " + event.uniqueID + " joins");
              break;
              
          webapis.nservice.MGR_EVENT_DEV_DISCONNECT:
              alert(event.deviceName + " with " + event.uniqueID + " leaves");
              break;
      }
  }
  webapis.nservice.registerManagerCallback(managerCallback);
  
  

Get Connected N-Service Devices

The webapis.nservice.getNServiceDevices method is used to get the N-Service client applications running on connected devices to Samsung Smart TV.

The method register two callbacks, the first is a type of NServiceDeviceListSuccessCallback and the second is a type of ErrorCallback. The first callback is invoked when the connected N-Service client devices successfully retrieved. The list of connected client devices is passed to the success callback as an array of NServiceDevice object.

The following example illustrates how to get connected N-Service client devices.

function deviceListSuccessCB(devices) {

     // If any N-Service host device is already connected
     if (devices.length > 0) {
 
        // Print out the properties of the N-Service host device
         alert("N-Service host unique ID : " + devices[0].getType());
         alert("N-Service host device name : " + devices[0].getName());
     }
 }
 
 function errorCB(error) {
     alert(error.name + " : " + error.message);
 }

 webapis.nservice.getNserviceDevices(deviceListSuccessCB, errorCB);
 

Send Broadcast Message

You can send a message to all the connected N-Service client applications using broadcastMessage method. It returns webapis.nservice.ERROR_CODE_NO_ERR if the operation is successfully completed. Otherwise, it returns webapis.nservice.ERROR_CODE_ERR.

The following example illustrates how to send a broadcast message.

 // In the client side, assume that the connection with host has been completed.
var result = webapis.nservice.broadcastMessage("Welcome everyone!");
if (result == webapis.nservice.ERROR_CODE_ERR) {
     alert("Broadcasting a message failed.");
  }  
  

Send Multicast Message

You can send a message to the N-Service client applications which joined a same group using multicastMessage method. It returns webapis.nservice.ERROR_CODE_NO_ERR if the operation is successfully completed. Otherwise, it returns webapis.nservice.ERROR_CODE_ERR.

The following example illustrates how to send a broadcast message.

 // In the client side, assume that the connection with host has been completed.
 var result = webapis.nservice.multicastMessage("group1", "Welcome to members of group 1!");

 if (result == webapis.nservice.ERROR_CODE_ERR) {
     alert("multi-casting a message failed to group1.");
  }  
  

Send Unicast Message

You can send a message to a N-Service client application which currently connected using sendMessage method. It returns webapis.nservice.ERROR_CODE_NO_ERR if the operation is successfully completed. Otherwise, returns webapis.nservice.ERROR_CODE_ERR.

The following example illustrates how to send a unicast message.

 function deviceListSuccessCB(devices) {

     // If any N-Service host device is already connected
     if (devices.length > 0) {
 
        // Send a message to first found device
         var result = devices[0].sendMessage("greeting! we have made communication channel properly.");
         if (result == webapis.nservice.ERROR_CODE_ERR) {
             alert("Error!, the message is not sent properly.");
         }
     }
 }
 
 function errorCB(error) {
     alert(error.name + " : " + error.message);
 }

 webapis.nservice.getNserviceDevices(deviceListSuccessCB, errorCB);
  

Handle N-Service Device Messages

The registerDeviceCallback method of NServiceDevice object lets you register an event listener that handles changes of a specific device.

The event listener can receive following events:

  • webapis.nservice.DEV_EVENT_MESSAGE_RECEIVED as a value of eventType attribute : The N-Service client device has sent a message to host. It returns NServiceDeviceMessageInfo object for an eventData attribute.
  • webapis.nservice.DEV_EVENT_JOINED_GROUP as a value of eventType attribute: The N-Service client device has joined a group. It returns NServiceDeviceGroup object for an eventData attribute.
  • webapis.nservice.DEV_EVENT_LEFT_GROUP as a value of eventType attribute: The N-Service client device has leaved a group. It returns NServiceDeviceGroup object for an eventData attribute.

The unregisterDeviceCallback method of NServiceDevice object is used to remove the event listener that handles the changes.

The following example illustrates how to handle events from the specific N-Service client device.

 function deviceListSuccessCB(devices) {
     function deviceCallback(msg) {
         switch (msg.eventType) {

             webapis.nservice.DEV_EVENT_MESSAGE_RECEIVED:
                 alert(msg.eventData.message); 
                 break;

             webapis.nservice.DEV_EVENT_JOINED_GROUP:
                 alert("A device is joined to " + msg.eventData.groupName);
                 break;

             webapis.nservice.DEV_EVENT_LEFT_GROUP:     
                 alert("A device is left from " + msg.eventData.groupName);
                 break;

          }
     }

     // If any N-Service client device is already connected, register a message handler to a device found firstly.
     if (devices.length > 0) {
         devices[0].registerDeviceCallback(deviceCallback);
     }
 }
 
 function errorCB(error) {
     alert(error.name + " : " + error.message);
 }

 webapis.nservice.getNserviceDevices(deviceListSuccessCB, errorCB);
 

Handle Upload File Event

You can handle an event which a N-Service client device uploaded a file using registerDeviceCallback method of NServiceDevice object. When the N-Service client uploaded a file, a JSON object which contains 'uploadFile' property will be returned as a event message notification. Also if the N-Service client device deleted the file, a JSON object which contains 'uploadFile' property will be returned as same manner.

The following example illustrates how to handle the uploading file or deleting file event from the specific N-Service client device.

 function deviceListSuccessCB(devices) {
     function deviceCallback(msg) {
         switch (msg.eventType) {
         
             case webapis.nservice.DEV_EVENT_MESSAGE_RECEIVED:
                 // Convert the message to object with JSON.parse() method
                 var msgObj = JSON.parse(msg.eventData.message); 
                 if (msgObj.uploadFile) {
                     alert("A request to uploaded file has arrival :" + msgObj.uploadFile);                 
                 } else if (msgObj.deleteFile) {
                     alert("A request to delete the uploaded file has arrival :" + msgObj.deleteFile);
                 } else {
                     alert("normal message has arrived :" + msg.eventData.message); 
                 }
                 
                 break;         
          }
     }

     // If any N-Service client device is already connected, register a message handler to a device found firstly.
     if (devices.length > 0) {
         devices[0].registerDeviceCallback(deviceCallback);
     }
 }
 
 function errorCB(error) {
     alert(error.name + " : " + error.message);
 }

 webapis.nservice.getNserviceDevices(deviceListSuccessCB, errorCB);