Manuals/Userful Network Video Wall/CMS Integration

From Userful Support
Jump to navigationJump to search

CMS Integration

Copyright © 2008-2015 Userful Corporation. All rights reserved.
(Updated 2015.04.28)

This is a legacy document and is only valid for Userful Network Video Wall™ 7.x versions.


This document is to help Linux-savvy Content Management System (CMS) and System Integrator (SI) partners do more advanced integration of their media players management software into Userful's Digital Signage solution.

The basic goal of this document is to enable a CMS and SI partners to minimize the need for any costly software changes on existing infrastructure. By using Userful’s innovative Station Mapping interface, zero-client stations, zero-session environment, and video wall software, Userful hopes to allow for light-lift integration into our digital signage offering.

Background & Terminology

Userful’s digital signage software is based upon Userful Multiplatform™ solution released February 2013. It features many innovative features that tie into digital signage, as discussed in this document.

The following terms are used:

  • Zero-Client: A standalone device that provides VGA, Sound, and a USB hub over ethernet is called a zero-client. Dozens of these devices can connect to a single Userful host PC, each autonomously controlled, configured, and managed by the Userful host software.
  • Zero-Session: For optimal efficiency with signage playback, Userful utilizes a way of launching and running programs on a screen called a zero-session. This allows for a zero-client device to startup with a blank role without a traditional desktop, minimizing its memory and CPU footprint. The zero-session typically acts like a kiosk interface, locking the zero-client to one particular display application.
  • Station Mapping: The zero-session’s role can be dynamically assigned in the Userful Control Center Station Mapping interface. This allows an administrator to identify groups of zero-clients by a display number, and then assign a role to each station. For example, in Station Mapping, each zero-session can be independently configured to run any type of full-screen role, like a kiosk application, a Web browser URL, or a media player playlist.
  • Station Mapping Session Container: Each unique station role is called a Station Mapping Session Container. A session container is a customized configuration of one container type, such as: the standard Linux desktop, a virtual machine, a media playlist, an HTML5 or Flash URL, or a local Linux program -- effectively becoming a customized signage player. The HTML5/Flash URL, native Linux program, are the primary means for third-party CMS integrators to access existing streams of CMS content over the network easily within the Userful Signage system. (The media playlist assumes content is already delivered via background process, and is available for offline playback.)
  • Video Wall: Multiple displays/stations can be grouped together to create one logical station output, thus forming a video wall. This logical group is then mapped to one specific session container, allowing for easy construction of video walls tied to CMS content.
  • Web Browser: Userful utilizes Chrome and Firefox as configurable web browsers within the zero-session. Ultimately, Chrome is recommended as it can be launched in a private-session kiosk mode easier, and it has better HTML5 and Flash integration support.
  • Media Player: Userful utilizes mplayer as a full-screen player of local media files. This program is launched in full-screen mode, using Xv display acceleration, and automatically loops its playlist. This program assumes that the media files have already been delivered to the Userful host system.
  • Native Command: A local Linux program that is installed onto the Userful host system by the SI. Userful’s Station Mapping will launch this program full-screen on each zero-session it is assigned to. Note, it is the SI’s responsibility to ensure this is a valid X11 program, runs properly in the CentOS 6.3 environment, and cannot be exited. Userful will simply launch this program full-screen without any window decorations or borders.

Note: All active zero-session sessions will automatically restart if the associated binary program crashes, terminates, or if a user manages to shut-down the program or station. This includes re-launching the web browser to the current URL, the Media Player playlist, and the native command where appropriate.


This document assumes that CMS content stream is already available via a publicly accessible URL, or via a custom (64-bit) Linux program. The URL and Linux program will likely need a way to uniquely identify themselves to the server that enables each station on the Userful system to attach to and play the correct content stream from the server. Typically this would be the device MAC address, but additional display attributes and host system information is also available.

All connected stations, session container types, and mapped stations are configured in Userful's browser accessible management program called Userful Control Center (UCC). As part of integration, Userful will help you create and configure one or more Station Mapping Session Containers, each customized to your display requirements. CMS administrators will then use these customized session containers to instruct zero-client stations to connect to their various CMS integration channels.

Exportable Userful Session Variables

To allow the CMS integrators to activate individual stations, existing content management infrastructure must be launched in specific ways, as defined by the CMS servers. Userful’s solution is to export various session variables to the CMS software launching points. This will help the CMS activate itself based upon the correct content streams configured uniquely for each zero-session display.

Below is a list of identifiers that can either be passed through as URL arguments when calling a web-page, or accessed via the shell environment by your Linux native program. All identifiers are standard within the zero-session environment.

For a Web Browser based zero-sessions, simply include the unique identifiers as URL arguments in the query-string. The zero-session will translate these variable names to their actual values when the station launches.

