The admin interface makes it easy to upload content, such as images and videos, and to 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
- Image editor
- Video editor
Implementation overview
There are 4 core parts to the Content Building API:
- Service definition — Defining the external service so it is displayed in the admin interface.
- Content building — Displaying a web page (or series of web pages) that guide the user through creating the content.
- Redirecting back to the Admin interface — Redirecting the user back to the admin interface with a reference to the new content.
- Returning content — Serving the content data to the digital signage platform so it can be imported.
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/test.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
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.
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
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
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.
Comments
0 comments
Please sign in to leave a comment.