Skip to main content

User Manual

Digital Signage technical information.

Introduction

This document outlines advanced features, configuration settings and APIs for extending digital signage functionality. Please note that this document is for advanced users only. All core digital signage operations can be performed in the web-based Administration Interface.

Other pages

Hardware Compatibility

This digital signage solution is designed for the Android Operating System.

DS Loader must be installed onto the Android device to connect it to the digital signage server platform.

The MAC address of the device will be displayed on the screen when DS Loader starts. This MAC address is used to link the device to a screen in the administration interface.

Minimum system requirements:

DS Loader will load a digital signage player. There are multiple player implementations available that can be selected in the administration interface. Please note that some players require newer versions of Android. For example, the ExoPlayer variants require Android 4.1.

A device running Android 4.4 or higher is recommended for displaying HTML5 content as it uses the Chrome web browser rendering component.

Video playback uses the Android multimedia framework. For HD and 4K video playback ensure the device is capable of supporting the content you upload.

If there are problems playing video content, edit the screen in the admin interface, click the software tab and select different player software. The ExoPlayer variant may work better for modern devices especially if gapless video playback is required.

Non standard screen outputs for LED arrays smaller than the device output are supported using the advanced options widthOverride and heightOverride in Screen Data.

Conditions

Conditions allow you to control when an item is displayed using JavaScript like expressions. Data defined in the active screen, stack item, slot or sequence can be used in expressions. This data can be populated by sensors such as GPS, player extensions (such as audience analytics tools), manually set in data fields or automatically updated by 3rd party services. The stack item will only display if the expression evaluates to true.

Basic syntax

Syntax Description
==Test for equality. For example temp == 23 will only return true when the data named temp is set to 23.
!=Test for inequality. For example temp != 23 will only return true when the data named temp is not set to 23.
>Test if one value is greater than another. For example temp > 23 will only return true when the data named temp is greater than 23.
<Test if one value is less than another. For example temp < 23 will only return true when the data named temp is less than 23.
>=, <=Syntax for greater than or equal to and less than or equal to.
&&Ensures two expressions are true. For example temp < 23 && screenSize > 40 only returns true when the data named temp is less than 23 and the data named screenSize is greater than 40.
||Ensures either expression is true. For example temp < 23 || screenSize > 40 returns true when the data named temp is less than 23 or the data named screenSize is greater than 40.
(, )Control grouping and order of evaluation. For example true || (true && false) returns true but (true || true) && false returns false.

There are a variety of predefined variables and helper functions to enable powerful logic to be defined.

Date and time functions

Syntax Description
time.after("2014-02-01")true if time is after 1st Feb midnight.
time.after("2014-02-01 12:00")true if time is after 1st Feb 12pm.
time.before("2014-02-15 13:00")true if time is before 15th Feb 1pm.
time.hour() == 13true if hour is 1pm.
time.decimalHour() > 13.5true if time is after 1:30pm (decimal).
time.after("13:30")true if time is after 1:30pm (time).
time.day() == "Thursday"true if day is Thursday.
time.weekday()true if it is a weekday.
time.weekend()true if it is a weekend.
time.month() == "August"true if month is August.
time.minute() == 5true at 5 minutes past every hour.
time.second() == 59true at 59 seconds past every minute.
time.date() == 1true if it is the 1st day of the month.
time.between("14:05", "16:30")true if time is between 2:05pm and 4:40pm.
time.between("18:00", "07:00")true if time is between 6pm and 7am of the following day.
time.between("2014-01-01", "2014-01-31")true if time is between 1st Jan 12am and 31st Jan 12am.
time.between("2014-01-01 10:00", "2014-01-31 14:00")true if time is between 1st Jan 10am and 31st Jan 2pm.
time.between("19:00", "22:00", "Europe/London")Use a custom timezone. - true if time is between 7pm and 10pm in London. (player 11.11+)
time.millis()Milliseconds since the UNIX epoch (January 1, 1970 00:00:00 UTC).

The time zone used by default will be the time zone of the device.

Geolocation functions

Syntax Description
distanceMiles(51.48, -0.10) < 10true if the location of the screen is less than 10 miles from the location with latitude of 51.48 and longitude of -0.10.
distanceKilometers(51.48, -0.10) < 20true if the location of the screen is less than 20 kilometers from the location with latitude of 51.48 and longitude of -0.10.
gpsInside(lat1,lng1,lat2,lng2,lat3,lng3...) true if the location of the screen is inside the polygon defined by the list of latitude longitude pairs. Please note, this function is designed for short distances (max 100km) that do not cross the international dateline. android-player-17.1.apk+ or android-exoplayer-3.1.apk+ required.
gpsInside("lat1,lng1,lat2,lng2,lat3,lng3...") Same as above but accepts a single argument quoted String representation of many latitude longitude pairs. In addition to improving performance this function allows other defined data to be used for example gpsInside(manhattanPolygon).

These functions require gpsLatitide and gpsLongitude to be set in the data. Screens will update these values automatically. For testing in the admin interface, set a test location using the Test Data Dialog.

More functions and values

Syntax Description
random()Generates a random number between 0 and 1. For example random() < 0.5 returns true 50% of the time. Note: Generates a new random number every time it appears in a condition.
randomThis value is set to a random number between 0 and 1. Note: A single number is generated after an item displays and available in all conditions. (Player 3.8+)

Variable scope and order of precedence

Variables within the current evaluation scope can be accessed in conditions. The scope includes; current item data, current slot data, current sequence data and screen data.

Screen data will override sequence data with the same name. This can be useful when setting defaults in the sequence data that will be overridden by specific screens to provide customisation.

The order of precedence is as follows: (Highest precedence used)

  1. Active item data
  2. Active slot data
  3. Active screen data
  4. Active sequence data (top to bottom when using base sequences)

When accessing data using the JavaScript DigitalSignage.getData(name) function the main sequence (which may differ to current sequence) is also in scope. This can be useful for HTML based sequence frames.

Smart Display Pacing

When an item contains a target number of plays, smart display pacing either displays or skips the item in a given loop of the sequence. A probabilistic model is used. The logic is as follows:

Smart display pacing appends the calculated required display probability to the item condition. For example random() < 0.4 represents a 40% probability of displaying the item in a sequence loop.

Screen data

