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.

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.

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.
  • Cross-Player Sync: The endpoint does not support cross-player sync.
  • 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 Unique Broadsign Control Player identifier, expected to represent a unique venue. string R
active_conditions Uses active conditions to generate playlists specific for those conditions. Passes an array of Condition objects. 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 Identifier for one screen within a venue. string O
duration

Time duration, in seconds, covered by the generated Playlist. The default value is 1 hour (3,600 seconds). The maximum supported value is 48 hours (172,800 seconds).

For example, if the duration is 1 hour, the returned Playlist will cover the next hour. The total duration of the returned items may be shorter than the covered time, for example if there are times where nothing is scheduled to play.

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

Response

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