Xibo Media Distribution Service - Creating a Player
On this page
XMDS
Xibo Media Distribution Service (XMDS) is a SOAP API published by the CMS and consumed by the Player applications. It is described by a WSDL which can be parsed by many IDEs and tools to produce client methods to call the API (for example you can set up a web reference in Visual Studio).
The SOAP service is published over HTTP and HTTPS. HTTPS is the recommended end point and the only option if your CMS runs on the Xibo in the Cloud service.
Information Exchange
The following pieces of information are exchanged between the CMS and the Players at regular intervals. The exact interval is defined by the collectionInterval
configured for the Display.
- Register
- Required Files
- Schedule
- File Download
- Resource Download *
- Media Inventory Status
- Logging
- Proof of Play Statistics
The 1.7 CMS introduced 2 more
- Screenshot *
- Status *
The 3.0 CMS introduced 1 more
- Report Faults (processed from 3.1 onward)
The starred services communicate outside the collection interval because they are driven be events that occur during normal running of the player.
Security
The CMS is configured with a secret CMS key
which is a required parameter for all information exchange. The Player is assigned a hardware key
which is used to identify the player as a Display in the CMS. HTTPS is recommended at all times to prevent the discovery of this information by a 3rd party.
Versioning
The API provides various schema versions:
- v3 - for use by players prior to 1.7
- v4 - for use by players 1.7
- v5 - for use by players 1.8+
- v6 - for use by players 3.0+
A v3
player will only be allowed to connect if it has already been registered to the CMS. This encourages new players to be commissioned with the latest versions. v5 will allow v4 registrations but will prevent access to XMR.
The XMDS schema version is only incremented when a breaking change is introduced.
Methods
Information exchanged between the Player and CMS is driven by the Player connecting to the CMS and calling the appropriate method.
Life Cycle
It is the decision of the author to decide how the XMDS service is called, however the current players implement guidelines which produce a stable, reliable result.
There are two types of calls, those that happen on the collection interval and those than happen at run time.
Collection Interval
Each collection interval a set of calls are made to the CMS - some of which can be run in parallel. The required sequence is shown in the numbered list below.
- Register Display
- Required Files
- Schedule
- Get File / Resource
- Media Inventory
- Submit Stats
- Submit Logs
- Report Faults
The Player must call RegisterDisplay
first and parse the response from the Player, if it is not registered it should stop there and not call the subsequent methods. In this case it is common to check at the next collection interval.
The Windows Player calls RegisterDisplay
during its configuration in the Player Options screen. Even so it must also be called on a timer so that updated settings are received and processed.
Once registered the player may then call RequiredFiles
and Schedule
. It is important that all Layouts in the Schedule
are checked for validity before they are shown as they will appear in Schedule
and RequiredFiles
at the same time and may not get have all their files downloaded.
Upon a successful call to RequiredFiles
the Player must parse the response and queue a GetFile
request for each layout, media and/or resource required file.
Upon a successful call to Schedule
the Player must parse the response and determine which Schedules should be put in rotation based on their from
and to
dates.
Each time a GetFile
call completes the Player should call MediaInventory
with the status of each Required File vs. its cache of those files.
Once complete the Player may submit its cached Stat/Log records to the CMS for processing.
Introduced in Soap6 and processed from 3.1 CMS version onward ReportFaults
allows Players to send a JSON string with details about the encountered problem.
Run Time
The run time calls occur outside the normal collection interval and are executed in response to certain events.
Resource Download
When a Media item is shown on a Layout by the Player it may be necessary to get an updated set of “resource content”. This content is CMS provided HTML that represents how the Player should display the Media. It should be downloaded and shown in a web view.
Resource content should always be cached locally so that the Player can decide the content is fresh or in the event the CMS is unavailable.
Submit Screen shot
The Player can submit a screen shot of the current output to the CMS.
Notify Status
The player should notify the status when the storage usage significantly changes and when a new layout is shown (if notify current layout is set).
Rate Limiting
XMDS itself does not implement rate limiting, however it is common for service providers (including Xibo in the Cloud) to add rate limiting at their service loadbalancer or proxy. For this purpose it is important to append the method being called to all XMDS requests. This is done using a query parameter, so //xmds.php?v=5&method=RegisterDisplay
.
It is important to adopt this convention when implementing a Player because requests without the method
query parameter are often rate limited severely.
Rate Limited requests will return the HTTP 429 response code and a Retry-After
header. The Player should repeat the request after waiting the time specified in Retry-After
. If the Retry-After
is not present it is convention to wait for the collection interval.
The Xibo in the Cloud rate limit requirements are documented against each method below, but keep in mind that these may not be the same for all service providers.
Definition v4/v5/v6
The definition of the SOAP service can be automatically consumed from the WSDL at //xmds.php?v={versionNumber}&wsdl
.
There are 2 common parameters to all Method calls:
- serverKey: The secret CMS server key.
- hardwareKey: The Player hardware key used to identify this Player as a Display.
RegisterDisplay
Register Display is used to add a new display to the CMS or receive updated settings for an existing display.
It takes the following parameters:
- serverKey
- hardwareKey
- displayName
- clientType
- clientVersion
- clientCode
- operatingSystem
- macAddress
v5
introduced 2 additional parameters:
- xmrChannel
- xmrPubKey
It returns the following XML string:
<?xml version="1.0" encoding="UTF-8"?>
<display date="2015-01-01 00:00:00" timezone="Europe/London" status="0" code="READY" message="Display is active and ready to start." version_instructions="" localDate="2015-01-01 00:00:00 +/- timezone">
<settingsNode>One or more settings nodes</settingsNode>
<commands>
<commandName>
<commandString></commandString>
<validationString></validationString>
</commandName>
</commands>
</display>
The Player should interpret the code
attribute on the root node to see if the Display has been granted access and “licensed” with the CMS. An administrator can licence a display by logging into the Web Portal, Editing the Display and selecting Licence = Yes.
The settingsNodes
are dependent on the clientType
provided.
The <commands>
element was introduced in v5
and contains a list of commands and their command strings. The <commandName>
changes with each command to indicate the actual command code as registered in the CMS.
The localDate
attribute is only available in CMS 1.8 and above (v5
and v4
) and will provide the local display date/time according to the Display Timezone setting configured in the Display Profile.
XMR
When connected to a v5
CMS the player is expected to generate a RSA pub/private key and a unique channel. It is expected to provide these details to the CMS on each register call.
The CMS will use the pub key to encrypt any messages sent to the Player on the XMR Public Address. The Player should subscribe to the XMR Public Address using the Channel it sent to RegisterDisplay
.
Messages sent through XMR are encrypted using openssl_seal
and should be decrypted accordingly.
Please see here for more information.
RequiredFiles
The required files method returns all files needed for the Player to play its scheduled Layouts entirely offline for the quantity of time specified by the REQUIRED_FILES_LOOKAHEAD
setting in the CMS. This setting defaults to 4 days.
It takes the following parameters:
- serverKey
- hardwareKey
It returns the following XML string:
<?xml version="1.0" encoding="UTF-8"?>
<files>
<file type="media" id="493" size="40408" md5="c90a4c420dd010a5e95dedb8927a29e7" download="xmds" path="weathericons-regular-webfont.woff" />
<file type="layout" id="29" size="303" md5="5e6ef3b612b39c83bf8c5cf9f2a75ef5" download="xmds" path="29" code="layoutCode" />
<file type="resource" id="29" layoutid="1" regionid="3" mediaid="5" updated="102984759" />
</files>
From CMS version 3.1 onward, an additional node purge
will be present in the XML string:
<purge>
<item id="149" storedAs="149.jpg"/>
<item id="63" storedAs="63.jpg"/>
</purge>
Each file
node contains the following attributes:
- type: Either media, layout or resource
- id: A unique ID for the file
Layout and Media file nodes also contain:
- size: The file size
- md5: A MD5 of the file to be used as a checksum
- download: Either
xmds
orhttp
- path: The intended save path
Layout file nodes also contain:
- code: An optional attribute indicating if this Layout has a Layout Code set (applicable from v3.0)
Resource file nodes also contain:
- layoutid: The layoutId that references this resource.
- regionid: The regionId that references this resource.
- mediaid: The mediaId that references this resource.
- updated: A timestamp indicating the last time this resource was updated.
Each item
in purge
node contains following attributes:
- id: Media ID set to be purged
- storedAs: the name of the file in Player local storage
The required files XML should be parsed and any files that are missing from the local cache OR that have a different MD5 should be downloaded again.
Files in purge node should be removed from the Player local storage.
Download Type
The CMS supports downloading files over XMDS directly or over directly over HTTP. If HTTP downloads are enabled the path
attribute will contain a fully qualified download path and a new attribute named saveAs
will be present showing the intended save path.
HTTP downloads are only valid for one usage and are refreshed with a new path
each time RequiredFiles
is called after the CMS sees a change in content that would require the Player to download new media items. This means that RequiredFiles will ordinarily contain links to download content which are not valid any longer if the Player has reported to the CMS that it has downloaded those files successfully.
When the download mode is xmds
the Player should call GetFile
.
Resource Files
Resource files are downloaded using the GetResource
call. The Player implementation is free to save these files with whatever name is most suitable. The Layout XML contains the layout, region and media Ids that can be used to return the relevant cached resource file.
GetFile
The GetFile
method is used to request a chunk (part) of a specific file id. This file must have been present in the RequiredFiles
return otherwise it will not be served.
The chunkSize
is left to the implementer and should be suitable for the type of network the Player is installed on. It should be noted that the smaller the chunkSize
, the more I/O load there will be on the CMS.
It takes the following parameters:
- serverKey
- hardwareKey
- fileId: The ID of the file being downloaded.
- fileType: The type of the file being downloaded.
- chunkOffset: The offset for the current file chunk being requested. Starts as 0.
- chunkSize: The size for the current file chunk.
It returns base64 encoded binary data representing the requested file, offset and size. The Player is responsible for reassembling the file and checking the MD5 of the completed file against the one provided in RequiredFiles
.
GetResource
The GetResource
method is used to request the HTML representation of a media item on a Layout in a Region. The CMS will calculate the necessary HTML to correctly display that media item once opened in a correctly sized webview.
The Layout XLF determines when a resource file should be loaded or when a native component is needed.
MediaInventory
The MediaInventory
method is used by the Player to update the status of its cached files in the CMS. The CMS uses this information to present the status of each Display in the “Displays” page.
It takes the following parameters:
- serverKey
- hardwareKey
- mediaInventory: XML representation of currently cached files vs required files.
Media Inventory
The XML structure for media inventory is:
<files>
<file type="media|layout|resource" id="1" complete="0|1" md5="c90a4c420dd010a5e95dedb8927a29e7" lastChecked="1284569347" />
</files>
- type: the type of file being reported for, either media, layout or resource
- id: the ID of the file.
- complete: whether the file is complete or not.
- md5: the md5 of the file in the local cache.
- lastChecked: a unix date/time for when the file was last by the player checked.
Schedule
The Schedule
method call provides the Player with a date/time aware set of Layouts that need to be played. The time window of schedule returned is controlled by the CMS setting REQUIRED_FILES_LOOKAHEAD
if the SCHEDULE_LOOKAHEAD
setting is On
.
It takes the following parameters:
- serverKey
- hardwareKey
It returns XML in the following format for v5/v6:
<schedule>
<default file="4">
<dependants>
<file>5.jpg</file>
</dependants>
</default>
<layout file="5" fromdt="" todt="" scheduleid="" priority="" shareOfVoice="" duration="" isGeoAware="" geoLocation="" cyclePlayback="" groupKey="" playCount="">
<dependants>
<file>5.jpg</file>
</dependants>
</layout>
<dependants>
<file>5.jpg</file>
</dependants>
<command code="CODE" date="" />
<overlays>
<overlay file="5" fromdt="" todt="" scheduleid="" priority="" isGeoAware="" geoLocation=""></overlay>
</overlays>
<actions>
<action fromdt="" todt="" scheduleid="" priority="" isGeoAware="" geoLocation="" syncEvent="" triggerCode="" actionType="" layoutCode="" commandCode=""/>
</actions>
</schedule>
The shareOfVoice
property may not be present if the CMS is a version earlier than 2.2. If it doesn’t exist the Player should assume a value of 0.
The isGeoAware
and geoLocation
properties may not be present if the CMS is a version earlier than 2.3.
The duration
property may not be present if the CMS is a version earlier than 2.3.10.
The actions
node was introduced in 3.1 CMS version.
The cyclePlayback
, groupKey
and playCount
properties were introduced in 3.1 CMS version.
It returns XML in the following format for v4 and below:
<schedule>
<default file="4" />
<layout file="5" fromdt="" todt="" scheduleid="" priority="" dependents="" />
<dependants>
<file>5.jpg</file>
</dependants>
</schedule>
The from and to dates are ISO formatted dates in the CMS time zone.
Default Layout
If there aren’t any Layouts in the Schedule window then the default Layout should be shown. If the Display is set to interleave default in the CMS then the Layout will appear as a <layout>
element and no additional logic is required.
Priority
The priority attribute determines whether a Layout is in the priority schedule or normal schedule. Priority schedules should be shown in preference to normal ones.
The attribute will either be empty or contain an integer value - when empty a value of 0 should be assumed. Only the highest priority layouts should be included in the schedule at any time.
Dependants
A list of global dependencies is provided in the dependents
element. This is a list of files that must be in the cache before any Layouts can be considered valid. These global dependencies are provided as the first entries in RequiredFiles
XML.
A Layout may also have dependants specific to itself and these are provided either as an attribute on the layout node (v3,v4) or as a <dependents>
child node (v5). Layout specific dependants should be checked in the off-line cache before the Layout is considered for playback.
Starting in v5 the default layout also has a <dependents>
child node.
Overlays
Starting in v5 overlay nodes may be provided in the overlays element. These describe layouts that should be overlaid on top of the normal layout schedule.
Overlays have a from/to dt, scheduleId and priority which have the same meaning as a normal layout
node. The order of overlay
nodes determines the order in which the overlay
layout regions should be applied, starting with the first and stacking on top.
Overlays should be applied on top of the existing Layout schedule and remain there while they are still considered to be in the schedule.
Share of Voice
Starting in v5 and in CMS versions of 2.2 and later, the shareOfVoice
property greater than 0 on a Layout indicates that the event should be considered an Interrupt Layout. Interrupt Layouts should be parsed into a separate schedule list by the Player and treated differently to the normal flow of events.
The share of voice parameter indicates the percentage of time which should be given aside to the Interrupt Layout. Interrupt Layouts appear in the schedule with all the usual properties of a normal layout, such as priority, display order, geoaware, etc. The player should make a list of normal and a list of interrupt layouts and then combine them such that an entire hour is represented and the share of voice requirements met.
A layout should always play through from start to finish - the purpose of an interrupt layout is to interrupt the normal schedule with an extra ordinary event.
Note: prior attempts at this functionality used a pause/resume methodology to interrupt the currently running normal layout and continue once the interrupt had completed. This proved unreliable and the methodology was changed as above in time for the later v2 players. We recommend any new player implementations use the newer methodology for consistency.
Actions
CMS version 3.1 and later, the actions
node was added to the schedule XML.
The action
nodes are generated from an event type introduced in CMS version 3.1 called Action, which allows for scheduling an interactive Action directly to the Player.
There are two use cases:
- Command :
actionType
parameter set tocommand
andcommandCode
that should be executed whentriggerCode
webhook is sent to the Player. - Layout :
actionType
parameter set tonavToLayout
andlayoutCode
with code identifier of the Layout that should be displayed whentriggerCode
webhook is sent to the Player. The Layout linked to this action type will be included in RequiredFiles XML.
Cycle Based Playback
CMS version 3.1 and later, the The cyclePlayback
, groupKey
and playCount
properties were introduced.
Campaigns can be configured to use cycle based playback with specified playCount, when one of such Campaigns is scheduled to the Player, the mentioned properties will be populated in Schedule XML.
The cyclePlayback
property comes from the Campaign, if it is enabled, then two following properties should be correctly interpreted by the Player.
The groupKey
is the ID of the scheduled Campaign, which helps the Player to recognise which Layouts are grouped in the same Campaign.
The playCount
is a number of plays should each Layout in the same group have before moving on.
SubmitLog
The SubmitLog
method is used by the Player to send useful audit/error logging information back to the CMS. The log messages should be kept to a minimum to prevent unnecessary traffic. The log level is defined in the Display Settings and defaults to “error”.
It takes the following parameters:
- serverKey
- hardwareKey
- logXml: XML representation for Log Messages
Be kind to your CMS! Log messages should be batched in packages of no more than 50 records. If a backlog of messages is building, 300 records can be sent at one time until the backlog has been cleared.
Log XML
The structure for Log XML is as follows:
<logs>
<log date="Y-m-d H:i:s" category="">Message</log>
</logs>
or it can provide more information
<logs>
<log date="Y-m-d H:i:s" category="">
<type>type</type>
<type>thread</type>
<type>method</type>
<type>message</type>
<type>scheduleID</type>
<type>layoutID</type>
<type>mediaID</type>
</log>
</logs>
- date: The local date, ISO formatted.
- category: Either error or audit. Audit messages are discarded unless auditing is switched on globally and on the display.
- type (optional): The type.
- message: The log message
- method (optional): The method.
- thread (optional): The Thread that the log message executed on.
SubmitStats
The SubmitStats
method is used to report Proof of Play statistics to the CMS.
It takes the following parameters:
- serverKey
- hardwareKey
- statXml: XML representation for Proof of Play Statistics
Be kind to your CMS! Stats messages should be batched in packages of no more than 50 records. If a backlog of messages is building, 300 records can be sent at one time until the backlog has been cleared.
Stat XML
The structure for Stat XML is as follows:
<stats>
<stat type="" fromdt="" todt="" scheduleid="" layoutid="" mediaid="" duration=0 count=1></stat>
</stats>
- type: The type of stat record, either layout or media.
- fromdt: The ISO date that the layout/media started playing.
- todt: The ISO date that the layout/media finished playing.
- scheduleid: The ID of the schedule that caused the Layout/Media to be shown.
- layoutid: The layoutId.
- mediaid: The mediaId.
- duration: The number of seconds for this record (if Hourly/Daily aggregation is enabled this will not be equal to the from/to dates)
- count: The number of events represented by this record (if Individual records are enabled this will always be 1).
Aggregation Level
Starting from v5 and CMS 2.1 or later, a Player can be configured to collect statistics in 3 aggregation levels:
- Individual
- Hourly
- Daily
When in Hourly or Daily the Player should aggregate the statistics records to either the hour or day accordingly, before they are sent. Events which cross the aggregation period (e.g. 22:56 to 23:02) should be split between hours. 4 seconds in the 22:00 period and 2 seconds in the 23:00 period.
This also means that the Player must wait until the period is over before sending statistics - i.e it cannot send 22:00 to 23:00 until after 23:00. For more information see collecting proof of play.
NotifyStatus
The NotifyStatus
method is used by the Player to update the CMS on various events in the Player life cycle.
It takes the following parameters:
- serverKey
- hardwareKey
- status: JSON encoded key/value string of properties to update on the display.
Properties supported by status
are:
{
"currentLayoutId": "The ID of the Current Layout",
"availableSpace": "The bytes of available space",
"totalSpace": "The bytes of total space",
"lastCommandSuccess": "Whether or not the last received Command was executed successfully",
"deviceName": "The name of the physical device",
"timeZone": "An IANA timezone identifier for the Displays timezone",
"latitude": "The current or last known latitude",
"longitude": "The current or last known longitude",
"statusDialog": {} // A json string representing up to date status information from the player
}
SubmitScreenShot
The SubmitScreenShot
method call is used by the Player to send a screen shot of the current playback to the CMS. The instruction to send a screen shot appears in the RegisterDisplay
call settings.
It takes the following parameters:
- serverKey
- hardwareKey
- screenShot: Base64 encoded binary representation of the screen shot image.
ReportFaults (Soap6)
The ReportFaults
method is used by the Player to send details about any issues it encountered back to the CMS.
This data is then presented on the Display Manage page in the CMS.
It takes the following parameters:
- serverKey
- hardwareKey
- fault: JSON encoded key/value string of properties with fault details.
Properties supported by fault
are :
{
"code": "The error code (integer)",
"reason": "The reason of the fault (string)",
"date": "The date the incident occured (dateTime string, Format Y-m-d H:i:s)",
"expires": "The date the fault expires (dateTime string, Format Y-m-d H:i:s)",
"layoutId": "The ID of the affected Layout (integer)",
"regionId": "The ID of the affected Region (integer)",
"widgetId": "The ID of the affected Widget (integer)",
"scheduleId": "The ID of the affected Schedule event (integer)",
"mediaId": "The ID of the affected Media (integer)"
}
Rate Limiting
Your CMS may issue a 429
HTTP response code to rate limit your requests. If you receive a 429 response code the CMS is too busy to service your request and you should try again later. A Retry-After
header will be included which gives a number of seconds you should wait before retrying.