# Wallboard Proof of Play System Documentation

## System Overview

Wallboard Proof of Play is an analytics system that tracks and reports digital signage content display, performance, and interactions. The system collects data about what content was displayed, for how long, and how users interacted with it.

**Core capabilities:**
- Multi-level tracking: Content, Page, Widget, and Asset levels
- Advertiser attribution across all content levels
- Custom statistics for business-specific metrics
- Audience/impression metrics from active viewer count signals
- 1-year data retention with 3-month maximum query window
- Export capabilities (CSV, image)

**Data collection principles:**
- Content and Slide types automatically report proof of play
- Media files in playlists require "Media asset proof of play" setting enabled
- Only completely played content counts (partial playback is not tracked)
- Audience metrics require an active viewer count source; default is 0 viewers
- System reports what actually played on screen (respects exclusive modes and schedule priorities)

## User Interface Access Points

### Analytics Menu Tabs
The main Proof of Play interface is accessible through Analytics → Proof of Play with these tabs:

**Contents Tab:** Primary view for content-centric analysis. Shows display time by content with grouping options that dynamically appear based on selection. When "All contents" is selected, grouping is limited to content page and widget only. When specific content is selected, all grouping options become available including device, device folder, media file, and custom statistics.

**Devices Tab:** Device-centric view with tag-based filtering capability. Supports filtering by device name, content, tag, or MAC address. Device folders enable geographic or organizational analysis. Tag filtering is available for pre-filtering devices but tags cannot be used for grouping.

**Media Files Tab:** Tracks media file performance when "Media asset proof of play" is enabled for playlist items. Often shows "No data" if media tracking is not enabled.

**Advertisers Tab:** Tracks advertiser performance with asset-level detail. Supports "Group by asset" for breakdown by page, media, or custom types. Enables generation of public links for external advertisers with key-based authentication for CSV export. Currently provides display metrics only without cost calculations or balance tracking.

**Channels Tab:** Reports on channel-based content distribution. Supports grouping by device, device folder, content, and content page.

**Sub Channels Tab:** Similar to Channels but for sub-channel level reporting within the channel hierarchy.

**Custom Statistics Tab:** Displays custom metrics collected through touch events or other custom tracking. Limited to device and device folder grouping only.

### Entity-Specific Proof of Play Access

**Direct entity shortcuts:** Every major entity in Wallboard has a direct Proof of Play access point that pre-filters data from that entity's perspective:

**Device Details → Proof of Play tab:** When viewing a specific device's details, a Proof of Play tab shows data filtered for that device. All grouping options available from device perspective (by content, content page, media file, advertiser, channel, custom statistics, widget).

**Content Details → Proof of Play tab:** When viewing a specific content's details, shows proof of play data pre-filtered for that content.

**Channels List → "Go to proof of play" button:** Direct navigation to proof of play pre-filtered for that specific channel.

**Similar shortcuts exist for:** Playlists, Schedules, Sub-channels, Media files, and other entities. Each provides pre-filtered proof of play view from that entity's perspective, eliminating need to manually search and filter in the main Analytics interface.

## Filtering and Grouping Logic

### Dynamic Performance Protection

The system prevents combinations that would generate excessive data points:

**All contents selected:**
- Available: Group by content page, Group by widget
- Disabled: Group by device, device folder, media file, custom statistics
- Reason: Prevents combinations like 50 contents × 1000 devices × 7 days = 350,000 data points

**Specific content selected:**
- All grouping options available
- Finer time granularity available (hourly instead of weekly minimum)

### Tag Filtering vs Grouping

Tags can be used for filtering devices but NOT for grouping. This is a filter-only feature that pre-selects devices before applying group by options. Example workflow: Filter by tag "store-budapest" → Select grouping by content → See only Budapest store performance.

### Time Granularity Restrictions

- Multiple contents: Weekly or daily breakdown only
- Single content: Hourly breakdown available
- Maximum query period: 3 months
- Data retention: 1 year

## Data Collection and Synchronization

### Offline Resilience and Batch Processing

**Local storage persistence:**
- Device continuously stores proof of play data in local storage
- Data retained for 1 week during offline periods
- No data loss during extended offline periods (up to 1 week)
- Automatic batch upload when device comes online

**Batch upload timing:**
- Normal operation: Batch upload every 15 minutes
- Minimum aggregation: 15-minute blocks (no finer granularity available)
- UI display: Minimum 1-hour blocks
- Practice shows finer granularity not needed for business reporting

