v4.1.0

Overview

Version 4.1.0 introduces comprehensive Quality of Experience (QoE) metrics to provide deeper insights into video playback performance and user experience. This release adds a new aggregate event type that captures key performance indicators (KPIs) for content playback.

---

🎯 New Features

Quality of Experience (QoE) KPI Metrics

A new QOE_AGGGREGATE event type has been introduced to provide aggregated quality metrics for video content playback. This event is sent as part of the VideoAction event type and includes the following KPI attributes:

QoE Attributes

Attribute	Type	Description
startupTime	Number (ms)	Time from CONTENT_REQUEST to CONTENT_START in milliseconds. Measures video startup performance. Only included if value is not null.
peakBitrate	Number (bps)	Maximum contentBitrate (in bits per second) observed during content playback. Tracks the highest quality achieved. Only included if value > 0.
hadStartupFailure	Boolean	Indicates if CONTENT_ERROR occurred before CONTENT_START. True if video failed to start due to an error.
hadPlaybackFailure	Boolean	Indicates if CONTENT_ERROR occurred at any time during content playback.
totalRebufferingTime	Number (ms)	Total milliseconds spent rebuffering during content playback (excludes initial buffering).
rebufferingRatio	Number (%)	Rebuffering time as a percentage of total playtime. Calculated as (totalRebufferingTime / totalPlaytime) × 100.
totalPlaytime	Number (ms)	Total milliseconds user spent watching content (excludes pausing, buffering, and ads). Represents actual content viewing time.
averageBitrate	Number (bps)	Average bitrate (in bits per second) across all content playback weighted by playtime.

Benefits

• Startup Performance Monitoring: Track how quickly videos begin playing for end users
• Quality Tracking: Monitor peak and average bitrates to understand content quality delivery
• Reliability Metrics: Identify startup and playback failures to improve content reliability
• Buffering Analysis: Measure rebuffering time and ratio to optimize buffering strategies
• User Engagement: Track actual playtime to understand true user engagement with content

---

📊 Use Cases

Performance Optimization

Use QoE metrics to:

• Identify slow startup times and optimize CDN delivery
• Detect frequent rebuffering issues and adjust adaptive bitrate algorithms
• Monitor quality degradation across different network conditions

Business Intelligence

• Calculate abandonment rates based on startup failures
• Correlate video quality (bitrate) with user engagement (playtime)
• Benchmark performance across different content types, devices, or regions

Alerting & Monitoring

Set up alerts for:

• High rebuffering ratios affecting user experience
• Startup failures exceeding acceptable thresholds
• Significant drops in average bitrate quality

---

📝 Implementation Details

Event Triggering

The QOE_AGGGREGATE event is sent automatically during harvest cycles when content playback metrics are available. No additional implementation is required beyond the standard video tracker integration.

Data Collection

• Metrics are calculated in real-time during video playback
• Startup time accounts for pre-roll ad breaks when applicable
• Bitrate tracking begins only after content start and excludes values before initialization
• Weighted average bitrate calculation ensures accurate quality representation

---

🔄 Breaking Changes

None. This release is backward compatible with version 4.0.x.

---

📚 Documentation Updates

• Updated DATAMODEL.md with comprehensive QoE attribute definitions
• Added QOE_AGGGREGATE to the list of Video Action event types
• Included detailed descriptions and calculation methods for all QoE KPIs

---

📦 Upgrade Instructions

To upgrade to version 4.1.0:

npm install @newrelic/video-core@4.1.0

Or update your package.json:

{
  "dependencies": {
    "@newrelic/video-core": "^4.1.0"
  }
}

No code changes are required. The QoE metrics will be automatically collected and reported once you upgrade.

---

🔗 Related Resources

• DATAMODEL.md - Complete data model documentation
• CHANGELOG.md - Full change history
• GitHub Repository

---

What's Changed

• feat(build): update build scripts and deps by @jbeveland27 in #12
• chore(deps): update mocha by @jbeveland27 in #13
• Update ad sample. by @asllop in #18

New Contributors

• @jbeveland27 made their first contribution in #12

Full Changelog: v0.32.4...4.1.0

v4.0.3

Bitrate Attribute Fix

Release Date: January 29, 2026

Fix

• Drop bitrate values before start - Modified getAttributes() in videotracker.js to check this.state.isStarted before adding bitrate attributes, preventing premature bitrate reporting before content starts

