@newrelic/video-videojs 4.2.0 → 4.2.1

package/CHANGELOG.md

@@ -1,3 +1,64 @@
+## [4.2.1](https://github.com/newrelic/video-videojs-js/compare/v4.2.0...v4.2.1) (2026-06-18)
+
+### Features
+
+- **Quality/Rendition Change Tracking:** Added optional support for automatic rendition change detection and reporting
+  - Integrated optional `videojs-contrib-quality-levels` plugin for quality level monitoring
+  - Implemented automatic rendition change event tracking with bitrate information
+  - Added lazy initialization of quality levels plugin support
+  - Tracks old and new bitrate during quality transitions
+  - Graceful fallback when quality levels plugin is not loaded
+
+### Documentation
+
+- **Quality/Rendition Tracking Guide:** Comprehensive documentation for enabling optional quality tracking
+  - Installation instructions for `videojs-contrib-quality-levels` plugin
+  - Detailed explanation of how the feature works
+  - Console debugging information for troubleshooting
+  - NRQL query examples for analyzing quality changes
+  - Updated README with Quality/Rendition Tracking section
+  - Feature Highlights section now includes rendition change tracking
+
+## [4.2.0](https://github.com/newrelic/video-videojs-js/compare/v4.1.2...v4.2.0) (2026-06-10)
+
+### Features
+
+- **MediaTailor Custom CDN Support:** Replaced URL-based auto-detection with explicit opt-in
+  - Customers now pass `mediatailor: true` (or `mediatailor: { trackingUrl, adSegmentPrefix }`) to enable the tracker — supports both default AWS hostnames and custom CDN domains
+  - Added `MT_DEFAULT_AD_SEGMENT_PATH` (`/tm/`) constant for AWS-recommended CDN ad-segment path; ad segments rewritten to a custom CDN domain under `/tm/` are detected automatically
+  - `isMediaTailorSegment()` now checks the default AWS segments hostname, the `/tm/` path, and an optional customer-supplied `adSegmentPrefix`
+  - Threaded `adSegmentPrefix` through HLS (VHS) and DASH manifest parsing
+  - Added explicit session initialisation via `mediatailor: { trackingUrl }` for POST `/v1/session/` flows
+
+- **Ad Tracking Configuration:** Introduced `config.ad.type` to control ad tracker selection
+  - Exposed `AD_TRACKING` constant with CSAI (flat value covering IMA / Brightcove IMA / Freewheel / generic) and SSAI sub-types (`DAI`, `MT`)
+  - SSAI requires an explicit sub-type — each platform needs its own SDK and cannot be auto-detected
+  - `SSAI.MT` implies `mediatailor: true`
+  - When `config.ad.type` is unset, falls back to CSAI auto-detection with a warning (backward compatible for v4.1.2 users)
+  - Co-located `segmentPrefix` and `trackingUrl` under `config.ad`
+  - Added `DaiAdsTracker` to static exports
+
+- **Logging Improvements:**
+  - Exposed `VideojsTracker.Log` as a static so UMD callers can set log level
+  - Logs active ad segment detection mode at tracker startup
+  - Logs the matched ad segment detection path on first ad break (once per session)
+  - Logs which CSAI framework was auto-detected (BrightcoveIma / IMA / Freewheel / generic)
+  - Replaced `console.log/warn/error` with `nrvideo.Log` across MediaTailor files
+
+### Bug Fixes
+
+- **Buffer End:** Fixed buffer end handling in tracker
+- **Plugin Registration:** Fixed `register-plugin.js` silently dropping the options object and not forwarding it to the `TrackerJS` constructor
+
+### Documentation
+
+- **README & SSAI Docs:** Updated for custom CDN support, clarified when `trackingUrl` and `adSegmentPrefix` overrides are needed, cleaned up `sessionId` references
+- **SSAI Troubleshooting:** Corrected `adSegmentPrefix` references to `config.ad.segmentPrefix`
+
+### Samples
+
+- **MediaTailor Lab:** Rewrote sample app with a clean minimal UI — license key / app ID / playback URL / format toggle, smart Load button (handles both session init and direct playback URLs), NR log level toggle, debug log showing detected mode, credentials persisted in localStorage
+
 ## [4.1.2](https://github.com/newrelic/video-videojs-js/compare/v4.1.1...v4.1.2) (2026-05-11)
 
 ### Features

package/README.md

@@ -15,6 +15,7 @@ The New Relic Video.js Tracker provides comprehensive video analytics for applic
 - 🔧 **Multi-Tech Support** - Works with VHS, hls.js, and Shaka Player
 - 📈 **QoE Metrics** - Quality of Experience aggregation for startup time, buffering, and playback quality
 - 🎨 **Event Segregation** - Organized event types: `VideoAction`, `VideoAdAction`, `VideoErrorAction`, `VideoCustomAction`
