Introduction

Stacks is an advanced digital signage platform for building dynamic sequences of multimedia.

Multiple display candidates are stacked vertically and dynamically chosen by evaluating user defined conditions. Conditions can incorporate date and time, geographic location and custom data.

Administration of large numbers of sequences is simplified by creating shared base sequences. This allows a user to be granted the ability to only modify a subset of items displayed on a screen. By using the stacking concept and powerful multi-user access controls, complicated dynamic sequences can be constructed for showing worldwide, national, regional and local advertising on an unlimited number of screens.

New Features

Enhanced stacking logic

Control when items display using custom conditions and dynamic data. It is now possible to write conditions to specifically target an audience. For example, show an advert for a womens coat when more women than men are looking at the screen, the temperature is below 15 degrees and its a Saturday.

Base sequences

Sequence stacking allows collaborative control of a common base sequence. Control which slots in a base sequence can be overridden by another user. Build complex stacked sequences merging international, national, regional, local and screen specific content. Each layer controlled by different users.

Inner sequences

Slots can contain inner sequences controlled by another user. Grant a user access to a specific slot in a sequence. Ideal for advertisers.

Composite items

Multiple images and videos can be positioned and displayed at the same time.

Access control lists

Grant one or more users or groups access to specific screens, sequences, library items or other users and groups.

Immediate data updates

DS Loader maintains an open UDP port which means changes can be sent to devices instantly.

Immediate software updates

New player software and custom player implementations can be sent instantly to DS Loader. (A rooted device is no longer required).

Playback synchronisation

Multiple screens on the local network can be synchronised to play slots at the same time. Video walls can be configured using shared base sequences for timing.

Data sharing

Players download images and videos from players on the local network when available (peer 2 peer).

Data integrity checking

All data is digitally signed and verified to prevent corruption and man in the middle attacks.

HD and 4K support

1080p HD video and ultra high definition 4K video capability (on supported devices).

Offline operation

All conditional logic is evaluated locally on the device. This means schedules and geolocation data evaluation does not require an Internet connection. Multimedia is also stored locally for perfect playback with no buffering delays.

Display reports

A record can be created for every item that is displayed on a screen. Each device automatically synchronises records with the server when a connection is available.

Advanced interactivity

As well as supporting HTML5 interactive content, custom events can be defined to trigger actions such as playing another sequence or collecting an email address.

HTML5 widgets

HTML5 widgets can be added to display rich, dynamic content to screens.

QRCodes, Barcodes, Beacons and NFC

Integration to various technologies to refer customers to more information.

RS-232 output

Control HDMI switches and other devices using USB to RS-232 adapters.

GPS tracking

Moving screens can be tracked and GPS data included on display reports. Ideal for screens on taxis.

E-mail integration

Media can be e-mailed directly to a sequence.

Worldwide scalability

Servers in Europe, America and Asia use asynchronous replication with eventual consistency to provide low latency connections, scalability and resilience worldwide.

Security

Secure connections using the latest encryption standards.

Admin Interface

The admin interface is used to manage multimedia, sequences, screens, users, groups and cloud configurations. The functionality available to a user is configurable.

Click the sign in with password button to sign in to the administration interface.

Sign In

An email address and password is required to sign in to the admin interface.

If you do not know your email address or password you must contact your digital signage manager or reseller.

Sequences

Click the new sequence button to create a new sequence.

Sequence Dialog

The general tab allows a label, type and defaults to be specified for the sequence.

The populated by media RSS feed option periodically synchronises items from a media RSS source. This is typically used to pull live news items from sources such as BlueFox or ScreenFeed.

The populated by e-mail option enables the platform to receive media e-mailed to a special address and adds the media to the sequence.

Default values are applied when adding new items to the sequence.

The advanced tab is used to configure advanced sequence settings. A base sequence can provide default items and restrictions for the sequence. An administrator may require a specific base to be used to control how your digital signage device operates.

Transition animations can be configured to provide visually pleasing movement between items in a sequence.

Multiple devices playing the same sequence can be synchronised. See Playback Synchronisation for more information.

The frame tab allows the items in the sequence to be framed. A frame may position or scale the main content and provide additional information to the sides. A frame can also be used to overlay branding above the main content.

The events tab allows triggers to be defined that perform actions and interrupt regular playback.

The access tab is used to grant additional users and user groups to access the sequence.

The data tab is used to add custom data to the sequence. The data may be used in condition evaluation or to store any additional information required.

(It is common for a sequence to be automatically created and to have a specific base sequence configured by an Administrator when you first sign in. Click edit to modify this sequence)

Slot Dialog

Click the stack heading to view options for configuring how the stack operates.

When the sequence is used as a base, stacking above can be disabled. This prevents the upper sequence from overriding items in this sequence stack or lower. Effectively, this guarantees items are displayed and can not be replaced by the upper sequence.

