Real-time POP API

Real-Time POP API

Broadsign Control can export proof-of-play (POP) data to an external location for input into third-party analytics platforms. You can customize analytics and reporting systems with up-to-the-minute proof-of-play information.

You control the frequency at which you receive the proof-of-play logs. Caching of information protects against network outages. Broadsign will upload the data as soon as the network connection resumes, protecting your statistics’ integrity.

Note: Real-time POP is different from Broadsign POP Log. Whereas real-time POP provides near-live data, Broadsign POP Log exports raw proof of play logs every 24 hours. See Broadsign POP Log.

Prerequisites

Real-Time POP is an intermediate-to-advanced feature of Broadsign Control. Before configuring it, ensure that you are familiar with the following:

Cache Behaviour

The external Real-Time POP API Proof-of-Play reporting mechanism is based on the player's current POP caching behaviour. It means that, if a network outage occurs, all POP is indefinitely stored locally and retried for submission as soon as the network becomes available again.

Note: The Real-Time POP API submits POP to a different URL than the Broadsign Server. It is therefore possible that the Broadsign Server is reachable and ingesting POP correctly, but the configured Real-Time POP server is not. In this eventuality, a given POP record that has been successfully submitted to the Broadsign Server, but not to the Real-time POP API, will be kept and retried for about 30 days (300,000 POP records).

For more information, see The Disk Tab.

Proxy Support

Your external proof of play submissions must respect any proxy settings you have configured in Broadsign Control Player. For more information, see The Proxy Tab.

To receive real-time proof of play data, you will need to enable the feature in a configuration profile for your player.

To configure Real-Time POP:

  1. Create a configuration.
  2. Create a player configuration profile.

  3. Open the configuration profile properties, and go to Integrations > POP.

  4. Configure the real-time POP settings:
    • Enable External POP reporting – Default = false. When enabled, Broadsign Control Player will try to submit proof of play to the external location.
    • External URL – A valid HTTP/HTTPS URL to which the proof of play will be HTTP POSTed. Mandatory if external proof of play is enabled.
    • API Key – Optional. If specified, Broadsign Control Player will submit this string with every HTTP POST request, adding to the security of the external proof of play service.
    • Report POP immediately – If activated, Broadsign will submit proof of play immediately after each playback.
    • Report POP every X seconds – If activated, Broadsign will buffer proof of play client-side and submit it every X seconds. Valid range: 1-65535 seconds. Broadsign applies a +/- 10% randomization client-side to avoid synchronizing the proof-of-play submission.
    • Max POPs per request – Default value: 1000. Valid Range: 1-65535. This setting controls the maximum number of proofs of play to send in one HTTP POST.
    • Verbose mode – Default=Off. When enabled, the proof of play JSON document will be more verbose, that is, it will use dictionaries instead of arrays. See Interpret the JSON Document (Protocol).
  5. Click OK or Apply.

Now you will receive proof of play logs at an external location, at the frequency you want.

Next, we will interpret the JSON document.

Broadsign generates the proof of play as a JSON document via HTTP/HTTP POST. The encoding is UTF-8; the HTTP headers are Content-Type: application/json.

Here is a sample JSON document (using arrays):

Copy 
{
        "api_key": "api_key",
        "player_id": 12345,
        "pop": [
            [display_unit_id, frame_id, n_screens, ad_copy_id, campaign_id, schedule_id, impressions, interactions, “end_time”, duration, “ext1”, “ext2”, "extra_data"],
            [display_unit_id, frame_id, n_screens, ad_copy_id, campaign_id, schedule_id, impressions, interactions, “end_time”, duration, “ext1”, “ext2”, "extra_data"]
        ]
        }

Here is a sample JSON document in verbose mode (using dictionaries):

Copy 
{
        "api_key": "aabbccddeeff",
        "player_id": 12345,
        "pop": [
            {
            “display_unit_id” : 4456,
            “frame_id”: 4457,
            “n_screens” : 1,
            “ad_copy_id” : 5001,
            “campaign_id” :  5002,
            “schedule_id” :  5003,
            “impressions” : 2, 
            “interactions” : 0,
            “end_time” : “2016-05-31T10:14:50.000”,
            “duration” : 5000,
            “ext1” : “bmb”,
            “ext2” : “1234543”,
            "extra_data" : "custom_json"
            },
            {
            “display_unit_id” : 4456,
            “frame_id”: 4457,
            “n_screens” : 1,
            “ad_copy_id” : 5005,
            “campaign_id” :  5006,
            “schedule_id” :  5007,
            “impressions” : 5, 
            “interactions” : 0,
            “end_time” : “2016-05-31T10:14:55.000”,
            “duration” : 15000,
            “ext1” : “”,
            “ext2” : “”,
            "extra_data" : "custom_json"
        }

The invariant parameters are:

Parameter Description
api_key This is the api_key as set in the configuration profile. See Edit Player Properties.
player_id This is the Broadsign Control Player ID# (64-bit unsigned integer). See Edit Player Properties.

The parameters that can vary (per play) are defined in a repeating array in the "pop" section:

Parameter Description
display_unit_id The display unit ID# at time of playback (64-bit unsigned integer). See Edit Display Unit Properties.
frame_id The frame ID# at time of playback (64-bit unsigned integer). See Frames.
n_screens The number of active screens at time of playback (32-bit unsigned integer). See Edit Player Properties.
ad_copy_id The ID# of the ad copy that played (64-bit unsigned integer). See Edit Ad Copy Properties.
campaign_id The ID# of the campaign that played (64-bit unsigned integer). See The General Section.
schedule_id The ID# of the schedule that played (64-bit unsigned integer). See Edit a Schedule.
impressions The number of impressions generated by the content that played (32-bit unsigned integer). See Day Parts Properties.
interactions The number of interactions generated by the content that played (32-bit unsigned integer). See Interactive Campaigns.
end_time ISO 8601 timestamp in local player time that indicates the time at which playback ended. String. See Edit a Schedule.
duration The duration of the playback in milliseconds. 32-bit unsigned int. See Default Pages in the Add Campaign Wizard.
ext1 An extra data field that identifies an external service name, for example, for Broadsign Publish, this field is set to bmb. String. See Broadsign Publish.
ext2

A second extra data field that can be recorded on a proof-of-play. Typically, this is a service-dependent custom field, for example, for Broadsign Publish, this field is the creator_msg_id. String. See Broadsign Publish. See Custom POP Action.
extra_data

Data from the custom_field custom_pop remote action feature. String. See Custom POP Action.

Note: If you have configured the Custom POP Action, the ext1, ext2, and extra_data parameters will contain details of your dynamic content, namely the external_value_1, external_value_2, and custom_field information. See Custom POP Action.

Any request resulting in an HTTP status code in the 2xx class is successful.

Broadsign will assume that any other response code is a failure. Broadsign Control Player will then try to resubmit the data.

Also, Broadsign will open an external incident that will include:

  • the HTTP response code; and,
  • the API endpoint.

Possible errors include:

  • no HTTP response from server
  • SSL error
  • send POP/URL error

Note: External incidents are hidden by default in Broadsign Control Administrator, but will appear when you check "Show External Incidents" in the incident report. Remember to enable incident reporting.