Real-Time Audience API Audience Source

The Real-Time Audience API Audience Source is used to configure a player to connect to the Broadsign Control Real-Time Audience API. The Real-Time Audience API allows developers to integrate audience data.

The Real-Time Audience API Audience Source allows you to specify multiple audience URLs, with optional frame criteria. If no frame criterion is specified, the audience URL is used for all frames. If a frame criterion is specified, then the audience URL is used for proof-of-play originating from frames with the associated criterion and bid requests. If a URL has no criterion, it acts as a default fallback URL, which means it will be used when a frame criterion does not match any other URL.

Note: The same ordering applies when a frame has multiple frame criteria that match one or multiple URLs.

The Real-Time Audience API is an advanced feature of Broadsign Control Administrator. Before configuring it, ensure that you are familiar with the following:

The Real-Time Audience API has two measurement components:

  • The "prediction" component – Broadsign Control Administrator requests the API to provide, in advance of the slot, estimated or expected audience numbers for when this slot will come up. This can be requested up to 35 seconds in advance and it is included in Broadsign Reach ad requests.
  • The "measurement" component – Broadsign Control Administrator requests the API to measure, during playback of a slot, the actual audience numbers. The measurement starts at the beginning of the slot and stops when playback completes. This information is reported with POPs.

To include audience data in your reports, you must enable the Audience source in a configuration profile for your player and select the Real-Time Audience API source.

To configure the Real-Time Audience API source:

  1. Create a configuration (see Configurations).
  2. Create a player configuration profile (see Configuration Profiles - Players).
  3. Open the Configuration Profile Properties and go to Integrations > Audience Source (see The Audience Tab).

  4. Configure the Real-Time Audience API source settings:
    • Enable Audience Source – To enable the source, select this box.
    • Audience Source – Select Use Real-Time Audience API.
    • URL – Associate real-time audience sources to specific frames using criteria. Not specifying any criterion is equivalent to targeting all frames. See URL Configuration Option.
    • Send real-time audience data in Reach bid requests – If enabled, the audience URL is queried and submitted as part of the Broadsign Reach Ad Request. Audience is computed by using the real-time audience API with the expected display time of the slot (can be up to a full loop ahead).
    • Use real-time audience data in Broadsign Control Campaign and proof-of-play reports – If enabled, the audience URL is queried and submitted as part of the audience information associated with each Broadsign Control proof-of-play report. If the real-time data source does not provide info for age or gender, then only impressions are recorded.
  5. Click OK or Apply.

You must have a HTTP service up and running, either on a network, or locally. The URL points to that HTTP service, which must return a JSON body. For more information on the API that allows developers to integrate audience data, see Broadsign Control Real-Time Audience API.

You can use variables that dynamically change in the URL. As a result, your playback data will vary depending on the audience data you provide during configuration.

The URL must include the action type at the minimum (pre,start,stop) and can also pass the following variables (see Content Variables):

  • action_name
  • expected_play_time
  • frame_id
  • campaign_id
  • content_id
  • content_name
  • expected_duration
  • app_name
  • player_id
  • display_unit_id
  • external_id
  • location_code
  • latitude
  • longitude

You can update these variables in the Ad Copy Properties - URLs tab (see URLs Tab)

Note: The delimiters for your variables are “{{” and “}}”.

Note: The variable replacement can happen anywhere in the URL except the protocol. Also, you can have multiple variables in the same URL.

To use content variables with the Real-Time Audience API:

For this example, we will set the variables using our configuration profile. To achieve the same results, you can also use the URLs tab in ad copy properties (see URLs Tab).

  1. Under "Associate real-time audience API URLs...", click Add. The Select Resources dialogue box opens.
  2. Under the URL tab, enter the URL.

    3. For example, if the remote URL is:

    http://localhost:10000/audience/{{action_name}}?frame_id={{frame_id}}&content_name={{content_name}}&player_id={{player_id}}

    and the current internal action is "start", frame id is 33333, player id is 555 and content name is "video", the URL requested by the player will be:

    http://localhost:10000/audience/start?frame_id=33333&content_name=video&player_id=555

  3. Under Frame Criteria, select the frame criterion that corresponds to that screen. In our example, we will use "F1".