Developer Guide: Trillboards SDK for Custom DOOH Signage

As physical environments increasingly transition to digital-first media networks, developers require agile, high-performance programmatic DOOH SDK solutions.

Traditional, closed digital signage software models are being disrupted by modern API-first, headless digital signage platform architectures.

According to industry analysts, the shift away from costly, per-screen monthly SaaS fees to developer-friendly, ad-supported monetization structures is lowering entry barriers for businesses of all sizes.

At the center of this movement is the Trillboards SDK, which allows developers to build robust, customized signage applications with ease.

With 60,000+ DOOH screens under contract and 14,765+ screens actively onboarded and emitting live heartbeats, Trillboards provides the enterprise-grade infrastructure required to scale a modern advertising network.

This guide provides a comprehensive, step-by-step walkthrough for integrating typescript DOOH ads into your custom hardware or software applications.

---

The Programmatic DOOH Landscape

Building a custom digital signage network from scratch is a massive engineering undertaking.

Historically, developers had to choose between paying exorbitant monthly fees to legacy CMS providers or spending upwards of $500,000 building a custom ad server.

Trillboards eliminates this dilemma by providing a completely free, API-first ad server.

Publishers pay $0/screen/month, allowing them to scale their hardware footprint without scaling their software costs.

Instead of charging software fees, the platform monetizes through ad demand.

The programmatic ad revenue is split exactly 60/40 in the publisher's favor: the venue or publisher keeps 60%, and Trillboards keeps 40%.

The Importance of OpenRTB 2.6 Integration

Standardizing programmatic trading is critical for attracting premium global advertisers.

As documented by the Out of Home Advertising Association of America (OAAA), the integration of DOOH specifications into the OpenRTB methodology provides standardized schemas and bid extensions tailored specifically to physical displays.

This includes crucial features like impression multipliers for multi-viewer screens.

By leveraging the Trillboards developer ecosystem, engineers can programmatically bridge global demand-side platforms (DSPs) to local venue screens with total measurement confidence.

To ensure maximum brand safety and advertiser trust, Trillboards executes a rigorous 14-check OpenRTB 2.6 supply-chain validation runbook (including sellers.json, ads.txt, and schain validation) on every single VAST request.

Furthermore, the platform's intelligent categorization engine has performed 92,354 creative-level classifications performed across 131 IAB Content Taxonomy top-level categories.

---

Prerequisites and Architecture

Before diving into the code, you must understand the core architecture of the Trillboards SDK.

Trillboards operates on a webhook-driven event architecture, handling device status, impressions, payouts, and audience spikes in real-time.

What You Will Need

To complete this tutorial, ensure you have the following prerequisites ready.

1. A Trillboards Developer Account (API Tier: Basic or Developer)
2. Node.js (v18+) and npm/yarn installed
3. A basic understanding of TypeScript and React (or vanilla JavaScript)
4. Your Trillboards API Key and Publisher ID

What You Will Build

We will construct a headless digital signage application that automatically registers devices, fetches programmatic demand, renders video ads, and fires cryptographic proof-of-play beacons.

Key Insight: The @trillboards/ads-sdk handles the heavy lifting of the VAST waterfall, meaning you don't have to manually parse XML or manage bid timeouts.

---

Step 1: Setting Up the Headless Digital Signage Platform

The first step in digital signage development with Trillboards is installing the necessary packages.

The TypeScript DOOH ads framework includes the feature-rich @trillboards/ads-sdk and the lightweight, zero-config @trillboards/connect library.

These libraries enable quick implementation within React, React Native, or Flutter applications running on standard WebViews or smart TVs.

Installation Commands

Open your terminal and initialize a new project, then install the SDK.

# Initialize a new Node project
npm init -y

# Install the Trillboards SDK packages
npm install @trillboards/ads-sdk @trillboards/connect

# Install TypeScript dependencies for development
npm install -D typescript @types/node

Once installed, you can import the core modules into your application.

---

Step 2: SDK Initialization and Authentication

