AppLink example

Table of Contents

  1. Introduction
  2. List of AppLink APIs
  3. AppLink Set-Up for the Dolby Voice Hub App
  4. AppLink Set-Up for the Dolby Conference Phone App
  5. Create the Dolby Voice Hub App
  6. Create the Dolby Conference Phone App
  7. Load and Run the Apps
  8. Links to AppLink Sample Code

Introduction

AppLink is the communication channel between the Dolby Video Hub's web app and the Dolby Conference Phone's QML app. It is provided as part of the respective APIs of the devices. Apps establish an AppLinkSession, a communication session, to start exchanging data. This document presents an example that shows how to establish and use this communication channel.

The Dolby Conference Phone example app displays buttons and a text field that allow the user to type messages and send them to the Dolby Voice Hub. The Dolby Voice Hub displays this text and sends the message back to the Dolby Conference Phone.

Dolby Conference Phone UI:

image

Dolby Voice Hub output:

image

The following lists all the Dolby Voice Hub and Dolby Conference Phone AppLink APIs.

dapi: AppLinkSession

Public Members

  name: string
  reachable: boolean
  url: string

Public Methods

  connect    (name: string, url: string)
  disconnect ()
  onConnect             (callback: function(ok:  boolean))
  onDisconnect          (callback: function(ok:  boolean))
  onReachableChanged    (callback: function(ok:  boolean))
  onTextMessageReceived (callback: function(msg: string))
  sendTextMessage       (msg: string)

QML type: AppLink

Properties

  reachable : bool

Signals

  newSession (AppLinkSession session)

QML type: AppLinkSession

Properties

  name      : string
  reachable : bool

Signals

  sessionEnded()
  textMessagseReceived (string msg)

Methods

  disconnect ()
  sendTextMessage (string msg)

The Dolby Voice Hub app initiates the AppLinkSession establishment process by calling the connect() method. The Dolby Conference Phone app receives AppLinkSession information on successful establishment via a newSession() signal.

Four dapi.appLinkSession callbacks must be defined in the Dolby Voice Hub app before it can communicate with the Dolby Conference Phone app:

  • onConnect
  • onDisconnect
  • onTextMessageReceived
  • onReachableChanged

// Callback for when the connection protocol ends, either succeeding or failing
dapi.appLinkSession.onConnect = function(succeeded) {
    if (succeeded) {
        output("AppLinkSession connected, reachable = " + (dapi.appLinkSession.reachable ? "true" : "false"));
    } else {
        output("AppLinkSession failed to connect");
    }
}

// Callback for when the session has ended
dapi.appLinkSession.onDisconnect = function() {
    output("AppLinkSession disconnected");
}

// Callback for when a text message has been received
dapi.appLinkSession.onTextMessageReceived = function(msg) {
    output("AppLinkSession received message: '" + msg + "'");
}

// Callback for when the state of the app on the Dolby Conference 
// Phone has changed (e.g., unreachable while it is reloading, etc.)
dapi.appLinkSession.onReachableChanged = function() {
    output("AppLinkSession reachable changed to " + (dapi.appLinkSession.reachable ? "true" : "false"));
}

Once the callback functions are defined, the hub app initiates the AppLinkSession establishment process by calling the connect() method. The phone app receives AppLinkSession information upon successful establishment via the newSession() signal. After the AppLinkSession is established, the apps can send messages to each other and disconnect.

Note: The example in this document takes advantage of AppLinkHelper.js which adds error handling and other functionality to these four API callbacks. AppLinkHelper.js is a component of the Dolby Hub API; however, a link to the code is provided below.

The Dolby Conference Phone app uses the onNewSession method to capture the signals from the Dolby Voice Hub.

Connections {
    target: Hub.appLink
    onNewSession: {
        //
    }
}

When a new AppLinkSession is received, the next step is to connect the appropriate signals from the session; for example, to be able to receive text messages. When the session is active, the phone app can send messages to the web app using the AppLinkSession::sendTextMessage method.

function myOnMessageReceived(session, msg) {
    // ...
}

function myOnSessionEnded(session) {
    // ...
}

Connections {
    target: Hub.appLink
    onNewSession: {
        session.textMessageReceived.connect(
            function(session) { return function(msg) { return myOnMessageReceived(session, msg); }}(session));

        session.sessionEnded.connect(
            function(session) { return function() { return myOnSessionEnded(session); }}(session));
    }
}