### API Access

**Proof of Play API:**
- Full API access available (not just advertiser public links)
- Authentication methods: User token or API key
- Provides programmatic access to all proof of play data
- Same filtering and grouping capabilities as UI

## Audience / Impression Measurement

Proof of Play can enrich playback with aggregate audience context. The displayer keeps an active viewer count while content runs and stores audience metrics with the same Proof of Play records used for content, asset, campaign, advertiser, message, device, and folder reporting.

**Viewer count sources:**
| Source | Behavior |
|--------|----------|
| Device predefined count | Device details settings can define a default plus date/time rules: fixed count for known attendance/capacity or foot-traffic count from pre-measured visitors/minute * average view time. |
| Content action | Runtime actions can set the active viewer count from static, received, datasource, or sensor-derived values. |
| Sensor event | External people-counting sources can send viewer-count values, e.g. microwave/radar occupancy sensors or camera-based people-counting integrations. |
| Datasource event | Datasource updates can provide viewer-count values for content-driven integrations. |
| Embedded/client integration | Embedded/runtime clients can set active viewer count through the displayer integration surface. |

**Reported audience fields:**
| Metric | Meaning |
|--------|---------|
| `viewerCount` / Total impressions | Estimated audience impressions. Positive count increases and overlap-at-start values are aggregated to avoid losing viewers already present when content starts. |
| `viewerAttention` / Total view time | Sum of viewer-count-weighted playback time. |
| `viewerAttentionRatio` | `viewerAttention` divided by maximum possible view time for the reported duration and impressions. |
| `viewerAverageAttention` | Average attention time derived from attention ratio and duration. |

**Rules and limits:**
- Audience measurement is aggregate count/attention reporting; camera integrations are treated as count sources, not identity/person-level analytics for this feature.
- If no viewer source is configured or available, active viewer count is 0.
- Device predefined rules are edited with standard device-management write access; date blocks and time slots are overlap-validated before save.
- Invalid negative/non-numeric viewer counts are ignored or fall back to 0 depending on input path.
- Rapid viewer-count changes are throttled; the last pending value wins after the cooldown.
- Foot-traffic rules are for predictable, pre-measured flows such as metro stations, lobbies, or hallways; fixed rules fit known-attendance cases such as concerts or ticketed events.
- Dynamic predefined counts model expected incoming viewers over a configured view-time window; sensor/datasource paths can provide live counts.

## Proof of Play Rules

### What Counts as a Play

**Complete playback requirement:**
- Content: All pages must finish displaying
- Slide: Full configured duration must elapse (Note: Playlists can only contain Slides, not multi-page Content)
- Video: Must play to completion
- Interrupted or skipped content: Does NOT count

### Playlist Content Restrictions

**Important clarification:**
- Playlists can ONLY contain Slides (single-page)
- Playlists CANNOT contain Content (multi-page)
- This simplifies proof of play logic in playlist contexts

### Playlist Playback Modes

**Default Mode:** Standard rotation participant
**Exclusive Mode:** When active, suppresses all Default and Fallback items
**Fallback Mode:** Only plays when no Default or Exclusive items are active

**Reporting logic:**
- Only the actually displayed content reports proof of play
- If Exclusive is active, Default and Fallback items do not report
- One content at a time principle: Multiple scheduled items don't report simultaneously

### Schedule Priority

When schedules overlap, the displayer selects one available schedule to play and report:
- Higher numeric priority wins (Priority 2 beats Priority 1)
- At the same priority, the earlier next availability wins; if those times are equal, the lower numeric schedule ID wins
- A higher-priority schedule starting during playback can interrupt the current schedule; selection is also re-evaluated when schedules change
- Non-playing content does not generate proof of play

### Working Hours Impact

**Screen Type:** During a Working Hours SCREEN-mode off period, no proof of play data is collected even though the device remains running
**Device Type:** Device powered off, no data collection possible

## Widget and Asset Statistics

### Configuration Hierarchy

```
Content (automatic - always tracked)
  ├── Page (automatic - always tracked)
  ├── Widget (optional - "Widget statistics" toggle in content editor)
  └── Asset (optional - "Asset statistics" toggle in content editor)
```

### Widget-Level Settings

Each widget in content editor has:
- **Widget statistics toggle:** Tracks widget display time
- **Asset statistics toggle:** Tracks media assets within widget (only relevant for media widgets)