Authentication is handled via secure API keys generated in your Trillboards publisher dashboard.

You must initialize the SDK before attempting to register screens or request ads.

Initializing the Client

Create a new file named trillboards-client.ts and add the following configuration.

import { TrillboardsAds } from '@trillboards/ads-sdk';

// Initialize the SDK with your Publisher credentials
const tbClient = new TrillboardsAds({
  publisherId: process.env.TRILLBOARDS_PUB_ID,
  apiKey: process.env.TRILLBOARDS_API_KEY,
  environment: 'production', // Use 'sandbox' for testing
  logLevel: 'info'
});

export default tbClient;

Understanding the Configuration Object

The configuration object accepts several crucial parameters.

Environment Settings

Always use sandbox during local development to prevent polluting your production analytics or triggering false ad requests.

Log Levels

Set logLevel to debug when troubleshooting VAST waterfall timeouts or OpenRTB bid rejections.

---

Step 3: Device Registration & Heartbeats

In a programmatic DOOH SDK, the platform must know a screen is online before it routes ad demand to it.

This is achieved through device registration and continuous heartbeats.

Registering a New Screen

When your custom signage software boots up for the first time, it should register itself with the Trillboards API.

import tbClient from './trillboards-client';

async function registerDevice() {
  try {
    const device = await tbClient.devices.register({
      hardwareId: 'MAC-ADDRESS-OR-UUID',
      resolution: '1920x1080',
      orientation: 'landscape',
      venueId: 'VENUE-12345', // Your IAB OpenOOH taxonomy venue ID
      capabilities: ['video/mp4', 'image/jpeg']
    });
    
    console.log(`Device registered successfully. ID: ${device.id}`);
    return device;
  } catch (error) {
    console.error('Device registration failed:', error);
  }
}

Emitting Live Heartbeats

Once registered, the device must emit a heartbeat every 60 seconds.

If a device misses three consecutive heartbeats, the Trillboards SSP automatically removes it from the active auction pool.

// Start the heartbeat interval
function startHeartbeat(deviceId: string) {
  setInterval(async () => {
    await tbClient.devices.heartbeat(deviceId, {
      status: 'online',
      temperature: 45, // Optional hardware telemetry
      freeMemory: '1024MB'
    });
  }, 60000); // 60 seconds
}

Pro Tip: Reliable heartbeats are critical for monetization. DSPs will not bid on inventory that appears offline or unstable.

---

Step 4: Requesting Programmatic Demand via OpenRTB 2.6

This is the core revenue engine of your headless digital signage platform.

When you request an ad, the Trillboards SSP executes a multi-demand-source VAST waterfall.

This waterfall includes integrations with Google Ad Manager (GAM), HiveStack, Vidverto, and the native OpenRTB exchange.

Formulating the Ad Request

To fetch an ad, you must provide context about the screen, the venue, and the audience.

async function fetchAd(deviceId: string) {
  const adResponse = await tbClient.ads.request({
    deviceId: deviceId,
    inventoryType: 'DOOH',
    adTypes: ['video'],
    maxDuration: 15, // Maximum 15-second spots
    minBitrate: 2500,
    bcat: ['IAB7-39', 'IAB8-18'], // Blocked IAB categories (e.g., adult, gambling)
    impFormat: {
      w: 1920,
      h: 1080
    }
  });

  return adResponse;
}

Handling the Response

The SDK parses the complex VAST XML response and returns a clean, developer-friendly JSON object.

This object contains the media URL, the cryptographic proof-of-play tokens, and the required tracking beacons.

Example JSON Response

{
  "adId": "ad_987654321",
  "mediaUrl": "https://cdn.trillboards.com/creatives/video_xyz.mp4",
  "duration": 15,
  "cpm": 12.50,
  "trackingEvents": {
    "impression": ["https://track.trillboards.com/imp?id=..."],
    "firstQuartile": ["https://track.trillboards.com/q1?id=..."],
    "midpoint": ["https://track.trillboards.com/mid?id=..."],
    "thirdQuartile": ["https://track.trillboards.com/q3?id=..."],
    "complete": ["https://track.trillboards.com/comp?id=..."]
  }
}

