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
• Automatic playout confirmation -- Reports successful playouts back to the Adlocaite API
• VAST tracking -- Fires impression, quartile, and completion tracking events
• Graceful error handling -- API errors are handled without crashing the Broadsign Player, with automatic retry and exponential backoff
• Debug mode -- Visual debug panel and detailed console logging for troubleshooting
• Browser-based test interface -- Test the full lifecycle 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 (V1)

1. Page Load -- Broadsign loads the HTML5 package and runs initialization (configuration, module setup).
2. BroadSignPlay() -- Broadsign calls BroadSignPlay() when the ad slot is displayed on screen. Only at this point is BroadSignObject.frame_id available to identify the screen.
3. Content loading -- The package requests an offer from the Adlocaite API, parses the VAST response, and loads the media asset (video or image). This happens while the slot is already visible, which can cause a brief loading delay (see Known Limitations).
4. Playback -- The media plays while VAST tracking events are fired at impression, start, quartiles (25%, 50%, 75%), and completion.
5. Playout confirmation -- After playback completes, the package confirms the playout via the Adlocaite API with duration and completion data.

Architecture

The package consists of four 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

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)
  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,
  requestTimeout: 10000,
  assetTimeout: 20000,
  maxLifecycleDuration: 60000,
  maxRetries: 3,
  retryDelay: 1000,
};

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

Required parameters

Offer configuration

Timeout configuration

Retry configuration

Debug configuration

Caching configuration (V2)

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
• Title monitoring -- Watches the document title changes (wait / ready / skip)
• 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.
2. No offers -- Use a frame_id that has no active campaigns. Expected: title changes to skip:no offers available.
3. Invalid screen -- Use a non-existent frame_id. Expected: 404 handled gracefully, title changes to skip.
4. Invalid API key -- Use pub_invalid. Expected: 401 error in logs, title changes to skip.

Strengths & limitations

Strengths

Known limitations

Skip signal timing (V1) -- Broadsign checks the document <title> within the first 1-2 seconds after page load to decide whether to skip the ad copy. However, BroadSignPlay() fires after this check window, which means the skip signal set by the integration arrives too late for Broadsign to act on it automatically. Workaround: Configure a separate fallback campaign in Broadsign Control. (Issue #4)

Loading delay (V1) -- Since the screen ID is only available after BroadSignPlay() fires, content must be fetched while the slot is already visible. This can cause a brief black screen or loading delay. Workaround: Ensure reliable network connectivity to the API and asset CDN. (Issue #3)

Fallback campaign required -- Because the skip signal timing issue prevents automatic waterfall fallback, publishers must configure a separate fallback campaign in Broadsign Control. Without it, empty ad slots will show a black screen.

No asset pre-caching -- The integration does not currently pre-cache ad assets. Each ad slot fetches its content live from the API, which means playback depends on network availability and speed at playout time. Asset pre-caching is planned for V2.

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:

V2 roadmap

Version 2 is in active development and will address the major V1 limitations:

Content pre-loading during off-screen buffering

V2 will load offers and media assets during Broadsign's off-screen pre-buffering phase (before BroadSignPlay() fires), enabling instant playback with no visible delay. The content will be fully buffered before the ad slot becomes visible.

Asset pre-caching

V2 will introduce a background cache manager that periodically fetches upcoming ad assets and stores them in the browser cache. This reduces load times and provides resilience against temporary network issues during playout.

Skip signal before check window

V2 will set the document title to skip before Broadsign's title check window (within the first 1-2 seconds of page load). This enables automatic waterfall fallback without requiring a dedicated fallback campaign in Broadsign Control.

Screen ID fallback chain

V2 will implement a fallback chain for screen identification:

1. frame_id (primary, current behavior)
2. display_unit_id (fallback if frame_id is not configured)
3. player_id (last resort)

This makes the integration more resilient to varying Broadsign configurations.

How to follow progress

• Track V2 development on GitHub Issues
• Contributions to V2 features are welcome -- see the Contributing Guide

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