Devices can be configured by adding advanced player settings to the screen data. The following settings are available.

NameDefaultExampleDescription
showStatusIconfalsetrueShow a small status icon in the bottom right when downloading media or there are communications problems.
blackConditionfalsetime.between("18:00", "06:59")When condition is true no images or videos will be displayed and the screen output will be black. CL
standbyConditionfalseWhen condition is true the app will exit. Please note the device will not enter standby and turn off the screen until the sleep period configured in the Android OS. The app will restart after standbyPeriod and check the condition again. CL
standbyPeriod3600000The period to remain in standby. After this period the app will resume.
restartTime03:00The time the app should restart. Comma separated list supported. DS Loader version 12.3+ and Player version 10.7+ required. Ignored until app active for 1 minute to prevent restart loops. System clock and time zone must be correct.
exitTime19:00As above except app exits and does not restart.
rebootTime00:00As above except reboot command issued. Requires rooted device and support for reboot shell command.
background#000000#FFFFFFThe background colour to display behind other content. Also sets a colour for the video blanker which masks black video when starting and stopping videos.
videoBlankerPeriod250100The period in milliseconds when a video starts and stops to display the video blanker. (requires background)
internetBlobsConditiontruetime.hour() == 3When true images and videos will be downloaded from the Internet if not available on the local network. CL
intranetBlobsConditiontrueWhen true images and videos will be downloaded from other devices on the local network. CL
blobstoreInternaltrueWhen true internal storage will be used to store images and videos.
blobstoreExternaltrueWhen true external storage will be used to store images and videos when the internal storage has less than 128MB available. Please note, on modern devices external storage is a second internal partition. To use an SD card or USB mass storage device you must specify the full path using blobstoreDir.
blobstoreDir/mnt/external_sdAdditional paths suitable for storing blobs. This path will be used if internal and external locations are disabled or have less than 128MB available. It is recommended that you create a directory on the storage device and use the full path because the root may be limited to 512 files. Multiple additional paths can be specified using blobstoreDir_0, blobstoreDir_1 etc.
blobstoreMaxSizeThe maximum total size in bytes that should be used for storing blobs.
blobTransferRateMin10240 (10 KiB/s)The minimum acceptable transfer rate for downloading. If the transfer rate drops below this value the download will be terminated and retried later.
blobTransferRateMax104857600 (100 MiB/s)The maximum acceptable transfer rate for downloading. Some devices can not play HD video content at full frame rate while downloading at high speed. For these devices try reducing to 1 MiB/s (1048576).
widthOverride640The width of the desired output. (widthOverride and heightOverride required)
heightOverride480The height of the desired output. (widthOverride and heightOverride required)
xOverride100The x position of the desired top left of output. (widthOverride and heightOverride required)
yOverride100The y position of the desired top left of output. (widthOverride and heightOverride required)
collectedDataTargetA server endpoint to POST collected data such as email addresses.
webviewAllowhttps://www.example.com/*Only allow the webview to access websites matching this pattern. To add multiple, suffix with a number starting with _0. E.g. webviewAllow_0=... webviewAllow_1=.... This setting restricts main address and iframe addresses but not resources loaded by the page.
webviewReuse10The number of WebView components to cache and reuse. Speeds up rendering web pages that display more than once. Set to 0 to disable.
webviewReusePeriod600000The period in milliseconds a cached WebView should reuse content and avoid reloading the page.
maxBitmapCacheSize20000000The maximum RAM (in bytes) that will be used to cache bitmap images. Default is half memMax.
manageSystemUiVisibilitytruefalseAttempt to hide the System UI. Disable this option if touch events are ignored.
passwordpasswordAdds a password field to the exit dialog. Password typed must match this password to exit.

CL - Conditional logic supported, for example time.between("18:00", "06:59") will automatically enable the setting between 6pm and 6:59am.

Settings for Audience Analytics

NameDefaultDescription
cameraId3The ID of the camera to use. When using a device with a single camera, set this to 0.
cameraWidth640The width in pixels the camera should capture.
cameraHeight480The height in pixels the camera should capture.
cameraOrientation0Camera orientation (0: original, 1: +90 degrees, 2: -90 degrees, 3: 180 degrees)
analyticsUseClienttrueEnable Analytics reporting. (required)
analyticsServerHost188.138.26.160IP address or host name of Analytics reporting server.
analyticsServerPort20001Port of Analytics reporting server.
analyticsReconnectInterval5Period in seconds to send reporting data.
analyticsDeviceKeyThe API key required for Analytics. (automatically generated)
analyticsDeviceIdThe device ID for this screen. (automatically generated)
analyticsPreviewfalseShow Analytics processing image. (default bottom right)
analyticsPreviewXPreview position in pixels from left of screen.
analyticsPreviewYPreview position in pixels from left of screen.
analyticsPreviewWidth640Preview width in pixels.
analyticsPreviewHeight480Preview height in pixels.

Audience Analytics debugging information

NameExampleDescription
analyticsErrorSet if error detected performing audience analytics.
analyticsIsConnectedtrueIs screen connected to Analytics servers.
analyticsIsConfigOktrueIs the Analytics configuration OK.
analyticsKeyStatusOKThe status of the Analytics licence key.

Screen data sent by players

Devices will periodically send the following data to the server. This data can be used in conditions to control if an item displays. For example the condition screenWidth > 1000 would ensure the item only displays if the width of the screen is greater than 1000 pixels.

