@newrelic/video-core 4.1.6-beta → 4.1.6

package/README.md

@@ -1,79 +1,557 @@
-[![Community Project header](https://github.com/newrelic/open-source-office/raw/master/examples/categories/images/Community_Project.png)](https://github.com/newrelic/open-source-office/blob/master/examples/categories/index.md#community-project)
-
 # New Relic Video Core - JavaScript
 
-The New Relic video tracking core library is the base for all video trackers in the browser platform. It contains the classes and core mechanisms used by the player specific trackers.
-It segregates the events into different event types based on action, such as video-related events going to `VideoAction`, ad-related events to `VideoAdAction`, errors to `VideoErrorAction`, and custom actions to `VideoCustomAction`.
+[![npm version](https://img.shields.io/npm/v/@newrelic/video-core.svg)](https://www.npmjs.com/package/@newrelic/video-core)
+[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
+
+The **New Relic Video Core** library (`@newrelic/video-core`) is the foundational framework for all browser-based video trackers in the New Relic ecosystem. It provides the core classes, state management, event harvesting, and data transmission pipeline that player-specific trackers extend.
+
+Events are categorized into four distinct types:
+
+| Event Type | Description |
+|---|---|
+| `VideoAction` | Content playback events (play, pause, seek, buffer, etc.) |
+| `VideoAdAction` | Ad-related events (ad start, end, quartile, break, etc.) |
+| `VideoErrorAction` | Error events (content errors, ad errors, crashes) |
+| `VideoCustomAction` | Custom events defined by the integrator |
+
+---
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Configuration](#configuration)
+  - [Info Object (Required)](#info-object-required)
+  - [Config Object (Optional)](#config-object-optional)
+- [Exposed API](#exposed-api)
+  - [Core](#core)
+  - [VideoTracker](#videotracker)
+  - [Tracker](#tracker)
+  - [Emitter](#emitter)
+  - [VideoTrackerState](#videotrackerstate)
+  - [Chrono](#chrono)
+  - [Log](#log)
+  - [Constants](#constants)
+- [Building a Custom Tracker](#building-a-custom-tracker)
+- [Tracker Methods Reference](#tracker-methods-reference)
+- [Getter Methods (Override These)](#getter-methods-override-these)
+- [Quality of Experience (QoE)](#quality-of-experience-qoe)
+- [Obfuscation Rules](#obfuscation-rules)
+- [Build & Development](#build--development)
+- [Distribution Formats](#distribution-formats)
+- [Testing](#testing)
+- [Data Model](#data-model)
+- [License](#license)
+
+---
 
-## Registering Trackers
+## Installation
 
-Any browser-based video tracker can extend the `VideoTracker` class and use its core functionality.
+```bash
+npm install @newrelic/video-core
+```
+
+Or include directly via UMD:
+
+```html
+<script src="dist/umd/nrvideo.min.js"></script>
+```
 
-To initialize a tracker, create an instance of your specific tracker class:
+## Quick Start
 
 ```javascript
+import nrvideo from '@newrelic/video-core';
+
+// 1. Define a custom tracker by extending VideoTracker
+class MyPlayerTracker extends nrvideo.VideoTracker {
+  getTrackerName() { return 'my-player'; }
+  getSrc() { return this.player.currentSrc; }
+  getDuration() { return this.player.duration; }
+  getPlayhead() { return this.player.currentTime; }
+  getRenditionWidth() { return this.player.videoWidth; }
+  getRenditionHeight() { return this.player.videoHeight; }
+
+  registerListeners() {
+    this.player.addEventListener('play', () => this.sendRequest());
+    this.player.addEventListener('playing', () => this.sendStart());
+    this.player.addEventListener('pause', () => this.sendPause());
+    this.player.addEventListener('ended', () => this.sendEnd());
+    this.player.addEventListener('waiting', () => this.sendBufferStart());
+    this.player.addEventListener('seeking', () => this.sendSeekStart());
+    this.player.addEventListener('seeked', () => this.sendSeekEnd());
+    this.player.addEventListener('error', () => this.sendError({
+      errorName: this.player.error?.message,
+      errorCode: this.player.error?.code
+    }));
+  }
+
+  unregisterListeners() {
+    // Remove all listeners added in registerListeners
+  }
+}
+
+// 2. Configure and register the tracker
 const options = {
   info: {
-    licenseKey: "xxxxxxxxxxx",
-    beacon: "xxxxxxxxxx",
-    applicationId: "xxxxxxx",
+    licenseKey: 'YOUR_LICENSE_KEY',
+    beacon: 'bam.nr-data.net',
+    applicationID: 'YOUR_APPLICATION_ID',
+  },
+  config: {
+    qoeAggregate: true,
   },
 };
 
-// User can get the `info` object by completing the onboarding process on New Relic.
-const tracker = new VideoSpecificTracker(player, options);
+const player = document.getElementById('myPlayer');
+const tracker = new MyPlayerTracker(player, options);
+
+// 3. Add tracker to Core to begin reporting
+nrvideo.Core.addTracker(tracker, options);
 ```
 
-Some of the APIs exposed and commonly used are:
+## Configuration
+
+The `options` object passed to `Core.addTracker()` consists of two parts:
+
+### Getting Your Configuration
 
-- `tracker.setUserId("userId")` &mdash; Set the user ID.
-- `tracker.setHarvestInterval(30000)` &mdash; Set the harvest interval time (in milliseconds).
-- `tracker.setOptions({ customData: { key: value } })` &mdash; Set custom options or data.
-- `tracker.sendCustom("CustomEvent", { data: "custom-test" })` &mdash; Send a custom event.
+Before initializing the tracker, obtain your New Relic configuration:
 
-Any event emitted by the tracker will be sent to New Relic and processed according to its type.
+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`
 
-Once the tracker is added, any event it emits will be sent to New Relic and processed by the following functions:
+### Info Object (Required)
+
+Obtained through the New Relic onboarding process. Two configuration modes are supported:
+
+**Mode 1 — With Application ID and Beacon:**
 
 ```javascript
-tracker.sendVideoAction("VideoEvent", { data: 1 });
-tracker.sendVideoAdAction("AdEvent", { data: "test-1" });
-tracker.sendVideoErrorAction("ErrorEvent", { data: "error-test" });
-tracker.sendVideoCustomAction("CustomEvent", { data: "custom-test" });
+info: {
+  licenseKey: 'YOUR_LICENSE_KEY',      // Required
+  applicationID: 'YOUR_APPLICATION_ID', // Required
+  beacon: 'bam.nr-data.net',            // Required when applicationID is provided
+}
 ```
 
+**Mode 2 — With App Name and Region:**
+
+```javascript
+info: {
+  licenseKey: 'YOUR_LICENSE_KEY', // Required
+  appName: 'My Video App',       // Required when no applicationID
+  region: 'US',                   // Required when no applicationID
+}
+```
+
+**Valid Beacon Endpoints:**
+
+| Region | Beacon |
+|---|---|
+| US | `bam.nr-data.net`, `bam-cell.nr-data.net` |
+| EU | `bam.eu01.nr-data.net` |
+| Staging | `staging-bam-cell.nr-data.net` |
+| GOV | `gov-bam.nr-data.net` |
+
+### Config Object (Optional)
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `qoeAggregate` | `boolean` | `false` | Enable Quality of Experience event aggregation. |
+| `qoeIntervalFactor` | `number` | `1` | Include QoE aggregate events once every N harvest cycles. Must be a positive integer. QoE events are always sent on the first and final harvest cycles. |
+| `obfuscate` | `array` | `[]` | Regex-based rules to mask sensitive data before transmission. See [Obfuscation Rules](#obfuscation-rules). |
+
+---
+
+## Exposed API
+
+All exports are available under the `nrvideo` namespace (UMD) or as named imports:
+
+```javascript
+import nrvideo from '@newrelic/video-core';
+
+// Available: nrvideo.Core, nrvideo.VideoTracker, nrvideo.Tracker,
+//            nrvideo.Emitter, nrvideo.VideoTrackerState, nrvideo.Chrono,
+//            nrvideo.Log, nrvideo.Constants, nrvideo.version,
+//            nrvideo.NrVideoEventAggregator, nrvideo.RetryQueueHandler,
+//            nrvideo.OptimizedHttpClient, nrvideo.HarvestScheduler,
+//            nrvideo.recordEvent
+```
+
+### Core
+
+Static class managing tracker registration and event dispatch.
+
+| Method | Description |
+|---|---|
+| `Core.addTracker(tracker, options)` | Registers a tracker and initializes video analytics config. Starts event reporting. |
+| `Core.removeTracker(tracker)` | Disposes and removes a tracker. Stops its event reporting. |
+| `Core.getTrackers()` | Returns the array of currently registered trackers. |
+| `Core.send(eventType, actionName, data)` | Sends an event to the collector. Called internally by event handlers. |
+| `Core.sendError(att)` | Sends a `VideoErrorAction` with `actionName: "ERROR"`. For external/app-level errors. |
+| `Core.forceHarvest()` | Forces an immediate harvest of all pending events. Returns a `Promise`. |
+
+### VideoTracker
+
+Base class for video player trackers. Extends `Tracker`.
+
+| Method | Description |
+|---|---|
+| `constructor(player, options)` | Initializes the tracker. Lifecycle: constructor → `setOptions` → `setPlayer` → `registerListeners`. |
+| `setPlayer(player, tag)` | Sets the player and optional DOM element. Calls `registerListeners()`. |
+| `setOptions(options)` | Configures tracker options (heartbeat, customData, adsTracker, isAd, parentTracker). |
+| `setAdsTracker(tracker)` | Sets a child ad tracker. Ad events are funneled through the parent. |
+| `setUserId(userId)` | Sets a user identifier included as `enduser.id` in all events. |
+| `setHarvestInterval(interval)` | Updates the harvest cycle interval in milliseconds. |
+| `dispose()` | Stops heartbeat, disposes ad tracker, unregisters listeners, clears references. |
+| `registerListeners()` | **Override this.** Attach player event listeners and map to `send*()` methods. |
+| `unregisterListeners()` | **Override this.** Detach player event listeners. |
+| `getAttributes(att)` | **Do NOT override.** Collects all video/ad attributes. Use getter methods instead. |
+
+**State-changing methods** (call these from `registerListeners`):
+
+| Method | Event Emitted (Content / Ad) | Description |
+|---|---|---|
+| `sendPlayerReady(att)` | `PLAYER_READY` | Player is initialized and ready. |
+| `sendRequest(att)` | `CONTENT_REQUEST` / `AD_REQUEST` | Playback has been requested. |
+| `sendStart(att)` | `CONTENT_START` / `AD_START` | First frame rendered. Starts heartbeat. |
+| `sendEnd(att)` | `CONTENT_END` / `AD_END` | Playback ended. Stops heartbeat. |
+| `sendPause(att)` | `CONTENT_PAUSE` / `AD_PAUSE` | Playback paused. |
+| `sendResume(att)` | `CONTENT_RESUME` / `AD_RESUME` | Playback resumed. |
+| `sendBufferStart(att)` | `CONTENT_BUFFER_START` / `AD_BUFFER_START` | Buffering started. |
+| `sendBufferEnd(att)` | `CONTENT_BUFFER_END` / `AD_BUFFER_END` | Buffering ended. |
+| `sendSeekStart(att)` | `CONTENT_SEEK_START` / `AD_SEEK_START` | Seek started. |
+| `sendSeekEnd(att)` | `CONTENT_SEEK_END` / `AD_SEEK_END` | Seek ended. |
+| `sendError(att)` | `CONTENT_ERROR` / `AD_ERROR` | Error occurred during playback. |
+| `sendRenditionChanged(att)` | `CONTENT_RENDITION_CHANGE` / `AD_RENDITION_CHANGE` | Stream quality changed. |
+| `sendDownload(att)` | `DOWNLOAD` | Download event. Requires `att.state`. |
+| `sendHeartbeat(att)` | `CONTENT_HEARTBEAT` / `AD_HEARTBEAT` | Sent automatically every 30s (2s for ads). |
+| `sendAdBreakStart(att)` | `AD_BREAK_START` | Ad break started (ads only). |
+| `sendAdBreakEnd(att)` | `AD_BREAK_END` | Ad break ended (ads only). |
+| `sendAdQuartile(att)` | `AD_QUARTILE` | Ad quartile reached. Requires `att.quartile`. |
+| `sendAdClick(att)` | `AD_CLICK` | Ad clicked. Requires `att.url`. |
+| `sendCustom(actionName, timeSinceAttName, att)` | Custom `VideoCustomAction` | Sends a custom event with a `timeSince` attribute. |
+
+### Tracker
+
+Base class providing heartbeat, custom data, and attribute management. Extends `Emitter`.
+
+| Method | Description |
+|---|---|
+| `setOptions(options)` | Set heartbeat interval, customData, and parentTracker. |
+| `getHeartbeat()` | Returns heartbeat interval in ms. Default: 30000 (content), 2000 (ads). |
+| `startHeartbeat()` | Starts the heartbeat interval. Called automatically on `sendStart`. |
+| `stopHeartbeat()` | Stops the heartbeat interval. Called automatically on `sendEnd`. |
+| `getAttributes(att)` | Returns base attributes (trackerName, coreVersion, isBackgroundEvent, etc.). |
+| `sendVideoAction(event, att)` | Emits a `VideoAction` event. |
+| `sendVideoAdAction(event, att)` | Emits a `VideoAdAction` event. |
+| `sendVideoErrorAction(event, att)` | Emits a `VideoErrorAction` event. |
+| `sendVideoCustomAction(event, att)` | Emits a `VideoCustomAction` event. |
+
+### Emitter
+
+Event system base class.
+
+| Method | Description |
+|---|---|
+| `on(event, callback)` | Subscribe to an event. Use `'*'` to listen to all events. |
+| `off(event, callback)` | Unsubscribe from an event. |
+| `emit(eventType, event, data)` | Emit an event to all subscribers. |
+
+### VideoTrackerState
+
+Internal state machine managing view lifecycle, QoE KPIs, and timing.
+
+| Property | Description |
+|---|---|
+| `numberOfErrors` | Error count for current view. |
+| `numberOfAds` | Total ads shown. |
+| `numberOfVideos` | Total videos played. |
+| `totalPlaytime` | Content viewing time in ms (excludes pausing, buffering, ads). |
+| `totalAdPlaytime` | Ad viewing time in ms. |
+| `startupTime` | Time from `CONTENT_REQUEST` to `CONTENT_START` in ms. |
+| `peakBitrate` | Maximum bitrate observed during playback. |
+
+### Chrono
+
+Utility class for measuring time lapses.
+
+| Method | Description |
+|---|---|
+| `start()` | Start the timer. |
+| `stop()` | Stop the timer and return delta. |
+| `getDeltaTime()` | Get elapsed time since `start()` in ms. |
+| `getDuration()` | Get accumulated duration across multiple start/stop cycles. |
+| `reset()` | Reset all values. |
+| `clone()` | Create a copy of the chrono. |
+
+### Log
+
+Static logging utility with configurable levels.
+
+| Method | Description |
+|---|---|
+| `Log.error(...msg)` | Log an error. |
+| `Log.warn(...msg)` | Log a warning. |
+| `Log.notice(...msg)` | Log a notice. |
+| `Log.debug(...msg)` | Log a debug message. |
+| `Log.debugCommonVideoEvents(player, extraEvents, report)` | Attach debug listeners for common HTML5 video events. |
+
+**Log Levels** (set via `Log.level`):
+
+```javascript
+nrvideo.Log.level = nrvideo.Log.Levels.DEBUG; // ALL, DEBUG, NOTICE, WARNING, ERROR, SILENT
+```
+
+### Constants
+
+| Constant | Value | Description |
+|---|---|---|
+| `Constants.AdPositions` | `{ PRE, MID, POST }` | Ad position enum. |
+| `Constants.COLLECTOR` | Object | Beacon endpoint URLs by region. |
+| `Constants.VALID_EVENT_TYPES` | Array | `['VideoAction', 'VideoAdAction', 'VideoErrorAction', 'VideoCustomAction']` |
+| `Constants.MAX_PAYLOAD_SIZE` | `1048576` | Maximum payload size (1 MB). |
+| `Constants.MAX_BEACON_SIZE` | `61440` | Maximum beacon size (60 KB). |
+| `Constants.MAX_EVENTS_PER_BATCH` | `1000` | Maximum events per batch. |
+| `Constants.INTERVAL` | `10000` | Default harvest interval (10s). |
+
+---
+
+## Building a Custom Tracker
+
+Extend `VideoTracker` and override getter methods and listener registration:
+
+```javascript
+class MyPlayerTracker extends nrvideo.VideoTracker {
+  // Required: identify your tracker
+  getTrackerName() { return 'my-custom-player'; }
+  getTrackerVersion() { return '1.0.0'; }
+
+  // Override getters to return player metadata
+  getVideoId() { return this.player.getContentId(); }
+  getTitle() { return this.player.getTitle(); }
+  getSrc() { return this.player.getSrc(); }
+  getDuration() { return this.player.getDuration() * 1000; } // in ms
+  getPlayhead() { return this.player.getCurrentTime() * 1000; }
+  getBitrate() { return this.player.getCurrentBitrate(); }
+  getRenditionName() { return this.player.getQualityLabel(); }
+  getRenditionHeight() { return this.player.getVideoHeight(); }
+  getRenditionWidth() { return this.player.getVideoWidth(); }
+  isLive() { return this.player.isLive(); }
+  isMuted() { return this.player.isMuted(); }
+  isFullscreen() { return this.player.isFullscreen(); }
+  getPlayrate() { return this.player.getPlaybackRate(); }
+  getPlayerName() { return 'My Player'; }
+  getPlayerVersion() { return this.player.version; }
+
+  // Map player events to tracker methods
+  registerListeners() {
+    this.player.on('play', () => this.sendRequest());
+    this.player.on('playing', () => this.sendStart());
+    this.player.on('pause', () => this.sendPause());
+    this.player.on('ended', () => this.sendEnd());
+    this.player.on('waiting', () => this.sendBufferStart());
+    this.player.on('canplay', () => this.sendBufferEnd());
+    this.player.on('seeking', () => this.sendSeekStart());
+    this.player.on('seeked', () => this.sendSeekEnd());
+    this.player.on('error', (e) => this.sendError({
+      errorName: e.message,
+      errorCode: e.code
+    }));
+  }
+
+  unregisterListeners() {
+    this.player.off('play');
+    this.player.off('playing');
+    // ... remove all listeners
+  }
+}
+```
+
+---
+
+## Getter Methods (Override These)
+
+These methods return `null` by default. Override them in your tracker to provide player-specific data:
+
+| Getter | Attribute Set | Description |
+|---|---|---|
+| `getVideoId()` | `contentId` / `adId` | Content or ad identifier. |
+| `getTitle()` | `contentTitle` / `adTitle` | Content or ad title. |
+| `getSrc()` | `contentSrc` / `adSrc` | Media source URL. |
+| `getDuration()` | `contentDuration` / `adDuration` | Duration in ms. |
+| `getPlayhead()` | `contentPlayhead` / `adPlayhead` | Current playback position in ms. |
+| `getBitrate()` | `contentBitrate` / `adBitrate` | Current bitrate in bits/s. |
+| `getManifestBitrate()` | `contentManifestBitrate` | Manifest/playlist declared bitrate in bps. |
+| `getSegmentDownloadBitrate()` | `contentSegmentDownloadBitrate` | Measured bitrate from segment download in bps. |
+| `getNetworkDownloadBitrate()` | `contentNetworkDownloadBitrate` | Network download throughput in bps. |
+| `getRenditionName()` | `contentRenditionName` / `adRenditionName` | Quality label (e.g., "1080p"). |
+| `getRenditionHeight()` | `contentRenditionHeight` / `adRenditionHeight` | Rendition height in px. |
+| `getRenditionWidth()` | `contentRenditionWidth` / `adRenditionWidth` | Rendition width in px. |
+| `isLive()` | `contentIsLive` | `true` if live stream. |
+| `isMuted()` | `contentIsMuted` / `adIsMuted` | `true` if muted. |
+| `isFullscreen()` | `contentIsFullscreen` | `true` if fullscreen. |
+| `getPlayrate()` | `contentPlayrate` | Playback speed (1.0 = normal). |
+| `getLanguage()` | `contentLanguage` / `adLanguage` | Language in locale notation (e.g., `en_US`). |
+| `getCdn()` | `contentCdn` / `adCdn` | CDN serving the content. |
+| `getFps()` | `contentFps` / `adFps` | Current frames per second. |
+| `isAutoplayed()` | `contentIsAutoplayed` | `true` if autoplayed. |
+| `getPreload()` | `contentPreload` | Preload attribute value. |
+| `getPlayerName()` | `playerName` | Player name. |
+| `getPlayerVersion()` | `playerVersion` | Player version. |
+| `getAdQuartile()` | `adQuartile` | Ad quartile (0–4). |
+| `getAdPosition()` | `adPosition` | Ad position (`pre`, `mid`, `post`). |
+| `getAdPartner()` | `adPartner` | Ad partner (e.g., `ima`, `freewheel`). |
+| `getAdCreativeId()` | `adCreativeId` | Ad creative identifier. |
+
+---
+
+## Quality of Experience (QoE)
+
+When `qoeAggregate` is enabled, the library tracks and reports QoE KPI metrics as `QOE_AGGREGATE` events:
+
+| KPI | Description |
+|---|---|
+| `startupTime` | Time from `CONTENT_REQUEST` to `CONTENT_START` in ms. |
+| `peakBitrate` | Maximum bitrate observed during playback. |
+| `averageBitrate` | Playtime-weighted average bitrate in bps. |
+| `totalPlaytime` | Total content viewing time in ms (excludes pausing, buffering, ads). |
+| `totalRebufferingTime` | Total ms spent rebuffering (excludes initial buffering). |
+| `rebufferingRatio` | `(totalRebufferingTime / totalPlaytime) × 100`. |
+| `hadStartupError` | `true` if error occurred before `CONTENT_START`. |
+| `hadPlaybackError` | `true` if error occurred at any time during playback. |
+
+QoE KPIs are refreshed before each harvest drain and always included in the final harvest at `CONTENT_END`.
+
+---
+
+## Obfuscation Rules
+
+Mask sensitive data in event payloads before transmission using regex-based rules:
+
+```javascript
+config: {
+  obfuscate: [
+    { regex: /\/user\/[^\/?"]+/, replacement: '/user/[REDACTED]' },
+    { regex: /token=[^&"]+/, replacement: 'token=[MASKED]' },
+  ]
+}
+```
+
+| Field | Type | Description |
+|---|---|---|
+| `regex` | `string` \| `RegExp` | Pattern to match in the serialized JSON payload. |
+| `replacement` | `string` | Replacement string for each match. |
+
+Rules are applied sequentially — the output of one rule feeds into the next. Invalid regex patterns are skipped with a warning logged via `Log.warn`.
+
+---
+
+## Build & Development
+
+```bash
+# Install dependencies
+npm install
+
+# Production build
+npm run build
+
+# Development build (unminified)
+npm run build:dev
+
+# Watch mode (production)
+npm run watch
+
+# Watch mode (development)
+npm run watch:dev
+
+# Clean build artifacts
+npm run clean
+```
+
+## Distribution Formats
+
+The build produces three output formats:
+
+| Format | Path | Usage |
+|---|---|---|
+| **UMD** | `dist/umd/nrvideo.min.js` | `<script>` tag → `window.nrvideo` |
+| **CommonJS** | `dist/cjs/index.js` | `require('@newrelic/video-core')` |
+| **ES Module** | `dist/esm/index.js` | `import nrvideo from '@newrelic/video-core'` |
+
+## Testing
+
+```bash
+# Run tests with coverage
+npm test
+```
+
+Tests are written using [Jest](https://jestjs.io/) and located in the `test/` directory.
+
+---
+
 ## Data Model
 
-To understand which actions and attributes are captured and emitted by the tracker under different event types, see [DataModel.md](DATAMODEL.md).
+For a comprehensive reference of all event types, attributes, and action names, see [DATAMODEL.md](DATAMODEL.md).
+
+---
+
+## License
+
+This project is licensed under the [Apache 2.0 License](LICENSE).
+
+---
+
+## Support
+
+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:**
+
+- [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
+
+**Additional Resources:**
+
+- [DATAMODEL.md](DATAMODEL.md) — Complete event and attribute reference
+- [DEVELOPING.md](DEVELOPING.md) — Building and testing instructions
+- [CONTRIBUTING.md](CONTRIBUTING.md) — Contribution guidelines
+
+---
 
-## Documentation
+## Contributing
 
-All classes are documented using autodocs. The documents, generated with [jsdoc](https://github.com/jsdoc/jsdoc), can be found in the `documentation` directory of the current repo.
+We encourage your contributions to improve the Video Core JS library! 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.
 
-# Support
+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.
 
-New Relic has open-sourced this project. This project is provided AS-IS WITHOUT WARRANTY OR DEDICATED SUPPORT. Issues and contributions should be reported to the project here on GitHub.
+For more details on how best to contribute, see [CONTRIBUTING.md](CONTRIBUTING.md).
 
-We encourage you to bring your experiences and questions to the [Explorers Hub](https://discuss.newrelic.com) where our community members collaborate on solutions and new ideas.
+---
 
-## Community
+## A Note About Vulnerabilities
 
-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 Explorers Hub. You can find this project's topic/threads here:
+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.
 
-https://discuss.newrelic.com/t/video-core-js-tracker/100303
+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/).
 
-## Issues / enhancement requests
+---
 
-Issues and enhancement requests can be submitted in the [Issues tab of this repository](../../issues). Please search for and review the existing open issues before submitting a new issue.
+## Acknowledgments
 
-# Contributing
+If you would like to contribute to this project, review [these guidelines](CONTRIBUTING.md).
 
-Contributions are encouraged! If you submit an enhancement request, we'll invite you to contribute the change yourself. Please review our [Contributors Guide](CONTRIBUTING.md).
+To all contributors, we thank you! Without your contribution, this project would not be what it is today.
 
-Keep in mind that when you submit your pull request, you'll need to sign the CLA via the click-through using CLA-Assistant. If you'd like to execute our corporate CLA, or if you have any questions, please drop us an email at opensource+videoagent@newrelic.com.
+---
 
-# License
+## License
 
-This project is distributed under the [Apache 2.0](https://apache.org/licenses/LICENSE-2.0.txt) License.
+The Video Core JS library is licensed under the [Apache 2.0 License](LICENSE).
 
-The video-core 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).
+The Video Core JS library 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).