Both are optional and disabled by default. Must be explicitly enabled per widget.

### Z-Index Limitation

Known issue: Overlapping widgets both report as played even if one is hidden behind another. The proof of play engine cannot detect z-index layering.

**Problem scenario:**
- Background widget (hidden): Reports as played (incorrect)
- Foreground widget (visible): Reports as played (correct)

**Workaround:** Only enable statistics on visible widgets

## Advertiser System

### Attribution Levels

Advertisers can be assigned at:
1. Channel level
2. Sub-channel level
3. Playlist item level
4. Content page level

**Hierarchy override rule:** Lower levels override higher levels (Content page advertiser overrides Channel advertiser)

### Public Advertiser Access

- Generate public proof of play links for external advertisers
- Links contain authentication key
- Provides CSV export of advertiser's own data only
- Read-only access to display metrics
- No cost calculation or balance features

### Current Limitations

- No monetary calculations
- No automated billing integration
- Advertisers cannot see competitor data

## Custom Statistics

### Touch Event Integration

Touch events can trigger "Store custom statistics" action with these fields:
- **Asset name:** Identifier for reports
- **Duration:** Seconds to record
- **Plays:** Play count to record
- **Interactions:** Interaction count to record

### Use Cases

**Product interaction tracking:**
```
Touch: Product selection
Asset name: "product_phone_X"
Duration: 30
Plays: 1
Interactions: 1
```

**Navigation tracking:**
```
Touch: Menu item click
Asset name: "menu_settings_clicked"
Duration: 0
Plays: 0
Interactions: 1
```

### Advanced Settings

- **Conditional logic:** "Depend on values of interactive widgets"
- **Security:** "Requires pin code authorization"
- **UI simplification:** Simplified view toggle

## Performance Considerations

### Automatic Optimizations

- Table view fallback when data exceeds chart capabilities
- Grouping option restrictions based on data volume
- Time granularity limits for large datasets

### Query Limits

- Maximum 3-month query window
- 1-year data retention
- Automatic aggregation for large result sets

### Known Limitations

1. **Z-index tracking:** Overlapping widgets both counted
2. **No partial playback:** Interrupted content not tracked
3. **No tag grouping:** Tags for filtering only
4. **Screen-off gaps:** Working Hours SCREEN-mode off periods produce no proof-of-play rows. Powering down only the physical panel (for example, with its remote or power button) does not suppress reporting while the player continues to run and its tracked screen state remains on. Proof of play records player activity, not independently verified viewer visibility.
5. **Audience source dependency:** Impression and attention metrics are only as accurate as the configured viewer-count source

## Special Content Types

### Screenshot Service
Screenshot-generated content does NOT generate proof of play data. The screenshot service only creates images without tracking display metrics.

### Video Wall (Multi-output)
- **Single content across outputs:** Reports as single aggregated play
- **Embedded content widgets:** Each embedded content reports separately
- Example: Main content with 4 embedded content widgets = 5 separate proof of play records

### Content Widget Embedding
When Content contains other Content widgets:
- Parent content reports its own proof of play
- Each embedded content widget reports separately
- Advertiser attribution can differ between parent and embedded content

## Technical Implementation Notes

### Data Collection Flow

```
Device displays content
    ↓
Content/Page automatically logged to local storage
    ↓
Widget statistics (if enabled) tracked
    ↓
Asset statistics (if enabled) tracked
    ↓
Touch interactions counted
    ↓
Data aggregated in 15-minute blocks
    ↓
Batch upload to server every 15 minutes (when online)
    ↓
If offline: Store up to 1 week locally
    ↓
When online: Upload all pending batches
    ↓
Advertiser attribution applied server-side
    ↓
Stored in database (1-year retention)
    ↓
Available via UI (1-hour minimum blocks) and API
```

### Key Behaviors

- Exclusive mode suppresses other content from reporting
- Schedule priorities determine single playing content
- Complete playback required for counting
- Background widgets incorrectly report as visible
- Tags enable filtering but not grouping
- Custom statistics require explicit touch event configuration

### Common Configuration Patterns

**Basic setup:** Content only (automatic tracking)
**Detailed tracking:** Enable widget statistics on key widgets
**Advertiser reporting:** Assign advertisers at appropriate level
**Interactive tracking:** Configure touch events with custom statistics
**Geographic analysis:** Use device tags for filtering, device folders for grouping