Configuring HTTP Real Time Events
Ian Maison avatar
Written by Ian Maison
Updated over a week ago

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

Using Real Time Events (RTEs) you can send HTTP messages from the player based on any of 4 events occurring (please see this overview article for more detail).

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, you might have your signage display linked to an audience measurement platform for real-time analytics.

To configure an RTE for HTTP Messaging, you can follow the steps below:

  1. Login to your Signagelive network.

  2. Go to Settings > Real Time Events.

  3. Click on the blue "+" button, and select Custom Event.

  4. Name your event (this will be saved as a template).

  5. 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).

  6. Select whether it is to be Enabled On All Supported Players and Assets.

  7. 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.

  8. 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, these are optional, however most systems will make use of 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 of the Values, Data Types and Formats you can set. There are no limits to the number of Placeholders you can have).

Body Configuration

pasted_image_0.png
{
"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$"
}

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.

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.

Placeholder Configuration

On the placeholder values tab you can specify how each placeholder is replaced with actual data at run time by the player.

You need to 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 useful 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 important as that 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.

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

Completing Set Up

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:

  1. Going to Settings > Real Time Events.

  2. Select the RTE you would like to configure.

  3. 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:

  1. Going to Network > Manage.

  2. Selecting the Player you would like to configure.

  3. Navigate to the Real Time Events tab on the far right.

  4. 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.

  1. Go to Content > Playlists.

  2. Select the desired Media Asset(s) from your Library.

  3. Go to the RTE Tab.

  4. Click the blue "+" button.

  5. Select from Template or Custom Events.

  6. 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.

How can I find out more?

You can always search for answers with the Signagelive Help Centre, but rest assured we have a dedicated Support Team that are ready to assist you with any questions you may have. We are always here to help as best we can, so just contact us for any help you require.

Did this answer your question?