1.Overview

The Signagelive Player API is a RESTful web service which will allow you to develop your own players to connect to Signagelive. All requests to authenticate and operate against the Signagelive API will be performed using SSL over HTTP (HTTPS) on TCP port 443.

The API will support data in both JSON and XML formats to enable maximum client support. The default format is JSON. All request and response examples are in JSON format. To request a response using XML clients must use the Accept header in requests with a value of application/xml

Requests and Responses
Information on all possible API requests can be found under ‘API Reference’.

See response codes for a list and description of the possible HTTP response codes that can be returned by the API.

1.1.End points - Media Player

Several endpoints are used by the Signagelive platform. We have supplied a list below for reference when connecting to the API, and for help configuring firewalls.

URL URL Protocol (Port) IP Address Description
api.signagelive.com HTTPS (443) 162.13.104.148 The primary endpoint for the Signagelive Player API.
static.signagelive.com HTTP (80), HTTPS (443) 46.38.179.225 Use for content delivery.

1.2.Concepts

To use the API effectively, you should understand several key concepts:

1.3.Workflow

All clients are required to follow the same basic workflow for connecting to the API:

All new client types must be registered with Signagelive via the Signagelive developer portal, we will then issue a unique Application ID that is to be used in all client requests to the API.

We reserve the right to suspend or terminate ApplicationIDs at any time without notice.

Registration of a new client

When the client is first initialized it makes a request to register itself as a new client, passing the Application ID, Application Key and Client ID
Signagelive returns a client key – this must then be used along with the Application ID and the client ID to authenticate the client to enable it to make further requests.

Authentication

Before the client is able to request configuration and call other Signagelive API methods it must first authenticate with the API.
The Signagelive client sends the Application ID, Application Key, Client ID and Client Key, if authentication is successful the Signagelive API returns an authentication token that must be used in all subsequent requests.
It is worth noting that authentication tokens are set to expire after 1 hour and the client will need to re-authenticate. Unauthenticated requests will receive an Unauthorized response from the API.

Configuration

When a client is registered and authenticated it can make the configuration call. The configuration call will return settings for the player such as configuration call interval, health check interval, network configuration and content to download.
If the client has content to download it should only download the content it does not have cached locally.
Once a download is complete the client should notify the Signagelive Player API of its success.

Activation of a new client

The first configuration downloaded by the client will contain a layout and playlist with a single full screen image which will display an activation code.
The user must login to the Signagelive UI and use this code to “activate” a client against a Signagelive licence.
The client is now activated and ready to have content deployed to it.
Subsequent requests (until new content is deployed) will return a default Signagelive layout.

1.3.1.Configuration Download

Each client will need to check Signagelive for configuration updates at pre-defined intervals. Unless the client has not yet downloaded any configuration from Signagelive, it should first perform a HEAD request to check the date the configuration was last updated. This will tell the client whether or not it has to perform a full configuration request.

Check the Last-Modified date the current configuration with a HEAD request.
If the configuration has been modified since it was last downloaded, download the full configuration with a GET request.

1.3.2.Content Download

When the content has changed, the client will need to download the default playlist and each individual layout, if these do not already exist on the local filesystem or have changed.

When all new content has been downloaded, all media assets that are no long present in the content can be deleted from the local filesystem. If an asset is deleted, the client should send a DeleteMediaFile notification to Signagelive using the ID of the media assset.

Downloading a Media Asset

Clients should use the following workflow when downloading a media asset:

  1. Check if the asset already exists on the local filesystem. Assets that have already been downloaded should not be downloaded again. Some assets such as IPTV streams and remote web pages do not need to be “downloaded” as they are not physical assets.
  2. Send the DownloadStart notification with the ID of the media asset. IDs are case sensitive.
  3. Download the media asset.
  4. Send the DownloadComplete notification with the ID of the media asset.

Downloading a Playlist

Clients should use the following workflow when downloading a playlist:

  1. Check if the playlist and it’s media assets have already been downloaded. If not, begin downloading.
  2. Send the DownloadStart notification with the ID of the playlist. IDs are case sensitive.
  3. Download each asset in the playlist.
  4. Send the DownloadComplete notification with the ID of the playlist.

Downloading a Layout

Clients should use the following workflow when downloading a layout:

  1. Send the DownloadStart notification with the ID of the layout.
  2. Download the background media asset, if present.
  3. For each zone:
    1. Download the background media asset, if present.
    2. Download the default media asset, if present.
    3. Download the default playlist, if present
    4. For each scheduled playlist:
      • Download the referenced playlist.
    5. Download any media assets referenced in the configuration_parameters of the zone.
  4. Send the DownloadComplete notification with the ID of the layout.

1.4.Date Time

Date Time values will be expressed using the ISO 8601 format e.g. 2012-12-31T23:59:59Z. Note that some date time values will be in UTC (using the ‘Z’ time zone designator) and some will be in local time.

Time only values will be expressed as a timespan in the form of “HH:MM:SS” e.g. “15:25:00” for 3:25 PM.

1.5.MIME Types

The following MIME types are supported by the Signagelive Player API:

Images

Extension MIME type
.bmp image/bmp
.gif image/gif
.jpg, .jpeg image/jpg
.png image/png
.tif, .tiff image/tiff
.svg image/svg+xml

Video

Extension MIME type
.avi video/avi
.divx video/divx
.flv, .f4v video/mp4
.m2ts video/mp2t
.m4v video/x-m4v
.mkv video/x-matroska
.mov video/quicktime
.mp4 video/mp4
.mpg, .mpeg video/mpeg
.qt video/quicktime
.swf application/x-shockwave-flash
.ts video/mp2t
.wmv video/x-ms-wmv

Audio

Extension MIME type
.m4a audio/mp4
.mka audio/x-matroska
.mp3 audio/mpeg
.ogg audio/ogg
.wav audio/vnd.wave
.wma audio/x-ms-wma

Web

Extension MIME type
.htm, .html text/html

Other

MIME type Description
application/octet-stream Used for executable applications
application/rss+xml RSS Feeds
application/vnd.signagelive.capture TV Capture
application/vnd.signagelive.interrupt Scheduled Interrupt
application/vnd.signagelive.iptv IPTV Stream
text/html Used for all remote web pages

