Adlocaite Docs

Contributing to the Broadsign Integration

The Adlocaite Broadsign integration is open source and contributions are welcome. This guide covers the architecture, development workflow, and standards you need to know before submitting changes.

GitHub Repository

Source code, issues, and pull requests: github.com/Adlocaite/adlocaite-broadsign

How to contribute

There are several ways to contribute:

Bug reports

Found a bug? Open an issue on GitHub with:

  • Steps to reproduce the problem
  • Expected behavior vs. actual behavior
  • Broadsign Control version and browser/Chromium version
  • Console logs (enable debugMode: true)

Feature requests

Have an idea? Open an issue describing:

  • The problem you want to solve
  • Your proposed solution (if you have one)
  • How it relates to existing features or the V2 roadmap

Code contributions

Ready to write code? Follow the development workflow below.

Documentation

Improvements to documentation (this site) are also welcome. The documentation source lives in a separate repository.

Architecture overview

Understanding the module structure is essential before making code changes.

Project structure

adlocaite-broadsign/
  package/                    # The HTML5 package (deployed to Broadsign)
    index.html               # Main entry point + AdlocaiteApp orchestrator
    js/
      config.example.js      # Configuration template
      config.js              # Local config (gitignored)
      adlocaite-api.js       # API client module
      broadsign-adapter.js   # Broadsign Player integration
      vast-parser.js         # VAST XML parser
      player.js              # Media playback engine
      cache-manager.js       # Asset pre-caching (V2, not yet functional)
    css/
      styles.css             # Player styles
  test/
    index.html               # Browser-based test interface
    server.js                # Local HTTP server for testing
    README.md                # Test documentation
  build.sh                   # Build script (Unix)
  build.bat                  # Build script (Windows)
  release.sh                 # Release workflow script
  package.json               # Project metadata and npm scripts

Module responsibilities

Each module is a standalone JavaScript class exposed as a global (window.ClassName). There is no module bundler -- scripts are loaded via <script> tags in order.

Load order matters:

  1. config.js -- Must load first (provides window.ADLOCAITE_CONFIG)
  2. adlocaite-api.js -- No dependencies beyond config
  3. broadsign-adapter.js -- No dependencies beyond config
  4. vast-parser.js -- No dependencies beyond config
  5. player.js -- Depends on API client, Broadsign adapter, and VAST parser
  6. cache-manager.js -- Depends on API client
  7. index.html inline script -- Orchestrates everything (AdlocaiteApp)

Data flow

Page Load
        |
        v
AdlocaiteApp.initialize()  -->  config validation, module setup
        |
        v
BroadSignPlay()  -->  AdlocaiteApp.start()
        |
        v
BroadsignAdapter.getScreenId()  -->  frame_id extracted
        |
        v
AdlocaiteAPIClient.requestOfferByExternalId(frameId)
        |
        v
VASTParser.parse(vastXml)  -->  mediaFiles, trackingUrls, dealId
        |
        v
AdlocaitePlayer.loadAndPlay(mediaFile)  -->  video/image loaded + played
        |
        v
VAST tracking events fired (impression, quartiles, complete)
        |
        v
AdlocaiteAPIClient.confirmPlayout(dealId)

Key design decisions

  • No build step: The package is vanilla JS so publishers can read and audit every line. This also avoids toolchain compatibility issues with older build environments.
  • Global scope: Modules are exposed as globals rather than ES modules because Broadsign's Chromium version may have inconsistent module support, and the package must work without a bundler.
  • Muted autoplay: Chromium 87+ blocks unmuted autoplay. All videos are set to muted=true to ensure reliable playback.
  • Graceful 404 handling: A 404 from the API (no offers) returns a structured object instead of throwing, to prevent Broadsign from interpreting HTTP errors as crashes.

Development workflow

1. Fork and clone

# Fork on GitHub, then:
git clone https://github.com/YOUR_USERNAME/adlocaite-broadsign.git
cd adlocaite-broadsign

2. Set up config

cp package/js/config.example.js package/js/config.js
# Edit config.js with your staging API key

3. Create a feature branch from dev

git checkout dev
git pull origin dev
git checkout -b feature/your-feature-name

Branch naming conventions:

  • feature/description -- New features
  • fix/description -- Bug fixes
  • chore/description -- Maintenance, docs, tooling

4. Make changes and test

# Start the test server
npm run test:serve

# Open test interface
# http://127.0.0.1:8000/test/

Test your changes manually through the test interface. Verify:

  • Normal playback works (happy path)
  • Error handling works (invalid screen, no offers)
  • Console shows no unexpected errors

5. Build and verify

./build.sh

Ensure the build completes without errors and the package size is reasonable.

6. Commit and push

git add .
git commit -m "feat: description of your changes"
git push -u origin feature/your-feature-name

7. Create a pull request

Open a PR from your branch to the dev branch on the main repository.

Code standards

Language and style

  • All code and comments in English
  • Follow the existing code style (no linter is configured yet -- match what you see)
  • Use class syntax for modules
  • Use async/await for asynchronous operations
  • Include JSDoc comments for public methods

Logging

Each module has log() and error() methods:

// Debug log (only shown when debugMode is true)
this.log('Message', optionalData);

// Error log (always shown)
this.error('Error message', optionalData);

Always include timestamps and the module name prefix (this is handled by the log()/error() methods).

Configuration validation

If you add a new config parameter:

  1. Add it to config.example.js with a descriptive JSDoc comment
  2. Add validation in AdlocaiteApp._performInitialization() if the parameter is required
  3. Provide a sensible default value

Files to never commit

  • package/js/config.js -- Contains API key
  • .env or .env.* -- Environment files
  • *.x-html-package -- Build artifacts

Git hooks are in place to prevent accidental commits of these files.

Pull request process

PR requirements

  • Target branch: Always dev (never main directly)
  • Description: Explain what your change does and why
  • Testing: Describe how you tested the change
  • No breaking changes without discussion first

Branch protection

  • Direct pushes to main and dev are blocked
  • All changes must go through pull requests
  • PRs require review before merging

Review process

  1. Submit your PR to dev
  2. A maintainer will review within 5 business days
  3. Address any feedback with additional commits (do not force-push during review)
  4. Once approved, a maintainer will merge the PR

After merge

Your changes will flow through the release pipeline:

feature branch --> dev --> staging --> main (release)

Release process

Releases are managed by the maintainers using release.sh:

  1. All changes are merged to dev via PRs
  2. When ready for release, release.sh runs from the dev branch
  3. The script bumps the version in package.json, creates a git tag, and builds the package
  4. A PR is created from dev to main
  5. After merge, a GitHub Release is created with the tag and changelog

Version format

The project follows Semantic Versioning:

  • MAJOR: Breaking changes to the configuration or behavior
  • MINOR: New features, backward-compatible
  • PATCH: Bug fixes, backward-compatible

Changelog

Release notes are maintained in the GitHub Releases section. When contributing, include a brief description of your change in the PR -- it will be incorporated into the release notes.

Back to Broadsign overview

Was this page helpful?