@newrelic/video-videojs 4.1.0 → 4.1.2

package/CHANGELOG.md

@@ -1,3 +1,42 @@
+## [4.2.0](https://github.com/newrelic/video-videojs-js/compare/v4.1.1...v4.2.0) (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
+
+- **README.md:** Added Best Practices section (contentTitle, userId, custom attributes, gradual rollout with feature flags)
+- **README.md:** Promoted Bitrate Metrics to top-level section with detailed table format and NRQL query examples
+- **README.md:** Updated Data Model event descriptions to include heartbeats and media errors
+- **README.md:** Fixed DATAMODEL.md link casing
+- **README.md:** Updated Table of Contents with new sections (Prerequisites, Best Practices, Bitrate Metrics)
+- **README.md:** Renamed Contributing to Contribute for consistency across trackers
+
 ## [4.1.0](https://github.com/newrelic/video-videojs-js/compare/v4.0.3...v4.1.0) (2026-04-08)
 
 ### Breaking Changes

package/README.md

@@ -22,13 +22,17 @@ The New Relic Video.js Tracker provides comprehensive video analytics for applic
 - [Installation](#installation)
   - [Option 1: NPM/Yarn](#option-1-install-via-npmyarn)
   - [Option 2: Direct Script Include](#option-2-direct-script-include-without-npm)
+- [Prerequisites](#prerequisites)
 - [Usage](#usage)
+- [Best Practices](#best-practices)
 - [Configuration Options](#configuration-options)
 - [API Reference](#api-reference)
+- [Bitrate Metrics](#bitrate-metrics)
 - [Ad Tracking Support](#ad-tracking-support)
+- [SSAI Guide](#ssai-guide)
 - [Data Model](#data-model)
 - [Support](#support)
-- [Contributing](#contributing)
+- [Contribute](#contribute)
 - [License](#license)
 
 ## Installation
@@ -91,11 +95,15 @@ For quick integration without a build system, include the tracker directly in yo
 
 **Setup Steps:**
 
-1. **Get Configuration** - Visit [one.newrelic.com](https://one.newrelic.com) and complete the video agent onboarding to obtain your credentials (`licenseKey`, `beacon`, `applicationId`)
-2. **Download Tracker** - Get `newrelic-video-videojs.min.js` from:
-   - [GitHub Releases](https://github.com/newrelic/video-videojs-js/releases) (recommended)
-   - Build from source: `npm run build` → `dist/umd/newrelic-video-videojs.min.js`
-3. **Integrate** - Include the script in your HTML and initialize with your configuration
+1. **Get Configuration** - Visit [one.newrelic.com](https://one.newrelic.com) and follow the Streaming Video & Ads onboarding flow to get your `licenseKey`, `beacon`, `applicationID`, and integration code snippet.
+2. **Integrate** - Include the script in your HTML and initialize with your configuration
+
+## Prerequisites
+
+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
 
 ## Usage
 
@@ -154,6 +162,148 @@ const options = {
 const tracker = new VideojsTracker(player, options);
 ```
 
+## Best Practices
+
+### 1. Setting `contentTitle`
+
+The `contentTitle` attribute will display a value if your video metadata contains title information. If the metadata does not include a title, `contentTitle` will not be populated. For best results, ensure you explicitly set this attribute during initialization:
+
+```javascript
+const tracker = new VideojsTracker(player, {
+  info: {
+    licenseKey: 'YOUR_LICENSE_KEY',
+    beacon: 'YOUR_BEACON_URL',
+    applicationId: 'YOUR_APP_ID',
+  },
+  customData: {
+    contentTitle: 'My Video Title', // Explicitly set from your metadata
+  },
+});
+```
+
+If your title changes dynamically (e.g., playlist or queue):
+
+```javascript
+tracker.setOptions({
+  customData: {
+    contentTitle: 'New Video Title',
+  },
+});
+```
+
+### 2. Setting `userId`
+
+Set a user identifier to track video analytics per user:
+
+```javascript
+// Set userId during initialization
+const tracker = new VideojsTracker(player, {
+  info: {
+    licenseKey: 'YOUR_LICENSE_KEY',
+    beacon: 'YOUR_BEACON_URL',
+    applicationId: 'YOUR_APP_ID',
+  },
+  customData: {
+    contentTitle: 'Video Title',
+    userId: 'user-12345',
+  },
+});
+
+// Or set userId separately using the API method
+tracker.setUserId('user-12345');
+```
+
+### 3. Adding Custom Attributes for Your Deployment
+
+Add custom attributes unique to your deployment to improve data aggregation and analysis:
+
+```javascript
+const tracker = new VideojsTracker(player, {
+  info: {
+    licenseKey: 'YOUR_LICENSE_KEY',
+    beacon: 'YOUR_BEACON_URL',
+    applicationId: 'YOUR_APP_ID',
+  },
+  customData: {
+    // Required for identification
+    contentTitle: videoMetadata.title,
+    userId: currentUser.id,
+
+    // Custom attributes for your deployment
+    subscriptionTier: 'premium', // User subscription level
+    contentProvider: 'studio-abc', // Content source
+    region: 'us-west-2', // Geographic region
+    cdnProvider: 'cloudflare', // CDN being used
+    deviceType: 'desktop', // Device category
+    appVersion: '2.1.0', // Your app version
+    campaign: 'spring-promo', // Marketing campaign
+  },
+});
+```
+
+**Use these attributes in New Relic queries:**
+
+```sql
+-- Analyze by subscription tier
+SELECT count(*) FROM VideoAction WHERE actionName = 'CONTENT_START'
+FACET subscriptionTier SINCE 1 day ago
+
+-- Monitor by region
+SELECT average(contentNetworkDownloadBitrate) FROM VideoAction
+FACET region SINCE 1 hour ago
+```
+
+### 4. Gradual Rollout with Feature Flags
+
+When deploying to production, use feature flags to enable the tracker gradually. This helps you:
+
+- Validate data collection without impacting all users
+- Monitor performance impact at scale
+- Catch issues before full deployment
+- Control monitoring costs
+
+```javascript
+// Example using a feature flag
+const rolloutPercentage = 5; // Start with 5% of users
+
+function shouldEnableTracking(userId) {
+  // Simple percentage-based rollout
+  const hash = userId
+    .split('')
+    .reduce((acc, char) => acc + char.charCodeAt(0), 0);
+  return hash % 100 < rolloutPercentage;
+}
+
+const player = videojs('myVideo');
+player.version = videojs.VERSION;
+
+// Only initialize tracker if user is in rollout
+if (shouldEnableTracking(currentUser.id)) {
+  const tracker = new VideojsTracker(player, {
+    info: {
+      licenseKey: 'YOUR_LICENSE_KEY',
+      beacon: 'YOUR_BEACON_URL',
+      applicationId: 'YOUR_APP_ID',
+    },
+    customData: {
+      contentTitle: videoMetadata.title,
+      userId: currentUser.id,
+      rolloutGroup: `${rolloutPercentage}%`, // Track which rollout group
+    },
+  });
+}
+```
+
+**Recommended Rollout Schedule:**
+
+| Phase     | Percentage | Duration  | Validation                         |
+| --------- | ---------- | --------- | ---------------------------------- |
+| Initial   | 5%         | 2-3 days  | Verify data flowing to New Relic   |
+| Early     | 15%        | 3-5 days  | Check data quality and performance |
+| Expansion | 25%        | 5-7 days  | Validate across device types       |
+| Majority  | 50%        | 1-2 weeks | Monitor at scale                   |
+| Full      | 100%       | Ongoing   | Complete deployment                |
+
 ## Configuration Options
 
 ### QoE (Quality of Experience) Settings
@@ -177,6 +327,10 @@ customData: {
 }
 ```
 
+> **Limit:** The maximum total number of custom attributes per event is **150**. Any attributes beyond this limit will be dropped.
+
+> **Note:** There are special reserved keywords used for default attributes (such as `actionName`, `contentBitrate`, `playerName`, `viewSession`, etc.). Please do not use these as custom attribute names, as they will be dropped. See [DATAMODEL.md](./DATAMODEL.md) for the complete list of reserved attribute names.
+
 ## API Reference
 
 ### Core Methods
@@ -259,6 +413,28 @@ player.on('userEngagement', () => {
 });
 ```
 
+## Bitrate Metrics
+
+The tracker captures four distinct bitrate metrics providing complete quality analysis:
+
+| Attribute                       | Description                                                                                                                       | Use Case                                     |
+| ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------- |
+| `contentBitrate`                | Encoding bitrate (in bps) of the currently playing rendition from the manifest                                                    | Monitor actual video quality being delivered |
+| `contentManifestBitrate`        | Maximum available bitrate (in bps) across all renditions in the manifest. Represents the highest quality capability of the stream | Understand maximum quality potential         |
+| `contentSegmentDownloadBitrate` | ABR estimated bandwidth (in bps) from the player's stats object, used by the ABR algorithm for quality switching decisions        | Analyze ABR decision-making                  |
+| `contentNetworkDownloadBitrate` | Instantaneous download throughput (in bps) from the most recent segment download. Represents raw network download speed           | Monitor real-time network performance        |
+
+### Bitrate Monitoring Example
+
+```javascript
+// All bitrate metrics are automatically captured and sent with each event
+// Access them in New Relic Insights queries:
+
+// NRQL Query Examples:
+// SELECT average(contentNetworkDownloadBitrate) FROM VideoAction WHERE actionName = 'CONTENT_HEARTBEAT'
+// SELECT contentBitrate, contentSegmentDownloadBitrate FROM VideoAction WHERE actionName = 'CONTENT_RENDITION_CHANGE'
+```
+
 ## Ad Tracking Support
 
 The tracker provides comprehensive ad tracking capabilities:
@@ -271,39 +447,94 @@ The tracker provides comprehensive ad tracking capabilities:
 
 ### SSAI/DAI Integration
 
-Server-Side Ad Insertion is fully supported with automatic detection and tracking:
+Server-Side Ad Insertion is supported with automatic tracker selection for supported integrations:
 
 ```javascript
-// SSAI is automatically detected - no additional configuration needed
+// 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
+// - SSAI-specific metadata when available
 ```
 
 **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).
+
+### 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
+
+```javascript
+import VideojsTracker 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);
+```
+
+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
+
+MediaTailor-specific behavior is automatic. The customer does not need to pass MediaTailor-only configuration flags into the tracker.
+
+## 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
+
+# Run tests in watch mode
+npm run test:watch
+```
+
+For more details, see [test/README.md](./test/README.md).
+
 ## Data Model
 
 The tracker captures comprehensive video analytics across four event types:
 
-- **VideoAction** - Playback events (play, pause, buffer, seek, quality changes)
+- **VideoAction** - Playback events (play, pause, buffer, seek, quality changes, heartbeats)
 - **VideoAdAction** - Ad events (ad start, quartiles, completions, clicks)
-- **VideoErrorAction** - Error events (playback failures, network errors)
+- **VideoErrorAction** - Error events (playback failures, network errors, media errors)
 - **VideoCustomAction** - Custom events defined by your application
 
-### Bitrate Metrics
-
-Four distinct bitrate metrics provide complete quality analysis:
-
-- `contentBitrate` - Current rendition encoding bitrate
-- `contentManifestBitrate` - Maximum available quality
-- `contentSegmentDownloadBitrate` - ABR bandwidth estimate
-- `contentNetworkDownloadBitrate` - Instantaneous throughput
-
-**Full Documentation:** See [datamodel.md](./datamodel.md) for complete event and attribute reference.
+**Full Documentation:** See [DATAMODEL.md](./DATAMODEL.md) for complete event and attribute reference.
 
 ## Support
 
@@ -320,11 +551,11 @@ If the issue has been confirmed as a bug or is a feature request, please file a
 
 ### Additional Resources
 
-- **[datamodel.md](./datamodel.md)** - Complete event and attribute reference
+- **[DATAMODEL.md](./DATAMODEL.md)** - Complete event and attribute reference
 - **[DEVELOPING.md](./DEVELOPING.md)** - Building and testing instructions
 - **[REVIEW.md](./REVIEW.md)** - Code review guidelines
 
-## Contributing
+## Contribute
 
 We encourage your contributions to improve the Video.js Tracker! Keep in mind that when you submit your pull request, you'll need to sign the CLA via the click-through using CLA-Assistant. You only have to sign the CLA one time per project.
 
@@ -332,14 +563,12 @@ If you have any questions, or to execute our corporate CLA (which is required if
 
 For more details on how best to contribute, see [CONTRIBUTING.md](./CONTRIBUTING.md).
 
-### A Note About Vulnerabilities
+### A note about vulnerabilities
 
 As noted in our [security policy](../../security/policy), New Relic is committed to the privacy and security of our customers and their data. We believe that providing coordinated disclosure by security researchers and engaging with the security community are important means to achieve our security goals.
 
 If you believe you have found a security vulnerability in this project or any of New Relic's products or websites, we welcome and greatly appreciate you reporting it to New Relic through our [bug bounty program](https://docs.newrelic.com/docs/security/security-privacy/information-security/report-security-vulnerabilities/).
 
-### Acknowledgments
-
 If you would like to contribute to this project, review [these guidelines](./CONTRIBUTING.md).
 
 To all contributors, we thank you! Without your contribution, this project would not be what it is today.