@newrelic/video-videojs 4.1.2 → 4.2.1

package/CHANGELOG.md

@@ -1,4 +1,65 @@
-## [4.2.0](https://github.com/newrelic/video-videojs-js/compare/v4.1.1...v4.2.0) (2026-05-11)
+## [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
@@ -306,6 +311,53 @@ if (shouldEnableTracking(currentUser.id)) {
 
 ## Configuration Options
 
+### Ad Tracking
+
+`config.ad.type` declares which ad category the tracker should wire up. **If not set, no ad tracking runs** — this is the safe default. Omitting it while passing other options triggers a console warning.
+
+#### CSAI — Client-Side Ad Insertion
+
+All CSAI frameworks (IMA, Brightcove IMA, Freewheel) share the `adsready` event path. The tracker auto-detects which one is present — no sub-type needed. Just declare `CSAI`.
+
+| Value    | Constant         | Behaviour                                                                  |
+| -------- | ---------------- | -------------------------------------------------------------------------- |
+| `'csai'` | `AD_TRACKING.CSAI` | Auto-detects: Brightcove IMA → IMA → Freewheel → generic fallback       |
+
+#### SSAI — Server-Side Ad Insertion
+
+Each SSAI platform has its own SDK and a completely different activation path — they cannot be auto-detected. **A sub-type is always required.**
+
+| Value        | Constant               | Behaviour                                                               |
+| ------------ | ---------------------- | ----------------------------------------------------------------------- |
+| `'ssai:dai'` | `AD_TRACKING.SSAI.DAI` | Google DAI (`google.ima.dai.api`)                                       |
+| `'ssai:mt'`  | `AD_TRACKING.SSAI.MT`  | AWS MediaTailor                                                         |
+
+```javascript
+import { AD_TRACKING } from '@newrelic/video-videojs';
+
+// CSAI — one value covers all client-side frameworks
+new VideojsTracker(player, { config: { ad: { type: AD_TRACKING.CSAI } } });
+
+// SSAI — sub-type always required
+new VideojsTracker(player, { config: { ad: { type: AD_TRACKING.SSAI.DAI } } });
+new VideojsTracker(player, { config: { ad: { type: AD_TRACKING.SSAI.MT } } });
+
+// SSAI.MT with custom CDN config
+new VideojsTracker(player, {
+  config: {
+    ad: {
+      type: AD_TRACKING.SSAI.MT,
+      segmentPrefix: '/my-cdn-path/',
+    },
+  },
+});
+
+// Change at runtime before first loadstart / adsready
+tracker.setAdTracking(AD_TRACKING.CSAI);
+```
+
+> **Extending later:** add a new key to `AD_TRACKING.SSAI` — validation derives from the object automatically. No other changes needed.
+
 ### QoE (Quality of Experience) Settings
 
 | Option              | Type    | Default | Description                                                                                                                                                                              |
@@ -378,6 +430,18 @@ tracker.setOptions({
 });
 ```
 
+#### `tracker.setAdTracking(type)`
+
+Change the ad tracking mode after the tracker is created. Must be called before the first `loadstart` or `adsready` event to take effect.
+
+```javascript
+import { AD_TRACKING } from '@newrelic/video-videojs';
+
+// Valid values: 'csai' | 'ssai:dai' | 'ssai:mt'
+tracker.setAdTracking(AD_TRACKING.CSAI);
+tracker.setAdTracking(AD_TRACKING.SSAI.MT);
+```
+
 ### Example: Complete Integration
 
 ```javascript
@@ -437,68 +501,134 @@ The tracker captures four distinct bitrate metrics providing complete quality an
 
 ## Ad Tracking Support
 
-The tracker provides comprehensive ad tracking capabilities:
-
 ### Supported Ad Technologies
 
-- **IMA (Interactive Media Ads)** - Google IMA SDK integration
-- **Freewheel** - Freewheel ad platform support
-- **SSAI (Server-Side Ad Insertion)** - Dynamic Ad Insertion (DAI) support
+| Category | Frameworks detected | Constant |
+|---|---|---|
+| CSAI | Google IMA, Brightcove IMA, Freewheel, generic | `AD_TRACKING.CSAI` |
+| SSAI | Google DAI | `AD_TRACKING.SSAI.DAI` |
+| SSAI | AWS MediaTailor | `AD_TRACKING.SSAI.MT` |
 
-### SSAI/DAI Integration
+See [Configuration Options → Ad Tracking](#ad-tracking) for full usage and examples.
 
-Server-Side Ad Insertion is supported with automatic tracker selection for supported integrations:
+### Google DAI Integration
 
 ```javascript
-// SSAI tracker selection is automatic for supported integrations
-const tracker = new VideojsTracker(player, options);
-
-// The tracker will automatically capture:
-// - Ad breaks, starts, and completions
-// - Ad quartiles and click events
-// - SSAI-specific metadata when available
+import { AD_TRACKING } from '@newrelic/video-videojs';
+const tracker = new VideojsTracker(player, { config: { ad: { type: AD_TRACKING.SSAI.DAI } } });
 ```
 
-**Example:** See [samples/dai/index.html](./samples/dai/index.html) for a complete SSAI implementation.
-
-> [!NOTE]
-> **Attention:**
-> This version supports tracking for SSAI (Server-Side Ad Insertion), including AWS MediaTailor. See [samples/media-tailor-lab.html](./samples/media-tailor-lab.html) and the [SSAI Guide](./docs/ssai.md).
+See [samples/dai/index.html](./samples/dai/index.html) for a complete example.
 
 ### AWS MediaTailor Integration
 
-The tracker automatically detects and tracks AWS MediaTailor SSAI streams. It supports:
-
-- **HLS and DASH** manifest formats
-- **VOD and LIVE** stream types
-- **Multiple ads (pods)** within a single break
-- **Quartile tracking** (25%, 50%, 75%)
-- **Tracking metadata enrichment** when MediaTailor tracking data is available
-
-#### Usage
+Supports HLS/DASH, VOD/LIVE, multiple ads per break, quartile tracking, and tracking metadata enrichment.
 
 ```javascript
-import VideojsTracker from '@newrelic/video-videojs';
+import { AD_TRACKING } from '@newrelic/video-videojs';
 
-// Initialize player with a sessionized MediaTailor playback URL
 player.src({
   src: 'https://your-mediatailor-endpoint.mediatailor.region.amazonaws.com/v1/master/...',
   type: 'application/x-mpegURL'
 });
 
-// Initialize tracker - MediaTailor support is automatic
-const tracker = new VideojsTracker(player, options);
+const tracker = new VideojsTracker(player, { config: { ad: { type: AD_TRACKING.SSAI.MT } } });
+
+// With custom CDN config
+const tracker = new VideojsTracker(player, {
+  config: {
+    ad: {
+      type: AD_TRACKING.SSAI.MT,
+      segmentPrefix: '/my-cdn-path/',
+    },
+  },
+});
+```
+
+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
 ```
 
-The tracker will automatically:
-1. Detect MediaTailor URLs (`.mediatailor.` in URL)
-2. Build the MediaTailor tracking endpoint from the sessionized playback URL
-3. Parse HLS or DASH manifests for ad markers
-4. Track ad breaks, ad starts, quartiles, and ad ends
-5. Enrich ad metadata with the MediaTailor tracking endpoint when available
-6. Handle VOD and LIVE streams appropriately
+**Step 2: Include in your HTML** (before the tracker script):
 
-MediaTailor-specific behavior is automatic. The customer does not need to pass MediaTailor-only configuration flags into the tracker.
+```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