---

Step 5: Playback, Proof-of-Play, and Telemetry

Playing the video is only half the battle in digital signage development.

You must prove to the advertiser that the ad actually played on the screen.

Cryptographic Proof-of-Play

Trillboards requires cryptographic proof-of-play signed with Ed25519 to prevent impression fraud.

The SDK handles this signing process automatically when you call the tracking methods.

import { useRef, useEffect } from 'react';

function AdPlayer({ adData }) {
  const videoRef = useRef(null);

  useEffect(() => {
    const video = videoRef.current;
    
    // Fire impression beacon when video starts
    const handlePlay = () => {
      tbClient.tracking.fireImpression(adData.adId);
    };

    // Fire completion beacon when video ends
    const handleEnded = () => {
      tbClient.tracking.fireCompletion(adData.adId);
    };

    video.addEventListener('play', handlePlay);
    video.addEventListener('ended', handleEnded);

    return () => {
      video.removeEventListener('play', handlePlay);
      video.removeEventListener('ended', handleEnded);
    };
  }, [adData]);

  return (
    <video 
      ref={videoRef} 
      src={adData.mediaUrl} 
      autoPlay 
      muted 
      style={{ width: '100%', height: '100%' }}
    />
  );
}

OM SDK (Open Measurement) Verification

For premium programmatic campaigns, DSPs require MRC-compliant ad verification.

The Trillboards SDK natively wraps the IAB Tech Lab's OM SDK, providing viewability telemetry without requiring additional custom code from your team.

---

Step 6: Real-Time Audience Intelligence

Advertisers pay higher CPMs for screens that can prove who is watching.

Trillboards excels in real-time audience intelligence, capturing demographics, dwell time, and attention metrics.

Currently, the platform has 675 IAB audience segments observed in live impressions over the past 60 days.

Webhooks and Audience Spikes

You can configure webhooks in your developer dashboard to receive real-time alerts when audience density spikes at a specific venue.

This allows your custom application to dynamically switch from ambient content to high-value programmatic ads.

// Example Express.js Webhook Receiver
app.post('/webhooks/trillboards', express.json(), (req, res) => {
  const event = req.body;

  if (event.type === 'audience.spike') {
    console.log(`Audience spike at venue ${event.venueId}!`);
    // Trigger immediate ad request in your application logic
  }

  res.status(200).send('Webhook received');
});

---

Step 7: Error Handling & Offline Caching

Physical screens operate in unpredictable environments with spotty internet connections.

A robust headless digital signage platform must handle offline scenarios gracefully.

Implementing IndexedDB Fallbacks

The @trillboards/connect library offers native capabilities for offline caching via IndexedDB.

This prevents black screens during connection drops.

async function safeFetchAd(deviceId: string) {
  try {
    // Attempt to fetch a fresh programmatic ad
    return await fetchAd(deviceId);
  } catch (error) {
    console.warn('Network offline, falling back to cached ad...');
    
    // Retrieve pre-cached fallback content from IndexedDB
    const cachedAd = await tbClient.cache.getFallbackContent(deviceId);
    return cachedAd;
  }
}

Key Insight: Always configure at least 3 fallback creatives (like house ads or weather widgets) in your publisher dashboard to ensure 100% screen uptime.

---

Partner Use Cases: Custom Hardware Integration

The flexibility of the Trillboards API allows operators to monetize incredibly unique physical footprints.

For example, developers are integrating the SDK into specialized kiosks, as VapeTM demonstrates with their smart vending machines with digital displays and advertising screens.

By embedding the SDK directly into the vending machine's Android-based operating system, operators generate passive programmatic revenue while customers interact with the hardware.

Similarly, high-traffic venues benefit from custom integrations, as JUUCE demonstrates with their portable phone charger rental kiosks with digital signage in stadiums.