1.6.Timezones

When specifying time zones to client applications, the Signagelive Player API supports a subset of the timezones available in the IANA Timezone Database. For compatiblity with Windows based clients, we have mapped these time zones to their corresponding Windows counterparts.

Windows Time Zone Name Description Time Zone ID
Dateline Standard Time (GMT-12:00) International Date Line West Etc/GMT+12
Samoa Standard Time (GMT-11:00) Midway Island, Samoa Pacific/Apia
Hawaiian Standard Time (GMT-10:00) Hawaii Pacific/Honolulu
Alaskan Standard Time (GMT-09:00) Alaska America/Anchorage
Pacific Standard Time (GMT-08:00) Pacific Time (US and Canada) America/Los_Angeles
Pacific Standard Time (Mexico) (GMT-08:00) Tijuana, Baja California America/Santa_Isabel
Mountain Standard Time (GMT-07:00) Mountain Time (US and Canada) America/Denver
Mountain Standard Time (Mexico) (GMT-07:00) Chihuahua, La Paz, Mazatlan America/Chihuahua
US Mountain Standard Time (GMT-07:00) Arizona America/Phoenix
Central Standard Time (Mexico) (GMT-06:00) Guadalajara, Mexico City, Monterrey America/Mexico_City
Canada Central Standard Time (GMT-06:00) Saskatchewan America/Regina
Central Standard Time (GMT-06:00) Central Time (US and Canada) America/Chicago
Central America Standard Time (GMT-06:00) Central America America/Guatemala
US Eastern Standard Time (GMT-05:00) Indiana (East) America/Indiana/Indianapolis
SA Pacific Standard Time (GMT-05:00) Bogota, Lima, Quito, Rio Branco America/Bogota
Eastern Standard Time (GMT-05:00) Eastern Time (US and Canada) America/New_York
Venezuela Standard Time (GMT-04:30) Caracas America/Caracas
Atlantic Standard Time (GMT-04:00) Atlantic Time (Canada) America/Halifax
Central Brazilian Standard Time (GMT-04:00) Manaus America/Cuiaba
SA Western Standard Time (GMT-04:00) La Paz America/La_Paz
Pacific SA Standard Time (GMT-04:00) Santiago America/Santiago
Newfoundland Standard Time (GMT-03:30) Newfoundland America/St_Johns
Greenland Standard Time (GMT-03:00) Greenland America/Godthab
Montevideo Standard Time (GMT-03:00) Montevideo America/Montevideo
Argentina Standard Time (GMT-03:00) Buenos Aires America/Argentina/Buenos_Aires
E. South America Standard Time (GMT-03:00) Brasilia America/Sao_Paulo
SA Eastern Standard Time (GMT-03:00) Georgetown America/Cayenne
Mid-Atlantic Standard Time (GMT-02:00) Mid-Atlantic Etc/GMT+2
Cape Verde Standard Time (GMT-01:00) Cape Verde Is. Atlantic/Cape_Verde
Azores Standard Time (GMT-01:00) Azores Atlantic/Azores
Greenwich Mean Time (Iceland) (GMT) Monrovia, Reykjavik Atlantic/Reykjavik
Greenwich Mean Time (GMT) Greenwich Mean Time : Dublin, Edinburgh, Lisbon, London Europe/London
Morocco Standard Time (GMT) Casablanca Africa/Casablanca
W. Europe Standard Time (GMT+01:00) Amsterdam, Berlin, Bern, Rome, Stockholm, Vienna Europe/Berlin
Central European Time (GMT+01:00) Brussels, Copenhagen, Madrid, Paris Europe/Paris
Central Europe Standard Time (GMT+01:00) Belgrade, Bratislava, Budapest, Ljubljana, Prague Europe/Budapest
Central European Standard Time (GMT+01:00) Sarajevo, Skopje, Warsaw, Zagreb Europe/Warsaw
W. Central Africa Standard Time (GMT+01:00) West Central Africa Africa/Lagos
Middle East Standard Time (GMT+02:00) Beirut Asia/Beirut
Namibia Standard Time (GMT+02:00) Windhoek Africa/Windhoek
Jordan Standard Time (GMT+02:00) Amman Asia/Amman
Israel Standard Time (GMT+02:00) Jerusalem Asia/Jerusalem
FLE Standard Time (GMT+02:00) Helsinki, Kiev, Riga, Sofia, Tallinn, Vilnius Europe/Kiev
Eastern Europe Standard Time (GMT+02:00) Minsk Asia/Nicosia
Eastern European Time (GMT+02:00) Athens, Bucharest, Istanbul Europe/Bucharest
Egypt Standard Time (GMT+02:00) Cairo Africa/Cairo
South Africa Standard Time (GMT+02:00) Harare, Pretoria Africa/Johannesburg
Russian Standard Time (GMT+03:00) Moscow, St. Petersburg, Volgograd Europe/Moscow
E. Africa Standard Time (GMT+03:00) Nairobi Africa/Nairobi
Georgian Standard Time (GMT+03:00) Tbilisi Asia/Tbilisi
Arabic Standard Time (GMT+03:00) Baghdad Asia/Baghdad
Arab Standard Time (GMT+03:00) Kuwait, Riyadh Asia/Riyadh
Iran Standard Time (GMT+03:30) Tehran Asia/Tehran
Arabian Standard Time (GMT+04:00) Abu Dhabi, Muscat Asia/Dubai
Mauritius Standard Time (GMT+04:00) Port Louis Indian/Mauritius
Azerbaijan Standard Time (GMT+04:00) Baku Asia/Baku
Caucasus Standard Time (GMT+04:00) Yerevan Asia/Yerevan
Afghanistan Standard Time (GMT+04:30) Kabul Asia/Kabul
Pakistan Standard Time (GMT+05:00) Islamabad, Karachi Asia/Karachi
West Asia Standard Time (GMT+05:00) Tashkent Asia/Tashkent
Ekaterinburg Standard Time (GMT+05:00) Ekaterinburg Asia/Yekaterinburg
India Standard Time (GMT+05:30) Chennai, Kolkata, Mumbai, New Delhi Asia/Kolkata
Sri Lanka Standard Time (GMT+05:30) Sri Jayawardenepura Asia/Colombo
Nepal Standard Time (GMT+05:45) Kathmandu Asia/Kathmandu
N. Central Asia Standard Time (GMT+06:00) Almaty, Novosibirsk Asia/Novosibirsk
Central Asia Standard Time (GMT+06:00) Astana, Dhaka Asia/Almaty
Myanmar Standard Time (GMT+06:30) Yangon (Rangoon) Asia/Rangoon
SE Asia Standard Time (GMT+07:00) Bangkok, Hanoi, Jakarta Asia/Bangkok
North Asia Standard Time (GMT+07:00) Krasnoyarsk Asia/Krasnoyarsk
W. Australia Standard Time (GMT+08:00) Perth Australia/Perth
North Asia East Standard Time (GMT+08:00) Irkutsk, Ulaan Bataar Asia/Irkutsk
Singapore Standard Time (GMT+08:00) Kuala Lumpur, Singapore Asia/Singapore
China Standard Time (GMT+08:00) Beijing, Chongqing, Hong Kong, Urumqi Asia/Shanghai
Taipei Standard Time (GMT+08:00) Taipei Asia/Taipei
Tokyo Standard Time (GMT+09:00) Osaka, Sapporo, Tokyo Asia/Tokyo
Yakutsk Standard Time (GMT+09:00) Yakutsk Asia/Yakutsk
Korea Standard Time (GMT+09:00) Seoul Asia/Seoul
AUS Central Standard Time (GMT+09:30) Darwin Australia/Darwin
Cen. Australia Standard Time (GMT+09:30) Adelaide Australia/Adelaide
West Pacific Standard Time (GMT+10:00) Guam, Port Moresby Pacific/Port_Moresby
AUS Eastern Standard Time (GMT+10:00) Canberra, Melbourne, Sydney Australia/Sydney
Vladivostok Standard Time (GMT+10:00) Vladivostok Asia/Vladivostok
E. Australia Standard Time (GMT+10:00) Brisbane Australia/Brisbane
Tasmania Standard Time (GMT+10:00) Hobart Australia/Hobart
Central Pacific Standard Time (GMT+11:00) Magadan, Solomon Is., New Caledonia Pacific/Guadalcanal
New Zealand Standard Time (GMT+12:00) Auckland, Wellington Pacific/Auckland
Fiji Standard Time (GMT+12:00) Fiji, Kamchatka, Marshall Is. Pacific/Fiji
Tonga Standard Time (GMT+13:00) Nuku’alofa Pacific/Tongatapu