The maximum duration limits the duration of items in the stack. If an item exceeds the duration, it will not be displayed. If the item refers to another sequence, the sequence will only show enough items to consume the duration. It will auto-progress next time the sequence displays.

Stack Item Dialog

Click the add button in a slot to add a new item to a sequence. The item editor will be displayed.

The general tab allows a Label to be specified for the item. The label is useful for reporting and indexing purposes. The Duration option controls how long an image or web page displays before progressing to the next item. If a video is uploaded and this field is not modified, it will be populated by the length of the video.

The display tab is where the multimedia to be displayed is defined. There are 3 display types:

• Single item - Display a single item consuming the full area of the sequence.
• Inner sequence - Display multiple items one after another from another sequence.
• Multiple items at the same time - Position and display multiple items and sequences on the screen at once.

Display a single Item

The Library button allows an item from the library to be selected to display in the sequence. The library functionality is not enabled for all users.

The Upload button allows a local file to be selected for upload. A new item will be added to the list below and will read "Pending". When the "Save" button is pressed the file will be uploaded and associated with the item. Multiple images and videos can be added with different resolutions. The player will select the best batch for the screen.

The Internet button shows a text field that can be used to specify the address of a Web page, Image or video. There are 4 types supported.

• A web page - A web page (HTML) to be displayed by the web browser on the device.
• Static media - An image or video on a server to be downloaded once and displayed.
• Dynamic media - An image or video on an external server to be periodically checked for updates and displayed.
• Custom - This option is reserved for advanced purposes such as mapping local HDMI or RTSP streams internally.

Make sure you press Add to add the new address to the list of resources.

The Build button presents a list of tools for building content. Examples include Weather and Text RSS feeds. This list is dynamic, expect more options soon.

Display multiple items at the same time.

Use the library and sequence buttons to add items. Drag to position and resize them. Click numbered buttons to edit and remove each item.

Items can overlap. The numbers represent order of drawing to the screen. To raise an item to the top, click the center icon.

Display an inner sequence

Select the sequence to display. Remember the inner sequence will only display for the duration configured by the item. If the inner sequence is longer it will automatically progress by one item each cycle of the outer sequence.

The condition tab is used to control when this item is displayed. The Start Date and End Date fields allow a specific date range to be quickly specified. The text area provides the ability to write JavaScript like expressions using data in the system. Buttons provide helper tools for writing advanced conditions.

More about advanced conditions

The advanced tab provides custom transition options and reporting options for collection of playback data. The playback data is useful for proof of play providing a complete report of what displays on each screen.

The events tab is used to define what happens when the screen is touched, a key is pressed or a condition is true.

An event consists of two parts; a trigger and an action. When the trigger occurs, the action is performed. Actions include displaying a web page, playing another sequence, collecting data (such as an email address) or adding advanced data.

A trigger can occur at any time while the item is displaying and the action will interrupt the playback of the active item.

The data tab is used to add custom data to the item. The data may be used in condition evaluation or to store any additional information required.

Test Data Dialog

The test data dialog allows you to set data to be used when evaluating advanced conditions. For example the time, gpsLatitude and gpsLongitude can be set to test whether the item will display at a particular time or GPS location. This is also useful for testing expressions using custom data.

Screens

Click the new screen button to create a new screen.

Screen Dialog

When adding a new screen, the general tab displays software download links. When the software is installed on a device, a MAC address will be displayed. This MAC address must be entered into the MAC address field in the interface to associate the device with the screen entry in the admin interface.

A meaningful label can be assigned to the screen to help find it in the future.

The display tab is used to control what is displayed on the screen. The drop down list will contain all the sequences you have created. Select a sequence to start playback on the screen. When instant updates are available the next and previous control buttons will become available. Pressing these buttons will instantly change the item displayed on screen making it possible to remotely control the sequence.

For sequence playback, a player must be selected under the player tab.

The software tab controls the player software used to display the sequence on the screen. Custom player implementations are available to provide advanced functionality such as using cameras for audience analytics and additional data collection.

Commands can be sent to a device to perform maintenance and debugging:

The location tab displays the current geographic location of the screen. If the device has GPS support, the location will be automatically updated. If no GPS device is available, the IP address will give a rough location. A location can also be manually specified.

The access tab is used to grant additional users and user groups to access the screen.

The data tab is used to add custom data to the screen. The data may be used in condition evaluation or controlling advanced player settings.

More about screen data

Users

Access to the platform requires an email address and a password. These credentials and other user related data is defined in a user item.

Administration interface features can be selectively shown and hidden to reduce complexity and simplify tasks. For example, a user may only be responsible for adding content to a sequence and only have the sequences tab visible. Another user may manage the screens and only need to screens tab visible.