These unique form factors leverage the SDK's OpenOOH venue taxonomy to accurately classify their inventory, ensuring DSPs bid appropriately on these highly targeted screens.

---

Advanced API Usage: Managing Devices via REST

While the SDK is ideal for frontend playback, backend systems often need to manage fleets of screens programmatically.

Trillboards provides a full OpenAPI spec with a Swagger UI available at /developer/docs.

Example: Fetching Device Status via cURL

You can query the status of your entire network using standard REST endpoints.

curl -X GET "https://api.trillboards.com/v1/devices?status=online" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

This allows CTOs and VP Engineering leads to integrate screen monitoring directly into their existing Datadog or Grafana dashboards.

API Tier Limits

Ensure you monitor your API usage based on your account tier.

• Basic Tier: 200 requests per minute.
• Developer Tier: 1,000 requests per minute (includes venue intelligence).
• Enterprise Tier: 5,000 requests per minute (includes raw data exports and dedicated SLAs).

---

Monetization Economics and Revenue Share

Unlike traditional digital signage software companies that offer no ad revenue, Trillboards IS the revenue layer.

The financial model is highly transparent and designed to incentivize network growth.

As stated previously, the programmatic ad revenue is split exactly 60/40 in the publisher's favor: the venue or publisher keeps 60%, and Trillboards keeps 40%.

Because you pay $0/screen/month for the software itself, your capital expenditure is limited entirely to your hardware and installation costs.

This API-first, free model has caught the attention of the broader industry.

Publications are noting this disruption; for instance, the shift is detailed when a startup pitches free CMS and device management platforms for SMB digital signage.

Furthermore, the platform's rapid expansion is evident as Trillboards debuts its all-in-one free initiative, proving that the ad-supported model is the future of physical media networks.

---

Conclusion and Next Steps

Building a custom ad-supported signage network no longer requires millions of dollars in venture capital or years of backend engineering.

By utilizing the Trillboards programmatic DOOH SDK, your development team can transform any screen into a revenue-generating asset in a matter of days.

From seamless typescript DOOH ads integration to rigorous OpenRTB 2.6 integration, the platform provides all the infrastructure-as-a-service required by modern media enterprises.

Ready to start building your own headless digital signage platform?

Create your free publisher account today, generate your API keys, and deploy your first screen.

---

Frequently Asked Questions (FAQ)

What programming languages does the Trillboards SDK support?

The primary Partner SDK (@trillboards/ads-sdk) is written in TypeScript, making it natively compatible with React, React Native, Node.js, and vanilla JavaScript. We also offer comprehensive REST APIs for integration with Python, Go, and C++ backends.

How does the 60/40 revenue share actually work?

The programmatic ad revenue is split exactly 60/40 in the publisher's favor: the venue or publisher keeps 60%, and Trillboards keeps 40%. There are no hidden fees, and you pay $0/screen/month for the ad server software.

Can I use the SDK on custom Android hardware?

Yes. Developers frequently use the SDK within React Native applications or standard WebViews running on custom Android-based smart displays, kiosks, and vending machines.

How does the SDK handle offline screens?

The @trillboards/connect library utilizes IndexedDB to cache fallback creatives locally on the device. If the screen loses internet connectivity, the SDK automatically plays the cached content to prevent black screens.

Is the Trillboards SSP compatible with Google Ad Manager (GAM)?

Absolutely. The platform features deep Google Ad Manager (GAM) integration, utilizing IVT-compliant VAST tags and OpenOOH venue taxonomy to ensure seamless waterfall execution alongside our native OpenRTB exchange.

How do I troubleshoot rejected OpenRTB bid requests?

We recommend setting the SDK logLevel to debug during development. Additionally, you can review the 14-check OpenRTB 2.6 supply-chain validation logs in your developer dashboard to identify issues with ads.txt, sellers.json, or missing venue taxonomy data.

Where can I find the full API documentation?

The complete OpenAPI specification, including interactive Swagger UI endpoints for device, audience, venue, and webhook management, is available in your publisher dashboard under the Developer Tools section.