In the above example, a JavaScript pattern is used to capture the session variable in the call to the signal handlers, but this is not mandatory. For example, logic can be added so that the session is set as a property of some other QML element; the session's signals are connected to methods of that QML element; and different sessions can be differentiated by the session's name property.

Furthermore, the Dolby Conference Phone app can have a signal to send text messages, that, when connected to the session's own sendTextMessage method, allows for sending text messages directly to the new session that is being established. When the Dolby Conference Phone app triggers this signal, a text message will be sent through the session:

function myOnMessageReceived(session, msg) {
    // ...
}

function myOnSessionEnded(session) {
    // ...
}

id: myDcpApp
signal mySendMessage(string msg)
Connections {
    target: Hub.appLink
    onNewSession: {
        session.textMessageReceived.connect(
            function(session) { return function(msg) { return myOnMessageReceived(session, msg); }}(session));

        session.sessionEnded.connect(
            function(session) { return function() { return myOnSessionEnded(session); }}(session));

        myDcpApp.mySendMessage.connect(
            function(session) { return function(msg) { session.sendTextMessage(msg); }}(session));
    }
}

Refer to the source code below.

5. Create the Dolby Voice Hub App

This example will take advantage of the nginx web server running on a Dolby SDK virtual machine; its IP address is 10.112.102.205.

Create an apps folder. Then create two folders under the nginx/apps folder; one is for the web app and the js subdirectory is for the AppLinkHelper library file.

[root@dcp-sdk ~]# mkdir /usr/share/nginx/html/apps

[root@dcp-sdk ~]# cd    /usr/share/nginx/html/apps

[root@dcp-sdk apps]# mkdir applink-web-app
[root@dcp-sdk apps]# mkdir applink-web-app/js


Copy the hub app source code into two files, e.g.,

     /usr/share/nginx/html/apps/applink-web-app/applink_demo.html

     /usr/share/nginx/html/apps/applink-web-app/js/AppLinkHelper.js

The applink_demo.html app can also source the local copy of AppLinkHelper.js instead of the one provided with this article.


The result should include the following:

File Description
/usr/share/nginx/html/apps/applink-web-app/applink_demo.html Dolby Voice Hub web app
/usr/share/nginx/html/apps/applink-web-app/js/AppLinkHelper.js AppLinkHelper


6. Create the Dolby Conference Phone App

Create a folder under the nginx folder for the phone app. Keeping the phone app file in a separate directory from the web app directory prevents the web app files from being included in the phone app certificate file during the signing process.

[root@dcp-sdk ~]# cd /usr/share/nginx/html/apps

[root@dcp-sdk apps]# mkdir applink-phone-app


Copy the phone app source code into one file, or, alternatively, create a new project using Qt Creator.

     /usr/share/nginx/html/apps/applink-phone-app/Servermain.qml

Sign the Dolby Conference Phone app.

The result should include the following:

File Description
/usr/share/nginx/html/apps/applink-phone-app/Servermain.qml Dolby Conference Phone QML app
/usr/share/nginx/html/apps/applink-phone-app/.app.cfg QML configuration file
/usr/share/nginx/html/apps/applink-phone-app/.app.cfg.sig QML signature file

7. Load and Run the Apps

Since this example uses the nginx web server running on a Dolby SDK virtual machine at IP address 10.112.102.205, the app locations must use this address. Use a browser to log into the Dolby Voice Hub's web UI to change the app settings:

Parameter Value Web UI Location
Dvms.HubApp.Url http://10.112.102.205/apps/applink-web-app/applink_demo.html Settings > Dolby Voice Conferencing Service > Hub Application
Phone.App.Url http://10.112.102.205/apps/applink-phone-app Dolby Conference Phone > Application > Application URL

Clicking the Save button in the web UI will start the app download process. Note that it takes about 7 seconds before text is displayed in the Dolby Voice Hub Session Messages panel. Type some text in the Dolby Conference Phone's text send field and press the Send button. The output will be similar to that shown in the images above.

8.1 Dolby Voice Hub App Source Code

Description Link to Web Page with Source Code Listing
Sample Dolby Voice Hub web app applink_demo.html
AppLinkHelper for web app AppLinkHelper.js

8.2 Dolby Conference Phone Source Code

Description Link to Web Page with Source Code Listing
Sample Dolby Conference Phone QML app Servermain.qml