NameExampleDescription
freeSpace_0121321321The number of bytes of free space on the primary storage device.
freeSpace_11584680960The number of bytes of free space on the secondary storage device.
gpsAltitude22.299999237060547The GPS altitude of the device.
gpsBearing0.0The GPS bearing of the device.
gpsLatitude51.19537291The GPS latitude of the device.
gpsLongitude0.27393845The GPS longitude of the device.
gpsSpeed1.5206907The GPS speed of the device.
hardwaremakoThe hardware label assigned to the device.
hardwareBoardMAKOThe hardware board label assigned to the device.
hardwareBootloaderMAKOZ30dThe hardware bootloader label assigned to the device.
hardwareBrandgoogleThe hardware brand label assigned to the device.
hardwareBuildKTU84PThe hardware build label assigned to the device.
hardwareDevicemakoThe hardware device label assigned to the device.
hardwareIdKTU84PThe hardware ID assigned to the device.
hardwareManufacturerLGEThe hardware manufacturer label assigned to the device.
hardwareModelNexus 4The hardware model label assigned to the device.
hardwareProductoccamThe hardware product label assigned to the device.
hardwareSerial004efcdb18961386The hardware serial assigned to the device.
hardwareTagsrelease-keysThe hardware tags assigned to the device.
hardwareTypeuserThe hardware type label assigned to the device.
hardwareVersionCodenameRELThe hardware version codename assigned to the device.
loaderUdpPort44326The port used to communicate directly with this device using UDP.
loaderVersion2.6The version of the loader codebase connecting this device to the server.
memFree439568The number of bytes of free RAM in the active JVM the loader runs in.
memMax201326592The maximum number of bytes available to the JVM for code execution.
memTotal14163968The total number of bytes the JVM has allocated.
requiredDataAvailable355141The number of bytes available locally to play the currently active sequence.
requiredDataTotal355141The number of bytes required to play the currently active sequence.
screenDpiX319.79The number pixels per inch vertically. (often inaccurate)
screenDpiY318.745The number pixels per inch horizontally. (often inaccurate)
screenHeight1184The number of pixels on the screen vertically.
screenWidth768The number of pixels on the screen horizontally.
totalData355141The number of bytes stored on the device for sequence playback.
wifiSignalLevel90The strength of the WiFi signal.
wifiSpeed65The speed in megabits of the active WiFi connection.
wifiSsidSKY56566The SSID of the access point WiFi is connected to.
plugged2The power status. Returns a value greater than 0 if the device is plugged in to mains power. This data is useful in the standbyCondition.

Screen data added by audience analytics

NameExampleDescription
males3The number of males detected looking at the camera.
females2The number of females detected looking at the camera.
kids1The number of children detected looking at the camera.
young1The number of young adults detected looking at the camera.
adults2The number of adults detected looking at the camera.
seniors1The number of seniors detected looking at the camera.
kidMales1The number of male children detected looking at the camera.
kidFemales2The number of female children detected looking at the camera.
youngMales3The number of young males detected looking at the camera.
youngFemales4The number of young females detected looking at the camera.
adultMales5The number of adult males detected looking at the camera.
adultFemales6The number of adult females detected looking at the camera.
seniorMales7The number of senior males detected looking at the camera.
seniorFemales8The number of senior females detected looking at the camera.
emotionHappy1The number of smiling faces detected looking at the camera.
emotionNeutral2The number of neutral faces detected looking at the camera.
emotionAngry3The number of angry faces detected looking at the camera.
emotionSurprised4The number of surprised faces detected looking at the camera.

Scrolling Text

Scrolling text can be displayed on the screen. The following values are used to set and style the scrolling text and can be added as data to the screen, sequence or item.

If scrolling text is set on a screen it can be overriden by an item. For example, adding scrollingTextCondition=false to an item would hide the scrolling text while the item is displayed.

NameDefaultExampleDescription
scrollingTextMy TextSet to scroll custom text on the screen. (Android only)
scrollingTextSpeed200Scrolling text speed in pixels per second.
scrollingTextGravitybottomPosition the scrolling text should be rendered.
scrollingTextSize100Text size of the scrolling text in pixels.
scrollingTextColor#FFFFFFColor of the scrolling text.
scrollingTextBackgroundColor#000000Color of the background behind the scrolling text.
scrollingTextPadding10Padding between scrolling text and edge of screen.
scrollingTextConditiontrueWhen true and scrollingText set, the scrolling text will be displayed. CL

Digital Clock

A clock can be displayed on the screen. The following values are used to set and style the clock and can be added as data to the screen.

NameDefaultExampleDescription
timePatternHH:mm:ssPatten to define date/time formatting. Set to show time. (Android only)
timeGravitytop rightPosition the date/time should be rendered.
timeTextSize100Text size of the date/time in pixels.
timeTextColor#FFFFFFColor of the text used for drawing date/time.
timePadding10Padding between date/time and edge of screen.
timeZoneOverrideEurope/LondonTimezone used to display current time. This will override the devices configured time zone.

Audio Volume

The volume of audio playback can be controlled by setting volume to a value between 0 and 1. The volume setting can be added as data to the screen, sequence or item.

If volume is set on a screen it can be overriden by an item. For example, adding volume=0 to a video item would mute the volume when it plays.

NameExampleDescription
volume0.5Set the volume of the audio. (Android only)

Playback Synchronisation

Multiple screens can be synchronised to start playing items at the same time. The screens must be on the same LAN and configured to display the same sequence or root base sequence. When sequences share the same root base sequence, ensure items stacked above have the same duration to prevent premature sequence progression.

Synchronisation will only occur when all data has been downloaded. It may also take up to 5 minutes to accurately synchronise the local clock after the player starts.

Accuracy varies depending on the hardware, Android version and the type of images and videos displayed. To obtain good playback synchronisation it is recommended the same hardware is used. The following modes can be set to further optimise accuracy of synchronisation.

NameValueDescription
syncVideoMode0Prepare then start the next video immediately after the previous item. This results in a variable duration gap between videos.
syncVideoMode1Prepare the next video and schedule it to start 350ms after the previous item. This mode adds 350ms to the duration of each item but increases accuracy and prevents the end of videos being skipped.
syncVideoMode2Prepare the next video, schedule it to start 250ms after the previous item then pause and resume the video for up to 100ms so target start time is achieved. This trick improves start time accuracy.
syncVideoMode3Prepare the next video 350ms before the end of the previous video and start it when the previous item finishes. (Requires decoding of two videos at the same time which is not supported on some devices)
syncVideoMode4Prepare the next video 350ms before the end of the previous video, start it 100ms before the previous item finishes then pause and resume the video for up to 100ms so target start time is achieved.

The default mode is 2. Modes 3 and 4 will remove the 350ms padding between items but may cause instability because the device will be processing 2 videos at the same time for a short period. All devices must use the same sync mode, please add this setting to sequence and inner sequence data.

When using a variety of devices and Android versions, some may start earlier than others. To compensate the following values can be added to the screen data.

NameValueDescription
syncOffset0Delay the transition between items (images and videos) by this number of milliseconds.
syncVideoOffset0Delay starting videos by this number of milliseconds.

Screen Brightness

