generate

Description

The generate endpoints are used to generate playlists server-side in Broadsign Air. The following endpoints are available:

Note: Any timestamps included in the playlists will use the timezone configured in Broadsign Control Administrator for the related Display Units. It is essential to ensure that the correct timezone is configured. If no timezone is set, the server will default to GMT+0 for the start and end date of campaigns, schedules, and opening hours under that Display Unit. Different Display Units can be set to different timezones if needed. For more information, see Timezone.

generate v1

generate v1 Endpoint

Version 1 of generate offers basic support to generate playlists.

Features

  • Synchronized Playback: Players with multiple screens must retrieve the same playlists. If several Players want to use the same playlist, they must fetch it with the same player_id, but with a different screen_id.
  • Offline playback support for 48 hours: Broadsign Air will generate a playlist for up to 48 hours to be used if the Player loses connectivity or goes offline. If the Player is offline for longer than 48 hours and the Playlist has been exhausted, the Playlist will fall back on filler content. To generate an offline playlist longer than 48 hours, use the generate_long endpoint.
  • Preemptible Content: Broadsign Air supports the concept of preemptible campaign for programmatic content to optimize campaign delivery. For more information, see Preemptible Content.

Limitations

  • Synchronization Not Guaranteed: Synchronization across players is not guaranteed between regular and offline playlists. When a single player has multiple screens, it's recommended to implement a synchronization mechanism to ensure they transition from regular to offline playlists simultaneously. Failure to do so may lead to incomplete proof-of-play recording, depending on the threshold. See Synchronized Players.

generate v2

generate v2 Endpoint

Version 2 of generate adds support for up to 3 frames.

Features

  • Synchronized Playback: Players with multiple screens must retrieve the same playlists. If several Players want to use the same playlist, they must fetch it with the same player_id, but with a different screen_id.
  • Frame Support: The endpoint supports up to 3 frames for content display. To configure more than 1 frame, contact Broadsign Services.
  • Offline playback support for 48 hours: Broadsign Air will generate a playlist for up to 48 hours to be used if the Player loses connectivity or goes offline. If the Player is offline for longer than 48 hours and the Playlist has been exhausted, the Playlist will fall back on filler content. To generate an offline playlist longer than 48 hours, use the generate_long endpoint.
  • Cross-Player Sync: The endpoint supports cross-player sync on one frame.
  • Preemptible Content: Broadsign Air supports the concept of preemptible campaign for programmatic content to optimize campaign delivery. For more information, see Preemptible Content.

Limitations

  • Synchronization Not Guaranteed: Synchronization across players is not guaranteed between regular and offline playlists. When a single player has multiple screens, it's recommended to implement a synchronization mechanism to ensure they transition from regular to offline playlists simultaneously. Failure to do so may lead to incomplete proof-of-play recording, depending on the threshold. See Synchronized Players.
  • Day Part Changes: The endpoint does not support playlists with items that are expected to play across a day part change if the frame layout is different in each day part.
  • Scheduled Conditions: The endpoint does not support scheduled conditions.

Endpoints

https://air.broadsign.com/playlist/v1/generate

https://air.broadsign.com/playlist/v2/generate

HTTP Method

POST

Request Body Parameters

Parameter Description Type Required (R) or Optional (O)

player_identifier

A user-defined Custom Unique ID identifier within the Broadsign Control Player system. It is intended to uniquely represent a single physical location or venue where the player is deployed.

 string R
active_conditions

Uses active conditions to generate playlists specific for those conditions. Passes an array of Condition objects.

For more information, see Criteria and Conditions.

 Array of Condition O
Condition.name Name of the condition. If active_conditions is used, this is mandatory. string R
Condition.exclusive If set to "true", after generating the loop, the player will strip out all slots that are without this condition.
  • If a slot has no condition at all, the player interprets as NOT having the exclusive condition. The player then removes it.
  • If multiple conditions are set to exclusive, the player assumes an OR condition. As a result, a player with any of the exclusive conditions applied will remain in the loop.
 boolean O
screen_identifier

Uniquely identifies individual screens within a venue that are connected to the same Broadsign Control Player. It is a customer-provided opaque value.

The screen_identifier helps accurately track how many screens have confirmed playback of content, which is crucial for providing accurate proof of plays in Broadsign Air.

Tip: Using clear and consistent screen identifiers is essential for generating accurate proof of play reports in Broadsign Air.

The same screen_identifier (for example, "screen-00", "screen-01") can be used across multiple venues, that is, they can be reused throughout different player_identifiers.

This field is not mandatory but is highly recommended for precise playback tracking.

For more information, see Reporting Players POPs with Broadsign Air.

 string O
duration

The time duration, in seconds, covered by the generated Playlist. The default value is 48 hours (172,800 seconds), which is also the maximum supported value.

For example, if the duration is set to 48 hours, the returned Playlist will cover the next two days. The total duration of the returned items may be shorter than the covered time if there are periods where nothing is scheduled to play.

Note: Setting a smaller duration increases the risk of missing Playlist items or experiencing black screens due to downtime or network issues. To minimize the risk of playback issues, it is recommended to use the default or longer durations where possible.

See api.proto for definition.

 google.protobuf.Duration O
next_expected_poll

The next time that this player is expected to request a new playlist. If this parameter is not specified in the request, the player is considered offline. This parameter is used by Broadsign Control to determine when players are MIA. For more information, see Player Incidents.

The format <year>-<month>-<day>T<hour>:<minute>:<seconds>.<milliseconds>Z is supported. For example: 2021-09-23T20:00:00.000Z.

Note: If the next_expected_poll value is lower than 20 minutes, it is automatically set to 20 minutes.

See api.proto for definition.

 google.protobuf.Timestamp O
exclude_programmatic_precaching_info

Turns on or off Broadsign Reach pre-caching.

If set to True, only returns information on Broadsign Reach content that is actually in the playlist.

Not setting this parameter or setting it to False will return all Broadsign Reach approved creatives.

 boolean O
force

Enabling this option will result in the following:

  • Broadsign Air immediately polls, no matter when the last poll was.
  • Broadsign Air deletes the stored playlist and forces a regeneration.

When enabled, you can poll up to 6 times every hour. After that, Broadsign Air sends a 429 Too Many Requests error message.

Note: This parameter is designed for development or debugging purposes. It should not be enabled in a live production environment.

 boolean O

Response

Refer to Response for complete information about the Broadsign Air Response parameters.