The Condition action allows third-party applications to communicate with a BroadSign Player, activating specific pieces of content for playback on the screen.
Conditions are programmed in BroadSign Administrator and are associated to either the bundle or the campaign. A specified condition must be met on the player in order for the associated content to be played.
A typical example would be two ad copies: one to play when it is raining outside, and one to play when it is sunny. A third party application could periodically check a weather feed and set the appropriate “Rainy” or “Sunny” condition in the player, causing it to display weather-sensitive content.
condition Action
You can call the Incident API using one of the following methods:
remote_action
: Exposes thecondition
action via the command-lineremote_action
tool.- XML: Exposes the
condition
action through simple XML commands sent to port 2324. - JSON: Exposes the
condition
action by sending JSON messages to the WebSocket server (port 2326). - Flash: Flash applications can call the API via ActionScript and the
condition
action.
A condition can be toggled on a player by invoking the standalone executable remote_action
which ships with BroadSign Player. It can be found in the player’s installation bin directory.
For example, to set a condition, type:
remote_action condition -e 1 -n "Cloudy Skies"
condition
is the action type, -e
is for enable and -n
is the name of the condition.
Continuing the example above, the equivalent command to deactivate this condition would be:
remote_action condition -e 0 -n "Cloudy Skies"
When you generate a playlist after setting a condition, by default the player will keep track of all the items played. Whenever you apply that same condition, it will continue from where it left off. If you require a different behavior, and want to reinitialize the conditional playlist, then you should use a regenerate option -r
:
remote_action condition -r 1 -e 1 -n "Cloudy Skies"
List all active conditions on a player:
The following allows you to list all conditions currently active on a player:
remote_action condition --la
A custom application can set and remove conditions on BroadSign Player by sending an XML message to the monitor_remote
port (2324).
<rc version="1" id="1" action="condition" enabled="1" name="cloudy"/>\r\n\r\n
The player will respond with the following document:
<rc id="1" version="1" action="condition" status="1"/>
When you generate a playlist after setting a condition, by default the player will keep track of all the items played. Whenever you apply that same condition, it will continue from where it left off. If you require a different behavior, and want to reinitialize the conditional playlist, then you should use the regenerate
option:
<rc version="1" id="1" action="condition" enabled="1" name="cloudy" regenerate="1"/>\r\n\r\n
List all active conditions on a player:
You can create a custom application to list all active conditions on a player. Send an XML message to the monitor_remote
port (2324):
<rc version="1" id="1" action="condition" list_active="1" />\r\n\r\n
The player will output the following XML document:
<?xml version="1.0"?>
<active_conditions>
<condition id="12323" name="Sunny"/>
<condition id="13323" name="Warm"/>
</active_conditions>
Conditions API – XML Parameters
Parameter | Description |
---|---|
version |
The version is always 1. |
id |
Contains the identifier of the request. |
action |
The kind of action to be taken; always condition . |
enabled |
Set to “0″ to disable the condition; set to “1″ to enable the condition. |
name |
The name of the condition to set. This must match the name of the criteria in BroadSign Administrator. Condition matching is case insensitive; however, whitespace must be exact. |
regenerate |
If set to “1”, this parameter enables you to reinitialize the playlist with the same condition. |
list_active |
Use this parameter when you want to list all conditions on the player. |
A custom application can set and remove conditions on BroadSign Player by sending a JSON message to port 2326. You will need to enable the WebSocket server. For more information, see Configuration Profiles – Players – The Remote Control Tab.
{
"rc": {
"version": "2",
"id": "1",
"action": "condition",
"enabled": "1",
"name": "cloudy"
}
}
The player will respond with the following document:
{
"rc": {
"id": "1",
"version": "2",
"action": "condition",
"status": "1"
}
}
When you generate a playlist after setting a condition, by default the player will keep track of all the items played. Whenever you apply that same condition, it will continue from where it left off. If you require a different behavior, and want to reinitialize the conditional playlist, then you should use the regenerate
option:
{
"rc": {
"version": "2",
"id": "1",
"action": "condition",
"enabled": "1",
"name": "cloudy",
"regenerate": "1"
}
}
List all active conditions on a player:
You can create a custom application to list all active conditions on a player. Send a JSON message to the WebSocket server (port 2326):
{
"rc": {
"version": "2",
"id": "1",
"action": "condition",
"list_active": "1"
}
}
The Player will output the following JSON document:
{
"active_conditions": {
"condition": [
{
"id": "12323",
"name": "Sunny"
},
{
"id": "13323",
"name": "Warm"
}
]
}
}
Conditions API – JSON Parameters
Parameter | Description |
---|---|
version |
The version is always 2. |
id |
Contains the identifier of the request. |
action |
The kind of action to be taken; always condition . |
enabled |
Set to “0″ to disable the condition; set to “1″ to enable the condition. |
name |
The name of the condition to set. This must match the name of the criteria in BroadSign Administrator. Condition matching is case insensitive; however, whitespace must be exact. |
regenerate |
If set to “1”, this parameter enables you to reinitialize the playlist with the same condition. |
list_active |
Use this parameter when you want to list all conditions on the player. |
Sample Actionscript
// Start ActionScript 2.0
var theSocket:XMLSocket = new XMLSocket();
theSocket.onConnect = function(myStatus) {
if (myStatus) {
// replace xxxx with the appropriate condition name
var myString:String = "<rc version=\"1\" id=\"1\" action=\"condition\" name=\"xxxx\" enabled=\"1\"/>\r\n\r\n";
theSocket.send(myString);
}
};
theSocket.connect("localhost", 2324);
List all active conditions on a player:
Use the following script to list all active conditions on a player:
// Start ActionScript 2.0
var theSocket:XMLSocket = new XMLSocket();
theSocket.onConnect = function(myStatus) {
if (myStatus) {
var myString:String = "<rc version=\"1\" id=\"1\" action=\"condition\" list_active=\"1\"/>\r\n\r\n";
theSocket.send(myString);
}
};
theSocket.connect("localhost", 2324);