Android Sender App

Android API can be implemented on mobile applications running on Android mobile or tablet devices. Simply include the provided .jar file into your existing application and add necessary codes to make your application into Smart View enabled one.

Develop Android Sender App

Add Permission

To use SmartviewSDK discover API

<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
<uses-permission android:name="android.permission.CHANGE_WIFI_MULTICAST_STATE" />
<uses-permission android:name="android.permission.BLUETOOTH" />
<uses-permission android:name="android.permission.BLUETOOTH_ADMIN" />

Proguard Exception

To prevent ProGuard , add the following lines in the proguard file

-dontwarn lombok.**
-dontwarn com.samsung.multiscreen.BuildConfig
-dontwarn javax.jmdns.impl.DNSCache

API Usage

There are many features of the SDK and it's APIs. However, there are 3 main features that all Smart View apps need to implement.

  • Discover
    -- Discover a compatible Samsung SmartTV on your network from your mobile application.
  • Launch
    -- Launch applications on the TV from your mobile application.
  • Communicate
    -- Connect and communicate with a TV application from your mobile app.

Discover TVs from a Mobile Application

From you mobile app, the first thing you'll want to do is find compatible TVs to interact with. Your mobile device and TV device need to be on the same WIFI network to work together. The mobile APIs provide a simple way to find TVs on your network. Typcially, you will use the APIs to start "scanning" the network for TVs and display a list to the user as they are found. Then allow the user to select a device to connect to.

The general mobile workflow is:

  • Start the Discovery Process
  • Listen for Events indicating services Added/Removed.
    Present the list of discovered TVs to the user
  • Stop the Discovery Process
    Once the user has selected a TV from the list

Example Android API Usage

// Get an instance of Search
final Search search = Service.search(getContext());

// Add a listener for the onServiceFound event
search.setOnServiceFoundListener(
    new OnServiceFoundListener() {
        @Override
        public void onFound(Service service) {
            Log.d(LOGTAG, "Search onFound() " + service.toString());
            // Add service to a visual list where your user can select.
            // For display, we recommend that you show: service.getName()
        }
    }
);

// Add a listener for the onServiceLost event
search.setOnServiceLostListener(
    new OnServiceLostListener() {
        @Override
        public void onLost(Service service) {
            Log.d(LOGTAG, "Search onLost() " + service.toString());
            // Remove this service from the display list
        }
    }
);

// Add a listener for the onStop event
search.setOnStopListener(
    new OnStopListener() {
        @Override
        public void onStop() {
            Log.d(LOGTAG, "Search onStop() services found: " + search.getServices().size());
        }
    }
);

// Start the discovery process with a timeout of 15 seconds.
search.start(1500);

// You can also stop the discovery process after some amount of time. Preferably once the user has selected a service to work with
search.stop();

Launching Installed TV App from a Mobile Application

Before you can work with an installed TV app, you must first know the "id" of the TV application you want to work with. You can get your tv app id when you register your app in Samsung Apps.

Once the TV app has been released into Samsung Apps, you must use the supplied app id.

There are 4 core functions for working with installed tv apps

  1. service.createApplication(appId, channelId) :
    -- Create an application reference to your tv app by app id, and channel id
  2. application.connect() :
    -- Connect to the tv application
  3. application.disconnect() :
    -- Disconnect from the tv application
  4. application.install():
    -- Install the tv application
// Example app id
String appId = "111299000796";

// Example channel id
// This is your "communication" channel id. Your TV app must use the same channelId
String channelId = "com.yourcompany.yourapp";

// Create an application instance.
Application application = service.createApplication(appId, channelId);

// Connect to the tv application. Note: This will also launch the tv application if not already launched
application.connect(new Result<Client>() {

    @Override
    public void onSuccess(Client client) {
        Log.d(LOGTAG, "Application.connect onSuccess()");
        // You can now send messages to the tv application
    }

    @Override
    public void onError(Error error) {
        Log.d(LOGTAG, "Application.connect onError() " + error.toString());

        // Uh oh. Handle the error.
        if (error.getCode() == 404) {
            // tv app is not installed, you can install it now (see code below)
        }
    }
});