Each user only sees the items they create unless they are granted access to other items. All items (including users) can be shared with other users using the access tab when editing items.

It is recommended that specific users are created to control API operations.

Click the new user button to create a new user.

User Dialog

The general tab allows a name, email and password to be specified. The email must be unique and is used when granting group access to objects in the system.

The location tab allows an address to be specified for the user. The search box allows an address to be found using google maps. An address can also specified by dragging the red marker or manually typing the address fields.

The advanced tab allows features to be enabled and a base sequence to be set. These options can only be enabled by another user with the features enabled already. The base sequence option restricts the sequences that can be displayed on the screen.

The auto setup tab speeds up the process of configuring the end user by automatically creating a sequence and screen for the end user.

The access tab is used to grant additional users and user groups to access to this user. If another user has access to a user they will be able to masquerade as the user and see all item that user has access to.

The data tab is used to add custom data to the user.

Groups

A group is useful for granting one or more users access to many items in a single operation. For example, newly registered users can be automatically added to a group. A special user can be given access to the group and act as an administrator for all the users.

Groups can be used for sharing items. For example, multiple library items can be added to a group then access to the group can be given to multiple users to form a shared library. Screens and sequences can also be grouped and managed by multiple users.

Click the new group button to create a new group.

Group Dialog

The general tab allows a label and a name to be defined for a group. The name must be unique and is used when granting group access to objects in the system.

The members tab lists all items assigned to a group. Everything in this list will be accessible to the users on the access tab.

The access tab is used to grant additional users and user groups to access to all the members in this group.

The data tab is used to add custom data to the group.

Library

The library makes it easy to reuse images and videos. An item can be uploaded into the library once and added to many sequences quickly and easily. Each item in the library can be shared with multiple users or groups of users and can act a template supporting modifications such as adding custom text.

Click the new item button to create a new item for the library.

Library Dialog

The library dialog provides a similar set of options to the stack item dialog. Please refer to the stack item dialog section.

Cloud Configuration

The domain name and path used to access the digital signage platform selects a cloud config. The cloud config controls branding, customisations and advanced settings. For example, the domain demo.example.com may allow anonymous registrations and assign users to the user group demo which has a sequence with restrictions imposed by a shared base sequence. The welcome logo, color scheme and favicon may all be customised and different default player applications, languages and timezones configured.

Branding Tools

The following web sites can be used for creating compatible bootstrap 3 theme CSS.

• Favicon.css - Favicon generator
• Bootswatch - Free themes for Bootstrap
• Bootstrap Magic - Theme creator

OAuth2 Configuration

Sign in can delegate authentication to Google, Microsoft and Yahoo! OAuth2 providers. To enable, a client ID and client secret must be configured for each.

• Google API Manager Credentials - Setup OAuth2 for Google sign in.
• Microsoft Application Registration Portal - Setup OAuth2 for Microsoft sign in.
• Yahoo! My Apps - Setup OAuth2 for Yahoo! sign in.

Reports

Reports provide access to data collected by the platform. This data includes user actions, proof of play and other collected data. Reports can be displayed in the administration interface or downloaded as a CSV for viewing in a spreadsheet application.

User Actions

All actions performed in the administration interface create user action records. The records form a comprehensive audit trail listing the changes made to screens, sequences, users and other items. It also includes failed sign in attempts and other important information. A user action record contains the following data:

• Action time
• User
• Action description
• Object type
• Snapshot

The snapshot makes it possible revert to earlier revisions of an object. It also makes it possible to restore deleted objects. To revert changes or restore a deleted object. Edit the record and click save.

User Summary

A summary of users and groups including counts of accessible items and storage used. This report is built using the configured access controls and will show duplicates where items are shared between users and groups.

Display Reports

To collect data for display reports an item in a sequence must have the collect playback data option enabled. When the item is displayed on a screen a display report record is created. A display report record contains the following data:

• Display time
• Item
• Sequence
• Screen

An item in a sequence can be assigned a custom ID. This will be included in the CSV file.

Collected Data

The platform provides the ability to collect additional data. For example, an event can be created that allows a viewer to touch an advert and register interest for a product. Data collected can include email addresses, phone numbers or other text data. A collected data record contains the following data:

• Collection time
• Item
• Sequence
• Screen
• Data collected

When a user is allowed to interact with a web page, each new web address visited will also be added to the collected data. Scanned barcodes and NFC tags will also be added to the collected data. Adding the option collectGps=true into the screen data will also instruct the player to collect GPS location. The location will be collected after 100 meters of movement at up to once per minute.

Advanced Conditions

Advanced 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

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

Date and time functions

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

Geolocation functions

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

Overriding data

The following order is used to collate data:

1. Active sequence data (base to top)
2. Active screen data
3. Active item data