For a custom Linux native program, these same unique identifiers are available as environment variables. These can be accessed within a simple bash shell wrapper, or directly via a C or C++ program environment.

Examples of both methods can be found in Section 5.

Primary Variables

The following variables Userful anticipates will be most useful for CMS and SI partners to activate their content.

Note: All station-specific values are unique to each network zero-client station. When Userful activates the station, the variables are accurate to the physical device’s characteristics and placement on the Userful display network.

Description Userful Variable Name Example Value
Station device MAC address ${USERFUL_STATION_MAC_ADDRESS} F8:0F:41:2A:B3:7B
Station device display number ${USERFUL_STATION_NUMBER} 3
Station device display resolution ${USERFUL_STATION_RESOLUTION} 1920x1080

Note: Since stations/devices can failover automatically from one host to another we recommend that as much as possible station identification should be tied to the station MAC (which will always be attached to the single screen that is plugged into it). The host MAC may vary as stations can move between host PCs whereas each network Station will have a unique MAC network wide.

Secondary Variables

The following variables Userful anticipates may be useful to CMS and SI partners.

Note: Userful strongly recommends that the Host and Station IP Addresses described below are internal and in the same private subnet. A router should be installed between the host PC and all zero-clients stations, where all network access is granted via a gateway on the router itself. As such, the IP Addresses are on this internal private subnet only.

Description Userful Variable Name Example Value
Host Name ${USERFUL_HOST_NAME} showcase*
Host MAC address ${USERFUL_HOST_MAC_ADDRESS} 50:E5:49:CE:DC:44
Host Software Version ${USERFUL_HOST_SOFTWARE_VERSION} 5.0-6161.12
Host (external) IP address ${USERFUL_HOST_IP_ADDRESS}
Station device (internal) IP address ${USERFUL_STATION_IP_ADDRESS}
Station session container type ${USERFUL_STATION_PROFILE_TYPE} Web Browser**
Station session container name ${USERFUL_STATION_PROFILE_NAME} CMS Site**
Station device name ${USERFUL_STATION_NAME} vidwall1**
Station device location ${USERFUL_STATION_LOCATION} hallway**

* Customizable by administrator at installation time
** Customizable by administrator within Userful Control Center (UCC) when managing stations

Example Implementation

Web Browser

Since Web Browser URLs can utilize query-string values rather easily, it will be up to the CMS hosts to retrieve the content Userful is supplying via URL for each station. Therefore, in UCC, if a Web Browser session container type is configured as the following URL template:${USERFUL_STATION_MAC_ADDRESS}&res=${USERFUL_STATION_DISPLAY_RESOLUTION}

The exported macro will be translated into its real value by Userful when it is launched by the web browser on the zero-session:

For every station configured to this session container, a unique URL will be constructed based upon the station's attributes.

Native Linux Program

Any native Linux program that is launched by the zero-session can utilize these environment variables. If the integrator wants to launch a native program that has not been coded for these environment variables, yet supports command-line arguments that require this data, a shell script wrapper may be required.

Therefore, in Station Mapping, if a Native Client session type can be configured to run the following shell script:


This shell script can in turn customized to use the environment variables, and launch the main program:


 /usr/bin/mydigitalsignage --mac ${USERFUL_STATION_MAC_ADDRESS} \

Since environment variables are accessible from within any program launched by Userful zero-session, in lieu of a wrapper, that program may be customized to read the environment variables directly. For example, in C the following function would suffice, and even allow for a fallback to system MAC:

char* get_station_mac_address(void) {
    char* mac = getenv("USERFUL_STATION_MAC_ADDRESS");
    if (mac == NULL || strlen(mac) == 0) {
        /* Fallback to read the system MAC if the environment 
         * MAC is not supplied */
    return mac;

Future Integration Support

Userful is open to feedback from CMS and SI partners with respect to how well this document and our software fulfills the need. The following features are currently in development and we would look forward to feedback on these and other integration ideas that you might have:

Cron Job Integration

Userful can launch a customized program at a pre-configured interval. This can be used to download offline media for the Media Player, or perhaps to send reports back up to CMS-specific APIs.


For more advanced integration, Userful also includes an JSON API that lets you pull additional information and run additional commands on the system. This API enables 3rd Party System Integrators, Content Management System developers, and Web-Content developers to pull-in information as well as run commands on the system. This API can be easily called from web pages (via javascript) or via a broad range of programming languages. Preliminary draft documentation on this API is available for feedback now and a few basic functions have been implemented to enable you to test and familiarize yourself with the system.

Feedback and Activity Reports

For a client player application launched via the command-line, it is easy to have this same application periodically communicate with the server to relay usage data and reports. However in a scenario where the browser is the player it becomes more complex.