1.7.Notification Types

Notifications are used to provide feedback about the status of clients to Signagelive users. The following notifications are supported by the Signagelive Player API:

  • SystemStart – This should be sent after the bootup of the client device/software
  • HealthCheck – This should be sent at regular intervals to indicate that the client is operational. The interval is determined by the value of the health_check_interval property on the connectivity object
  • DownloadStart – This should be sent when the player begins to download a layout, playlist , media asset or other file
  • DownloadComplete – This should be send when the download is complete
  • DownloadFail – This should be send if a download has failed
  • DeleteMediaFile – This should be sent if the client deletes a file from the local filesystem. This could be because it is a media asset that is no longer present in any playlists
  • FirmwareUpdateComplete – This should be sent when a client has performed a firmware update successfully
  • FirmwareUpdateFailed – This should be sent if a client has performed a firmware update but it has failed
  • ContentDownloadComplete – This notification can be used to notify the Signagelive Player API that all content has been downloaded successfully. Using this instead of the using DownloadComplete event on individual items means that download progress cannot be viewed from Signagelive

1.8.Request Headers

Client applications will identify themselves to Signagelive using the following headers, some or all of which will be added to each request:

Header Description
X-SIGNAGELIVE-APP-ID Application IDs will be issued by Signagelive via the Signagelive Developer Portal and are unique to the client application. The Application ID identifies the application type/client type and it’s Signagelive capabilities.
X-SIGNAGELIVE-APP-KEY Application Keys are managed via the developer portal and are used to authenticate the application with the API.
X-SIGNAGELIVE-CLIENT-ID The client ID must uniquely identify each client, we recommend that the client ID is generated from hardware serial numbers to ensure uniqueness and security and to ease asset tracking.

Supported characters are alphanumeric and the following non-alphanumeric characters:

/ \ – :

Length must be between 17 and 255 characters.

X-SIGNAGELIVE-CLIENT-KEY Client Keys are issued to individual clients upon initial registration with the Signagelive API and are to be supplied with all authentication requests.
X-SIGNAGELIVE-AUTH-TOKEN The authentication token issued by the authenticate method.

In the event that you are unable to send custom headers with a request to a method or media asset it is possible to use query string parameters as an alternative:

Header Equivalent Query String Parameter
X-SIGNAGELIVE-APP-ID sl_app_id
X-SIGNAGELIVE-APP-KEY sl_app_key
X-SIGNAGELIVE-CLIENT-ID sl_client_id
X-SIGNAGELIVE-CLIENT-KEY sl_client_key
X-SIGNAGELIVE-AUTH-TOKEN sl_auth_token

1.9.Response Codes

The Signagelive Player API will return standard HTTP response codes, clients are expected to respect the response from the API, particularly relating to bad requests, rate limits etc and not attempt to make the call again until either the issue has been resolved or timeout period has passed.

Code Text Description
200 OK Success
201 Created The request has been fulfilled and resulted in a new resource being created
204 No Content The request was successfully processed, but is not returning any content
400 Bad Request The request cannot be fulfilled due to bad syntax
401 Unauthorized Authentication has failed:

X-SIGNAGELIVE-APP-ID header has an invalid Application ID

Application ID, Client ID and Client Key are not linked

403 Forbidden The Signagelive client licence has expired
404 Not Found The resource could not be found
405 Method Not Allowed A request was made to a resource using a request method not supported by that resource
408 Request Timeout The server timed out waiting for the request
409 Conflict The request could not be completed because the request would conflict with data already available on the server
429 Too Many Requests The client is over its rate limit, requests should be suspended until the time specified in header X-RateLimit-Reset has passed
500 Internal Server Error A generic error message as a result of a server error
501 Not Implemented The server does not recognise the request method
503 Service Unavailable The servers are up but currently overloaded with requests.