The screen brightness can be controlled by setting screenBrightness to a value between 0 and 1. The brightness setting can be added as data to the screen, sequence or item.

If brightness is set on a screen it can be overridden by an item. For example, adding screenBrightness=1 to an image would set maximum brightness when it displays.

NameExampleDescription
screenBrightness0.5Set the brightness of the screen. (Android with built in screen only)

Screen Orientation

The screen orientation can be controlled by setting orientation to one of the values below. This option will override the internal orientation sensor. Please note, some devices ignore this setting.

NameValueDescription
orientation6Set landscape orientation
orientation8Set reverse landscape orientation
orientation1Set portrait orientation
orientation9Set reverse portrait orientation

See Android Documentation for more orientation settings.

Barcodes and Near Field Communication (NFC)

Scanning Barcodes

Barcodes are automatically read when a USB barcode reader is connected (keyboard emulation). If an event is configured with a matching barcode trigger, the action will be performed.

Scanning NFC tags

NFC tags are automatically read when placed near the device. If an event is configured with a matching NFC trigger, the action will be performed.

Examples:

To display a dynamic web page for many barcodes add ~barcode in the address for the web page action. This will be replaced with the barcode. For example http://www.example.com/shopping.php?barcode=~barcode would display the web page http://www.example.com/shopping.php?barcode=123456789 if the barcode 123456789 was scanned. Use ~nfcTagText for NFC tags.

Send phone to a custom web address

A phone or tablet with NFC support can also be placed near a digital signage player to open a web browser and load a web page. To configure the destination web page address, set nfcUrl to the address of a web page. The nfcUrl setting can be added as data to the screen, sequence or item.

To complete the NFC transfer, the digital signage screen must be touched.

NameExampleDescription
nfcUrlhttp://www.example.comSend a phone or tablet near to the screen to a web address.

NFC does not function when the digital signage player runs above the Android screen lock.

Beacons

Bluetooth low energy (BLE) beacons and the physical web

Screens running Android 5.1+ and supported BLE hardware can broadcast a beacon. The beacon can be received by nearby devices to perform actions on the screen. See Physical Web

NameExampleDescription
beaconConfigblepwEnable the default BLE Physical Web implementation.
beaconConfighttp://example.comOverride the default implementation and direct user to custom address. Note: Eddystone URL Spec restricts this to 17 characters.

RS232 Communications

RS232 communications makes it possible to send and receive data between the player and an external device. Examples of external devices include: HDMI switches, TVs and alarms. Most USB to RS232 adapters using Prolific or FTDI chipsets are supported.

Examples:

RS232 Configuration

Special configuration data is required to setup the communications. The configuration must be added to screen data.

NameExampleDescription
rs232config9600,8,1,noneSet the baudrate to 9600, data bits to 8, stop bits to 1 and parity to none.

RS232 Output

To send a command to the serial device, add the command to the data of an item.

NameExampleDescription
rs232outputavi=1 When the item displays, this will send avi=1 to the serial device.

By default, ASCII data will be sent to the serial device. To send binary data to the serial device, encode to hex and add rs232outputFormat=hex to the data.

NameExampleDescription
rs232outputFormathex The output is provided as HEX and should be converted to binary before sending.
rs232outputAA11FF010112 When the item displays, this will send AA11FF010112 to the serial device.

The rs232output data will only be sent to the device when the value changes. This prevents continuously sending the same data.

To send data when the player starts. The data can be added to a variable named rs232outputAtStart in screen data.

RS232 output communications requires loader version 12.5, player version 11.2 or above and a compatible USB to RS232 adapter.

RS232 Input

The player monitors data sent from external serial devices. After a CR or LF is received, the ASCII text string is added to a screen data variable named rs232input and can be used in condition evaluation, as an event trigger or read using the JavaScript Interface on a web page.

Only ASCII data separated by CR or LF is supported. RS232 input communications requires player version 21.3 or above.

RS232 Output for Samsung Screens

A custom configuration for monitoring and controlling Samsung TVs with RS232 input is available. Add rs232config=samsung to screen data to enable. When enabled, the following values will be added to screen data.

NameExampleDescription
samsungScreenPowerStatusonScreen power status. Values: on off.
samsungScreenInputSourcehdmi1Screen input source. Values: hdmi1 hdmi2 dvi dtv display_port.
samsungScreenVolume25Screen output volume. Values: 0-100

Screen status will be checked every 10 seconds. Additional options can be added to rs232config to automatically maintain the status.

NameExampleDescription
rs232configsamsung,offKeep the samsung screen turned off.
rs232configsamsung,on,hdmi1Keep the samsung screen turned on and set to HDMI 1 input.
rs232configsamsung,vol=22Keep the samsung screen at a volume of 22.

Screen status can also be updated by sequence items. This can be useful, for example, to switch to another input based on conditions or events. Add rs232output to item data.

NameExampleDescription
rs232outputhdmi2Switch to HDMI 2 input now.
rs232outputdtv,vol=50Switch to digital TV input and set volume to 50 now.

RS232 Output for Samsung Screens requires loader version 12.5 and player version 14.1 or above.

Advanced Interaction

The following data can be used to control interactive presentations.

NameDefaultDescription
enableSwipetrueEnable swiping to navigate sequences.
enableTouchEventstrueEnable touch events to trigger actions.
showTouchAnimationstrueAnimate movement of items when swiped or touched.
showSequenceButtonsfalseDisplay left and right navigation buttons.
showSequenceBranchBackButtontrueAfter navigating to another web page, item or sequence, show an up arrow to return.

Custom App Launch

An Android app can be launched after an event trigger by providing the package name in the launch app action.

Custom intents can be launched by providing the data required for the Android Intent. Supported data includes:

NameExampleDescription
actionandroid.intent.action.VIEWThe Android action to perform.
datahttp://www.example.com/Data to provide for the action. (optional)
categoryandroid.intent.category.LAUNCHERThe category of the event. (optional)
packagecom.android.chromeThe package name for the Intent handling class. (optional)
typetext/plainContent type of the data. (optional)

Extra intent data is application specific. Data names must not contain dots. Extra intent data is automatically added prefixed with android.intent.extra.. For example, TEXT will add android.intent.extra.TEXT to the extras of the intent.

Example for launching Chrome to display web page

Custom

