@trillboards/connect

Zero-friction partner onboarding SDK for digital signage ad monetization. One init() call handles device registration, ad fetching, rendering, offline caching, and analytics.

Installation

npm install @trillboards/connect

Or via CDN:

<script src="https://unpkg.com/@trillboards/connect/dist/trillboards-connect.global.js"></script>

Quick Start

const TrillboardsConnect = require('@trillboards/connect');
// or: import TrillboardsConnect from '@trillboards/connect';

const trillboards = TrillboardsConnect.init({
  apiKey: 'trb_partner_xxx',
  deviceId: 'my-screen-001',
  containerId: 'ad-container',
  options: {
    heartbeatInterval: 60000,
    adInterval: 60,
    muted: true,
    offlineCache: true,
    analytics: true,
  },
});

trillboards.on('ready', (data) => {
  console.log('SDK ready:', data.fingerprint);
});

trillboards.on('ad_start', (data) => {
  console.log('Ad started:', data.ad.id);
});

Configuration

| Option | Type | Default | Description | |--------|------|---------|-------------| | apiKey | string | required | Partner API key (trb_partner_xxx) | | deviceId | string | required | Unique device identifier | | containerId | string \| HTMLElement | null | DOM container for ad rendering | | options.heartbeatInterval | number | 60000 | Heartbeat interval in ms | | options.adInterval | number | 60 | Ad rotation interval in seconds | | options.muted | boolean | true | Start video ads muted | | options.offlineCache | boolean | true | Enable IndexedDB offline caching | | options.analytics | boolean | true | Enable analytics event buffering | | options.deviceType | string | 'digital_signage' | Device type for registration | | options.deviceName | string | 'SDK Device: <deviceId>' | Friendly device name | | options.display | object | auto-detected | Display specs { width, height } | | options.location | object | {} | Location { lat, lng, address, venue_type } | | options.metadata | object | {} | Custom metadata sent with registration | | options.objectFit | string | 'cover' | CSS object-fit for ad rendering |

Events

| Event | Data | Description | |-------|------|-------------| | ready | { deviceId, fingerprint, screenId, embedUrl } | SDK fully initialized | | device_registered | { fingerprint, screen_id, embed_url } | Device registered with API | | device_status | { from, to, deviceId } | Device status changed | | ad_start | { ad, type, timestamp } | Ad started rendering | | ad_complete | { ad, type, duration, completed } | Ad finished rendering | | ad_error | { ad, type, error } | Ad rendering error | | impression | { ad, result, totalImpressions } | Impression tracked | | heartbeat | { beat, status, timestamp } | Heartbeat sent | | heartbeat_error | { error, consecutiveFailures, willRetry } | Heartbeat failed | | sync_complete | { total, synced, failed } | Offline impressions synced | | connectivity_change | { online } | Online/offline status changed | | analytics_flush | { flushed, errors } | Analytics buffer flushed | | socket_connected | { socketId } | Socket.io connected | | socket_disconnected | { reason } | Socket.io disconnected | | config_updated | { config, source } | Config updated via socket | | error | { phase, error, fatal? } | General error |

API

TrillboardsConnect.init(config)

Initialize the SDK. Returns a ConnectInstance that begins initialization asynchronously.

TrillboardsConnect.create(config)

Create an uninitialized instance for advanced use cases. Call instance.initialize() manually.

Instance Methods

| Method | Description | |--------|-------------| | on(event, callback) | Register an event listener | | off(event, callback) | Remove an event listener | | nextAd() | Skip to the next ad | | pause() | Pause ad rotation | | resume() | Resume ad rotation | | getState() | Get complete SDK state | | queueOfflineImpression(data) | Queue an impression for offline sync | | syncOffline() | Force sync offline impressions | | cacheAdsOffline(ads) | Cache ads for offline playback | | destroy() | Clean up all resources |

Sub-Modules

For advanced usage, sub-modules are exposed directly:

• TrillboardsConnect.device — Registration, fingerprinting, heartbeat
• TrillboardsConnect.auction — Ad fetching, rendering, VAST parsing
• TrillboardsConnect.offline — IndexedDB caching and impression queue
• TrillboardsConnect.branding — CSS injection and white-labeling
• TrillboardsConnect.analytics — Event buffering and batch sending

License

MIT