@newrelic/video-videojs 4.0.3 → 4.1.0

package/CHANGELOG.md

@@ -1,13 +1,46 @@
-## [4.0.3](https://github.com/newrelic/video-videojs-js/compare/v4.0.2...v4.0.3) (2025-11-21)
+## [4.1.0](https://github.com/newrelic/video-videojs-js/compare/v4.0.3...v4.1.0) (2026-04-08)
+
+### Breaking Changes
+
+- **Method Renames:** Bitrate methods renamed for clarity
+  - `getMeasuredBitrate()` → `getSegmentDownloadBitrate()` - ABR bandwidth estimate from player stats
+  - `getDownloadBitrate()` → `getNetworkDownloadBitrate()` - Instantaneous network throughput
+  - **Note:** Most users won't be affected as these methods are primarily used internally by the tracker
+
+### Deprecated
+
+- **Removed `getRenditionBitrate()` method** - No longer needed with improved bitrate tracking system
+
+### Enhancements
 
+- **Bitrate Metrics Refactoring:**
+  - Implemented consistent fallback pattern across all bitrate methods (VHS direct access → tech wrapper fallback)
+  - Simplified network download bitrate to use direct throughput access
+  - Enhanced bitrate tracking with four distinct metrics for comprehensive quality analysis
+  - Updated all tech wrappers (VHS, hls.js, Shaka) with consistent implementations
+
+- **Comprehensive Documentation Rewrite:**
+  - **README.md:** Complete rewrite with professional structure, badges, features section, table of contents, two installation options, expanded API reference, and clear New Relic support channels
+  - **datamodel.md:** Complete rewrite with comprehensive event reference, all four bitrate metrics definitions, QoE attributes, complete attribute tables for all event types, and SSAI/DAI support documentation
+  - **DEVELOPING.md:** Complete development guide with setup, build instructions, project structure, testing guidelines, and release process
+  - **REVIEW.md:** NEW FILE - Code review guidelines and standards for contributors
+
+### Documentation
+
+- Added clear instructions to obtain configuration from [one.newrelic.com](https://one.newrelic.com)
+- Updated all bitrate metric definitions with accurate sources and use cases
+- Added comprehensive API reference with method signatures and examples
+- Enhanced support section with multiple New Relic support channels
+- Added third-party library license disclosure
+
+## [4.0.3](https://github.com/newrelic/video-videojs-js/compare/v4.0.2...v4.0.3) (2025-11-21)
 
 ### Bug Fixes
 
-* removed github token ([f5f9ade](https://github.com/newrelic/video-videojs-js/commit/f5f9ade01c9af411d72ec74874f8d0750c5f0f66))
+- removed github token ([f5f9ade](https://github.com/newrelic/video-videojs-js/commit/f5f9ade01c9af411d72ec74874f8d0750c5f0f66))
 
 # CHANGELOG
 
-
 ## [4.0.2] - 2025-10-21
 
 ### Bug Fixes

package/README.md

@@ -1,131 +1,351 @@
 [![Community Project header](https://github.com/newrelic/opensource-website/raw/master/src/images/categories/Community_Project.png)](https://opensource.newrelic.com/oss-category/#community-project)
 
-# New Relic Videojs Tracker Agent
+# New Relic Video.js Tracker
 
-The New Relic Videojs Tracker enhances your media applications by tracking video events, playback errors, and other activities, providing comprehensive insights into performance and user interactions.
+[![npm version](https://badge.fury.io/js/%40newrelic%2Fvideo-videojs.svg)](https://badge.fury.io/js/%40newrelic%2Fvideo-videojs)
+[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
 
-- The Videojs tracker is available as a ready-to-use JavaScript snippet for easy copy-paste integration.
-- New Relic Videojs tracker auto-detects events emitted by Videojs Player.
-- Ensure that the **Browser agent** is successfully instrumented before deploying the media tracker.
-- For questions and feedback on this package, please visit the [Explorer's Hub](https://discuss.newrelic.com), New Relic's community support forum.
-- Looking to contribute to the Player Name agent code base? See [DEVELOPING.md](./DEVELOPING.md) for instructions on building and testing the browser agent library, and Contributors.
+The New Relic Video.js Tracker provides comprehensive video analytics for applications using Video.js Player. Track video events, monitor playback quality, identify errors, and gain deep insights into user engagement and streaming performance.
 
-## Adding The Videojs Tracker To Your Project
+## Features
 
-To integrate New Relic Tracker Agent into your web application effectively, you'll need to instrument the Browser Agent code first and then add the player script. Below is a guide on how to do this within your HTML file:
+- 🎯 **Automatic Event Detection** - Captures Video.js player events automatically without manual instrumentation
+- 📊 **Comprehensive Bitrate Tracking** - Four distinct bitrate metrics for complete quality analysis
+- 🎬 **Ad Tracking Support** - Full support for IMA, Freewheel, and SSAI (Server-Side Ad Insertion)
+- 🔧 **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`
+- 🚀 **Easy Integration** - NPM package or direct script include
+
+## Table of Contents
+
+- [Installation](#installation)
+  - [Option 1: NPM/Yarn](#option-1-install-via-npmyarn)
+  - [Option 2: Direct Script Include](#option-2-direct-script-include-without-npm)
+- [Usage](#usage)
+- [Configuration Options](#configuration-options)
+- [API Reference](#api-reference)
+- [Ad Tracking Support](#ad-tracking-support)
+- [Data Model](#data-model)
+- [Support](#support)
+- [Contributing](#contributing)
+- [License](#license)
+
+## Installation
+
+### Option 1: Install via NPM/Yarn
+
+Install the package using your preferred package manager:
+
+**NPM:**
+
+```bash
+npm install @newrelic/video-videojs
+```
+
+**Yarn:**
+
+```bash
+yarn add @newrelic/video-videojs
+```
+
+### Option 2: Direct Script Include (Without NPM)
+
+For quick integration without a build system, include the tracker directly in your HTML:
 
 ```html
 <!DOCTYPE html>
-<html lang="en">
+<html>
   <head>
-    <meta charset="UTF-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <title>New Relic Tracker Integration</title>
-    <script src="path/to/browser-agent.js"></script>
-    <!-- snippet code generated  -->
-    <script src="path/to/videojs-tracker.js"></script>
+    <!-- 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>
+
+    <!-- New Relic Video.js Tracker -->
+    <script src="path/to/newrelic-video-videojs.min.js"></script>
   </head>
   <body>
-    <!-- Your HTML content -->
+    <video id="myVideo" class="video-js" controls width="640" height="480">
+      <source src="https://your-video-source.mp4" type="video/mp4" />
+    </video>
+
+    <script>
+      // Initialize Video.js player
+      var player = videojs('myVideo');
+
+      // Configure New Relic tracker with info from one.newrelic.com
+      const options = {
+        info: {
+          licenseKey: 'YOUR_LICENSE_KEY',
+          beacon: 'YOUR_BEACON_URL',
+          applicationId: 'YOUR_APP_ID',
+        },
+      };
+
+      // Initialize tracker
+      const tracker = new VideojsTracker(player, options);
+    </script>
   </body>
 </html>
 ```
 
-## Adding the agent package to your project
+**Setup Steps:**
 
-To make the tracker available to your application, install via [NPM](https://docs.npmjs.com/cli/v8/commands/npm-install) or [Yarn](https://classic.yarnpkg.com/lang/en/docs/cli/install/).
+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
 
-```shell
-$ npm install @newrelic/video-videojs
-```
+## Usage
 
-```shell
-$ yarn add @newrelic/video-videojs
-```
+### Getting Your Configuration
+
+Before initializing the tracker, obtain your New Relic configuration:
+
+1. Log in to [one.newrelic.com](https://one.newrelic.com)
+2. Navigate to the video agent onboarding flow
+3. Copy your credentials: `licenseKey`, `beacon`, and `applicationId`
 
-## Instantiating the Videojs Tracker
+### Basic Setup
 
+```javascript
+import VideojsTracker from '@newrelic/video-videojs';
+
+// Initialize Video.js player
+const player = videojs('myVideo');
+
+// Set player version (required)
+player.version = videojs.VERSION;
 
-> [!NOTE]
-> **Attention:**  
-> This version uses the latest **standalone** version of the Videojs Tracker, In order to initialize it you need to do the following:
+// Configure tracker with credentials from one.newrelic.com
+const options = {
+  info: {
+    licenseKey: 'YOUR_LICENSE_KEY',
+    beacon: 'YOUR_BEACON_URL',
+    applicationId: 'YOUR_APP_ID',
+  },
+};
 
-Steps to get NREUM config
- - Create a New Relic account and obtain your license key.
- - Install the New Relic Streaming video agent in your application.
- - Configure the video agent with your license key and application ID.
+// Initialize tracker
+const tracker = new VideojsTracker(player, options);
+```
 
-The NREUM config looks like this:
+### Advanced Configuration
 
 ```javascript
-/* Get the info object from the video agent onboarding */
-options = {
+const options = {
   info: {
-    beacon: 'xxxxxxxxxxx',
-    licenseKey: 'xxxxxxxxxxx',
-    applicationID: 'xxxxxxxxxxxx',
+    licenseKey: 'YOUR_LICENSE_KEY',
+    beacon: 'YOUR_BEACON_URL',
+    applicationId: 'YOUR_APP_ID',
+  },
+  config: {
+    qoeAggregate: true, // Enable QoE event aggregation
+    qoeIntervalFactor: 2, // Send QoE events every 2 harvest cycles
+  },
+  customData: {
+    contentTitle: 'My Video Title',
+    customPlayerName: 'MyCustomPlayer',
+    customAttribute: 'customValue',
   },
 };
+
+const tracker = new VideojsTracker(player, options);
 ```
 
+## Configuration Options
+
+### QoE (Quality of Experience) Settings
+
+| Option              | Type    | Default | Description                                                                                                                                                                              |
+| ------------------- | ------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `qoeAggregate`      | boolean | `false` | Enable Quality of Experience event aggregation. Set to `true` to collect QoE metrics like startup time, buffering, and average bitrate.                                                  |
+| `qoeIntervalFactor` | number  | `1`     | Controls QoE event frequency. A value of `N` sends QoE events once every N harvest cycles. Must be a positive integer. QoE events are always included on first and final harvest cycles. |
+
+### Custom Data
+
+Add custom attributes to all events:
+
 ```javascript
-import VideojsTracker from "@newrelic/video-videojs";
+customData: {
+  contentTitle: 'My Video Title',      // Override video title
+  customPlayerName: 'MyPlayer',        // Custom player identifier
+  customPlayerVersion: '1.0.0',        // Custom player version
+  userId: '12345',                     // User identifier
+  // Add any custom attributes you need
+}
+```
 
-// pass player version
-player.version = videojs.VERSION;
+## API Reference
 
-// initialize VideojsTracker with player and options
-const tracker = new VideojsTracker(player, options);
+### Core Methods
 
-// ================================================= //
+#### `tracker.setUserId(userId)`
 
-//For setting custom attributes const tracker
-const tracker = new VideojsTracker(player, {
+Set a unique identifier for the current user.
+
+```javascript
+tracker.setUserId('user-12345');
+```
+
+#### `tracker.setHarvestInterval(milliseconds)`
+
+Configure how frequently data is sent to New Relic. Accepts values between 1000ms (1 second) and 300000ms (5 minutes).
+
+```javascript
+tracker.setHarvestInterval(30000); // Send data every 30 seconds
+```
+
+#### `tracker.sendCustom(actionName, attributes)`
+
+Send custom events with arbitrary attributes.
+
+```javascript
+tracker.sendCustom('VideoBookmarked', {
+  timestamp: Date.now(),
+  position: player.currentTime(),
+  userId: 'user-12345',
+  bookmarkId: 'bookmark-789',
+});
+```
+
+#### `tracker.setOptions(options)`
+
+Update tracker configuration after initialization.
+
+```javascript
+tracker.setOptions({
   customData: {
-    contentTitle: 'Override Existing Title',
-    customPlayerName: 'myGreatPlayer',
-    customPlayerVersion: '9.4.2',
+    contentTitle: 'New Video Title',
+    season: '1',
+    episode: '3',
   },
 });
+```
 
-// For setting userId
-tracker.setUserId('userId');
+### Example: Complete Integration
 
-// set tracker interval, between 1s - 5mins
-tracker.setHarvestInterval(1000)
+```javascript
+import VideojsTracker from '@newrelic/video-videojs';
+
+// Initialize player and tracker
+const player = videojs('myVideo');
+player.version = videojs.VERSION;
+
+const tracker = new VideojsTracker(player, {
+  info: {
+    licenseKey: 'YOUR_LICENSE_KEY',
+    beacon: 'YOUR_BEACON_URL',
+    applicationId: 'YOUR_APP_ID',
+  },
+  config: {
+    qoeAggregate: true,
+  },
+});
 
-// For Sending custom Action with Attributes
-tracker.sendCustom('CustomAction', { data: "custom-test" })
+// Set user context
+tracker.setUserId('user-12345');
 
+// Configure reporting interval
+tracker.setHarvestInterval(30000);
+
+// Send custom events
+player.on('userEngagement', () => {
+  tracker.sendCustom('UserEngaged', {
+    action: 'like',
+    timestamp: Date.now(),
+  });
+});
 ```
 
-## Support for SSAI Ads
+## Ad Tracking Support
+
+The tracker provides comprehensive ad tracking capabilities:
 
-> [!NOTE]
-> **Attention:**  
-> This version supports tracking for SSAI (Server-Side Ad Insertion), checkout examples in [/samples/dai/index.html](./samples/dai/index.html)
+### 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
+
+### SSAI/DAI Integration
+
+Server-Side Ad Insertion is fully supported with automatic detection and tracking:
+
+```javascript
+// SSAI is automatically detected - no additional configuration needed
+const tracker = new VideojsTracker(player, options);
+
+// The tracker will automatically capture:
+// - Ad breaks, starts, and completions
+// - Ad quartiles and click events
+// - SSAI-specific metadata
+```
+
+**Example:** See [samples/dai/index.html](./samples/dai/index.html) for a complete SSAI implementation.
 
 ## Data Model
 
-To understand which actions and attributes are captured and emitted by the Videojs Player under different event types, see [DataModel.md](./DATAMODEL.md).
+The tracker captures comprehensive video analytics across four event types:
+
+- **VideoAction** - Playback events (play, pause, buffer, seek, quality changes)
+- **VideoAdAction** - Ad events (ad start, quartiles, completions, clicks)
+- **VideoErrorAction** - Error events (playback failures, network 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.
 
 ## Support
 
-New Relic hosts and moderates an online forum where customers can interact with New Relic employees as well as other customers to get help and share best practices. Like all official New Relic open source projects, there's a related Community topic in the New Relic [Explorer's Hub](https://discuss.newrelic.com).
+Should you need assistance with New Relic products, you are in good hands with several support channels.
+
+If the issue has been confirmed as a bug or is a feature request, please file a [GitHub issue](../../issues).
+
+### Support Channels
 
-We encourage you to bring your experiences and questions to the [Explorer's Hub](https://discuss.newrelic.com) where our community members collaborate on solutions and new ideas.
+- **[New Relic Documentation](https://docs.newrelic.com)**: Comprehensive guidance for using our platform
+- **[New Relic Community](https://discuss.newrelic.com)**: The best place to engage in troubleshooting questions
+- **[New Relic University](https://learn.newrelic.com)**: A range of online training for New Relic users of every level
+- **[New Relic Technical Support](https://support.newrelic.com)**: 24/7/365 ticketed support. Read more about our [Technical Support Offerings](https://docs.newrelic.com/docs/licenses/license-information/general-usage-licenses/support-plan)
+
+### Additional Resources
+
+- **[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
 
-We encourage your contributions to improve New Relic Videojs Tracker! Keep in mind 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. If you have any questions, or to execute our corporate CLA, required if your contribution is on behalf of a company, please drop us an email at opensource@newrelic.com.
+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.
+
+If you have any questions, or to execute our corporate CLA (which is required if your contribution is on behalf of a company), drop us an email at opensource@newrelic.com.
 
-**A note about vulnerabilities**
+For more details on how best to contribute, see [CONTRIBUTING.md](./CONTRIBUTING.md).
+
+### 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/).
+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.
 
 ## License
 
-New Relic Videojs Tracker is licensed under the [Apache 2.0](http://apache.org/licenses/LICENSE-2.0.txt) License.
+The Video.js Tracker is licensed under the [Apache 2.0](http://apache.org/licenses/LICENSE-2.0.txt) License.
+
+The Video.js Tracker also uses source code from third-party libraries. Full details on which libraries are used and the terms under which they are licensed can be found in the [third-party notices document](./THIRD_PARTY_NOTICES.md).