Proof of play -- per-layout and per-widget duration tracking with IndexedDB persistence
Hour-boundary splitting -- stats crossing hour boundaries are split for correct CMS aggregation
Aggregation modes -- individual or aggregated submission (configurable from CMS)
Event stats -- point-in-time engagement data (touch, webhook, interactive triggers)
Log reporting -- display logs batched and submitted to CMS (max 50 per batch)
Fault alerts -- error deduplication with 5-minute cooldown, triggers CMS dashboard alerts
enableStat -- per-layout/per-widget stat suppression via XLF flags
Quota resilience -- auto-cleans oldest 100 submitted records on IndexedDB quota exceeded

Architecture

Renderer events                StatsCollector              CMS
(widgetStart/widgetEnd)        (IndexedDB)                (XMDS)
                                    |
widgetStart(id, layout) -----> startWidget() -----> [in-progress Map]
                                    |
widgetEnd(id, layout) -------> endWidget() -------> [split at hour]
                                    |                      |
                                    v                      v
                               IndexedDB            getStatsForSubmission(50)
                               (xibo-player-stats)         |
                                    |                formatStats() -> XML
                                    |                      |
                                    v               submitStats() -----> CMS
                               clearSubmittedStats()

Renderer events                LogReporter                 CMS
(errors, status)               (IndexedDB)                (XMDS)
                                    |
log('error', msg) -----------> _saveLog() -------> IndexedDB
reportFault(code, reason) ---> [dedup 5min] -----> [alertType field]
                                    |
                               getLogsForSubmission(50)
                                    |
                               formatLogs() -> XML
                                    |
                               submitLog() ---------> CMS

Installation

npm install @xiboplayer/stats

Usage

StatsCollector -- proof of play

import { StatsCollector, formatStats } from '@xiboplayer/stats';

const stats = new StatsCollector();
await stats.init();

// Track layout playback
await stats.startLayout(123, 456); // layoutId, scheduleId
// ... layout plays for 30 seconds ...
await stats.endLayout(123, 456);

// Track widget playback
await stats.startWidget(789, 123, 456); // mediaId, layoutId, scheduleId
// ... widget plays ...
await stats.endWidget(789, 123, 456);

// Record interactive event
await stats.recordEvent('touch', 123, 789, 456); // tag, layoutId, widgetId, scheduleId

// Submit to CMS
const pending = await stats.getStatsForSubmission(50);
if (pending.length > 0) {
  const xml = formatStats(pending);
  await xmds.submitStats(xml);
  await stats.clearSubmittedStats(pending);
}

Aggregated submission

// When CMS aggregationLevel is 'Aggregate':
const aggregated = await stats.getAggregatedStatsForSubmission(50);
// Groups by (type, layoutId, mediaId, scheduleId, hour) and sums durations
const xml = formatStats(aggregated);
await xmds.submitStats(xml);
// Clear using _rawIds from aggregated records

LogReporter -- CMS logging

import { LogReporter, formatLogs, formatFaults } from '@xiboplayer/stats';

const reporter = new LogReporter();
await reporter.init();

// Log messages (stored in IndexedDB, submitted in batches)
await reporter.error('Failed to load layout', 'PLAYER');
await reporter.info('Layout loaded successfully', 'PLAYER');
await reporter.debug('Rendering widget 42', 'RENDERER');

// Report fault (triggers CMS dashboard alert)
await reporter.reportFault('LAYOUT_LOAD_FAILED', 'Layout 123 failed to render');
// Same code won't be reported again within 5 minutes (deduplication)

// Submit logs to CMS
const logs = await reporter.getLogsForSubmission(50);
if (logs.length > 0) {
  const xml = formatLogs(logs);
  await xmds.submitLog(xml);
  await reporter.clearSubmittedLogs(logs);
}

// Submit faults (faster cycle, ~60s)
const faults = await reporter.getFaultsForSubmission(10);
if (faults.length > 0) {
  const json = formatFaults(faults);
  await xmds.reportFaults(json);
  await reporter.clearSubmittedLogs(faults);
}

Stat Types

Type	Tracked by	Fields
`layout`	startLayout/endLayout	layoutId, scheduleId, start, end, duration, count
`media`	startWidget/endWidget	mediaId, widgetId, layoutId, scheduleId, start, end, duration
`event`	recordEvent	tag, layoutId, widgetId, scheduleId, start (point-in-time)

API Reference

StatsCollector

new StatsCollector(cmsId?)

Method	Returns	Description
`init()`	Promise	Initialize IndexedDB (idempotent)
`startLayout(layoutId, scheduleId, opts?)`	Promise	Start tracking layout
`endLayout(layoutId, scheduleId)`	Promise	End layout, save to DB
`startWidget(mediaId, layoutId, scheduleId, widgetId?, opts?)`	Promise	Start tracking widget
`endWidget(mediaId, layoutId, scheduleId)`	Promise	End widget, save to DB
`recordEvent(tag, layoutId, widgetId, scheduleId)`	Promise	Record instant event
`getStatsForSubmission(limit?)`	Promise	Get unsubmitted stats (default 50)
`getAggregatedStatsForSubmission(limit?)`	Promise	Get grouped stats
`clearSubmittedStats(stats)`	Promise	Delete submitted records
`getAllStats()`	Promise	All stats (debugging)
`clearAllStats()`	Promise	Clear everything (testing)

LogReporter

new LogReporter(cmsId?)

Method	Returns	Description
`init()`	Promise	Initialize IndexedDB
`log(level, message, category?, extra?)`	Promise	Store log entry
`error(message, category?)`	Promise	Shorthand for log('error', ...)
`audit(message, category?)`	Promise	Shorthand for log('audit', ...)
`info(message, category?)`	Promise	Shorthand for log('info', ...)
`debug(message, category?)`	Promise	Shorthand for log('debug', ...)
`reportFault(code, reason, cooldownMs?)`	Promise	Report fault with dedup (default 5min cooldown)
`getLogsForSubmission(limit?)`	Promise	Get unsubmitted logs (default 50)
`getFaultsForSubmission(limit?)`	Promise	Get unsubmitted faults (default 10)
`clearSubmittedLogs(logs)`	Promise	Delete submitted records

Formatters

Function	Returns	Description
`formatStats(stats)`	string	Format stats as XML for XMDS SubmitStats
`formatLogs(logs)`	string	Format logs as XML for XMDS SubmitLog
`formatFaults(faults)`	string	Format faults as JSON for XMDS ReportFaults