v4.0.2

Unit Test Enhancement

Release Date: November 3, 2025

Chore

• Unit test: Ad mock - Added mock file for mocking NRVideo to enable unit testing of individual components separately

v4.0.1

Released: October 22, 2025

⏱️ Enhanced Error Tracking Attributes

We've added two new timing attributes to provide better insights into error recovery patterns and video playback health:

timeSinceLastError

• Type: Number (milliseconds)
• Scope: Content events only
• Purpose: Tracks time elapsed since the last content error occurred
• Availability: Only included in events after a content error has occurred

timeSinceLastAdError

• Type: Number (milliseconds)
• Scope: Ad events only
• Purpose: Tracks time elapsed since the last ad error occurred
• Availability: Only included in ad events after an ad error has occurred

🔧 Technical Improvements

Smart Error Context Detection

• Context-Aware Timing: The goError() method now intelligently starts the appropriate timer based on current context (content vs. ad)
• Independent Tracking: Content and ad errors are tracked separately for more granular analytics
• Conditional Inclusion: Error timing attributes are only included when relevant, reducing data noise

Enhanced State Management

• Improved VideoTrackerState: Better error state handling with proper timer isolation
• Robust Error Recovery: Enhanced error tracking helps identify recovery patterns and performance issues
• Memory Efficient: Timers only run when needed, optimizing resource usage

📊 Analytics Benefits

Better Error Recovery Insights

• Track how long users experience issues after errors occur
• Identify patterns in error recovery across different content types
• Separate analysis of content vs. ad error impacts

Enhanced Monitoring Capabilities

• Monitor video playback health more effectively
• Detect and analyze error clustering patterns
• Improve user experience by understanding error impact duration

🧪 Quality Assurance

Comprehensive Test Coverage

• New Test Cases: Added comprehensive tests for error timing functionality
• Delta Time Validation: Tests verify correct time calculations for both content and ad errors
• Context Isolation: Tests ensure proper separation between content and ad error tracking
• Independent Timer Operation: Verified that both error types can be tracked simultaneously

Backward Compatibility

• ✅ Non-Breaking: All existing functionality remains unchanged
• ✅ Additive Only: New attributes are only added when errors occur
• ✅ Conditional: No impact on events when no errors have occurred

📚 Documentation Updates

Updated Data Model

• DATAMODEL.md: Added comprehensive documentation for new error timing attributes
• Conditional Behavior: Clear documentation of when attributes are included
• Context Specificity: Detailed explanation of content vs. ad error tracking

Updated Changelog

• Version History: Complete changelog with detailed feature descriptions
• Implementation Notes: Technical details for developers

🔍 Usage Examples

Content Error Tracking

// After a content error occurs
{
  "eventType": "VideoAction",
  "actionName": "CONTENT_HEARTBEAT", 
  "timeSinceLastError": 5420,  // 5.42 seconds since last error
  // ... other attributes
}

v4.0.0

💥 Breaking Changes

Decoupled Architecture

The browser agent has been completely redesigned as a standalone unit, independent of the New Relic Browser Agent. This represents a fundamental architectural shift that provides greater flexibility and control.

✨ Key Features

🔧 Independent Logic

• Dedicated Harvesting System: The agent now uses its own specialized data collection and harvesting logic
• Self-Contained Architecture: No longer dependent on Browser Agent infrastructure
• Enhanced Performance: Optimized specifically for video tracking use cases

🚀 Simplified Onboarding

• Streamlined Integration: Easier setup process reflecting the new decoupled nature
• Reduced Dependencies: Fewer external requirements for implementation
• Better Developer Experience: Clear separation of concerns makes integration more straightforward

🔄 Migration Guide

For Existing Users

This is a breaking change that requires migration from the previous coupled implementation:

1. Update Integration Code: The agent initialization and configuration have changed
2. Review Dependencies: Remove any Browser Agent specific dependencies
3. Test Thoroughly: Validate that video tracking continues to work as expected

New Users

• Follow the updated installation and setup documentation
• Take advantage of the simplified onboarding process
• No need to configure Browser Agent integration

📦 Installation

npm install @newrelic/video-core

v3.1.1

What's Changed

• AD_ERROR event type updated to VideoErrorAction for standardized video error reporting.

v3.1.0

What's Changed

• Added npm publish support—install with npm i.