// Disconnect from the application
boolean stopTVApp = true;// if this is false, then the TV app will not stop
application.disconnect(stopTVApp, new Result<Client>() {
      
   @Override
   public void onSuccess(Client client) {
       Log.d(LOGTAG, "Application.disconnect onSuccess()");           
   }
   
   @Override
   public void onError(Error error) {
       Log.d(LOGTAG, "Application.disconnect onError() " + error.toString());
   }
});

// Install the application on the TV. 
// Note: This will only bring up the installation page on the TV. 
//       The user will still have to acknowledge by selecting "install" using the TV remote.
application.install(new Result<Boolean>() {

    @Override
    public void onSuccess(Boolean result) {
        Log.d(LOGTAG, "Application.install onSuccess() " + result.toString());

    }

    @Override
    public void onError(Error error) {
        Log.d(LOGTAG, "Application.install onError() " + error.toString());

        // Uh oh. Handle the error.
    }
});

Sending Messages from a Mobile Application to TV Application

Once your mobile application and TV application are connected, you can send messages to/from any or all clients connected including the TV.

For each message, you must supply a:

  • Message ID
    -- This is just a short string describing your message. example: "fireMissile"
  • Message Data
    -- This is any string containing the data for your message.
  • Message Target
    -- This can be one of the Message.TARGET constants or a Client or a list of Clients.
// Note: The TV application is designated as the "HOST"
String messageId = "fireMissile";
String messageData = "{\"speed\":\"100\"}"; // Data can be any string including a json string

// Send a message to the TV application only.
application.publish(messageId, messageData, Message.TARGET_HOST);

// Send a "broadcast" message to all clients EXCEPT yourself 
application.publish(messageId, messageData, Message.TARGET_BROADCAST);

// Send a message to all clients INCLUDING yourself 
application.publish(messageId, messageData, Message.TARGET_ALL);

// Send a message to a specific client (by id)
ChannelClient client = channel.getClients().get(clientId);
application.publish(messageId, messageData, client);

// Send a message to a list of clients
List<ChannelClient> clients = ... // You can create any combination list of clients
application.publish(messageID, messageData, clients);

Receiving Messages in a Mobile Application

To receive incoming messages from another device, you need to add a message listener for messages that you expect to receive.

Received messages will include the message payload, and which client sent the message.

// Listen for a message by event
application.addOnMessageListener("fireMissile", new OnMessageListener() {

    @Override
    public void onMessage(Message message) {
        Log.d(LOGTAG, "Application.onMessage() message: " + message.toString());
    }
});

Adding Event Listeners in a Mobile Application

There are several events that occur during the lifecycle of a Smart View application.

You can add listeners for any or all of them. Below are the recommended set of events to listen for.

// Listen for the connect event. This event is fired when "you" connect.
application.setOnConnectListener(new OnConnectListener() {

    @Override
    public void onConnect(Client client) {
        Log.d(LOGTAG, "Application.onConnect() client: " + client.toString());                
    }

});

// Listen for the disconnect event. This event is fired when "you" are disconnected
application.setOnDisconnectListener(new OnDisconnectListener() {

    @Override
    public void onDisconnect(Client client) {
        Log.d(LOGTAG, "Application.onDisconnect() client: " + client.toString());                
    }

});

// Listen for the client connect event. This even is fired when "another" client connects
application.setOnClientConnectListener(new OnClientConnectListener() {

    @Override
    public void onClientConnect(Client client) {
        Log.d(LOGTAG, "Application.onClientConnect() client: " + client.toString());                
    }

});

// Listen for the client disconnect event. This event is fired when "another" client disconnects
application.setOnClientDisconnectListener(new OnClientDisconnectListener() {

    @Override
    public void onClientDisconnect(Client client) {
        Log.d(LOGTAG, "Application.onClientDisconnect() client: " + client.toString());                
    }

});

// Listen for a message by event. This event is fired when an incoming messages is received.
application.addMessageListener("fireMissile", new OnMessageListener() {

    @Override
    public void onMessage(Message message) {
        Log.d(LOGTAG, "Application.onMessage() message: " + message.toString());
    }
    
});