This quick start provides a basic introduction to Broadsign Air. By following these steps, you will be able to add the "player" that represents your own player and generate a playlist.
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.
Note: For more information on the Broadsign Air configuration, see Configure Broadsign Air.
To get started with Broadsign Air:
- Request that Broadsign Air is activated on your domain. See Prerequisites.
- Once activated, create an API user in Broadsign Control Administrator and generate a REST API Token for it in Broadsign Control Administrator. See Add a User in Broadsign Control Administrator
- Schedule content (campaigns, ad copies, etc.) to your display units. See Add Campaigns.
- Add a player registration using a custom id in that display unit. See Add a Player in Broadsign Control Administrator.
- If you need different content playing in sync on multiple players using the generate v1 endpoint, set up a Display Unit Group. See Synchronized Players.
- Generate a playlist by calling this API with a curl command (see Sample Request Using Curl).
- If you are using generate v1:
- If you are using generate v2:
- If you are using generate_long:
- If applicable, confirm the Proof of Play (PoP) using the REST API token (see confirm_playback):
Note: Once you have registered the player, you must activate (promote) it with a playlist generation request using the player info.
There are two versions of the generate endpoint. The response will differ depending on the version used.
Request
Copy
curl -X POST \
https://air.broadsign.com/playlist/v1/generate \
-H 'Authorization: Bearer cbdbc369a063de6c0f458557f1456602' \
-d '{
"player_identifier": "abcd1234",
"screen_identifier": "1",
"duration": "3600s"
}'Response
The Broadsign Air server return items and content similar to the following (see Response).
Copy
{
"items": [
{
"startTime": "2019-06-14T14:17:26.456Z",
"duration": "5s",
"token": "CgphbGV4YW5kcmVjEgNVVEMaDAj22I7oBRCAhLjZASICCAUoAToDCNMBQgMIlRtKAwiSG2IDVVUwcgMI4BE=",
"contentIndex": 0,
"campaignIndex": 0,
"frameIndex": 0,
"geometryIndex": 0
},
{
"duration": "5s",
"token": "CgphbGV4YW5kcmVjEgNVVEMaDAj72I7oBRCAhLjZASICCAUoAToDCNQBQgMInhtKAwiSG2IDVVUwcgMI4BE=",
"contentIndex": 1,
"campaignIndex": 1,
"frameIndex": 0,
"geometryIndex": 0
},
{
"duration": "5s",
"token": "CgphbGV4YW5kcmVjEgNVVEMaDAio2Y7oBRCAhLjZASICCAUoAToDCNMBQgMIlRtKAwiSG2IDVVUwcgMI4BE=",
"contentIndex": 2,
"campaignIndex": 2,
"frameIndex": 0,
"geometryIndex": 0
},
],
"contents": [
{
"name": "Content-0",
"mimeType": "jpg",
"uri": "https://my-storage-url.com/content/9e6b1fb31f50.jpg",
"size": "187435",
"hash": {
"type": "CRC32",
"payload": "ODc1ZTlmYg=="
},
"adCopyId": "211"
},
{
"name": "Content-1",
"mimeType": "mp4",
"uri": "https://my-storage-url.com/content/9e6b1fb31f51.mp4",
"size": "97434227",
"hash": {
"type": "CRC32",
"payload": "ODI0MmZjMjg="
},
"adCopyId": "212"
},
{
"name": "Content-2",
"mimeType": "x-html-package",
"uri": "https://my-storage-url.com/content/9e6b1fb31f52.x-html-package",
"size": "97227",
"hash": {
"type": "CRC32",
"payload": "ODI0MmZjMjg="
},
"adCopyId": "213",
"dataSynchronizations": [
{
"from": "https://weather.com/data.json",
"to": "sync_data/weather_data.json",
"behavior": "FILE_SYNCHRONIZATION",
"expiry": "480s",
"refreshPeriod": "60s",
"timeoutPeriod": "120s"
}
],
"htmlPackageParameters": {
"mainHtmlFilePath": "assets/index.html"
}
},
{
"name": "FillerContent",
"mimeType": "jpg",
"uri": "https://my-storage-url.com/content/9e6b1fb31f53.jpg",
"size": "244768",
"hash": {
"type": "CRC32",
"payload": "ODc1ZTlmYg=="
},
"adCopyId": "214"
},
],
"identification": {
"playerId": "123",
"displayUnitId": "124",
"displayUnitLatlong": {
"latitude": 45.5164,
"longitude": -73.5548
},
"displayUnitAddress": "1100 Robert-Bourassa Montreal"
},
"campaigns": [
{
"campaignId": "321"
},
{
"campaignId": "322"
},
{
"campaignId": "323"
}
],
"frames": [
{
"frameId": "411",
"fillerIndices": [0],
"name": "center",
"criteriaIndices": [0]
}
],
"geometries": [
{
"width": 1920,
"height": 1080,
"fullscreen": true
}
],
"fillers": [
{
"contentIndex": 3,
"duration": "30s"
}
],
"criterias": [
{
"criteriaId": 511,
"name": "CriteriaForCenterFrame"
}
],
"dataSynchronizations": [
{
"from": "https://source.test.com/data.txt",
"to": "common/data.txt",
"behavior": "FILE_SYNCHRONIZATION",
"expiry": "60s",
"refreshPeriod": "6000s",
"timeoutPeriod": "120s"
}
]
}The generate v2 endpoint supports multiple frames playlists. See Multiple Frames Support for more details.
Request
Copy
curl -X POST \
https://air.broadsign.com/playlist/v2/generate \
-H 'Authorization: Bearer cbdbc369a063de6c0f458557f1456602' \
-d '{
"player_identifier": "abcd1234",
"screen_identifier": "1",
"duration": "3600s"
}'Response
The Broadsign Air server return items and content similar to the following (see Response).
Copy
{
"playlists": [
{
"items": [
{
"startTime": "2022-08-29T17:37:56.111Z",
"duration": "3600s",
"token": "CgphbGV4YW5kcmVjEgNVVEMaDAj22I7oBRCAhLjZASICCAUoAToDCNMBQgMIlRtKAwiSG2IDVVUwcgMI4BE=",
"geometryIndex": 1
},
{
"duration": "3600s",
"token": "CgthaXJfcGxheWVyMhIDVVRDGM+q3tWuMCDAzyQoATjCmAFA19gBSNPYAXDSmAE=",
"contentIndex": 1,
"geometryIndex": 1
},
{
"duration": "3600s",
"token": "CgthaXJfcGxheWVyMhIDVVRDGI/6gtauMCDAzyQoATjaAUDX2AFI09gBcNKYAQ==",
"contentIndex": 2,
"geometryIndex": 1,
"frameIndex": 2
},
{
"duration": "3600s",
"token": "CgthaXJfcGxheWVyMhIDVVRDGM/Jp9auMCDAzyQoATitAkDX2AFI09gBcNKYAQ==",
"contentIndex": 3,
"geometryIndex": 1,
"frameIndex": 2
},
{
"duration": "3600s",
"token": "CgthaXJfcGxheWVyMhIDVVRDGI+ZzNauMCDAzyQoATjblwFA19gBSNPYAXDSmAE=",
"geometryIndex": 1,
"frameIndex": 4
},
{
"duration": "3600s",
"token": "CgthaXJfcGxheWVyMhIDVVRDGM/o8NauMCDAzyQoATjCmAFA19gBSNPYAXDSmAE=",
"contentIndex": 1,
"geometryIndex": 1,
"frameIndex": 4
},
{
"duration": "3600s",
"token": "CgthaXJfcGxheWVyMhIDVVRDGI+4ldeuMCDAzyQoATjaAUDX2AFI09gBcNKYAQ==",
"contentIndex": 2,
"geometryIndex": 1,
"frameIndex": 6
}
]
},
{
"items": [
{
"startTime": "2022-08-29T17:37:56.111Z",
"duration": "3600s",
"token": "CgthaXJfcGxheWVyMhIDVVRDGI/budWuMCDAzyQoATjblwFA19gBSfasdfAXDSmAE=",
"frameIndex": 1
},
{
"duration": "3600s",
"token": "CgthaXJfcGxheWVyMhIDVVRDGM+budWuMCDAzyQoATjblwFA19gBSfasdfAXDSmAE=",
"contentIndex": 1,
"frameIndex": 1
},
{
"duration": "3600s",
"token": "CgthaXJfcGxheWVyMhIDVVRDGI/6gtauMCDAzyQoATjaAUfdsaaAFI09gBcNKYAQ==",
"contentIndex": 2,
"frameIndex": 3
},
{
"duration": "3600s",
"token": "CgthaXJfcGxheWVyMhIDVVRDGM/Jp9auMCDAzyQoATjfusDX2AFI09gBcNKYAQ==",
"contentIndex": 3,
"frameIndex": 3
},
{
"duration": "3600s",
"token": "CgthaXJfcGxheWVyMhIDVVRDGI+ZzNauMCDAzyQoATjblwFA19gBSNPYAXDSmAE=",
"frameIndex": 5
},
{
"duration": "3600s",
"token": "CgthaXJfcGxheWVyMhIDVVRDGM/o8NauMCDAzyQoATjCmAFA19gBSNPYAXDSmAE=",
"contentIndex": 1,
"frameIndex": 5
},
{
"duration": "3600s",
"token": "CgthaXJfcGxheWVyMhIDVVRDGI+4ldeuMCDAzyQoATjaAUDX2AFI09gBcNKYAQ==",
"contentIndex": 2,
"frameIndex": 7
}
]
},
],
"contents": [
{
"name": "Content-0",
"mimeType": "jpg",
"uri": "https://my-storage-url.com/11045825-19889464/8e649eb2-4e0a-4727-8d8c-9e6b1fb31f50.jpg",
"size": "187435",
"hash": {
"type": "CRC32",
"payload": "ODc1ZTlmYg=="
},
"adCopyId": "211"
},
{
"name": "Content-1",
"mimeType": "jpg",
"uri": "https://my-storage-url.com/11045825-19889464/8e649eb2-4e0a-4727-8d8c-9e6b1fb31f50.jpg",
"size": "97227",
"hash": {
"type": "CRC32",
"payload": "ODI0MmZjMjg="
},
"adCopyId": "212"
},
{
"name": "Content-2",
"mimeType": "x-html-package",
"uri": ""https://my-storage-url.com/content/9e6b1fb31f52.x-html-package"",
"size": "97227",
"hash": {
"type": "CRC32",
"payload": "ODI0MmZjMjg="
},
"adCopyId": "2122",
"dataSynchronizations": [
{
"from": "https://weather.com/data.json",
"to": "sync_data/weather_data.json",
"behavior": "FILE_SYNCHRONIZATION",
"expiry": "480s",
"refreshPeriod": "60s",
"timeoutPeriod": "120s"
}
]
"htmlPackageParameters": {
"mainHtmlFilePath": "assets/index.html"
}
},
{
"name": "FillerContent",
"mimeType": "jpg",
"uri": "https://my-storage-url.com/11045825-19889464/8e649eb2-4e0a-4727-8d8c-9e6b1fb31f50.jpg",
"size": "244768",
"hash": {
"type": "CRC32",
"payload": "ODc1ZTlmYg=="
},
"adCopyId": "2222"
},
{
"name": "FillerContent-LeftScreen",
"mimeType": "jpg",
"uri": "https://my-storage-url.com/11045825-19889464/8e649eb2-4e0a-4727-8d8c-9e6b1fb31f50.jpg",
"size": "244768",
"hash": {
"type": "CRC32",
"payload": "ODc1ZTlmYg=="
},
"adCopyId": "2226"
}
],
"identification": {
"playerId": "2272",
"displayUnitId": "3472"
"displayUnitLatlong": {
"latitude": 45.5164,
"longitude": -73.5548
},
"displayUnitAddress": "1100 Robert-Bourassa Montreal"
},
"campaigns": [
{
"campaignId": "19889482"
},
{
"campaignId": "14889444"
},
{
"campaignId": "99932"
}
],
"frames": [
{
"frameId": "19889456",
"fillerIndices": [0],
"name": "LeftFrame-DayPart1",
"criteriaIndices": [0]
},
{
"frameId": "19889901",
"fillerIndices": [1],
"name": "RightFrame-DayPart1",
"criteriaIndices": [1]
},
{
"frameId": "1489431",
"fillerIndices": [0],
"name": "LeftFrame-DayPart2",
"criteriaIndices": [0]
},
{
"frameId": "18890012",
"fillerIndices": [1],
"name": "RightFrame-DayPart2",
"criteriaIndices": [1]
},
{
"frameId": "12437980",
"fillerIndices": [0],
"name": "LeftFrame-DayPart3",
"criteriaIndices": [2]
},
{
"frameId": "132795",
"fillerIndices": [1],
"name": "RightFrame-DayPart3",
"criteriaIndices": [2]
},
{
"frameId": "89001",
"fillerIndices": [0,1],
"name": "LeftFrame-DayPart4",
"criteriaIndices": [0]
},
{
"frameId": "1988457",
"fillerIndices": [0,1],
"name": "RightFrame-DayPart4",
"criteriaIndices": [1]
}
],
"geometries": [
{
"width": 1920,
"height": 1080,
"fullscreen": true
}
]
"fillers": [
{
"contentIndex": 3,
"duration": "30s"
}
},
{
"contentIndex": 4,
"duration": "60s"
}
}
],
"criterias": [
{
"criteriaId": 36890241,
"name": "CriteriaForLeftFrame"
},
{
"criteriaId": 36890456,
"name": "CriteriaForRightFrame"
},
{
"criteriaId": 36890625,
"name": "AnotherCriteria"
}
]
"dataSynchronizations": [
{
"from": "https://source.test.com/data.txt",
"to": "common/data.txt",
"behavior": "FILE_SYNCHRONIZATION",
"expiry": "0s",
"refreshPeriod": "6000s",
"timeoutPeriod": "120s"
}
]
}The generate_long endpoint allows Players to fetch offline playlists that are available for up to 14 days.
Request
Copy
curl -X POST \
https://air.broadsign.com/playlist/v2/generate_long \
-H 'Authorization: Bearer cbdbc369a063de6c0f458557f1456602' \
-d '{
"player_identifier": "abcd1234",
"screen_identifier": "1",
"date": {
"year": 2022,
"month": 8,
"day": 29
}
}'Response
The Broadsign Air server return items and content similar to the following (see Response).
Copy
{
"playlists": [
{
"items": [
{
"startTime": "2022-08-29T17:37:56.111Z",
"duration": "3600s",
"token": "CgphbGV4YW5kcmVjEgNVVEMaDAj22I7oBRCAhLjZASICCAUoAToDCNMBQgMIlRtKAwiSG2IDVVUwcgMI4BE=",
"geometryIndex": 1
},
{
"duration": "3600s",
"token": "CgthaXJfcGxheWVyMhIDVVRDGM+q3tWuMCDAzyQoATjCmAFA19gBSNPYAXDSmAE=",
"contentIndex": 1,
"geometryIndex": 1
},
{
"duration": "3600s",
"token": "CgthaXJfcGxheWVyMhIDVVRDGI/6gtauMCDAzyQoATjaAUDX2AFI09gBcNKYAQ==",
"contentIndex": 2,
"geometryIndex": 1,
"frameIndex": 2
},
{
"duration": "3600s",
"token": "CgthaXJfcGxheWVyMhIDVVRDGM/Jp9auMCDAzyQoATitAkDX2AFI09gBcNKYAQ==",
"contentIndex": 3,
"geometryIndex": 1,
"frameIndex": 2
},
{
"duration": "3600s",
"token": "CgthaXJfcGxheWVyMhIDVVRDGI+ZzNauMCDAzyQoATjblwFA19gBSNPYAXDSmAE=",
"geometryIndex": 1,
"frameIndex": 4
},
{
"duration": "3600s",
"token": "CgthaXJfcGxheWVyMhIDVVRDGM/o8NauMCDAzyQoATjCmAFA19gBSNPYAXDSmAE=",
"contentIndex": 1,
"geometryIndex": 1,
"frameIndex": 4
},
{
"duration": "3600s",
"token": "CgthaXJfcGxheWVyMhIDVVRDGI+4ldeuMCDAzyQoATjaAUDX2AFI09gBcNKYAQ==",
"contentIndex": 2,
"geometryIndex": 1,
"frameIndex": 6
}
]
},
{
"items": [
{
"startTime": "2022-08-29T17:37:56.111Z",
"duration": "3600s",
"token": "CgthaXJfcGxheWVyMhIDVVRDGI/budWuMCDAzyQoATjblwFA19gBSfasdfAXDSmAE=",
"frameIndex": 1
},
{
"duration": "3600s",
"token": "CgthaXJfcGxheWVyMhIDVVRDGM+budWuMCDAzyQoATjblwFA19gBSfasdfAXDSmAE=",
"contentIndex": 1,
"frameIndex": 1
},
{
"duration": "3600s",
"token": "CgthaXJfcGxheWVyMhIDVVRDGI/6gtauMCDAzyQoATjaAUfdsaaAFI09gBcNKYAQ==",
"contentIndex": 2,
"frameIndex": 3
},
{
"duration": "3600s",
"token": "CgthaXJfcGxheWVyMhIDVVRDGM/Jp9auMCDAzyQoATjfusDX2AFI09gBcNKYAQ==",
"contentIndex": 3,
"frameIndex": 3
},
{
"duration": "3600s",
"token": "CgthaXJfcGxheWVyMhIDVVRDGI+ZzNauMCDAzyQoATjblwFA19gBSNPYAXDSmAE=",
"frameIndex": 5
},
{
"duration": "3600s",
"token": "CgthaXJfcGxheWVyMhIDVVRDGM/o8NauMCDAzyQoATjCmAFA19gBSNPYAXDSmAE=",
"contentIndex": 1,
"frameIndex": 5
},
{
"duration": "3600s",
"token": "CgthaXJfcGxheWVyMhIDVVRDGI+4ldeuMCDAzyQoATjaAUDX2AFI09gBcNKYAQ==",
"contentIndex": 2,
"frameIndex": 7
}
]
},
],
"contents": [
{
"name": "Content-0",
"mimeType": "jpg",
"uri": "https://my-storage-url.com/11045825-19889464/8e649eb2-4e0a-4727-8d8c-9e6b1fb31f50.jpg",
"size": "187435",
"hash": {
"type": "CRC32",
"payload": "ODc1ZTlmYg=="
},
"adCopyId": "211"
},
{
"name": "Content-1",
"mimeType": "jpg",
"uri": "https://my-storage-url.com/11045825-19889464/8e649eb2-4e0a-4727-8d8c-9e6b1fb31f50.jpg",
"size": "97227",
"hash": {
"type": "CRC32",
"payload": "ODI0MmZjMjg="
},
"adCopyId": "212"
},
{
"name": "Content-2",
"mimeType": "x-html-package",
"uri": ""https://my-storage-url.com/content/9e6b1fb31f52.x-html-package"",
"size": "97227",
"hash": {
"type": "CRC32",
"payload": "ODI0MmZjMjg="
},
"adCopyId": "2122",
"dataSynchronizations": [
{
"from": "https://weather.com/data.json",
"to": "sync_data/weather_data.json",
"behavior": "FILE_SYNCHRONIZATION",
"expiry": "480s",
"refreshPeriod": "60s",
"timeoutPeriod": "120s"
}
]
"htmlPackageParameters": {
"mainHtmlFilePath": "assets/index.html"
}
},
{
"name": "FillerContent",
"mimeType": "jpg",
"uri": "https://my-storage-url.com/11045825-19889464/8e649eb2-4e0a-4727-8d8c-9e6b1fb31f50.jpg",
"size": "244768",
"hash": {
"type": "CRC32",
"payload": "ODc1ZTlmYg=="
},
"adCopyId": "2222"
},
{
"name": "FillerContent-LeftScreen",
"mimeType": "jpg",
"uri": "https://my-storage-url.com/11045825-19889464/8e649eb2-4e0a-4727-8d8c-9e6b1fb31f50.jpg",
"size": "244768",
"hash": {
"type": "CRC32",
"payload": "ODc1ZTlmYg=="
},
"adCopyId": "2226"
}
],
"identification": {
"playerId": "2272",
"displayUnitId": "3472"
"displayUnitLatlong": {
"latitude": 45.5164,
"longitude": -73.5548
},
"displayUnitAddress": "1100 Robert-Bourassa Montreal"
},
"campaigns": [
{
"campaignId": "19889482"
},
{
"campaignId": "14889444"
},
{
"campaignId": "99932"
}
],
"frames": [
{
"frameId": "19889456",
"fillerIndices": [0],
"name": "LeftFrame-DayPart1",
"criteriaIndices": [0]
},
{
"frameId": "19889901",
"fillerIndices": [1],
"name": "RightFrame-DayPart1",
"criteriaIndices": [1]
},
{
"frameId": "1489431",
"fillerIndices": [0],
"name": "LeftFrame-DayPart2",
"criteriaIndices": [0]
},
{
"frameId": "18890012",
"fillerIndices": [1],
"name": "RightFrame-DayPart2",
"criteriaIndices": [1]
},
{
"frameId": "12437980",
"fillerIndices": [0],
"name": "LeftFrame-DayPart3",
"criteriaIndices": [2]
},
{
"frameId": "132795",
"fillerIndices": [1],
"name": "RightFrame-DayPart3",
"criteriaIndices": [2]
},
{
"frameId": "89001",
"fillerIndices": [0,1],
"name": "LeftFrame-DayPart4",
"criteriaIndices": [0]
},
{
"frameId": "1988457",
"fillerIndices": [0,1],
"name": "RightFrame-DayPart4",
"criteriaIndices": [1]
}
],
"geometries": [
{
"width": 1920,
"height": 1080,
"fullscreen": true
}
]
"fillers": [
{
"contentIndex": 3,
"duration": "30s"
}
},
{
"contentIndex": 4,
"duration": "60s"
}
}
],
"criterias": [
{
"criteriaId": 36890241,
"name": "CriteriaForLeftFrame"
},
{
"criteriaId": 36890456,
"name": "CriteriaForRightFrame"
},
{
"criteriaId": 36890625,
"name": "AnotherCriteria"
}
]
"dataSynchronizations": [
{
"from": "https://source.test.com/data.txt",
"to": "common/data.txt",
"behavior": "FILE_SYNCHRONIZATION",
"expiry": "0s",
"refreshPeriod": "6000s",
"timeoutPeriod": "120s"
}
]
}Note: Some “0” values have been included in this example for sake of clarity. Actually, 0 values are omitted in the serialized output and are to be assumed as the default value. The default values of any other type used are also omitted from results ("false" for boolean values and "" for string values). This is done for performance and payload size reasons.
Once promoted, the new player appears in Broadsign Control Administrator under the Players resource tab. For more information, see Players (Resource) in the Broadsign Control documentation.
Copy
curl -X POST https://air.broadsign.com/playlist/v1/confirm_playback \
-H 'Authorization: Bearer cbdbc369a063de6c0f458557f1456602' \
-d '{
"player_identifier": "abcd1234",
"screen_identifier" : "1",
"confirmed_items": [
{
"playlist_item_token":"CgphbGV4YW5kcmVjEgNVVEMaDAj22I7oBRCAhLjZASICCAUoAToDCNMBQgMIlRtKAwiSG2IDVVUwcgMI4BE=",
"custom_data": { "ext1":"", "ext2": "" }
}
]
}'