Broadsign Integration

An open-source HTML5 package for Broadsign Control that connects your DOOH screens to Adlocaite programmatic demand. Built for publishers who run Broadsign as their playout system.

Overview

The Adlocaite Broadsign Integration is an HTML5 package (.x-html-package) that runs inside the Broadsign Control Player. When Broadsign schedules an ad slot for this package, it automatically requests a programmatic advertisement from the Adlocaite API, plays the creative (video or image), fires VAST tracking events, and confirms the playout.

The package is designed as a self-contained unit: no external build tools, no server-side components, no dependencies beyond what ships in the package. You configure it with your API key, build the package with a single command, and upload it to Broadsign Control.

Key features

• VAST 2.0/3.0/4.0 support -- Industry-standard ad serving protocol for video and image creatives
• VAST tracking pixels -- Fires impression, start, quartile, and completion events; the complete pixel is the playout signal to the backend
• PREBUFFER pre-loading -- Content is loaded off-screen during Broadsign's pre-buffering phase for instant playback
• Strict Accept -- No playback without a deal_id; offers that fail to close commercially are skipped, not silently served
• WebSocket skip signal -- Reliable skip via Broadsign Remote Control API for seamless waterfall fallback
• Remote error logging -- Optional Axiom integration for production monitoring
• Graceful error handling -- API errors are handled without crashing the Broadsign Player, with fast fail and retry
• Debug mode -- Visual debug panel and detailed console logging for troubleshooting
• Browser-based test interface -- Test the full lifecycle with PREBUFFER simulation, without a Broadsign Player
• Zero dependencies -- Pure vanilla JavaScript, no external libraries or build tools
• Open source (MIT) -- Fully inspectable and modifiable

Current status

How it works

The integration follows a linear lifecycle within a single Broadsign ad slot:

Playback lifecycle

1. Pre-Loading (PREBUFFER) -- Broadsign loads the HTML5 package off-screen. During this phase, BroadSignObject.frame_id is already available. The package immediately requests an offer from the Adlocaite API, parses the VAST response, accepts the offer, and pre-loads the media asset. Accept and media download run in parallel.
2. Strict Accept -- The package only proceeds to playback if the accept call returned a deal_id. Without a deal the offer was not commercially closed, so the package skips rather than serve inventory.
3. Skip Signal -- If no offer is available, the network fails, or the accept did not produce a deal_id, the package sends a skip_next WebSocket command to Broadsign's Remote Control API (ws://localhost:2326). Broadsign then moves to the next item in the programmatic waterfall. The offer request uses a 2s timeout with one 1s retry to ensure skip fires within the PREBUFFER window.
4. BroadSignPlay() -- Broadsign calls BroadSignPlay() when the ad slot becomes visible. Pre-loaded content plays instantly with no loading delay.
5. Playback & Tracking -- The media plays while VAST tracking pixels are fired at impression, start, quartiles (25%, 50%, 75%), and completion. The complete pixel is the playout signal to the backend -- there is no separate confirm endpoint call.

Architecture

The package consists of five core modules:

Integration comparison

Adlocaite offers multiple integration paths for publishers. Choose the one that fits your infrastructure:

Getting started

Prerequisites

Before you begin, make sure you have:

• Adlocaite Publisher API key -- Obtain one through the Publisher Onboarding process
• Screens registered in Adlocaite -- Each screen needs an external_id matching the Broadsign frame_id (see Screen Registration)
• Git installed on your machine
• Broadsign Control 15.4+ (Chromium 87+) for production deployment
• Remote Control enabled in Broadsign Control Player settings (required for WebSocket skip signaling)

Step 1: Clone the repository

git clone https://github.com/Adlocaite/adlocaite-broadsign.git
cd adlocaite-broadsign

Step 2: Configure your API key

cp package/js/config.example.js package/js/config.js

Open package/js/config.js and set your API key and environment:

const ADLOCAITE_CONFIG = {
  // Your publisher API key (required)
  apiKey: 'pub_your_actual_api_key_here',

  // Use production URL for live screens
  apiBaseUrl: 'https://api.adlocaite.com/functions/v1/api',

  // Minimum bid price in cents (100 = 1.00 EUR, 0.5 = half a cent)
  minBidCents: 100,

  // Disable debug mode for production
  debugMode: false,

  // Keep other defaults unless you have specific requirements
  // ...
};

See the full Configuration Reference below for all available options.

Step 3: Build the package

./build.sh

This creates adlocaite-broadsign.x-html-package in the project root. The build script validates your config, injects the version number, and packages everything into a zip file with the .x-html-package extension.

Step 4: Deploy to Broadsign Control

1. Open Broadsign Control Administrator
2. Navigate to Library > Ad Copies
3. Click Upload and select the .x-html-package file
4. Assign the ad copy to your campaign

Step 5: Configure a fallback campaign

Deployment checklist

Configuration reference

Configuration lives in package/js/config.js. This file is loaded as a global JavaScript object and must not be committed to version control (it contains your API key).

The config file exports a global ADLOCAITE_CONFIG object:

const ADLOCAITE_CONFIG = {
  apiKey: 'pub_your_api_key_here',
  apiBaseUrl: 'https://api.adlocaite.com/functions/v1/api',
  minBidCents: 100,
  vastMode: true,
  debugMode: false,
  axiomToken: '',
  axiomDataset: 'broadsign',
  packageVersion: '2.0.0',
};

if (typeof window !== 'undefined') {
  window.ADLOCAITE_CONFIG = ADLOCAITE_CONFIG;
}

Required parameters

