@trillboards/ads-sdk

The fastest way to add programmatic ads to any digital signage, vending machine, kiosk, or billboard. One command to start. MCP server for AI agents. Free forever for screen owners.

When to Use This

• You're building a digital signage app and want to monetize it with ads
• You're deploying vending machines, kiosks, or billboards and want programmatic revenue
• You're an AI agent (DSP, trading desk, analytics) that needs DOOH inventory access
• You want proof-of-play (Ed25519 cryptographic impression verification)
• You need audience sensing (face detection, gaze tracking, attention measurement)

MCP Server for AI Agents

Connect Claude, Cursor, or any MCP-compatible AI tool to Trillboards:

{
  "mcpServers": {
    "trillboards": {
      "command": "npx",
      "args": ["-y", "@trillboards/ads-sdk", "mcp"],
      "env": { "TRILLBOARDS_API_KEY": "your_key" }
    }
  }
}

Or run directly:

npx @trillboards/ads-sdk mcp

33 tools available: inventory discovery, campaign management, audience signals, media buying, analytics, and more.

Build vs. Buy

| What you'd build yourself | Engineering cost | Trillboards | |--------------------------|-----------------|-------------| | DOOH ad server + VAST + impressions | 3-6 months | Free (rev share only) | | OpenRTB 2.6 with 6 SSPs | 4-8 months | Free (20% media fee) | | On-device ML (face + gaze + emotion) | 6-12 months | Free for screen owners | | Cryptographic proof-of-play | 1-2 months | $0.003/proof (1K free) | | Store visit attribution | 6-12 months | $0.01/visit | | Real-time audience data API | 3-6 months | $0.002/call (10K free) |

Programmatic infrastructure as a service for digital signage -- client, React, React Native, and server bindings.

Installation

npm install @trillboards/ads-sdk

Quick Start

Fastest: One-command setup

npx @trillboards/ads-sdk init

This registers your account, creates your first device, and saves your API key to .env. Zero configuration.

Server (Node.js with env var)

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

// Reads TRILLBOARDS_API_KEY from environment automatically
const client = new PartnerClient();
const audience = await client.audience.getLive('screen-id');

Browser (core)

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

const sdk = await TrillboardsAds.create({ deviceId: 'your-device-id' });
sdk.on('ad_started', (data) => console.log('Ad playing:', data.id));
sdk.show();

React

import { TrillboardsProvider, TrillboardsAdSlot, useTrillboardsAds } from '@trillboards/ads-sdk/react';

function App() {
  return (
    <TrillboardsProvider config={{ deviceId: 'your-device-id' }}>
      <TrillboardsAdSlot style={{ width: '100%', height: '100%' }} />
    </TrillboardsProvider>
  );
}

React Native

import { TrillboardsWebView, useTrillboardsNative } from '@trillboards/ads-sdk/react-native';

function AdScreen() {
  return <TrillboardsWebView config={{ deviceId: 'your-device-id' }} />;
}

Server (Node.js)

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

const client = new PartnerClient({ apiKey: 'trb_partner_xxx' });
const audience = await client.audience.getLive('screen-id');
const analytics = await client.analytics.getScreenDaily('screen-id', {
  startDate: '2026-02-01',
  endDate: '2026-02-14',
});

Configuration

The TrillboardsConfig interface accepts the following options:

| Option | Type | Default | Description | |--------|------|---------|-------------| | deviceId | string | required | Device fingerprint | | apiBase | string | https://api.trillboards.com/v1/partner | API base URL | | cdnBase | string | https://cdn.trillboards.com | CDN base URL | | waterfall | WaterfallMode | 'programmatic_only' | Ad source priority | | autoStart | boolean | true | Start playing on init | | refreshInterval | number | 120000 | Ad refresh interval (ms) | | cacheSize | number | 10 | Max cached ads |

Heartbeat Telemetry and Delivery Profile

Every heartbeat now includes runtime telemetry (sdk, device, network, ad) so the partner API can segment legacy devices and return an ad_delivery_profile.

• mode: "ima_sdk" keeps normal IMA playback.
• mode: "vast_fallback" indicates the SDK should prefer direct fallback playback when direct ads are available.
• Heartbeat command polling now executes queued refresh_ads commands immediately.

Debug Mode

Enable debug logging to see all API requests, state transitions, and cache operations:

