@newrelic/video-videojs 4.1.1 → 4.2.0

package/CHANGELOG.md

@@ -1,3 +1,31 @@
+## [4.1.2](https://github.com/newrelic/video-videojs-js/compare/v4.1.1...v4.1.2) (2026-05-11)
+
+### Features
+
+- **AWS MediaTailor Support:** Added comprehensive support for AWS MediaTailor SSAI with DASH
+  - Implemented MediaTailor tracker with manifest polling and ad tracking
+  - Added MediaTailor lab sample for testing and demonstration
+  - Enhanced DASH support for MediaTailor integration
+  - Added unit test cases for MediaTailor functionality
+  - Improved MediaTailor tracker reliability and event handling
+
+### Bug Fixes
+
+- **Bitrate Data Types:** Updated bitrate data types for improved accuracy and consistency
+- **Manifest Fetch Error Handling:** Added proper error handling for manifest fetch failures
+- **MediaTailor Configuration:** Moved MediaTailor config variables to global scope for better accessibility
+
+### Documentation
+
+- **SSAI Documentation:** Updated SSAI documentation to include MediaTailor integration details
+- **MediaTailor Naming:** Clarified MediaTailor helper and state naming conventions
+
+### Build & Infrastructure
+
+- **Release Workflow:** Standardized release workflow with smart detection
+- **Dependencies:** Updated semantic-release dependencies and package-lock.json
+- **Cleanup:** Removed unrelated test infrastructure files, scripts, and dependencies
+
 ## [4.1.1](https://github.com/newrelic/video-videojs-js/compare/v4.1.0...v4.1.1) (2026-04-17)
 
 ### Documentation

package/README.md

@@ -29,6 +29,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)
+- [SSAI Guide](#ssai-guide)
 - [Data Model](#data-model)
 - [Support](#support)
 - [Contribute](#contribute)
@@ -305,6 +306,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                                                                                                                                                                              |
@@ -377,6 +425,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
@@ -436,29 +496,76 @@ 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 fully supported with automatic detection and tracking:
+### Google DAI Integration
 
 ```javascript
-// SSAI is automatically detected - no additional configuration needed
-const tracker = new VideojsTracker(player, options);
+import { AD_TRACKING } from '@newrelic/video-videojs';
+const tracker = new VideojsTracker(player, { config: { ad: { type: AD_TRACKING.SSAI.DAI } } });
+```
+
+See [samples/dai/index.html](./samples/dai/index.html) for a complete example.
+
+### AWS MediaTailor Integration
+
+Supports HLS/DASH, VOD/LIVE, multiple ads per break, quartile tracking, and tracking metadata enrichment.
+
+```javascript
+import { AD_TRACKING } from '@newrelic/video-videojs';
+
+player.src({
+  src: 'https://your-mediatailor-endpoint.mediatailor.region.amazonaws.com/v1/master/...',
+  type: 'application/x-mpegURL'
+});
+
+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.
+
+## SSAI Guide
+
+For customer-facing SSAI integration details, supported MediaTailor behavior, troubleshooting guidance, and sample usage, see [docs/ssai.md](./docs/ssai.md).
+
+
+## Testing
+
+This project includes comprehensive unit tests for all tracker functionality.
+
+```bash
+# Install dependencies
+npm install
+
+# Run tests
+npm test
+
+# Run tests with coverage
+npm run test:coverage
 
-// The tracker will automatically capture:
-// - Ad breaks, starts, and completions
-// - Ad quartiles and click events
-// - SSAI-specific metadata
+# Run tests in watch mode
+npm run test:watch
 ```
 
-**Example:** See [samples/dai/index.html](./samples/dai/index.html) for a complete SSAI implementation.
+For more details, see [test/README.md](./test/README.md).
 
 ## Data Model