Offer configuration

Debug configuration

Remote logging (Axiom)

Environment setup

Staging -- Use for testing and development. Staging uses separate API keys and campaign data from production.

{
  apiKey: 'pub_your_staging_key',
  apiBaseUrl: 'https://staging.api.adlocaite.com/functions/v1/api',
  debugMode: true,
  minBidCents: 1,    // Low threshold for testing
}

Production -- Use for live screens serving real ad campaigns.

{
  apiKey: 'pub_your_production_key',
  apiBaseUrl: 'https://api.adlocaite.com/functions/v1/api',
  debugMode: false,   // Always disable in production
  minBidCents: 100,   // Set your actual minimum
}

Screen registration

Each Broadsign screen must be registered in the Adlocaite platform with a matching identifier. The integration uses the Broadsign frame_id as the screen identifier.

How screen matching works

1. Broadsign provides BroadSignObject.frame_id to the HTML5 package at runtime
2. The integration sends this frame_id to the Adlocaite API as an external_id
3. The API looks up the screen by its external_id and returns matching offers

Fallback identification methods (in order): URL parameter ?screen_id=, localStorage value adlocaite_screen_id.

Finding your frame_id

Check your Broadsign Player debug logs to find the frame_id value. The frame_id is assigned by Broadsign when you configure a frame (display area) in Broadsign Control.

Alternatively, in the test interface, the frame_id field shows what value would be used.

Registering in Adlocaite

In the Adlocaite Dashboard, set the screen's external_id to match the Broadsign frame_id. For detailed instructions, see External Screen IDs.

Verifying the mapping

Enable debugMode: true and check the console logs for:

[Broadsign Adapter] Screen ID (frame_id) from BroadSignObject: 842292831

Then verify the API responds with offers (not 404) for this screen ID.

Testing

The built-in test interface (/test/) simulates the Broadsign Control Player in your browser.

Starting the test server

npm run test:serve
# Open http://127.0.0.1:8000/test/

Test interface features

• Configuration panel -- Set frame_id, API key, environment, resolution, and options
• BroadSignObject simulation -- Mocks the BroadSignObject that Broadsign injects
• Manual lifecycle control -- "Load Package" initializes the integration, "Trigger Play" calls BroadSignPlay()
• Real-time log output -- All console output from the package is displayed
• Status monitoring -- Observes WebSocket skip commands and the package's playback status events
• Persistent config -- Settings are saved to localStorage and can be passed via URL parameters

Quick test via URL parameters

http://127.0.0.1:8000/test/?api_key=pub_xxx&frame_id=842292831&env=staging&debug=true

Test scenarios

1. Happy path -- Configure a valid frame_id and API key, load package, trigger play. Expected: ad plays successfully, complete tracking pixel fires at end.
2. No offers -- Use a frame_id that has no active campaigns. Expected: WebSocket skip_next sent, logs show "no offers available".
3. Invalid screen -- Use a non-existent frame_id. Expected: 404 handled gracefully, skip signal sent.
4. Invalid API key -- Use pub_invalid. Expected: 401 error in logs, skip signal sent.
5. Accept failure (Strict Accept) -- Force an expired offer (let one age past 12 minutes before triggering play) or otherwise cause /offers/response/{offerId} to return 4xx. Expected: skip signal sent with reason accept failed, Axiom event includes the backend error_code. The ad does not play.

Strengths & limitations

Strengths

Known limitations

Remote Control required -- The WebSocket skip mechanism requires Broadsign's Remote Control API to be enabled on the player. Without it, there is no reliable skip mechanism and the player may show black screens when no ad is available.

Fallback campaign required -- Publishers must configure a fallback campaign in Broadsign Control. When the integration signals skip, Broadsign needs fallback content to display instead.

No automated test suite -- The integration currently relies on manual testing via the browser-based test interface. Automated end-to-end tests are planned but not yet implemented.

Muted video playback -- Due to Chromium 87+ autoplay policies, all video playback is muted (muted=true). This is a browser-level restriction -- unmuted autoplay is blocked by the Chromium engine used in Broadsign Control.

Comparison with direct API

If you can build a custom integration using the Core API directly, here is what you gain and lose compared to using the Broadsign package:

Troubleshooting

No screen ID available

The package cannot determine which screen to request offers for.

• In Broadsign Player: Verify that frame_id is configured in your Broadsign setup
• In the test interface: Enter a frame_id in the configuration panel
• Check Broadsign Player debug logs for BroadSignObject values

404 -- No offers available

The API cannot find matching offers for this screen.

• Verify the screen is registered in Adlocaite with the correct external_id
• Check that there are active campaigns targeting this screen
• Ensure the screen's resolution matches available ad creatives

401 -- Invalid API key

Authentication failed.

• Verify your API key in config.js starts with pub_
• Check that the key is for the correct environment (staging vs. production)
• Ensure there are no trailing spaces or newlines in the key

CORS errors

Asset loading fails with cross-origin errors.

• Ad asset servers must include Access-Control-Allow-Origin: * header
• This is configured on the Adlocaite side -- contact support if you encounter this

Black screen / no ad playing

The ad slot is visible but nothing appears.

• Ensure a fallback campaign is configured in Broadsign Control
• Enable debugMode: true in config and check console output
• Verify the API is reachable from the player network

Build fails

The build.sh script reports errors.

• Ensure package/js/config.js exists (copy from config.example.js)
• Check that zip is installed (brew install zip on macOS, apt install zip on Ubuntu)
• Verify the API key line is not still set to the placeholder pub_xxxx