Hi, it´s me again and I have been playing around with the new Web Engine feature that came with CE9.9.0 a few days ago.
This is just a wonderful feature with so many different use-cases that I don´t really know where to start. But the most obvious use-case is to re-purpose the device while it is not in use with Digital Signage, and at the same time have the option to create on-demand web views or web apps when needed.
First of all, what is the difference between a web app and a web view? Well, nothing really but there is a difference on what the devices support. The Webex Board has a big touch screen and also have a mode called; Interactive Mode, which basically means you can interact with the web page you have opened, perfect for "Web Apps". The other devices you may view a web site but you cannot interact with it.
So for now, Webex Board is the only device that support interactive "Web Apps", you can even create native shortcut icons to open different apps on-demand without creating complex macros, which is great for those who likes it simple.
I like to make it a little bit more complicated for the benefit of flexibility, but we will take a look at both aspects as we go.
Please enjoy, and I hope this will inspire you to create something amazing!
Summary
Supported hardware
Cisco Webex Board (all models), Room Kit, Room Kit Plus, Room55, Room 55 Dual, Room 70 (Dual), Room 70 G2 (Dual), Room Kit Mini, Room Kit Pro
The Web Engine is the core feature used for Digital Signage and Web Apps. So, the first thing you must do is to enable this from the web interface or which ever method you prefer.
xConfiguration WebEngine Mode: On
We will be talking about Digital Signage and then about the UI Extensions while moving towards Web Apps.
Digital Signage
Digital Signage is a feature designed for re-purposing devices for displaying content of a web page when not in use. When the device enters half-wake the device will temporary display the content of the URL provided for the signage configuration until the device goes into standby. For Webex Boards there is also an interactive mode, which allows a user passing by the device, to interact with the web page displayed on the board. This could be a map of the building, todays lunch menu or whatever you want!
Typical use cases
- Digital signage
- Dashboards
- Digital collaboration tools such as Trello / Realtime Board
- Facility services as building maps or room bookings
- Help, instructions
- Games, ice breakers
- Display emergency information
Feature description, functional overview, compatibility
When the device enters standby it will no longer display the web page on screen to save power (for example outside office hours). Today we do not have a native way of defining office hours on the devices, although you can do, with a macro. This means that it is possible to make the device display content, only during office hours and never go into standby during this time. Extending the standby timer will increase the duration of the web view, but it is limited to 120 minutes (2 hours) for now.
xConfiguration Standby Delay: 120
Lets look at some examples on how to configure and set up Digital Signage.
Configurations
First of all, and I cannot stress this enough, you need to make sure the Web Engine is turned on for Digital Signage to work.
xConfiguration WebEngine Mode: On
Then you can enable the standby signage mode. Set the Standby Signage Mode to On and how often you want the page to refresh in seconds. Then finally, type in the URL to the page you want to load.
xConfiguration Standby Signage Audio: Off
xConfiguration Standby Signage InteractionMode: NonInteractive xConfiguration Standby Signage Mode: On xConfiguration Standby Signage RefreshInterval: 1 xConfiguration Standby Signage Url: "http://<url to something awesome>"
Important note: Self-signed or other custom CA certificates on any HTTPS sites you are trying to open will not work in CE9.9.0 :( as it only validates toward a pre-installed list of Certificate Authorities. This will most likely improve in later versions of CE.
Interaction mode is for Webex Boards only and allow you to navigate the displayed web page, clicking links and filling in forms and so on using the pop-up on-screen keyboard.
For example, if you have a website monitoring statistics of some kind, this can be displayed on the system screen while in "Halfwake". When the device enters Standby mode the screen will go black as usual to save power.
Here is a simple example on how to setup standby control during office hours, I have just tested this quickly so you probably want to expand on this and fix the bugs you may encounter :D.
const xapi = require('xapi');
//Define office hours and days 1 = Monday etc
const dayFrom = 1;
const dayTo = 5;
const hourFrom = 8;
const hourTo = 16;
/*
* Timer interval, checking the time of day. If the time is in office hours it will check the current state.
* If the device is in standby (which it will usually be in the mornings, it will automatically set the device in halfwake.
* After checking the standby state it will reset the standby timer, not the halfwake timer which means that the device will go into halfwake but never in standby during the office hours.
*/
function signageControl() {
setInterval(function() {
if (checkOfficeHours()) {
xapi.status.get('Standby State').then(standbyState => {
if (standbyState === "Standby") {
xapi.command('Standby Halfwake');
}
else if (standbyState === "Halfwake") {
resetStandbyTimer();
}
});
}
}, 50 * 1000);
}
function checkOfficeHours() {
var d = new Date();
var hour = d.getHours();
var day = d.getDay();
if (day >= dayFrom && day <= dayTo) {
return (hour >= hourFrom && hour < hourTo);
}
return false;
}
function resetStandbyTimer(){
xapi.command('Standby ResetTimer', { Delay: 5 });
}
signageControl();
You can expand on the above as well to display different content at different time of the day. I could expand on this forever, but we have to move on :). Feel free to copy any of these examples and make them your own and better.
Remember that whatever web site you choose to display on the screen and what functionality is provided is up to the content creator (maybe that is you?) either if it is a static web page with information or a dynamic web app with animations or interaction capabilities.
Examples (Interactive mode)
Lets create a simple interactive signage example, I mean -really- simple and I am not focusing on creating something slick here, it´s just to plant a seed in your brain.
Use your favorite web server accessible by the Webex Board (IIS, apache, nginx or whatever). I am going to use a simple background using CSS and a couple of links that the user can click to interact with the Board.
index.php (could also be .html) which is located in the <web-root>/signage
<!DOCTYPE html>
<html>
<style>
body{
background-image: url('cisco.png');
background-size: cover;
height: 100vh;
padding:0;
margin:0;
}
a {
font-size: 3em;
text-decoration: none;
}
</style>
<center><h1>WELCOME TO CISCO</h1></center>
<a href='map.php'>Click here to see a map</a> <br>
<a href='lunch.php'>Click here to see todays lunch menu</a>
</html>
I then set the correct configurations:
xConfiguration WebEngine Mode: On
xConfiguration Standby Signage Audio: Off xConfiguration Standby Signage InteractionMode: Interactive xConfiguration Standby Signage Mode: On xConfiguration Standby Signage RefreshInterval: 0 xConfiguration Standby Signage Url: "http://10.10.10.1/signage"
I set the refresh interval to 0 so that the page never refreshes automatically, you should consider this as it can be disturbing for users navigating the page. As the final step the end I set the URL to my web server.
Note: The refresh interval is in seconds and is useful if the page displaying content has dynamic values that needs to be refreshed or if the server logic is to show random content on each request (depending on the use-case etc..). If the content is heavy to load, you should use a longer refresh timer so that the page gets time to load and display the content for a while.
If the device is currently NOT in halfwake, nothing will happen after setting the configurations. If you see the black screen and the device is in standby it is normal since the web page will only show as long as the device is in halfwake mode.
You can trigger halfwake from the web interface or xAPI:
xCommand Standby Halfwake
Note the black line at the bottom saying "Tap here to start". This is visible when a web page is being displayed in signage mode (not using web app), as tapping the screen anywhere else will try to interact with the web view. Pressing the "home" button on the webex board will also wake the system up from halfwake.
The screen now renders my web page, which is quite simple. The links on the screen are just normal <a href> links but I have not created them yet, so when I click the links it will display:
If you use broken links, like I have in this case, you will see "File not found". A floating "back" button will appear when you start navigating so you can move back in case you get lost on the web page. There is no forward button. The Room Devices render the web pages but you have no standard browser functionality (like typing in a URL, bookmark etc, but you do have a back button, which helps a lot).
So lets take a look at the "map.php".
map.php
<!DOCTYPE html>
<html>
<style>
body{
background-image: url('cisco.png');
background-size: cover;
height: 100vh;
padding:0;
margin:0;
}
a {
font-size: 3em;
text-decoration: none;
}
</style>
<a href='index.php'><<-Go back</a>
<center>
<h1> Here is a map of the building</h1>
</center>
<iframe src='http://internal.domain.com/map' height='100%' width='100%'>
</iframe>
</html>
The markup above will render a link to navigate back to the "index.php" and will also render an external page using an iframe.
As you now see how this works in a simple form, you can start create your own signage flow or help customers understanding how they should get started. The burden is on the user that is creating this to get the flow properly in place like with any web site you are creating for whatever purpose. Note that you don´t have to create this from scratch if you already have a working site, just type in the URL to the site you want to open. The device needs to be able to access the page over the network.
Example of rolling signage in NonInteractive mode using a macro
Other Room Devices do not support Interactive mode, which means that the user cannot click links or interact with the web page. So this mode is for displaying either static content or over-time dynamic content, for example, information about on-going activities in the workplace or other useful information / statistics / recognitions etc..
NonInteractive mode works exactly the same way as the examples above but without the navigation options, if you touch the screen anywhere, it will wake up the system. You can customize the server side to show a slideshow / gif or video content. Macros can also customize the behavior to an extent where you can randomize the content on intervals the way you want.
There are apps or other ways of creating automated slideshows without updating the link every time, but here is a macro example (see description after the code example):
signageCarousel.js
const xapi = require('xapi');
//1
const baseUrl = 'http://10.10.10.1/noninteractive/';
const links = [
'image1.jpg',
'image2.jpg',
'image3.jpg'
];
var slideshowInterval;
var standbyInterval;
let index = -1;
//2
function resetStandbyTimer() {
xapi.command('Standby ResetTimer', {
Delay: 100
});
}
//3
function show() {
++index;
if (index >= links.length) {
index = 0;
}
xapi.config.set('Standby Signage Url', baseUrl + links[index]);
}
//4
function init(state) {
if (state == "Halfwake") {
slideshowInterval = setInterval(show, 15000);
standbyInterval = setInterval(resetStandbyTimer, 90000);
} else {
clearInterval(slideshowInterval);
clearInterval(standbyInterval);
}
}
//5
xapi.status.get('Standby State').then(init);
xapi.status.on('Standby State', init);
Description:
1: Define the base url and an array of "links", I have used images to create an image carousel (without any server side coding), the images are just stored on the web server.
2: resetStandbyTimer() will reset the standby timer to prevent the device from entering standby until someone puts it in standby or wakes it up from halfwake. This is not recommended as the device will constantly loop through the images forever and during weekends. But I use it in my example to show that it is possible. It is also possible to tweak the example to extend the standbytimer to only reset during office hours.
3: show() is the URL changer. It will loop through one of the links index each time it is called by the interval and set a new URL in the config which will take effect instantly (as the device is already in halfwake mode).
4: init() is the function that starts and stops the intervals depending on the standby state. If the standby state is halfwake, we will start two intervals, one to control the standbytimer and one to change the signage URLs on a given interval (15 seconds).
5: It will get the current status of the standby state and test the value through the init function. If the state is Off or the device is in Standby, nothing happens. If the state is in halfwake it will start the carousel right away. xapi.status.on will start a listener for change in the standby state and test the value through init every time. So if someone wakes up the system by tapping the touch panel the carousel will stop and start again when entering halfwake.
Again, this may not work perfectly so feel free to change the behavior as you please.
UI Extensions editor
Just to make it clear, In-Room Control is now re-named to "UI Extensions", it still has the same basic functionality as before but with a few updates to the editor it-self. You can now select what kind of buttons you want to create and on a Webex Board there is a brand new button you can add, called "Web Apps". These are simply buttons for opening Web Apps from a connected Touch 10 or on-screen from a Webex Board. Note that the web app button is only supported on Webex Board for the time being because it has interactive mode. You can of course emulate the same thing using a macro and an action button on the other devices.
Let´t take a quick look at creating a webapp button.
Having a button that natively opens a web app without the need for creating a supplementing macro is great for many use-cases where you only need to open a web app on demand. You can create many web app buttons to get a selection up there so, knock your self out!
So what is special about this button is that you configure the URL it is supposed to open, directly in the UI Extensions button properties. Easy, right? :)
This is all I need to do before pushing the button to the codec using the now highlighted blue button on the top menu.
What about the icon you may wonder.. yes, and this is pretty cool. The device will look for a favicon on the web site its trying to open and set this as the button icon, and yes, you may choose your own icon by setting a specific URL to an image that will become the icon image.
That's it, now you press the button and it opens the bbc.com web site.
Using this feature will enable the user to annotate on the web page as well (different from signage)! You can move this button around on the screen as well.
Creating your own buttons for web views on devices that do not have the web app option
Access the web interface of the device.
Now go into the UI Extensions editor (former In-Room Control editor) on the web interface.
Integration > UI Extensions Editor
As you see in the screenshot above I have create one panel that should open the BBC News page. The button is configured to show "Out of Call" only. This is because Web Views only works out of call, so it does not make any sense to have the button display while in a call.
Type in the name of the button and select an suitable icon and color. Tip: Select the globe icon if nothing else matches.
The panel ID is set to "bbc" and is the event we will be listening for in our macro example.
Once done, upload the button to the codec by pressing the highlighted "Up arrow" in the top bar.
Creating the macro
Please see below for a simple example to get make the buttons bring up the web view. Note that the xAPI command for Web View is the feature we use here.
const xapi = require('xapi');
function open(url) {
xapi.command('UserInterface WebView Display', { Url: url })
.catch(e => console.log('Not able to open url', e.toString()));
}
function guiEvent(event) {
console.log('Pressed button', event.PanelId);
// First button on your home page. change the panel id and url below to what you want // The panel id must match the id you typed in the inroom editor
if (event.PanelId === 'bbc') {
open('https://bbc.com');
}
// Second button on your home page
else if (event.PanelId === 'office') {
open('https://www.office.com');
}
}
xapi.event.on('UserInterface Extensions Panel Clicked', guiEvent);
The "open" function will open the URL that is passed to it from the guiEvent function depending on which button is pressed. At the very bottom an event listener has started to pick up the "Clicked" events from the panel that will contain our panel Id's that we setup earlier in the UI part.
If the panelId is "bbc" we will open "https://bbc.com" using the xapi.command('UserInterface WebView Display', {Url: url}) as you see above.
Remember to activate the macro before you press the action button, and you are good to go! :) Note that it makes more sense displaying web pages that shows all the information needed in one page because on these systems you cannot navigate the web page. If you want to display a QR code or something similar this would work perfectly with this example.
A button to clear the web view / or a timeout on the webview it self can also be useful to improve user experience.
Known Issues, Limitations & Advisories
- Currently the Signage Mode is limited to showing content when Halfwake triggers until the device enters standby. You can increase the standby timer to extend the time the content will display on screen or create a macro like the example above.
- Touch 10 do not support rendering of web pages with this feature in any scenario.
Compatibility
Since the browser is based on a standard Chromium browser, most of the features you expect from a modern desktop browser is available.
Features such as HTML5, EcmaScript 6, CSS3, web fonts, multi-touch, SVG, canvas, iframes, web sockets, web assembly, web workers and more are available.
Note that the following features are currently NOT supported:
- WebGL
- Password manager
- Plugins (Flash etc..)
- Downloading and uploading files
- Notifications
Some of the above may be added later, but no guarantees can be provided now.
How many windows / tabs are supported?
Only one web tab / window is supported. If a web page tries to open a page in a new window or tab, it will replace the existing page.
Multimedia
Standard video codecs are supported, such as WebM and Mpeg4. Decoding is done through software. It is not recommended to go beyond 720p resolution as this will lead to choppy performance!
What about audio / volume?
The volume follows the volume setting of the video system. For digital signage, the audio is "Off" by default to avoid unwanted noise by accident, but it can be controlled with the following configuration.
xConfiguration Standby Signage Audio: <on/off>
You can of course enforce volume and mute control on top of this by using JavaScript audio frameworks.
Browser info:
The web engine is based on Chromium / Qt WebEngine with V8 JavaScript. The Chromium version is upgraded every time Cisco updates the Qt version in RoomOS/CE, meaning it will not be as up-to-date as your Chrome laptop version, but will be updated periodically.
You can inspect the version at any time by looking at the user agent, i.e. by visiting http://whatsmyuseragent.org/ on your device.
Is user data persisted?
For digital signage, web engine is running in persistent ("desktop browser") mode, meaning that cookies, local storage etc. are saved to disk and persisted across reboots and even upgrades. This means its possible to have persisted logins for team dashboards etc.
Are touch events supported (developer related)?
Yes, the Webex Board supports up to 10 simultaneous touch events, using ontouchstart, ontouchmove and ontouchend. The traditional onclick event is also supported but not recommended since it incurs a slight delay to detect gestures.
Note that the ordering of touch events is not stable so use the touch event "identifier" to keep track of simultaneous touches.
How to prevent the standard zoom gestures in the rendered web views?
Two finger zoom is default of accessibility and convenience, but not always wanted, for example in immersive apps, such as Google Maps, whiteboards and games where you need more control. You can overwrite this with preventDefault:
document.querySelector('.myCanvas').ontouchstart = (e) => {
e.preventDefault();
// .. my action
}
// similar for ontouchmove and ontouchend
What is the viewport / screen size?
The logical viewport is 1920 pixels wide, and 1080 pixels high minus whatever is used for the toolbar (typically less than 200 pixels).
The actual rendering is done on a 4k canvas (3840 x 1260, similar to Apple´s Retina mechanism, so text and images will be crisp. Be sure to provide high resolution images and assets for the optimal user experience.
Developers can also modify the viewport meta tag, i.e.:
<meta name="viewport" content="width=960, initial-scale=1">
Are JavaScript dialogs available?
Yes, most of the JavaScript dialogs such as alerts, prompt and confirm works like on a desktop and is implemented using the native dialogs of the video system.
Uploading and downloading dialogs are not supported!
What fonts are available?
Currently only the system font of RoomOS / CE (sans serif). Web fonts are supported though so third party app developers can add their own fonts as needed with CSS, i.e.:
@font-face {
font-family: handwriting; src: url(handwriting.woff);
}
div {
font-family: handwriting;
}
Login and authorization
One of the most challenging aspects for a web app on a shared video device is the user login. We cannot just store the users credentials like on a personal device, since it can be used by anyone, and entering the username and password on a large-screen, soft keyboard device is both annoying and unsafe.We will strive towards a solution that makes this easy and safe in the future. In the meantime, the model solution is to use a second, personal device for authentication and authorization.
User flow:
- The user launches the web app on the video device
- The user is prompted and enters their email
- The web app sends a notification to the user's phone
- The user accepts the login on the phone
- The web app is automatically logged in on the video device
The Microsoft Authenticator for Office 365 an example of how this can be implemented in a way that is convenient, fast and safe for the user.
What animations are supported?
Both CSS transitions and web animations are supported and hardware accelerated whenever possible. This typically means the transform and opacity CSS property. Try to avoid doing animations that requires DOM or layout operations.
How to improve performance?
The web engine has the difficult task of running modern, full scale web content on a 4K screen while having lower priority than the main video features. This means it can sometimes struggle with heavy web sites such as Google Maps 3D and similar.
But there are many things a developer can do to improve performance. This is worthy of its own guide, but here are a few things you can try:
- Start testing on the device early in development, if possible, or use a mobile device
- Avoid using images that are larger than needed, resize them on the server
- Reduce the number of layers with opacity
- Avoid drop shadows
- Avoid huge canvases, load content dynamically as needed instead
- Use only hardware accelerated CSS / web animations
- Skip certain features, eg animations, based on user agent
- Avoid doing much work in event handlers, delegate to async tasks
- Use requestAnimationFrame instead of setInterval if you are doing low level animations/simulations
- Move heavy calculations / algorithms to WebAssembly
- Best but also most challenging: Learn the performance monitor of Chromium and use it actively.
Can I create offline applications?
Yes. Web workers are supported, and can be used to speed up initial loading of heavy web apps.
Note that currently the web views are not available if the device does not have network, so real offline apps are not possible.
Keyboard input
The RoomOS / CE soft keyboard behaves similarly to the touch keyboards on Android and iOs, and pops up any time an input field gets focus.
The content also scrolls up if needed so both the input field and keyboard are visible.
It does not support specialized formats such as numeric, calendar and color picker at the moment.
A vertical soft keyboard does not encourage a lot of text input and provides little privacy, so keep that in mind.
Localization
The web engine sends the language header of the current language in each HTTP requests, i.e.
Accept-Language: fr for French.
A web app can then translate the content to the current language, either server side by looking at the header, or in JavaScript by querying
useragent.language in the browser.
Non-fullscreen windows?
Currently only fullscreen web views are supported. In the future we may support different types such as web dialogs and side-bars.
Multiple screens?
For digital signage, content is cloned to the extra screens. A web view cannot be logically stretched across multiple screens. In other cases than signage, only the primary monitor will display the web view.
Best practices
Writing web apps for a shared device with a huge touch screen comes with its own set of challenges. A dedicated best practice manual may be offered later, but here are a couple of pointers:
- The screens are large and the user can be very close to it - choose your content based on wether you prefer interactive use (smaller font and content) or passive audience (larger font and content).
- Provide high resolution assets for crisp graphics
- Only use hardware accelerated CSS animations (transform and opacity)
- If possible, provide a second, personal device for log in such as Microsoft Authenticator
- Use local storage to store temporary user data, to prevent data loss if the web view is closed by accident
- Don't rely on multiple tabs
Style guide
As a third party developer you do of course have the tools and freedom to design the web content exactly as you like or to match your company's visual profile.
If you prefer something that feels native and in line with the Cisco design language, you can find everything you need at https://momentum.design/.
As well as styles and guide lines, this web site contains CSS, assets, fonts and icons and component support for popular web frameworks.
Can the content access the xAPI?
At the moment, not directly.
The Cisco video systems provide rich and powerful API integrations through the xAPI, such as making calls, starting presentations, counting the number of people in the room etc.
Currently a web view does not have direct access to the xAPI, but it can access it the same way as other integrations, provided that credentials to the video systems are available.
Alternatives include local REST APIs (on premise deployments), HTTP feedback (web hooks), cloud APIs or direct web socket communication.
For more info about these, see separate RoomOS / CE developer documentation. Be careful about exposing credentials in your client side code, though, and consider going through your web app's server.
What about non-touch / non-interactive devices?
At the moment, the only supported device that has touch screen capability is the Webex Board, but all the new Cisco video devices such as Room Kit, Room Kit Mini, Room 55 etc also support web view.
Troubleshooting, diagnostics
Page lifecycle:
As soon as the user hits the home button, the state of the web page is lost. When the user starts the web activity again, the same url is reloaded. You can save the current state of the page and and re-apply it by always saving to local storage (or session storage), then fetching those state values whenever the page loads.
Remote developer console
xConfiguration WebEngine RemoteDebugging: On
The remote developer console is by far the most important and powerful tool available to third-party developers. This is a standard Chrome dev console, that you can run remotely on your own laptop to inspect what is happening in the web engine. See the log console and manipulate the content live just like with local web development.
When this is enabled all the web views will display a prominent warning that they may be monitored as a privacy warning.
Accessing the remote debugger via a browser is done like this when remote debugger is enabled (the URL is also listed on the device screen together with the warning):
http://<codecip>:9222
Remote debugger is only supported with Google Chrome browser and Chromium Browser.
Using this tool I can troubleshoot failing functions or check elements that are not displayed correctly in the web view. In the above screenshot I can view the page that is rendered on the device from my laptop. This tool should be used for debugging and development only. Remember to turn it off when done.
System Resources
The web engine has a lower priority than the main video features and is restricted. Currently it is limited to 1 CPU core and 650 MB of memory (excluding GPU usage). If the web page requires more memory than allowed, Chromium will try to optimize usage with the memory pressure handler. Failing this the web view will eventually be terminated and show an error page. The web view may also be terminated if the video system is running on low memory in general.
For Room Kit Pro there are 6 cores and 8 GB of memory but the restriction is currently the same as the other devices.
Resources & References
Special thanks to Tore Bjolseth for all the details.
4 Comments