actionandroid.intent.action.VIEW
datahttp://www.example.com/
packagecom.android.chrome

Example for printing using QuickPrinter

Custom

actionpe.diegoveloper.printing
typetext/plain

Extras

TEXT<BIG>Text Title<BR>Testing <BIG>BIG<BR><BIG><BOLD>string <SMALL> text<BR><LEFT>Left aligned<BR><CENTER>Center aligned<BR><UNDERLINE>underline text<BR><QR>12345678<BR><CENTER>QR: 12345678<BR>Line<BR><LINE><BR>Double Line<BR><DLINE><BR><CUT>

Admin Interface Functionality

The administration interface can be configured for specific users and cloud configurations. The following data can be used to show, hide and disable functionality available to a user or cloud.

NameDefaultDescription
showServerConfigstrueDisplay the cloud config tab and list accessible cloud configs.
createServerConfigtrueAllow creation of new cloud configurations.
showGroupstrueDisplay the groups tab and list accessible groups.
createGrouptrueAllow creation of new groups.
showUserstrueDisplay the users tab and list accessible users.
createUsertrueAllow creation of new users.
showUserSettingsItemtrueDisplay the user settings item.
showLibrarytrueDisplay the library tab and list accessible library items.
createLibraryItemtrueAllow creation of new library items.
showHometrueDisplay the home tab.
showSequencestrueDisplay the sequences tab and list accessible sequences.
createSequencetrueAllow creation of new sequences.
showScreenstrueDisplay the screens tab and list accessible screens.
createScreentrueAllow creation of new screens.
showReportstrueShow the reports tab.
showSoftwareLinkstrueShow the links to download the installation software.
showUserManualLinktrueShow the link to this manual page.
showAccessControlstrueDisplay the access tab and allow user to grant access to other users and groups.
showDatatrueShow the data tab and allow the user to add and modify raw data in objects.
createCompositeItemtrueAllow the creation of items that display multiple images and videos at the same time.
addCompositeWidgetItemfalseAllow a widget to be selected and added to a composite item.
addCompositeSequenceItemtrueAllow an inner sequence to be selected and added to a composite item.
pageSize20The number of rows displayed in a table on a single page.
reportPageSize100The number of items to display on each page of a report.
maxResults5000The maximum results to fetch from the server in a single request.
showAdvancedConditiontrueDisplay the advanced condition for stack items.
editStackSettingstrueAllow the user to edit stack settings such as maximum duration and stacking above.
showFullJsonfalseDisplay the link to view the full raw JSON of a sequence.
displayItemShowBuildButtontrueDisplay button for building content using a content builder.
displayItemShowInternetButtontrueDisplay button for importing from an Internet source or displaying a web page.
displayItemShowLibraryButtontrueDisplay button for selecting an item from the library.
displayItemShowUploadButtontrueDisplay button for uploading new items.
showDownloadButtontrueShow download button to export data. (Note: does not apply to reports)
showMultipleSelectButtontrueShow the multiple selection button to perform actions on multiple items.
showSearchButtontrueShow the search button used filter items by search text, groups and columns.
editUserLabeltrueAllow the user to edit their name.
editUserLocationtrueAllow the user to edit their location.
showUserAdvancedtrueShow the advanced tab in the edit user dialog.
editSequenceLabeltrueAllow sequence label to be changed. Can also be set in sequence data (user data overrides it).
showRssPreviewOptiontrueShow option to preview the sequence or screen as an evaluated Media RSS feed.
showSequenceTestDataOptiontrueShow option to add test data to a sequence. Used for testing advanced conditions.
showExpireOptionstrueShow options to expire, reactivate and remove expired items from a sequence.
showFindSequenceOptiontrueShow find sequence option to stack items linking to an inner sequence.
showCopyOptiontrueShow copy option.
showRemoveOptiontrueShow remove option.
showEditOptiontrueShow edit option.
showAddItemOptiontrueShow add item option.
showScreenStatusReporttrueShow the option to view the live screen status report.
showScreenStatusHistoryReporttrueShow the option to view the historical screen status report.
showScreenLocationReporttrueShow the option to view the screen location report.
showSimulatortrueShow the option to simulate playback for testing.
showSequenceMappingReporttrueShow the option to view the screen mapping report.
showUserSummaryReporttrueShow the option to view the user and group summary report.
showUserActionReporttrueShow the option to view the user action report.
showDisplaySummaryReporttrueShow the option to view the display summary report.
showDisplayReporttrueShow the option to view the display report.
showMediaUploadReporttrueShow the option to view the media upload report.
showCollectedDataReporttrueShow the option to view the collected data report.
showAnalyticsReporttrueShow the option to view the analytics report.
defaultReportSearchTypescreenSets the default report search type for display report, display summary and collected data. Valid values screen sequence libraryitem screenId sequenceId itemId libraryItemId.
extendedOfflineThreshold604800000The delay (in milliseconds) a screen can be offline before it is hidden from the screens tab.
showHomeServiceStatustrueShow the service status (server, replication and reporting health) on the home tab.
showBillingStatusfalseShow the billing status - billing group applied and how many screen not in a billing group.

Additional visibility options can be added on request.

Advanced Content Types

HTML5

The platform is designed to display web pages directly from the Internet. Sometimes it is necessary to host the site locally on the device so it can work in offline mode or reduce delays loading. To achieve these goals it is possible to create a zip file containing all the HTML and resources for the site and upload it to the platform.

Zipped web page

Name the web page index.html and make all paths to images, JavaScript and CSS relative. Compress index.html and resources into a single zip file. Upload the zip file as regular item and it will be recognised as a zipped web page.

The zip will automatically be extracted onto the device and read locally by the internal web browser.

Streaming media

An item can provide a streaming media address to display live video. Examples include:

PDF, SWF, DOC, PPT etc

Using these formats is not recommended. However, if they are uploaded, 3rd party viewer extensions may be used to attempt to display them. It is best to use JPEG images and H264 encoded video for consistent output for digital signage.

Advanced content types are only supported on Android devices.

Android Screen Lock

To prevent users launching other apps or tampering with Android settings, enable the Android screen lock. DS Loader will run above the screen lock when the device is turned on.

To configure the screen lock, go to Android Settings - Security - Screen Lock

It may still be poosible to exit the player, but this will only result in the screen lock appearing. The player will automatically return to the foreground after 1 minute.