This means that screen data will override sequence data with the same name. It can be useful setting defaults in the sequence data that will be overriden by specific screens to provide customisation when conditions are evaluated.

Screen data

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

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

Audience Analytics debugging information

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.

Screen data added by audience analytics

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.

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.

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.

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.

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.

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.

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.

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:

• Display an image, video or sequence when a specific barcode or NFC tag is scanned.
• Display a web page from by a 3rd party service related to the scanned barcode or NFC tag.
• Automatically add data to the screen to control volume, standby, brightness or advanced stack item conditions with custom barcodes and 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.

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

RS-232 Output

RS-232 output makes it possible to send commands to many HDMI switches and TVs that support serial communications. Most USB to RS-232 adapters using Prolific or FTDI chipsets are supported.

Examples:

• When a specific item is displayed, or condition is true an HDMI switch can change the input to display alternative video source.
• A TV could be turned on or off or the volume updated.

RS-232 Configuration

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

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

To send binary data to the serial device, encode to hex and add rs232outputFormat=hex to the data.

RS-232 communications requires loader version 12.5 and player version 11.2 or above.

The player does not send repeated data, this prevents triggers repeatedly sending the same action when conditions are true.

RS-232 Output for Samsung Screens

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

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

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.

RS-232 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.

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:

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

Example for printing using QuickPrinter

Custom

Extras

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.

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:

• rtsp:// - Video streamed via RTSP from another device e.g. rtsp://192.168.0.2/live-video.rtsp
• camera:// - Local camera e.g. camera://0 or camera://1
• hdmi:// - Local HDMI input e.g. hdmi://localhost?port=1
• hdmi://zidoo - Special HDMI input from Zidoo device
• http:// - Remote video streamed from the Internet via HTTP e.g. http://www.example.com/remote-video.mp4 - Not recommended. Non-live video should be imported into our content management system to benefit from our CDN, P2P, caches and offline playback.

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.

Android Device Support

DS Loader will work on almost all Android devices. Minimum requirements:

• Android 2.1
• Single core 700MHz
• 256MB RAM
• Screen resolution 240x240
• 20MB available storage + sequence size (listed in sequence header)

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

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.

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.

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. Remote Trigger API - To remotely trigger screens to perform actions.
3. Reporting API - Automate fetching large playback reports.
4. RESTful API - Full modification of all system objects.
5. Content Building API - Linking a content building service into the admin interface.

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:

• /rest-api/v1/screens - GET list of screens.
• /rest-api/v1/screens/[SCREEN-ID] - GET, PUT and DELETE a specific screen.
• /rest-api/v1/sequences - GET list of sequences.
• /rest-api/v1/sequences/[SEQUENCE-ID] - GET, PUT and DELETE a specific sequence.
• /rest-api/v1/libraryitems - GET list of library items.
• /rest-api/v1/libraryitems/[LIBRARY-ITEM-ID] - GET, PUT and DELETE a specific library item.
• /rest-api/v1/users - GET list of users.
• /rest-api/v1/users/[USER-ID] - GET, PUT and DELETE a specific user.
• /rest-api/v1/groups - GET list of groups.
• /rest-api/v1/groups/[GROUP-ID] - GET, PUT and DELETE a specific group.
• /rest-api/v1/serverconfigs - GET list of server configs. (Also known as cloud configs).
• /rest-api/v1/serverconfigs/[SERVER-CONFIG-ID] - GET, PUT and DELETE a specific server config.

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:

• /rest-api/v1/accesscontrol - GET list of access controls.
• /rest-api/v1/accesscontrol/[ACTOR-ID]/[OBJECT-TYPE]/[OBJECT-ID] - DELETE an access control.

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.

• ?groupName=[GROUP-NAME]
• ?groupId=[GROUP-ID]

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:

• ?filter=modifiedMillis>=1533901286294
• ?filter=label=="test"
• ?filter=mycustomkey=="mycustomvalue"
• ?filter=androidSdk>20&&screenSize<55

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.

• UserManagementExample.java [Output]

Library items, Sequences and media uploads.

• LibraryItemUploadExample.java [Output]
• SequenceItemUploadExample.java [Output]

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:

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.

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

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

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.

• QuickDataApiExample.java

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.

A simple example is available here.

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

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

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

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

Display Summary

Set aggregation to item, screen or item_and_screen as required.

Collected Data Report

The fields contained in the reports can be selected using a parameter named fields containing a comma separated list of field names.

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.

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

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.blobstore.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.

Uploading to custom S3 bucket

Uploading to custom Google Cloud Storage bucket

Uploading to custom blobstore

Uploading to custom server using FTP

Uploading to custom server using SCP

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.

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:

• void start(Context context)
• void setLoaderData(Map<String, String> data)

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

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.

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)

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

Ports used for local communications (LAN)

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.

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