Application Programming Interface (API)


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 API

The following endpoints are enabled for restful communications:

Generic Object Structure

All objects follow a common basic structure.

    "id": "ABCEF1234567",
    "data": {
        "label": "My label",
        "version": "23",
        "createdMillis": "1404910684273",
        "modifiedMillis": "1412943312770",

The id field is used to uniquely store and reference the object. 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 usually contains a label, a version number and two timestamps. Additional fields will vary depending on the object type.

The Restful API is currently READ ONLY. Please use the Quick Data API for making changes to
data inside objects.

Quick Data API

The following endpoints can be used for quickly making changes to data in 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:

This would set the data named offer to the value 1 in the sequence with the ID 1234567ABCEF.
This would 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.

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.

This would display the sequence with ID 1234567ABCDEF on the screen with the ID ABCEF1234567.
This would display the scrolling text HelloWorld! on the screen with the ID ABCEF1234567.
This would 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.

This will remove the data named scrollingText from the screen with the ID ABCEF1234567.

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

Name Example Description
remoteDataSource Endpoint to get JSON object from.
remoteDataFetchPeriod 10000 The 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

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 extemely 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

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)

This will download a report containing all items displayed since January 2014.

A report for a specific screen can be downloaded by setting the screenId parameter.

This will download a report containing all items displayed on the screen with MAC 1234567ABCDEF since January 2014.

The sequenceId and itemId parameters can be used for specific sequences and stack items.

Collected Data Report

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

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:

Additional Blobstores

In addition to the global blobstore, 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


Uploading to custom blobstore

blobstoreConfig blobstore://[SERVER-DOMAIN-NAME]

Uploading to custom server using FTP

blobstoreConfig ftp://[USERNAME]:[PASSWORD]@[SERVER-DOMAIN-NAME]/blobstore/

Uploading to custom server using SCP

blobstoreConfig scp://[USERNAME]:[PASSWORD]@[SERVER-DOMAIN-NAME]/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.

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

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