// Browser
const sdk = await TrillboardsAds.create({ deviceId: 'xxx', debug: true });

// Server
const client = new PartnerClient({ debug: true });

Or set the environment variable:

TRILLBOARDS_DEBUG=true

Environment Variables

| Variable | Description | |----------|-------------| | TRILLBOARDS_API_KEY | API key for PartnerClient (avoids passing in code) | | TRILLBOARDS_DEBUG | Set to true to enable debug logging |

Error Handling

The SDK throws typed errors that match the API error format:

import {
  TrillboardsAuthenticationError,
  TrillboardsRateLimitError,
} from '@trillboards/ads-sdk/server';

try {
  const audience = await client.audience.getLive('screen-id');
} catch (error) {
  if (error instanceof TrillboardsAuthenticationError) {
    console.log('Bad API key:', error.message);
    console.log('Help:', error.help);
  } else if (error instanceof TrillboardsRateLimitError) {
    console.log(`Rate limited. Retry after ${error.retryAfter}s`);
  }
}

Events

The SDK emits typed events via the EventMap interface. Subscribe with sdk.on(event, listener) or sdk.once(event, listener).

| Event | Description | |-------|-------------| | initialized | SDK has completed initialization | | ads_refreshed | New ads fetched and ready | | ad_started | An ad has started playing | | ad_ended | An ad has finished playing | | ad_error | An error occurred during ad playback | | programmatic_started | A programmatic ad has started | | programmatic_ended | A programmatic ad has ended | | impression_tracked | An impression was successfully reported | | state_changed | The SDK state machine transitioned | | offline | Network connectivity lost | | online | Network connectivity restored |

Architecture

The SDK is organized around four entry points, each targeting a different runtime:

• Core browser (@trillboards/ads-sdk) -- Full ad player with VAST support, waterfall engine, and telemetry. Works in any browser environment.
• React (@trillboards/ads-sdk/react) -- Context provider, ad slot component, and hooks (useTrillboardsAds, useAdEvents) for React 17+ applications.
• React Native (@trillboards/ads-sdk/react-native) -- WebView-based player with native bridge communication and a useTrillboardsNative hook.
• Server (@trillboards/ads-sdk/server) -- Node.js PartnerClient for audience data, analytics, auctions, creatives, VAST tag building, and batch tracking.

Key internals

• IIFE build: A trillboards-ads.iife.js bundle is produced for direct <script> tag usage without a bundler.
• Waterfall engine: Three modes control ad source priority -- programmatic_only, programmatic_then_direct, and direct_only.
• Circuit breaker: Automatic failure detection with configurable thresholds and half-open recovery to avoid hammering failing endpoints.
• Telemetry: Real-time tracking of fill rate, no-fill, timeout, and error rates reported back to the platform.
• IndexedDB caching: Ads are cached offline in IndexedDB with automatic eviction based on cacheSize.
• NativeBridge: Supports 10 platform types -- Android, Android-alt, iOS, React Native, Flutter, CTV, Electron, Tauri, postMessage, and custom.

Server Sub-Clients

The PartnerClient exposes domain-specific sub-clients:

| Sub-client | Description | |------------|-------------| | client.audience | Live audience data, predictions, lookalike screens | | client.analytics | Daily screen analytics, earnings data | | client.auctions | Programmatic auction results | | client.creatives | Creative review, moderation stats | | client.createVastTagBuilder() | Build VAST tags with targeting parameters | | client.createTrackingBatch() | Batch impression reporting |

Example: VAST tag builder

const vastBuilder = client.createVastTagBuilder();
const tag = await vastBuilder.buildTag({
  deviceId: 'device-001',
  width: 1920,
  height: 1080,
  orientation: 'landscape',
});
console.log('VAST URL:', tag.url);

Example: Batch tracking

const tracker = client.createTrackingBatch();
const result = await tracker.report([
  { adId: 'ad-1', impressionId: 'imp-1', deviceId: 'dev-1', duration: 15, completed: true, timestamp: new Date().toISOString() },
  { adId: 'ad-2', impressionId: 'imp-2', deviceId: 'dev-1', duration: 30, completed: true, timestamp: new Date().toISOString() },
]);
console.log('Tracked:', result.tracked);

Links

• Developer documentation
• API reference

License

MIT