Android System UI

Many devices display system user interface controls at the bottom of the screen. For example, back, home and recent apps buttons. The player usually hides these components automatically, but it may be possible to make them reappear.

The player includes a mechanism to completely remove the System UI, but it requires ROOT privileges. There are 2 methods of gaining ROOT privileges:

  1. Signing DS Loader with the manufacturer system keys
  2. ROOTing the device

If neither of these options are possible. The System UI can be aggressively hidden by adding the following to screen data systemUiHideDelay=0.

For devices used exclusively for digital signage, we recommend removing the Android System UI (com.android.systemui) completely and setting a password in screen data.

Tip: Enable the Android Screen Lock to ensure the screen lock appears if the player exits. The player will automatically return to the foreground after 1 minute.

Android Day Dream

The digital signage player can also run as an Android Day Dream (screen saver)

To enable the day dream, go to Settings - Screen - Day Dream - DS Loader

Application Programming Interface (API)

We have 5 public APIs available for integrating with the digital signage platform and automating operations.



  1. Quick Data API - Quick modification of fields inside objects.
  2. Reporting API - Automate fetching large playback reports.
  3. RESTful API - Full modification of all system objects.
  4. Content Building API - Linking a content building service into the admin interface.
  5. Remote Trigger API - To remotely trigger screens to perform actions.

Authentication

All API requests must include a valid session ID in a cookie or an authentication header matching the credentials of a user using basic HTTP authentication.

The session ID cookie will be automatically used if you have signed into the admin interface and are using the same web browser to make API requests.

RESTful Object API

Please refer to our documentation at swaggerhub. This development resource makes it easy to test and understand RESTful operations:

TargetR Stacks REST API at SwaggerHub

Generic Object Structure

All objects follow a common structure.

{
    "id": "ABCEF1234567",
    "type": "object-type",
    "data": {
        "label": "My label",
        "version": "23",
        "createdMillis": "1404910684273",
        "modifiedMillis": "1412943312770",
    },
}

The id field is used to uniquely store and reference an object of a specific type. The data field references an inner object containing a map of name value pairs. Anything can be stored in this map and used in condition evaluation and for other purposes. All values in the data must be text strings, however, they will be dynamically cast to numbers and boolean values when condition evaluation is performed.

The data contains a label, a version number, created and modified dates in milliseconds since the epoc. Additional fields will vary depending on the object type. The quickest way to learn the additional fields and object structure is to click the "REST API" button in the data tab of objects within the admin interface.

RESTful Endpoints:

Updates can only be performed on the items the authenticated user has access to. To control access to items, access controls are used and can be updated using the following endpoints:

New objects can be created by a POST or PUT without including an ID for the new object. New objects will automatically create a new access control allowing the authenticated user to access it.

Access Controls are used to assign items to a Group. Each access control references the group and an item in the group. All users with access to the group have access to items in the group.

Searching by group

To search for members of a group, the group name or group ID can be added to the list request.

For example, /rest-api/v1/libraryitems?groupName=mycustomgroup will return library items in the group named mycustomgroup.

This operation avoids querying access controls to find items in a group and then fetching the items individually.

Applying user visibility

A masquerade parameter can be used to list objects a specific user is able to access. For example ?masquerade=[USER-ID]. Please note, the active user (as defined by the authenticated API credentials) must have permissions to access the specific user to perform masquerading.

Filtering by predicate

To filter results from a list request a filter parameter can be used. The filter is a predicate that is applied to data in each object. For example:

Please URL encode the value of the filter to encapsulate any special characters.

Example Java Code

The following examples require json_simple-1.1.jar on the classpath. This library is used to help construct the JSON for the server communications.

Users, Groups and Access Controls

This example demonstrates how to create users and groups and apply access controls.

Library items, Sequences and media uploads.

List responses can be filtered by group by adding the query parameter groupId or groupName referencing a group to return.

Quick Data API

The Quick Data API can be used for making changes to data in objects without the complexity of managing JSON objects. The purpose of this API is to automate adding data that is used in stack item evaluation.

Data can be sent as a URL encoded form post or as query parameters in the URL. For example:

/api/screen-data/ABCEF1234567?temp=23&wet=true
Set the data named temp to the value 23 and the data named wet to the value true in the screen with the ID ABCEF1234567.
/api/sequence-data/1234567ABCEF?offer=1
Set the data named offer to the value 1 in the sequence with the ID 1234567ABCEF.

The Quick Data API can also be used to make data changes that are not part of stack item evaluation. For example quickly changing the sequence being displayed or updating scrolling text on a screen. Changes take effect instantly.

/api/screen-data/ABCEF1234567?sequenceId=1234567ABCDEF
Display the sequence with ID 1234567ABCDEF on the screen with the ID ABCEF1234567.
/api/screen-data/ABCEF1234567?scrollingText=HelloWorld!
Display the scrolling text HelloWorld! on the screen with the ID ABCEF1234567.
/api/user-data/1A2B3C4D5E6F7?label=Joe%20Blogs
Set the data named label to the value Joe Bloggs in the user with the ID 1A2B3C4D5E6F7.

To remove data from an object, provide the name and equals with no value.

/api/screen-data/ABCEF1234567?scrollingText=
Remove the data named scrollingText from the screen with the ID ABCEF1234567.

To modify data in a group of screens in a single request.

/api/group-screen-data/london.screens?overrideTimeZone=Europe/London
Overrides the time zone of all screens in the group named london.screens with overrideTimeZone=Europe/London.

The group-screen-data endpoint is for updating data for multiple screens and does not return data. The response body will be OK if successful.

Example Java Code

Simple examples demonstrating the quick data API.

Reporting API

The reporting API is used to stream large reports and collected data for further analysis.

Click the download button in the interface to download a report. Reports can be extremely large and the total size of the report is not known because it streamed directly out of the database.

To download a report via API use the following endpoints:

Display Report

/api/display-report/full.csv
This will download the report of items displayed in the last 24 hours. Reporting must be enabled for each item individually to appear in the report.

Custom date ranges can be specified using startMillis and endMillis parameters. (Milliseconds since the epoc)

/api/display-report/full.csv?startMillis=1388534400000
This will download a report containing all items displayed since January 2014.