+- 🌐 **Rendition Change Tracking** - Monitor quality/rendition changes with automatic rendition change event reporting
 - 🚀 **Easy Integration** - NPM package or direct script include
 
 ## Table of Contents
@@ -29,6 +30,7 @@ The New Relic Video.js Tracker provides comprehensive video analytics for applic
 - [API Reference](#api-reference)
 - [Bitrate Metrics](#bitrate-metrics)
 - [Ad Tracking Support](#ad-tracking-support)
+- [Quality/Rendition Tracking](#qualityrendition-tracking)
 - [SSAI Guide](#ssai-guide)
 - [Data Model](#data-model)
 - [Support](#support)
@@ -105,6 +107,9 @@ Before using the tracker, ensure you have:
 - **New Relic Account** - Active New Relic account with valid application credentials (`beacon`, `applicationId`, `licenseKey`)
 - **Video.js Player** - Video.js player integrated in your application
 
+**Optional:**
+- **Quality Tracking Plugin** - To track rendition/quality changes, optionally install `videojs-contrib-quality-levels` (see [Quality/Rendition Tracking](#qualityrendition-tracking) section for details). This is not required — the tracker works perfectly without it.
+
 ## Usage
 
 ### Getting Your Configuration
@@ -542,6 +547,89 @@ const tracker = new VideojsTracker(player, {
 
 Works with default AWS hostnames and custom CDN domains. See [docs/ssai.md](./docs/ssai.md) for custom CDN setup and advanced options.
 
+## Quality/Rendition Tracking
+
+The tracker can automatically detect and report rendition (quality) changes when adaptive bitrate (ABR) video is played. This is an **optional feature** — the tracker works perfectly fine without it.
+
+### Optional: Enable Quality Tracking
+
+To enable quality/rendition change tracking, install and include the **videojs-contrib-quality-levels** plugin:
+
+**Step 1: Install the plugin**
+
+```bash
+npm install videojs-contrib-quality-levels
+```
+
+**Step 2: Include in your HTML** (before the tracker script):
+
+```html
+<!-- Video.js Player -->
+<link href="https://vjs.zencdn.net/7.20.3/video-js.css" rel="stylesheet" />
+<script src="https://vjs.zencdn.net/7.20.3/video.js"></script>
+
+<!-- Quality Levels Plugin (Optional - only needed for rendition tracking) -->
+<script src="https://cdn.jsdelivr.net/npm/videojs-contrib-quality-levels/dist/videojs-contrib-quality-levels.min.js"></script>
+
+<!-- New Relic Video.js Tracker -->
+<script src="path/to/newrelic-video-videojs.min.js"></script>
+```
+
+### How It Works
+
+When the plugin is enabled:
+- The tracker monitors the quality levels plugin for rendition change events
+- When a rendition change occurs (automatic ABR or user-initiated), a `RENDITION_CHANGE` event is sent to New Relic
+- The event includes quality metadata: bitrate, width, height, and label
+- Quality changes are tracked for both content and ad playback
+
+If the plugin is **not** loaded:
+- The tracker continues to work normally
+- All video events are tracked (play, pause, buffering, seeking, etc.)
+- Quality/rendition change events are simply not captured
+- A debug message logs to the console: `[QualityLevels] player.qualityLevels is not a function`
+
+### Console Debugging
+
+During development, if the plugin is enabled, the tracker logs quality change events to the console:
+
+```
+[QualityLevels] Plugin initialized successfully
+[QualityLevels] Change event fired!
+[QualityLevels] selectedIndex: 1
+[QualityLevels] Selected level: {width: 1280, height: 720, bitrate: 2500000, …}
+[QualityLevels] Sending rendition changed event
+```
+
+If you see this message instead:
+```
+[QualityLevels] player.qualityLevels is not a function
+```
+
+It means the plugin is not loaded or not available. This is fine — the tracker will continue tracking all other video metrics.
+
+### NRQL Query Examples
+
+When quality tracking is enabled:
+
+```sql
+-- Track rendition changes over time
+SELECT count(*) FROM VideoAction 
+WHERE actionName = 'CONTENT_RENDITION_CHANGE'
+FACET contentBitrate SINCE 1 day ago
+
+-- Monitor average bitrate during playback
+SELECT average(contentBitrate) FROM VideoAction 
+WHERE actionName = 'CONTENT_HEARTBEAT'
+FACET contentRenditionWidth, contentRenditionHeight 
+SINCE 1 hour ago
+
+-- Analyze quality upgrades vs downgrades
+SELECT contentBitrate FROM VideoAction 
+WHERE actionName = 'CONTENT_RENDITION_CHANGE'
+SINCE 24 hours ago
+```
+
 ## SSAI Guide
 
 For customer-facing SSAI integration details, supported MediaTailor behavior, troubleshooting guidance, and sample usage, see [docs/ssai.md](./docs/ssai.md).