This article covers the following steps:
Using Real-Time Events (RTEs), you can send HTTP messages from the player based on any of four events occurring (please see this overview article for more details).
Requirements before you begin:
A supported player (BrightSign/PC Appliance, Chrome OS) that is activated against a valid Signagelive licence
An active endpoint to get HTTP messages
HTTP messages are network-based data commands that can be sent on the LAN or across the Internet and are typically used to integrate with software solutions. For instance, your signage display might be linked to an audience measurement platform for real-time analytics.
Configure an RTE over HTTP
Login to your Signagelive network.
Go to Settings > Real Time Events.
Click on the blue "+" button, and select Custom Event.
Name your event (this will be saved as a template).
Set the Cache Expiry (The period of time in seconds that the player should cache and retry failed requests before discarding them. Leave as zero to cache failed request indefinitely).
Select whether it is to be Enabled On All Supported Players and Assets.
You now have a choice of when the RTE is to occur, select the appropriate tabs from Asset Download, Asset Start, Asset Complete or Asset Remove.
Within the tab, select HTTP.
You will now be presented with the option to set.
Type - either GET, PUT or POST (these will be defined by the system you are integrating with) GET will request data PUT and POST will send data.
URL.
Headers (This is information about the request being sent; it is optional, but most systems will use headers).
Body (This is the actual JSON data that is being sent).
Placeholder Values (These are placeholders for your data fields in the url, headers or body). The Placeholder Fields will determine which Values, Data Types and Formats you can set. There are no limits to the number of Placeholders you can have).
Example HTTP Request (body only)
The Body tab allows you to build a JSON template that will be sent when the event is fired. The example above shows how a simple Proof of Play integration may be configured.
Here is an example of what you can input into a JSON object inside the body tab. This is the actual request that will be sent each time this RTE is sent to your HTTP URL:
{
"serialNumber":"$player_serial_number$",
"description":"$player_description$",
"address1":"$player_address_1$",
"address2":"$player_address_2$",
"city":"$player_city$",
"state":"$player_state$",
"zip":"$player_zip$",
"ref1":"$player_ref_1$",
"ref2":"$player_ref_2$",
"ref3":"$player_ref_3$",
"ref4":"$player_ref_4$",
"ref5":"$player_ref_5$",
"ref6":"$player_ref_6$",
"ref7":"$player_ref_7$",
"ref8":"$player_ref_8$",
"ref9":"$player_ref_9$",
"ref10":"$player_ref_10$",
"asset":{
"id":"$assetid$",
"name":"$assetName$"
},
"start":"$starttime$",
"end":"$endtime$",
"reason":"$reason$"
}All of the field values are placeholders (see section below) which will be replaced at run time with dynamic values from the player however could be static values if a dynamic value is not required.
Simple Example of a HTTP request
A simplified example of this technology would be the use of a local trigger to interrupt content based on an Asset Completing its playback:
Content-type: application/json
Method: POST
URL: http://localhost:6200/interrupts/trigger
{
"triggerKey": "A"
}
Placeholder Values Configuration
On the placeholder values tab, you can specify how the player replaces each placeholder with actual data at run time:
Specify the name of the placeholder carefully ensuring the name of each placeholder matches those you have specified in either the Url, Header or Body sections.
You can either select a dynamic data field or a value
Some fields will give you formatting options for example:
Date times and ID fields can be formatted to match the API you are integrating with
Setting a value here may be helpful if it is likely to change, as this is simpler than editing the JSON template
You can also specify the data type for the value, which will alter the formatting, e.g. wrapping strings with quotation marks.
Placeholder Values are essential as they allow you to insert dynamic values. When adding placeholders to your RTE configuration, they are wrapped with $ symbols to easily identify them and segment them from common key or data values.
Available Data Fields
The following data fields are exposed on the media player:
All Events
Field Name | Description |
clientDetails.signageliveSerialNumber | Value of Player Serial number |
clientDetails.description | Value of Player Name entered into the UI for the specific player |
clientDetails.address1 | Value of Player Address 1 entered into the UI for the specific player |
clientDetails.address2 | Value of Player Address 2 entered into the UI for the specific player |
clientDetails.city | Value of Player City entered into the UI for the specific player |
clientDetails.state | Value of Player County entered into the UI for the specific player |
clientDetails.zipCode | Value of Player Post Code entered into the UI for the specific player |
clientDetails.referenceCode1 | Value of Player Reference Code 1 entered into the UI for the specific player |
clientDetails.referenceCode2 | Value of Player Reference Code 2 entered into the UI for the specific player |
clientDetails.referenceCode3 | Value of Player Reference Code 3 entered into the UI for the specific player |
clientDetails.referenceCode4 | Value of Player Reference Code 4 entered into the UI for the specific player |
clientDetails.referenceCode5 | Value of Player Reference Code 5 entered into the UI for the specific player |
clientDetails.referenceCode6 | Value of Player Reference Code 6 entered into the UI for the specific player |
clientDetails.referenceCode7 | Value of Player Reference Code 7 entered into the UI for the specific player |
clientDetails.referenceCode8 | Value of Player Reference Code 8 entered into the UI for the specific player |
clientDetails.referenceCode9 | Value of Player Reference Code 9 entered into the UI for the specific player |
clientDetails.referenceCode10 | Value of Player Reference Code 10 entered into the UI for the specific player |
Media Asset Downloaded
Field Name | Description |
mediaAsset.externalId | ID of the Media Asset - Type should be specified as ID and a formatter set to either int or string, see below for ID Type formatters. |
mediAsset.name | Name of Media Asset file |
Media Asset Play Start
Field Name | Description |
pma.externalId | ID of the Playlist Media Asset - Type should be specified as ID and a formatter set to either int or string, see below for ID Type formatters |
pma.mediaAsset.externalId | ID of the Media Asset - Type should be specified as ID and a formatter set to either int or string, see below for ID Type formatters |
pma.mediaAsset.name | Name of Media Asset file |
start | Start time of the media asset
Must be set to a datetime however can be formatted, see data formatters |
Media Asset Play Complete
Field Name | Description |
pma.externalId | ID of the Playlist Media Asset - Type should be specified as ID and a formatter set to either int or string, see below for ID Type formatters |
pma.mediaAsset.externalId | ID of the Media Asset - Type should be specified as ID and a formatter set to either int or string, see below for ID Type formatters |
pma.mediaAsset.name | Name of Media Asset file |
start | Start time of the media asset
Must be set to a datetime however can be formatted, see data formatters |
end | End time of the media asset
Must be set to a datetime however can be formatted, see data formatters. |
startReason | String detailing why the asset played |
endReason | String detailing why the asset stopped |
Media Asset Removed
Field Name | Description |
mediaAsset.externalId | ID of the Media Asset - Type should be specified as ID and a formatter set to either int or string, see below for ID Type formatters |
mediAsset.name | Name of the Media Asset |
Special Values
The following special values will be supported and will be dynamically inserted by the media player
Field Name | Description |
$now$ | This will insert the current date time into the request object |
ID Formatters
Formatter | Example | Comments |
int | This will return the Signagelive object ID in int format as exposed by the Network API |
|
string | This will return the Signagelive Object ID in the format returned by the Player API |
|
If a formatter is not specified the data will be returned using the string formatter.
Date Time and Formatters
Dates will be returned by default in ISO 8601 format e.g. 2012-12-31T23:59:59Z if no formatter is provided, to specify a formatter add to the Placeholder Config for the placeholder a format field with a value below:
Formatter | Example | Comments |
ISO8601 | 2012-12-31T23:59:59Z |
|
| epochSeconds | Returns the date time expressed in whole seconds since the epoch |
Custom[format specifiers] | Custom[yyyy-MM-dd:hh:MM:ss] | See below for descriptions of each time component |
Format Specifier | Description | Example |
d | The day of the month, from 1 through 31. | 2009-06-01T13:45:30 -> 1
2009-06-15T13:45:30 -> 15 |
dd | The day of the month, from 01 through 31 | 2009-06-01T13:45:30 -> 01
2009-06-15T13:45:30 -> 15 |
h | The hour, using a 12-hour clock from 1 to 12. | 2009-06-15T01:45:30 -> 1
2009-06-15T13:45:30 -> 1 |
hh | The hour, using a 12-hour clock from 01 to 12. | 2009-06-15T01:45:30 -> 01
2009-06-15T13:45:30 -> 01 |
H | The hour, using a 24-hour clock from 0 to 23. | 2009-06-15T01:45:30 -> 1
2009-06-15T13:45:30 -> 13 |
HH | The hour, using a 24-hour clock from 00 to 23. | 2009-06-15T01:45:30 -> 01
2009-06-15T13:45:30 -> 13 |
m | The minute, from 0 through 59. | 2009-06-15T01:09:30 -> 9
2009-06-15T13:29:30 -> 29 |
mm | The minute, from 00 through 59. | 2009-06-15T01:09:30 -> 09
2009-06-15T01:45:30 -> 45 |
M | The month, from 1 through 12. | 2009-06-15T13:45:30 -> 6 |
MM | The month, from 01 through 12. | 2009-06-15T13:45:30 -> 06 |
s | The second, from 0 through 59. | 2009-06-15T13:45:09 -> 9 |
ss | The second, from 00 through 59. | 2009-06-15T13:45:09 -> 09 |
t | The first character of the AM/PM designator. | 2009-06-15T13:45:30 -> P |
tt | The AM/PM designator. | 2009-06-15T13:45:30 -> PM |
yyyy | The year as a four-digit number. | 0001-01-01T00:00:00 -> 0001
0900-01-01T00:00:00 -> 0900
1900-01-01T00:00:00 -> 1900
2009-06-15T13:45:30 -> 2009 |
Applying an HTTP RTE Template
Once you have created your template you can configure them against the network, player(s) or media asset(s) as desired. These are explained below:
Network
This will enable the RTEs across all supported players and assets on your Signagelive network. You enable this by:
Going to Settings > Real Time Events.
Select the RTE you would like to configure.
Select the tick box labelled Enabled On All Supported Players and Assets.
Player
This will enable RTEs for all assets played by the player. You can do this by:
Going to Network > Manage.
Selecting the Player you would like to configure.
Navigate to the Real Time Events tab on the far right.
Select the RTEs that you would like to enable.
Please Note: Only players that Support Real Time Events will show the RTE tab.
Media Asset
This will enable RTEs on the specific Media Assets that you select, and will therefore apply whenever the asset is published to a supporting Player.
Go to Content > Playlists.
Select the desired Media Asset(s) from your Library.
Go to the RTE Tab.
Click the blue "+" button.
Select from Template or Custom Events.
Select or configure the desired event.
Please Note
It is possible to have multiple RTEs defined, for example: on an asset set a serial RTE to control lighting and on the player set a HTTP RTE to send PoP data to a 3rd party system.
If you configure the same RTE on all 3 levels (Network, Player and Asset), then it will be executed 3 times.
It is recommended that you create these as templates for the whole network using the numbered steps at the top above. This ensures that the RTEs you create can be reused or applied to different assets. If you create them against specific assets, they cannot be transferred and will need to be created again.