Content Building API

The content building API links external content building services directly into the administration interface to help users build digital signage content.

Work in progress!

Support documentation is under development.

Introduction

The admin interface makes it easy to upload content such as images and videos and configure web pages to display on digital signage screens. However, it is often necessary to use an external application, such as a paint program, video editor or web page editor to build the content before adding it to the digital signage platform. The Content Building API is designed to make this disjointed process seamless by providing a way of redirecting out of the admin interface into a content building tool and then returning with the content ready to be imported automatically.

For example, a Twitter option in the admin interface could direct the user to a special Twitter web application service. The user could be asked to specify a twitter hashtag and the web service could generate a JPEG of recent tweets containing the hashtag. The user is then redirected back to the admin interface where the JPEG is immediately imported ready for displaying on digital signage screens.

The Content Building API makes this possible and provides additional support for automatically refreshing dynamic content periodically.

Content building examples:

Weather
Currencies
Stocks and shares
News summaries
Menu board with prices
Bus time tables
Cinema times
Traffic information
Twitter
Facebook
Image editor
Video editor

Implementation overview

There are 4 core parts to the Content Building API:

Defining the external service so it is displayed in the admin interface.
Displaying a web page (or series of web pages) that guide the user through creating the content.
Redirecting the user back to the admin interface with a reference to the new content.
Serving the content data to the digital signage platform so it can be imported.

1. Service Definition

To display content building options in the admin interface, the external services must be defined. This is done using a service definition that is added to your web server. The service definition contains one or more references to external content building services in JavaScript Object Notation (JSON). Essentially the JSON response is a list of names and web address that will be displayed in the administration interface and help direct the user to the external content building services.

The service definition will be requested by our servers when a user clicks the option to Build content using another service in the administration interface.

Service definition example

{
  "builders": [
    { 
      "name": "Web Page Example",
      "description": "Builds a web page to be displayed by the player",
      "url": "https://staging.stacks.targetr.net/assets/dev/contentbuilder/setup-html-output.html",
      "contentType": "text/html",
      "serverImport": false
    },    
    { 
      "name": "Image Example",
      "description": "Builds an image that will be refreshed daily.",
      "url": "https://staging.stacks.targetr.net/assets/dev/contentbuilder/setup-image-output.html",
      "requireAspectRatio": true,
      "defaultRefreshPeriod": 86400000,
      "contentType": "text/jpeg",
      "serverImport": true
    }
   ]
}

Name	Default	Description
`name`		The name of the content building service. This will be displayed in the admin interface.
`description`		The description should provide a short summary of the content building service. This will be shown under the name in the admin interface.
`url`		The URL of the content building service. This is where the user will be redirected if they choose to build content using the service.
`iconSrc`		A URL to an image to be displayed as an icon for the content building service. Not currently used.
`serverImport`	`true`	Content building services will typically return a JPEG or MP4 to import. This will be transferred to players using our Content Delivery Network (CDN) and local Peer 2 Peer communications. If this value is set to `false` only the URL will be sent to the player. The player will be responsible for downloading and displaying the content in a WebView. This option is for web pages only.
`requireAspectRatio`	`false`	There is an option in the admin interface to select a pre-configured aspect ratio. If this field is set to true, the user can select an aspect ratio before redirecting to the content building service.
`contentType`		The content type the content building service will return. For example `image/jpeg image/png video/mp4 text/html` etc.
`defaultRefreshPeriod`		This is a hint for how often the content needs to be updated in milliseconds. Please note, the HTTP caching headers returned by the web server will override this setting. Exclude the field from the definition if the content should only be imported once and not updated.

Enabling content building services

The content building services listed in the administration interface is controlled by adding data to the cloud configuration. The data named contentBuilder can contain a URL (or local Java class name) to a content building service definition. This service definition will be used to populate the list. For example:

contentBuilder=https://stacks.targetr.net/assets/dev/contentbuilder/example.json

If multiple service definitions are required they should be numbered sequentially as follows: contentBuilder_0=... contentBuilder_1=... contentBuilder_2=... etc.

Built-in content building services

If no content building services are defined in the cloud configuration, several built-in content building services will be listed by default. To list built-in content building services in addition to external services, the following special Java class names can be added in addition to external service definitions.

net.targetr.contentbuilder.Weather
net.targetr.contentbuilder.Currencies
net.targetr.contentbuilder.Rss
net.targetr.contentbuilder.Twitter
net.targetr.contentbuilder.PicMonkey
net.targetr.contentbuilder.Canva
net.targetr.contentbuilder.Pixlr

For example, to show external content building services followed by the built-in weather and RSS content builders the following could be added to the cloud configuration:

contentBuilder_0=https://www.example.com/contentbuilder/example.json
contentBuilder_1=net.targetr.contentbuilder.Weather
contentBuilder_2=net.targetr.contentbuilder.Rss

2. Content Building

After choosing a content building service, the current item state is saved in the administration interface and the user is redirected to the url defined in the service definition. This web page must now ask the user for details to build the content.

During this process, which may take place over several web pages, it is important to maintain the callback parameter. This is required to redirect back to the administration interface when the user has provided all the details necessary to build the new content.

If requireAspectRatio=true is contained in the service definition, the aspectRatio parameter will be included in the web request. This will be set to the aspect ratio selected by the user in the administration interface.

3. Redirecting back to administration interface

A callback parameter will be included in the web request. This is the URL for redirecting the user back into the administration interface when content building is complete.

Example callback parameter

callback=https%3A%2F%2Fstacks.targetr.net%2Fbuilder_callback%3FconfigName%3Dstacks.targetr.net%26itemType%3Dlibraryitem%26itemId%3D109FE03EF12448%26pendingId%3Dd-1064537285760736

The callback parameter must be URL decoded. Most server side frameworks do this automatically. See JavaScript example for doing this client side.

The content building service must add the final content url to the address before redirecting. This must be URL encoded.

Example redirect

https://stacks.targetr.net/builder_callback?configName=stacks.targetr.net&itemType=libraryitem&itemId=109FE03EF12448&pendingId=d-1064537285760736&url=http%3A%2F%2Fwww.example.com%2Fgenerated-content-123456.jpg

4. Returning content

After the user is redirected to the administration interface, the server will fetch the content specified by the url parameter. This content will be downloaded, then uploaded to all the configured blobstores ready for the players to download and share.

If the service definition specifies serverImport=false then no server side import will occur. Instead the library item or stack item will be updated to contain a web resource pointing to the URL. The player will display this URL in a web browser component. Please note, this bypasses the CDN and p2p. Direct connections will be made from the players to the web pages and referenced resources. For this reason it will not function if the player has restricted access to the Internet.

Implementation example

This simple example allows the user to enter some text which is used to generate a web page that displays the text in a large font. This example is a pure clientside implementation and returns a URL to the digital signage platform that is displayed on the players.

Testing your implementation

Please create a new cloud configuration specifically for testing new content building services. Set contentBuilder to the web address of the service definition JSON and make sure you access the admin interface with the cloud configuration name in the address bar.