2.API Reference

2.1.Registration

Each Signagelive client must be registered with the Signagelive system before it can be managed and content deployed. Once a player is registered it is issued with a unique client key that is used to authenticate.

To create the registration the client should send a POST with an empty body to Signagelive.

Request

Verbs URI Description
POST {api_version}/client/register/ Allows you to create a new client registration request

This operation does not require a method body

Headers

Header Description
X-SIGNAGELIVE-APP-ID Application IDs will be issued by Signagelive and are unique to the client application when a new client application is added to Signagelive.
X-SIGNAGELIVE-APP-KEY Application Keys are managed via the developer portal and are used to authenticate the application with the API.
X-SIGNAGELIVE-CLIENT-ID The client ID must uniquely identify each client, we recommend that the client ID is generated from hardware serial numbers to ensure uniqueness and security and to ease asset tracking.

Supported characters are alphanumeric and the following non-alphanumeric characters:

/ \ – :

Length must be between 17 and 255 characters

Response

Normal response code(s): 201

The client must store the client_key value and supply it with all subsequent requests to the authentication method as the X-SIGNAGELIVE-CLIENT-KEY header.

2.2.Client Authentication

When a player has registered with the server, it must be authenticated before it can perform other operations such as configuration or notifications.

Request

Verbs URI Description
POST {api_version}/client/authenticate/ Returns the client authentication token

This operation does not require a method body

Headers

Header Description
X-SIGNAGELIVE-APP-ID Application IDs will be issued by Signagelive and are unique to the client application when a new client application is added to Signagelive.
X-SIGNAGELIVE-APP-KEY Application Keys are managed via the developer portal and are used to authenticate the application with the API.
X-SIGNAGELIVE-CLIENT-ID The client ID must uniquely identify each client, we recommend that the client ID is generated from hardware serial numbers to ensure uniqueness and security and to ease asset tracking.

Supported characters are alphanumeric and the following non-alphanumeric characters:

/ \ – :

Length must be between 17 and 255 characters

X-SIGNAGELIVE-CLIENT-KEY Client Keys are issued to individual clients upon initial registration with the Signagelive API and are to be supplied with all authentication requests.

Response

Normal response code(s): 201

The ‘token’ must be stored and included with subsequent requests as the X-SIGNAGELIVE-AUTH-TOKEN header. Each token will last one hour. Additional requests from the client to the authentication method before the token expiry time (“expires” in the response body, expressed as UTC) will return the same token. After the expiry time, a new token will be issued.

2.3.Client Configuration

Once a client is registered and authenticated the client should request its configuration and begin operations defined within it.

To configure a client with new content the client requests its configuration, the configuration details the content and other configuration information such as content check frequency, health check frequency and diagnostic log upload requests, network configuration etc.

The first configuration downloaded by the client will contain a layout and playlist with a single full screen image which will display an activation code.

The user must login to the Signagelive UI and use this code to “activate” a client against a Signagelive licence.

The client is now activated and ready to have content deployed to it.

Subsequent requests (until new content is deployed) will return default Signagelive content.

Request

Verbs Uri Description
HEAD {api_version}/client/configuration/ Returns the Last Modifed Date held by the server for the client’s configuration
GET {api_version}/client/configuration/ Returns the client configuration object

Headers

Header Description
X-SIGNAGELIVE-APP-ID Application IDs will be issued by Signagelive and are unique to the client application when a new client application is added to Signagelive.
X-SIGNAGELIVE-APP-KEY Application Keys are managed via the developer portal and are used to authenticate the application with the API.
X-SIGNAGELIVE-AUTH-TOKEN The authentication token returned by the authentication method.

HEAD Response

No response body is returned.

Response Headers

Header Description
Last-Modified The date/time that that configuration was last updated, expressed as an RFC 1123 date.

Normal response code(s): 200

GET Response

The client configuration object contains a number of objects, each will be explained below, a sample response (with child object detail removed for brevity):

Normal response code(s): 200

Definition of child objects

