broadsign-player v1.1.6

bsp-interface

Features

• BroadSignPlay/Render Lifecycle hook
• Content Variable and Monitor Sync integration
• Simplified Video API interface
• Simplified BSP Player API interface

Browser Support

Latest ✔	Latest ✔	Latest ✔	Latest ✔	Latest ✔	8+ ✔

Installing

Using npm:

$ npm install broadsign-player

Using a cdn:

<script src="https://unpkg.com/broadsign-player@1.1.4/lib/min.js"></script>

When using a CDN, the module will be namedspaced as BSP

Examples

Accessing Content Variables

Content variables are available through the props object.

import BSP from 'broadsign-player';

const bsp = BSP();

console.log(bsp.props)

When running outside of a BroadSign Player environment, Automatic Variables are automagically simulated. The default values are:

{
  ad_copy_id: '111111',
  campaign_id: '222222',
  display_unit_id: '333333',
  display_unit_address: '444444',
  display_unit_location_code: '555555',
  display_unit_lat_long: '40.7,-73.8',
  display_unit_resolution: '1080x1920',
  frame_id: '666666',
  frame_resolution: '1080x1920',
  player_id: '777777'
}

To simulate custom content variables in a dev environment, you can pass an object like so:

import BSP from 'broadsign-player';

const contentVariables = {
	display_unit_lat_long: '40.1234567,-70.7654321',
	foo: 'bar'
}

const bsp = BSP(contentVariables);

console.log(bsp.props)

// {
//   ad_copy_id: '111111',
//   campaign_id: '222222',
//   display_unit_id: '333333',
//   display_unit_address: '444444',
//   display_unit_location_code: '555555',
//   display_unit_lat_long: '40.1234567,-70.7654321',
//   display_unit_resolution: '1080x1920',
//   frame_id: '666666',
//   frame_resolution: '1080x1920',
//   player_id: '777777',
//.  foo: 'bar'
// }

BroadSignPlay/Render hook

import BSP from 'broadsign-player';

const bsp = BSP();

bsp.render = () => {
	console.log('Do something like, start a video or a timer!')
}

In a Dev environment, the render method is executed after 3 seconds. When running on the BroadSign Player, this hook is tied directly to the BroadSignPlay function call. Documentation on this can be found here.

BroadSign Video API simplification

import BSP from 'broadsign-player';

const bsp = BSP();
// params ::: path to video, width, height, offset X, offset Y
bsp.playVideo('videos/video.mp4', 1080, 1920, 0, 0);

This is all you need to do, the module takes care of preparing and playing video in a dev environment and a production environment. The only restriction is that you can't call this method in the bsp.render() hook, i.e:

// This is an example of what NOT to do
import BSP from 'broadsign-player';

const bsp = BSP();

bsp.render = () => {
	bsp.playVideo('videos/video.mp4', 1080, 1920, 0, 0);
}
// This is an example of what NOT to do

This is bad and won't work. The reason being that when running on a BroadSign Player, the application needs time to prepare the video.

BroadSign Player API simplified

import BSP from 'broadsign-player';

const bsp = BSP();


bsp.stop();

bsp.trigger();

bsp.setCondition();

bsp.getConditions();

bsp.setExt();

bsp.showLoop();

bsp.nowPlaying();

bsp.logBroadSignIncident();

bsp.screenShot();

bsp.skipNext();

Full BSP API documentation at the bottom

BroadSign Fetch Local File (monitor sync integration)

import BSP from 'broadsign-player';

const monitorSyncConfig = {
	'dataOne.json': cv => `http://www.mapping.com/getInfo?location=${cv.display_unit_lat_long}`,
	'dataTwo.xml': () => 'http://www.someXmlFile.com/rss.xml';
}

const bsp = BSP({}, monitorSyncConfig);

bsp.fetchSyncData('data.json', (err, data) => {
	console.log(data)
})

In a development environment, the urls returned in the monitorSyncConfig object are fetched on every call to bsp.fetchSyncData. In a production environment, the application attempts to read the file from the sync/ folder, using the object key name. For example, for the code snippet above, the ad copy in BroadSign would need a monitor sync configuration such as:

<monitor_sync_config version="1">
	<sync refresh_period="1800000" expiry="0" timeout_period="30000">
		<url sync_mode="1">
			<from>http://www.mapping.com/getInfo?location={{display_unit_lat_long}}</from>
			<to>dataOne.json</to>
		</url>
	</sync>
	<sync refresh_period="1800000" expiry="0" timeout_period="30000">
 		<url sync_mode="1">
			<from>http://www.someXmlFile.com/rss.xml</from>
			<to>DataTwo.xml</to>
		</url>
	</sync>
</monitor_sync_config>

The functions provided in the monitorSyncConfig object are provided the content variables as the first parameter, and all content variables can be used in the url.

Recipe examples

Recipe One: Use the Video API with params provided from content variables:

import BSP from 'broadsign-player';

const config = {path: 'video.mp4', width: 1080, height: 1920 };

const bsp = BSP(config);

const { path, width, height } = bsp.props;

bsp.playVideo(path, width, height);

Locally, this will run as instructed in the config object but in a production environment it will read the content variables provided through the BroadSign pipelines (ad copy, player, display unit content variables).

BSP API

• BSP
  • .setCondition(cb, name, enabled, exclusive)
  • .getConditions(cb)
  • .stop(cb, [frame_id])
  • .setExt(cb, customVals)
  • .trigger(cb, trigger_id)
  • .showLoop(cb, frame_id, loops)
  • .nowPlaying(cb, frame_id)
  • .logBroadSignIncident(cb, problem_description)
  • .screenShot(cb, destination_url, scale_factor, screenshot_duration, screenshot_frequency)

bsp.setCondition(cb, name, enabled, exclusive)

Sets a string condition (name) on the BroadSign Player

Kind: method of BSP

bsp.getConditions(cb)

Returns a list of currently active conditions on the player.

Kind: method of BSP

bsp.stop(cb, frame_id)

Stops the currently playing content.

Kind: method of BSP

bsp.setExt(cb, customVals)

Sets a the ext1 and ext 2 fields in the pop request.

Kind: method of BSP

bsp.trigger(cb, trigger_id)

Sends a trigger to the player.

Kind: method of BSP

bsp.showLoop(cb, frame_id, loops)

Returns the scheduled loop for the next n loops.

Kind: method of BSP

bsp.nowPlaying(cb, frame_id)

Returns the currently playing piece of content for a specific frame, or all frames.

Kind: method of BSP

bsp.logBroadSignIncident(cb, problem_description)

Logs a custom incident to BroadSign.

Kind: method of BSP

bsp.screenShot(cb, destination_url, scale_factor, screenshot_duration, screenshot_frequency)

Takes a series of screenshots and sends them to an http destination

Kind: method of BSP