A report for a specific screen, sequence, stack item or library item can be downloaded by setting type and id parameters.

/api/display-report/full.csv?startMillis=1388534400000&type=screen&id=1234567ABCDEF
This will download a report containing all items displayed on the screen with ID/MAC 1234567ABCDEF since January 2014.

Set type to screen, sequence, item or libraryitem as required.

Display Summary

/api/display-summary/full.csv?aggregation=item
This will download the display counts for items displayed in the last 24 hours grouped by item.

Set aggregation to item, screen or item_and_screen as required.

Collected Data Report

/api/collected-data-report/full.csv
This will download the report of collected data in the last 24 hours. The collect data event must be set for each item individually and data must be entered by the user to appear in the report.

The fields in the CSV can be selected by including a parameter named fields populated with a comma separated list of field names.

Custom data can be fetched from referenced library items, sequences and screens by prefixing the name with libraryItem. sequence. or screen..

For example, to include itemId, screenId and the custom field myCustomField stored in the screen data, the following parameter can be added to the request: ?fields=itemId,screenId,screen.myCustomField

Remote Trigger API

A remote API call can be made to trigger a pre-configured event on a specific screen or group of screens. The trigger can be used to interrupt current playback and display another item or sequence of items. It is also possible to remotely trigger JavaScript within an active web page. This makes it possible to remotely control interactive web pages. Using the ds-loader layer 1 communications (UDP), triggers are typically delivered in under 200ms.

The remote trigger API call is of the following format: /api/screen-trigger/SCREEN-MAC?name=DATA where SCREEN-MAC is the MAC address of the screen and DATA is the data that matches the configured trigger event or provides additional data to a JavaScript function in an active web page.

To listen for triggers in an interactive web page it is necessary to have configured a function with the following name: DigitalSignageTriggerCallback. This function will be called when the remote API call is made.

Additional JavaScript functions are available to help with building web pages controlled remotely.

NameDescription
function DigitalSignageStartCallback(){}Called when the web page starts being displayed.
function DigitalSignageTriggerCallback(data){}Called when the remote trigger API is used. The data will be the data provided to the remote trigger API.
function DigitalSignageEndCallback(){}Called when the web page ends being displayed (after configured duration).
DigitalSignage.setResumeDelay(30000)Delays sequence progression by 30 seconds. This is useful if you know a user is still interacting and do not want to interrupt them.
DigitalSignage.getScreenId()Returns the screen ID (MAC address) of the screen displaying the web page.
DigitalSignage.getData(name)Gets data value of the specified name stored in the screen, active item, stack or sequence data.
DigitalSignage.getScreenData(name)Gets data value of the specified name stored in the screen data.
DigitalSignage.putScreenData(name, value)Puts data value in to the screen data.
DigitalSignage.getOffsetPlaybackData(offset, name)Gets data value from previous (offset=-1) or next (offset=1) positions in main sequence. This can be used to populate HTML sequence frames to display what is on next for example. When offset positive, this function simulates progressing to future items. It will only return items that have a condition that evaluates to true and is fully downloaded.
DigitalSignage.getPlayerTime()Returns the internal player time in milliseconds since epoch. This time is updated based on server time and is typically more accurate than the system clock (especially if NTP is blocked or disabled).

A simple example is available here.

Remote Data Source

Players can periodically connect to a web server and fetch a JSON object. The data in the JSON object will be used when evaluating conditions.

NameExampleDescription
remoteDataSourcehttp://api.example.com/jsonEndpoint to get JSON object from.
remoteDataFetchPeriod10000The period in milliseconds between downloads.

For example, a web server on a train could be configured to return the next station and arrival time:

{
    "nextStation": "London Bridge",
    "eta": 4
}

A condition (in a stack item or event trigger) could use this data to display an item, another sequence or trigger a custom action:

nextStation == "London Bridge" && eta < 5

Local Web Server

A web server is built in to the player. This web server can be accessed using a web browser on your local network.

The local web server provides 3 useful functions:

The internal web server is not started by default. To enable the internal web server, add the following into screen data.

This starts the web server listening on port 9090. The following addresses will then become available:

The local-ip-address can be found in the localAddress field within screen data.

The internal web server is only available in android-player-21.0.apk and later.

Blobstore and Blob Sharing

All images, videos and other resources are named based on their raw data. The Blob naming convention provides efficient storage, avoids data duplication, provides the ability to verify data and safely share the data between local devices with strong consistency.

A Blob name is the MD5 of the binary data followed by a dash then the length in bytes.

For example: 962B5B1AF8C3B868D87979E92D8BFCE7-164197

A Blob can be cached forever because a Blob with a given name never changes.

Dynamic content uses snapshots. A snapshot is the dynamically generated Blob at a specific point in time. Snapshots are updated after they are used in a lazy fashion.

Blobstores can be shared with multiple servers and served using a content delivery network (CDN).

For example: http://d3psb5pjgez07s.cloudfront.net/962B5B1AF8C3B868D87979E92D8BFCE7-164197

Additional Custom Blobstores

To supplement the global blobstores, additional blobstores can be specified in a cloud config. This makes it possible for a digital signage network to use their own infrastructure for storing and distributing images and videos.

When configured, all new data uploaded will be transferred to one or more additional servers. Players will download using HTTP from the configured endpoints.

The cloud config must use a fully qualified domain name and players must be configured with a matching serverAddress for the custom blobstore to be used.

Uploading to custom S3 bucket

blobstoreConfigs3,[AMAZON-ACCESS-KEY],[AMAZON-SECRET-KEY],[BUCKET-NAME],[BUCKET-REGION]
blobstoreHttpEndpointhttp://s3.amazonaws.com/[BUCKET-NAME]/
blobstoreHttpsEndpointhttps://s3.amazonaws.com/[BUCKET-NAME]/

Uploading to custom Google Cloud Storage bucket

blobstoreConfiggcs,[GOOGLE-SERVICE-ACCOUNT-JSON-KEY-FILE-PATH],[BUCKET-NAME]
blobstoreHttpEndpointhttp://storage.googleapis.com/[BUCKET-NAME]/
blobstoreHttpsEndpointhttps://storage.googleapis.com/[BUCKET-NAME]/

Note, JSON Key file must be added to our servers manually.

Uploading to custom blobstore