Name Description
change_id The change ID of the configuration. This is incremented whenever an an action is performed within the Signagelive UI to change the contents of the configuration.
last_modified The date/time the configuration was last modified, expressed as UTC
connectivity Describes the intervals at which the client will connect to the API
network Describes how the device should configure its local network adapter
logging Describes the logging schemes that are in place, and whether the logs should be sent to the signagelive API for analysis
screen_control Describes the times that the screen should be switched on – if it is not populated it should be assumed that the screen is always on. Also includes configuration parameters for the control method e.g. RS232
synchronization If the client is a member of a sync group (i.e. all content across a group of clients plays in sync, the syncronisation object identifies the members of the group, and the communication ports
content The content object contains the content that needs to be played and when, along with advanced features such as interrupts
firmware_update Provides details of any client firmware updates that should be downloaded
client_details Describes client specific data such as Signagelive serial number, licence expiry date and the address of the client location
meta_data Meta data is a list of key value pair data that can be used by the client to localise data e.g. it could be a post/zip code or a security key for a third party content system. Meta data will also contain reserved Signagelive key value pairs to identify device serial number, licence expiry and other Signagelive data items.

2.3.1.Connectivity

The connectivity object describes the intervals at which the client will connect to the API for various operations.

The example below, shows a fully populated connectivity object, please refer to field definitions relating to scenarios whereby fields will be omitted.

Field Definitions
Name Description Required
configuration_check_time The time of day that the client should get its configuration with the Signagelive API No – if the configuration_interval_scheme is not set to ‘regularinterval’ this field will be omitted.
configuration_check_interval The interval expressed in minutes that the client should get its configuration No – if the configuration_interval_scheme is not set to ‘timeofday’ this field will be omitted.
configuration_interval_scheme Identifies the scheme that the client is configured to connect to the Signagelive API. Possible values are:

  1. regularinterval
  2. timeofday
Yes
health_check_interval The interval expressed in minutes that the client should call the health check notification method – see here for details on health check notification Yes
diagnostics_update_time The time of day that the client will send diagnostics information to the Signagelive API No – if the diagnostics_interval_scheme is not set to ‘regularinterval’ this field will be omitted.
diagnostics_update_interval The interval in minutes the client will send diagnostics information to the Signagelive API – See here for diagnostics calls Yes
diagnostics_interval_scheme Identifies the scheme that the client is configured to send diagnostics information to the Signagelive API. Possible values are:

  1. regularinterval
  2. timeofday
Yes
system_reboot_time The time of day the client should perform an automated reboot. No

2.3.2.Network

Describes how the device should configure its local network adapter.

Field Definitions
Name Description Required
use_dhcp Indicates if the player should obtain its network settings using DHCP Yes
ipv4_address IPv4 address to configure the network adapter with No – If use_dhcp is set to true
subnet_mask Subnet Mask to configure the network adapter with No – If use_dhcp is set to true
default_gateway Default gateway address to configure the network adapter with No – If use_dhcp is set to true
dns1 Primary DNS address to configure the network adapter with No – If use_dhcp is set to true
dns2 Secondary DNS address to configure the network adapter with No – If use_dhcp is set to true
proxy_server If a proxy server is required, the address and port are specified Yes
use_wifi Indicates if a wireless network adapter is in use Yes
wifi_network_name Name of wireless network to join No – If use_wifi is set to false
wifi_pass_phrase Passphrase for wireless network No – If use_wifi is set to false
wifi_security_type Type of wifi security being used.

Possible values: “open”, “wep”, “wpa_psk” and “wpa2_psk”.

No – If use_wifi is set to false.

2.3.3.Logging

The logging object describes the logging schemes that are in place, and whether the logs should be sent to the signagelive API for analysis.

Log files should be delivered in the device native format and will be available for download from Signagelive

Field Definitions
Name Description Required
application.on Indicates if the player should be performing application logging. Yes.
application.level Indicates the level of log output to produce, permitted values are Debug, Info, Warn, Error, Fatal. No – If application.on is set to false then this value is omitted.
application.upload Indicates if the log files should be uploaded after the current configuration check has completed. No – If application.on is set to false then this value is omitted.
screencapture.on Indicates if the player should take screenshots for logging purposes. Yes.
screencapture.frequency Indicates the frequency in minutes at which screenshots should be take, or null if a single screenshot has been requested. No – If screencapture.on is set to false then this value is omitted.
screencapture.screenshot_at_next_content_check Indicates whether or not a single screenshot should be taken at the next content check. This can be as well as or instead of setting a frequency for screenshots. No – If screencapture.on is set to false then this value is omitted.

2.3.4.Content

The content object contains the content that needs to be played and when, along with advanced features such as interrupts.

The Signagelive Player API returns a linear schedule. Display order and start/end times are calculated by the API. Schedules will not overlap.

Field Definitions
Name Description Required
default_playlist_id The ID of the default playlist.

A default playlist plays when either there is no content in the schedule or the scheduled content has failed to play

No
schedule An array of scheduled layout objects, arranged in a linear schedule, earliest first. Yes – although it may be empty
interrupts A collection of interrupt objects. Interrupts are actions that occur as a result of an external action.

Interrupt objects have a trigger and an action as a result of that trigger.

A trigger specifies the type of trigger, along with a key value pair array of configuration parameters.

An action defines the layout to play and the duration that it should be displayed for before returning to the scheduled content

Yes – although it may be empty
A collection of layout objects. Each layout defines one or more zones and playlists that will play in them. Yes – although it may be empty
playlists An array containing all playlists present across all layouts and default playlists. Yes
media_assets An array containing all media assets present across all layouts and playlists Yes

2.3.4.1.Scheduled Layouts

A scheduled layout object defines when a layout will be displayed.

Field Definitions
Name Description Required
layout_id The ID of the layout to be displayed. Yes
start The day and time that the asset is valid from. Values will either be a date/time (ISO 8601) or null. No – If the layout is being displayed as an interrupt a start and end is not required.
end The day and time that the asset is valid to. Values will either be a date/time or null. No – If the layout is being displayed as an interrupt a start and end is not required.

2.3.4.2.Layout

Field definitions:
Name Description Required
id Id of the layout Yes
name Name of the layout Yes
is_deployed A boolean value indicating whether or not a client has reported that it has already downloaded the layout. If false, the client must notify the Signagelive API of the download after all media has been downloaded. This will be false when the layout is first deployed and if any changes are made to the schedule, layout design or content. Yes
width Width of the layout design Yes
height Height of the layout design Yes
background_color background color expressed as a hexadecimal RGB No – omitted if a background image is being used
background_asset_id The ID of the media asset that should be displayed as the layout background. No – omitted if a background image is not set
zones Array of zones for the layout. Zones define content areas, which may contain playlists, rss tickers, web pages, video capture output etc. Yes

Zone Object

Name Description Required
id Id of the zone Yes
x x coordinate of the zone relative to the layout position Yes
y y coordinate of the zone relative to the layout position Yes
width width of the zone Yes
height height Yes
z-index The zones position in the layouts z order Yes
background_color background color expressed as a hexadecimal RGB No – omitted if a background image is being used
background_asset_id Media asset reference object indicating the media asset object that should be displayed as the zone background. If both an asset ID and a color are specified, the media asset will take precedence. No – omitted if a background image is not set
default_media_asset_id The ID of the media asset to display if there is not a default playlist specified, and there is no scheduled item configured to play in the zone at any given time Yes
default_playlist_id The ID of the default playlist. The default playlist, if configured, will play when there are no scheduled items for the zone at any given time. Yes
type The type of zone, supported values are:

  • media
  • text
Yes
scheduled_playlists Array of scheduled playlist objects arranged in a linear schedule, earliest first. Yes – although the array could be empty
configuration_parameters Array of key values pairs containing configuration parameters to configure the zone e.g. ticker scroll direction, shape etc Yes – although the array could be empty
Note on scaling of layouts/zones.

Layouts are designed to fit the screen, irrespective of the difference between the layout’s design size and client screen resolution.

Media players are expected to calculate the relative size and positions of layout zones based upon the ratio of the screen resolution and the layout design.

Configuration parameters for text zones

Where a zone type is “text”, the following configuration parameters may be used to configure the appearance and behaviour of the zone:

Name Description Required
font The name of the font to be used when displaying the text. No
font_asset_id The ID of the media asset which represents the font file which must be downloaded to install the font when the layout designer has selected a non standard font. No
font_size The size of the font in points. If not specified, the text should be scaled to fit the window appropriately. No
font_color The text color expressed as a hexadecimal RGB. No
bold A string representation of a boolean value (“true” or “false”) indicating whether the text should be bold. No
italic A string representation of a boolean value (“true” or “false”) indicating whether the text should be italic. No
underline A string representation of a boolean value (“true” or “false”) indicating whether the text should be underlined. No
animation How the text should be animated. Possible values:

  • scroll_right_to_left – Text scrolls from right to left.
  • scroll_left_to_right – Text scrolls from left to right.
  • scroll_bottom_to_top – Text scrolls from bottom to top.
  • scroll_top_to_bottom – Text scrolls from top to bottom.
  • fade – Text fades in and out
  • none – No animation. A single text item is displayed
No
speed A number from 1-10 indicating how fast the text should scroll/fade in and out, 1 being slow and 10 being fast. No – default will be 5
pause The amount of time, in seconds, to pause the ticker when each text item is shown on screen. No – default will be 0
seperator_asset_id The ID of the media asset to be used as a “separator” image – it appears between the individual text assets. No

 

Scheduled Playlist Object

A scheduled playlist object define when a particular playlist will be played.

Field definitions:
Name Description Required
playlist_id The ID of the playlist to be played. Yes
start The start date/time of the playlist. Yes
end The end date/time of the playlist. Yes

2.3.4.3.Playlist

A playlist object represents a collection of media files that are to be played. It can either be a default playlist which will play if no other content is scheduled (either full screen or within a layout) or as a scheduled playlist within a layout zone.

Field definitions:
Name Description Required
id The ID of the playlist within the Signagelive system Yes
name The name of the playlist as defined by its creator Yes
media_assets An array of playlist media asset objects in the order in which they are to be played Yes

 

Playlist Media Asset Object

A playlist media asset object represents a media file within a playlist or a background asset in a zone or layout. The ‘id’ will correspond to a media asset object in the media_assets array on the content object.

Field definitions:
Name Description Required
id The ID of the playlist media asset Yes
media_asset_id The ID of the media asset to be played Yes
duration The duration in seconds that the asset should play for. 0 indicates play to length for videos. Yes
validity The recurrence object specifying on which days of the week on which the item will play and between which times of day. Can be null. Yes
meta_data An array of string key/value pairs containing configuration information for the media asset Yes

2.3.4.4.Validity

The validity object is used to specify when a media asset is valid from/to and on which days of the week it will be active.

Field definitions:
Name Description Required
start The day and time that the asset is valid from. Values will either be a date/time (ISO 8601) or null. No – Not required if validity will be based on day of the week only.
end The day and time that the asset is valid to. Values will either be a date/time or null. No – Not required if validity will be based on day of the week only.
start_time The time of day that the item can be displayed from. No – Not required if validity is based only on a start and end date.
end_time The time of day that the item can be displayed to. No – Not required if validity is based only on a start and end date.
days The days on which the item is valid. It is an integer representation of binary flags.

1 = Sunday

2 = Monday

4 = Tuesday

8 = Wednesday

16 = Thursday

32 = Friday

64 = Saturday

i.e a value of 6 indicates that the screen control plan is valid Monday and Tuesday.

No – Not required if validity is based only on a start and end date.

Where a start and end date are specified, the media asset is to be played between those dates only.

Where a start_time, end_time and days are specified, the asset is only to be played between the times of day and days of the week given. If the end_time is before the start_time the item has been configured to be active overnight.

An asset could have a start and end specified, or a start_time, end_time and days specified, or both. Validity can be specified on media assets and playlist media assets. Where validity is specified on both, the playlis media asset validity will override that on the media asset itself.

If the value of a validity object is null, the item has no validity configured and can be considered to be valid at all times.

2.3.4.5.Media Asset

A media asset object represents an item of media to be played. The types of media supported are determined by the client.

NB HEAD requests are not supported for media assets. If a media asset is updated, it’s file name will change.

Field definitions:

No

Name Description Required
id The ID of the media asset within the Signagelive system Yes
name The name of the media asset Yes
local_file_name Local filename if it is a downloadable asset such as a video, image etc. If this is not supplied, the file name should remain the same as it is on the remote server.
type Mimetype of the media asset, supported mime types include (note additional audio, image and video mime types are supported):

  • audio/mpeg
  • image/jpg
  • video/mp4
  • application/x-shockwave-flash
  • text/html
  • application/octet-stream (for exes)
  • application/vnd.signagelive.iptv
  • application/rss+xml
  • application/vnd.signagelive.capture
  • application/vnd.signagelive.interrupt
Yes
url The location where the media asset can be downloaded. Please note that all requests for media must be accompanied by the authentication headers:

  • X-SIGNAGELIVE-APP-ID
  • X-SIGNAGELIVE-AUTH-TOKEN
No
hash The hash value used to verify the integrity of the media asset No
hash_type The type of hash. Values are “CRC32” or “MD5”. No
size The size of the media asset in bytes No
validity The validity object specifies when the asset is valid from and to, and on which days of the week it will play and between which times of day. Can be null. Yes
meta_data An array of string key/value pairs containing configuration information for the media asset Yes

2.3.4.6.Interrupt

The interrupt object details events to listen for and actions to perform when they are received. Currently only key presses are supported and the action will be a layout to display

Field definitions:
Name Description Required
name The name of the interrupt Yes
trigger An object describing how the interrupt is triggered. Yes
action An object describing interrupt action. Yes
Trigger Field definitions:
Name Description Required
type The type of interrupt trigger. Only KeyboardEvent is currently supported. Yes
configuration_parameters A collection of name/value pairs specifying how the interrupt is initiated and cancelled. Yes
Trigger configuration parameters:
Name Description Required
ActionKey The key use to initiate the interrupt. Yes
CancelKey The key used to cancel the interrupt. No
Action field definitions
Name Description Required
layout_id The id of the layout to play. Yes
duration Duration to play the layout for in seconds, if the layout is not cancelled. If duration is 0, the layout will play until all playlists in the layout have been played at least once. Yes

 

Scheduling Example

Only one interrupt will be active at any one time. When an interrupt is cancelled or ends, the scheduled content will resume playing. When a second interrupt is triggered while the first is playing, the first is automatically cancelled.

Example 1:

  1. Scheduled content is playing
  2. Interrupt 1 is triggered
  3. Interrupt 1 plays
  4. Interrupt 1 finishes playing
  5. Scheduled content plays

Example 2:

  1. Scheduled content is playing
  2. Interrupt 1 is triggered
  3. Interrupt 1 plays
  4. Interrupt 2 is triggered
  5. Interrupt 2 plays
  6. Interrupt 2 is cancelled
  7. Scheduled content plays

2.4.Screen Control

The screen control object describes the times that the screen should be switched on – if it is not populated it should be assumed that the screen is always on.

The example below is for a screen that turns on at 9AM and off at 5PM every day using RS232.

Field Definitions
Name Description Required
plans Plans is an array of plan objects that specify on/off times and the days that the plan is valid

A plan has the following fields:

on: expressed as time in seconds from midnight that day

off: expressed as time in seconds from midnight that day

days: The days that this screen control plan is valid for. It is an integer representation of binary flags.

1 = Sunday

2 = Monday

4 = Tuesday

8 = Wednesday

16 = Thursday

32 = Friday

64 = Saturday

i.e a value of 6 indicates that the screen control plan is valid Monday and Tuesday.

No – if there are no plans then the screen is determined to be on all of the time
configuration_parameters Configuration parameters are a key value pair array of parameters that can be used to configure a screen controller such as RS232 No – if there are no plans then the screen is determined to be on all of the time
Configuration Parameters:

All values are sent as strings.

Name Description Required
type The type of control being used. Values are RS232, MinicomDSVision3000 or SystemDefault Yes
on_command The text command used to turn on the screen. No – this parameter is required for RS232 control only.
off_command The text command used to turn off the screen. No – this parameter is required for RS232 control only.
sync_command The text command used to send the sync command. No – this parameter is required for RS232 control only.
port_name The name of the COM port being used for RS232 or Minicom DS Vision 3000 control No – this parameter is required for RS232 or Minicom DS Vision 3000 control only.
baud_rate The baud rate for the connection. No – this parameter is required for RS232 control only.
data_bits The number of data bits per character. Values are “5”,”6”,”7”,”8” or “9” No – this parameter is required for RS232 control only.
parity The parity bit type. Values are none, odd, even, mark or space. No – this parameter is required for RS232 control only.
stop_bits The number of stop bits used. Values are “0”, “1”, “1.5” or “2”. No – this parameter is required for RS232 control only.
send_carriage_return Send a carriage return after each command. Values are “true” or “false”. No – this parameter is required for RS232 control only.

2.5.Synchronisation

If the client is a member of a sync group (i.e. all content across a group of clients plays in sync, the synchronization object identifies the members of the group, and the communication ports. Each sync group will have a “master” which will broadcast a message to the other group members to tell them when to move to the next asset. By default this will be the lowest serial number in the group. If a master has failed (defined by not sending a sync signal for a number of times in a row – configured by the missed sync threshold) the group will try to use a new master. The next sync master will be the next lowest serial number. In the example below, if 1234 fails, 2345 will become the new master.

Field Definitions
Name Description Required
enabled Indicates if this client is a member of a synchronization group Yes
configuration_paremeters An array of key/value pairs to configure the method of communication. See below for details. No – if enabled is false, then this value is omitted
wait_timeout Time in seconds to wait at the end of an asset before moving to the next asset if a sync signal is not received No – if enabled is false, then this value is omitted
missed_sync_threshold The permitted number of missed sync signals before either promoting oneself to a master or accepting sync signals from another master No – if enabled is false, then this value is omitted
default_master The serial number of the default master for the sync group. This will be the lowest serial number in the group No – if enabled is false, then this value is omitted
group_members A list of the serial numbers of the other members in the synchronization group – when in slave mode only accept sync signals from the members of the current group No – if enabled is false, then this value is omitted
sync_group_id The ID of the sync group. No – if enabled is false, then this value is omitted
Configuration Parameters
Name Description Required
type The type of communication used. Only ‘udp’ is currently supported. Yes
broadcast_address The datagram broadcast address. Yes
send_port The port from which to send datagram packets. Yes
receive_port The port on which to listen for datagram packets. Yes

2.6.Firmware Update

The firmware update object contains download information for a client firmware update.

Field Definitions
Name Description Required
id The id of the firmware update. Yes
version The version number Yes
url The location where the update package can be downloaded. Yes
hash The hash value used to verify the integrity of the media asset No
hash_type The type of hash. Values are “CRC32” or “MD5”. No
size The size of the update package, in bytes. No

When the firmware has been updated successfully, the client should send the FirmwareUpdateComplete notification.

2.7.Client Details

The client details object contains site specific information relating to the client.

Field Definitions
Name Description Required
activation_code Will contain the 6 digit activation code prior to activation. Yes
serial_number The Signagelive serial number which is generated at activation. Yes
licence_expires The licence expiry date Yes
description The description as entered by the user Yes
address_1 The first line of the address Yes
address_1 The second line of the address Yes
city The town/city Yes
state State/County Yes
zip_code Zip/Post code Yes
reference_code_1 Reference Code 1 Yes
reference_code_2 Reference Code 2 Yes
reference_code_3 Reference Code 3 Yes
latitude Latitude of the client’s location, in decimal degrees Yes, but can be null
longitude Longitude of the client’s location, in decimal degrees Yes, but can be null
time_zone The time zone of the client, specified as a TZID from the IANA Time Zone Database. Yes
utc_offset The utc offset in minutes Yes

2.8.Meta Data

Meta data is an array of key value pairs that can be used by the client to localise data e.g. it could be a post/zip code or a security key for a third party content system.

3.Notifications

Notifications are used to provide provide the Signagelive UI with information about the state of the client.

Request

Verb URI Description
POST {api_version}/client/notifications/ Posts a notification that the client has performed an action.
Headers:
Header Description
X-SIGNAGELIVE-APP-ID Application IDs will be issued by Signagelive and are unique to the client application when a new client application is added to Signagelive.
X-SIGNAGELIVE-APP-KEY Application Keys are managed via the developer portal and are used to authenticate the application with the API.
X-SIGNAGELIVE-AUTH-TOKEN The authentication token returned by the authentication method.

Body:

Field definitions:
Name Description Required
type The action performed by the client. See below for details. Yes
object_id The ID of the object that the notification relates to (if applicable) No – see below
data Custom information regarding the event being sent. This can be a simple text message or a json string. No

Notification Types:

Type Description Notes
SystemStart A notification that the client has initialized – this should be called after a bootup of the device or software is started. object_id not required
HealthCheck A notification that the client is up and running at that all systems are operational.

This should be called regularly at the interval defined in the configuration response connectivity object, health_check_interval property.

object_id not required
DownloadStart A notification that the player has begun to download a layout, playlist, media asset or other object. object_id required
DownloadComplete A notification that the player has completed the download of a layout, playlist, media asset or other object. object_id required
DownloadFail A notification that a download has failed. object_id required
DeleteMediaFile A notification that the client has deleted a file from the local system object_id required
FirmwareUpdateComplete A notification that a firmware update has been applied successfully. object_id not required
FirmwareUpdateFailed A notification that a firmware update has failed. object_id not required
ContentDownloadComplete A notification that all content has been downloaded successfully. Using this instead of the using DownloadComplete event on individual items means that download progress cannot be viewed from Signagelive. object_id not required

Please note that PlayStart, PlayComplete and PlayFail will not be available in the the initial release of the API.

Normal response code: 204

Alternative reponse code: 403 – This response will be sent when the player has not yet been activated with a Signagelive licence. The request should not be re-sent.

4.Client System Reporting

Clients can notify Signagelive of key system information using the System Report, to identify hardware installed, hardware status and key application and system settings.

Information should be sent to Signagelive by the value specified by diagnostics_update_interval in the connectivity object.

Request

Verb URIs Description
POST {api_version}/client/systemreport Posts system information to Signagelive, see request body for further details

Headers:

Header Description
X-SIGNAGELIVE-APP-ID Application IDs will be issued by Signagelive and are unique to the client application when a new client application is added to Signagelive.
X-SIGNAGELIVE-APP-KEY Application Keys are managed via the developer portal and are used to authenticate the application with the API.
X-SIGNAGELIVE-AUTH-TOKEN The authentication token returned by the authentication method.

Normal response code: 204

Alternative reponse code: 403 – This response will be sent when the player has not yet been activated with a Signagelive licence. The request should not be re-sent.

Sample Request Body:

None of the top level objects are required, as the information may not be available on specific devices.

Name Description Required
system An object containing general system information such as operating system and manufacturer. No
client An object containing information about client software/firmware. No
cpu An object containing information on the CPU such as model name and speed. No
memory An object containing information about available RAM. Values are expected in megabytes. No
storage An object containing information about available hard disk storage. Values are expected in megabytes. No
temperature An array of objects containing information about available temperature sensors. No
graphics_devices An array of objects containing information about installed graphics adapters. No
network_adapters An array of objects containing information about active IP enabled network adapters. No
installed_applications An array of objects containing information about all installed applications. No
running_processes An array of objects containing information about running processes. No
app_settings App Settings is a key/value pair array of application settings, this should be used for settings such as media storage location No
system_settings System Settings is a key/value pair array of system settings, this should be used to send values of important system settings to Signagelive. No

Field Definitions:

system:
Name Description Required
name Device/NetBIOS name Yes
operating_system_name Operating system name Yes
operating_system_version Operating system version Yes
manufacturer Computer manufacturer Yes
model Computer model Yes
up_time Up time in seconds Yes
system_time Current system time Yes
time_zone The Time Zone ID of the time zone that the player is set to. This must be one of oursupported time zones. Yes
utc_offset An integer value representing the offset of the local time zone from UTC, in minutes. Yes

client:
Name Description Required
version Software/firmware version Yes

cpu:
Name Description Required
name CPU Model name Yes
speed CPU Speed in MHz Yes
usage Percent CPU usage at the time the report is generated Yes

memory:
Name Description Required
total_available Total RAM available in megabytes Yes
total_used RAM used in megabytes Yes
storage:
Name Description Required
name The name of the partition/drive Yes
format The file system format. Yes
total_available Total storage available in megabytes Yes
total_used Storage used in megabytes Yes
temperature:
Name Description Required
sensor_name The name of the temperature sensor. Yes
temperature Temperature value. Yes
temperature_units Units for ‘temperature’. Valid units are ‘celsius’, ‘fahrenheit’ or ‘kelvin’. Yes

graphics_devices:
Name Description Required
name The name of the graphics device Yes
current_resolution_horizontal The horizontal resolution. Yes
current_resolution_vertical The vertical resolution Yes

network_adapters:
Name Description Required
type The type of network adapter. Supported values are:

  • ethernet
  • wifi
  • mobile
Yes
use_dhcp A boolean value to indicate whether or not the adapter is DHCP enabled Yes
ipv4_address The IPv4 address assigned to the adapter Yes
subnet_mask The subnet mask Yes
default_gateway The default gateway Yes
dns1 Primary DNS Yes
dns2 Secondary DNS Yes
mac_address The MAC address of the network adapter, without byte separators. Yes
installed_applications:
Name Description Required
display_name The display name of the application Yes
publisher The publisher of the application Yes
version The version of the application Yes

running_processes:
Name Description Required
name The name of the running process Yes
description The description of the running process Yes
average_cpu_usage Average CPU usage Yes
average_memory_usage Average memory usage Yes
current_cpu_usage Current CPU usage Yes
current_memory_usage Current memory usage Yes
app_settings:

App Settings is a key/value pair array of application settings. This should be used for settings such as media storage location and other application specific settings. The following key values are reserved. The do not need to be used, however if used they must be used for the described purpose.

Key Value Description
media_storage The location on the device file system where media is stored.
log_storage The location on the device file system where logs are stored.
system_settings:

System Settings is a key/value pair array of system settings, this should be used to send values of important system settings to Signagelive. The following key values are reserved. The do not need to be used, however if used they must be used for the described purpose.

Key Value Description
ewf_status For Windows based PCs, the status of the Enhanced Write Filter, on/off.
tray_notifications The status of tray icon notifications, on/off.
Suggest Edit