blobstoreConfigblobstore://[SERVER-DOMAIN-NAME]
blobstoreHttpEndpointhttp://www.mycustomserver.com/
blobstoreHttpsEndpointhttps://www.mycustomserver.com/

Uploading to custom server using FTP

blobstoreConfigftp://[USERNAME]:[PASSWORD]@[SERVER-DOMAIN-NAME]/blobstore/
blobstoreHttpEndpointhttp://www.mycustomserver.com/blobstore/
blobstoreHttpsEndpointhttps://www.mycustomserver.com/blobstore/

Uploading to custom server using SCP

blobstoreConfigscp://[USERNAME]:[PASSWORD]@[SERVER-DOMAIN-NAME]/blobstore/
blobstoreHttpEndpointhttp://www.mycustomserver.com/blobstore/
blobstoreHttpsEndpointhttps://www.mycustomserver.com/blobstore/

After adding a new blobstore configuration, test it by uploading content.

Multiple blobstores can be specified by using numbered name suffixes. For example blobstoreConfig_0=..., blobstoreConfig_1=..., blobstoreConfig_3=.... The blobstores must share the same HTTP endpoints (Round Robin DNS).

A newly configured blobstore can be primed using the /blobstore-sync tool. This tool requires a user ID. All blobs accessible to the user will be transferred.

Please contact us before attempting to add a custom blobstore.

Custom Update Packages

DS Loader version 15+ provides functionality to download, extract and execute a custom update package. Update packages can be used to install custom APKs and change settings using Linux shell commands.

A custom update package is a ZIP archive containing a shell script named update.sh and any additional files needed by the shell script to perform the update.

When the custom update command is sent to DS Loader with a URL to the custom update package, the following actions will be performed:

  1. ZIP file downloaded from URL.
  2. Update directory created.
  3. ZIP file extracted to update directory.
  4. Shell session started in update directory.
  5. Shell commands in file update.sh executed.
  6. Update directory and contents deleted.

Please note, the Android permissions remain in effect. To perform system operations, the device must be rooted.

Example custom update package - Installs a useful file manager

Custom Players

DS Loader provides a platform for loading software. Usually this will be a digital signage player but can potentially be anything.

Custom players for the Android platform must implement the following methods:

The Context is an Activity or a DreamService. The custom player must call setContentView(View v) in the Context to draw to the screen.

The method setLoaderData()<String, String> data) receives data and commands from the loader e.g. URL to download sequence data etc.

The loader control communications is designed to instigate secondary communications mechanisms such as JSON data transfer over HTTP. The virtual persistent UDP connection enables the server to instantly send messages to DS Loader and (indirectly) to player software at any time.

To add additional software to the list of players in the interface the following data must be added to a cloud config

player_android_0=custom-player-0.3.jar,com.example.player.CustomPlayer
This will add a new item to the player list named custom-player-0.3. When selected, the server will instruct DS Loader to download custom-player-0.3.jar and call start() in the class with the name com.example.player.CustomPlayer.

Contact your digitial signage provider for information about adding custom players. Custom players must be added to the server platform and be digitally signed before DS Loader will execute their custom code.

Internationalisation

The administration interface has support for multiple languages. A Locale can be added to the path to switch between languages. For example: /zh/.

A default locale can also be applied to cloud config data. For example localeOverride=zh.

Contact your digitial signage provider for information about adding support for new languages.

Security

Administration Interface

All user accounts are protected by an email address and password. Traffic between the web browser and user interface is encrypted using the latest encryption standards (when SSL Certificate installed).

All passwords are scrambled before storage using bcrypt hashing.

Live traffic analysis is performed to prevent brute force attacks. All actions, including failed password attempts, are stored in an audit log that can not be deleted.

A password policy can be defined in a cloud config to restrict passwords that can be used.

Devices

There are two layers of security between devices and servers. All data on the first layer (loader comms) is digitally signed by a private key on secure servers. Devices verify the data using a public key before to invoking second layer communications (player comms). The second layer uses digital signatures in additional to an optional TLS connection.

DS Loader will only execute new player applications that are digitally signed with the correct key.

We have the ability to transition to new keys in the event of a private key security breach.

Cloud Service

The digital signage service is distributed across servers in America, Europe and Asia using different cloud providers. Traffic is routed to the closest available server using latency based routing with health checks. Asynchronous replication with eventual consistency provides low latency connections, scalability and resilience worldwide. Multimedia is stored and delivered from Amazon S3 and Google Cloud Storage. Additional storage and CDNs can be configured.


Please contact your digital signage administrator before connecting 250 or more screens.

Device Communications

Automatic Network Setup

No inbound ports need to be opened in your firewall. For security, inbound connections can be blocked.

Ensure that devices can make outbound connections to the Internet. Devices will connect to one of our active servers and use multiple CDNs for media data transfer. We can not provide a white list because all IPs are subject to change because we use a variety of cloud infrastructure.

Ports used for server communications (WAN)

TypeDestination PortNotes
Loader CommunicationsHTTP (TCP 80)(required)
UDP 9091For instant updates. (optional, recommended)
Player CommunicationsHTTP (TCP 80)(required)
HTTPS (TCP 443)For extra security. (optional)

Please be aware that Android devices also require NTP (UDP 123) to set their system clock.

Ports used for local communications (LAN)

TypeDestination PortNotes
Peer to Peer Blob Sharing (data requests)Broadcast UDP 9097(optional, recommended, v11+)
Peer to Peer Blob Sharing (data transfer)TCP ephemeral port(optional)
Playback SynchronisationBroadcast UDP 9096(optional)
Local data and triggersBroadcast UDP 9098(optional, v18.5+)

Daily Bandwidth Estimate

The following estimates are based on loader comms every 30 seconds and player comms every 1 minute with infrequent updates over a full 24 hour period. Transfer of multimedia must be added to estimations. Blob data is only transferred once and cached locally.

TypeDirectionCalculationTotal
Loader CommunicationsDevice to Server100 bytes x 2 x 60 x 24281 KB
Loader CommunicationsServer to Device100 bytes x 2 x 60 x 24281 KB
Player CommunicationsDevice to Server2 KB x 60 x 242880 KB
Player CommunicationsServer to Device10 KB x 24720 KB
Total< 5MB (per device per day)

Local network blob sharing is used when devices display the same content. This eliminates duplicate Internet downloads.