Implement dash.js data collection and update readme.md

Author: HarishKumar097

CHANGELOG.md

@@ -2,16 +2,23 @@
 
 All notable changes to this project will be documented in this file.
 
+## [1.0.2]
+- Added support for DASH.js video player monitoring
+- Enhanced analytics collection for DASH streams
+- Improved error tracking for DASH.js players
+
 ## [1.0.1]
 - Resolved proper cleanup of HLS streams upon the viewComplete event.
-- Enhanced stream handling logic: when a new player instance is initialized while another is in progress, the SDK now correctly destroys the previous player’s data monitoring and seamlessly switches to capture analytics for the incoming player.
+- Enhanced stream handling logic: when a new player instance is initialized while another is in progress, the SDK now correctly destroys the previous player's data monitoring and seamlessly switches to capture analytics for the incoming player.
 
 ## [1.0.0]
 
 ### Added
-- **Integration with HLS**:
-  - Enabled video performance tracking using FastPix Data SDK, supporting HLS streams with user engagement metrics, playback quality monitoring, and real-time streaming diagnostics.
-  - Provides robust error management and reporting capabilities for HLS video performance tracking.
-  - Allows customizable behavior, including options to disable cookies, respect `Do Not Track` settings, and configure advanced error tracking and automatic error handling.
-  - Includes support for custom metadata, enabling users to pass optional fields such as `video_id`, `video_title`, `video_duration`, and more.
-  - Introduced event tracking for `videoChange` to handle metadata updates during playback transitions.
+- Initial release of FastPix Video Data Core SDK
+- Support for HLS.js video player monitoring
+- Real-time analytics collection and reporting
+- Custom event tracking capabilities
+- Error tracking and diagnostics
+- Performance metrics collection
+- Stream-level analytics
+- User interaction tracking

README.md

@@ -1,27 +1,30 @@
 # Introduction:
 
-This SDK simplifies integration steps with [HLS.js](https://github.com/video-dev/hls.js), enabling the collection of player analytics. It enables automatic tracking of video performance metrics, making the data readily available on the [FastPix dashboard](https://dashboard.fastpix.io) for monitoring and analysis. While the SDK is developed in TypeScript, the published npm package currently includes only the JavaScript output. TypeScript support, including type definitions, will be released in a future version.
+FastPix Video Data Core SDK monitors and analyzes **HLS.js** and **DASH.js** video players. Get instant insights into video performance with our monitoring features:
 
-# Key Features:
+- Real-time stream analytics (manifest loading, segments, quality switches)
+- Player performance data (startup time, buffering, quality)
+- Network metrics (bandwidth, request timing)
+- Error logs and diagnostics
+- User interaction events
 
-- **Track Viewer Engagement:** Gain insights into how users interact with your videos.
-- **Monitor Playback Quality:** Ensure video streaming by monitoring real-time metrics, including bitrate, buffering, startup performance, render quality, and playback failure errors.
-- **Error Management:** Identify and resolve playback failures quickly with detailed error reports.
-- **Customizable Tracking:** Flexible configuration to match your specific monitoring needs.
-- **Centralized Dashboard:** Visualize and compare metrics on the [FastPix dashboard](https://dashboard.fastpix.io) to make data-driven decisions.
+The SDK instantly collects and sends all metrics to the [FastPix dashboard](https://dashboard.fastpix.io) for easy viewing. Currently available as a JavaScript bundle, with TypeScript support coming soon.
 
 # Prerequisites:
 
-## Getting started with FastPix:
+## Getting Started
 
-To track and analyze video performance, initialize the FastPix Data SDK with your Workspace key (learn more about [Workspaces here](https://docs.fastpix.io/docs/workspaces)):
+To begin tracking your video analytics, you'll need your FastPix workspace key. Here's how to get it:
 
-1. **[Access the FastPix Dashboard](https://dashboard.fastpix.io)**: Log in and navigate to the Workspaces section.
-2. **Locate Your Workspace Key**: Copy the Workspace Key for client-side monitoring.
+1. Sign up or login to [FastPix Dashboard](https://dashboard.fastpix.io).
+2. Navigate to the workspace page.
+3. Copy your preferred workspace key.
+
+That's it! You're ready to integrate the SDK into your video player.
 
 # Step 1: Installation and Setup:
 
-To get started with the SDK, install using npm or your favourite node package manager 😉:
+Install the SDK using npm or another package manager of your choice:
 
 ```bash
 npm i @fastpix/video-data-core
@@ -35,9 +38,12 @@ import fastpixMetrix from "@fastpix/video-data-core";
 
 # Step 3: Basic Integration
 
-The `workspace_id` is a mandatory field that must be provided. In addition, install the hls.js package, import the Hls instance, and attach it to the HTML5 video element. Pass both the Hls instance and the Hls constructor function, along with custom metadata, to the `fastpixMetrix.tracker` function.
+Before using the FastPix Video Data Core SDK, ensure you have installed either HLS.js or DASH.js player libraries:
+
+The `workspace_id` is a mandatory field that must be provided. Below are the 
+integration steps for both HLS.js and DASH.js players.
 
-Once the player has loaded the URL and playback has started, the SDK will then begin tracking the analytics.
+## HLS.js Integration
 
 ```javascript
 // Import HLS.js library for video streaming
@@ -50,10 +56,10 @@ const initializationTime = fastpixMetrix.utilityMethods.now();
 
 // Create a new HLS instance
 const hlsPlayerInstance = new Hls();
-hlsPlayerInstance.loadSource(""); // Load the video stream
+hlsPlayerInstance.loadSource("YOUR_HLS_URL"); // Load the video stream
 hlsPlayerInstance.attachMedia(videoPlayerElement);
 
-// Custom metadata for tracking
+// Custom dimensions for tracking
 const trackingData = {
   workspace_id: "WORKSPACE_KEY", // Unique key to identify your workspace (replace with your actual workspace key)
   player_name: "Main Video Player", // A custom name or identifier for this video player instance
@@ -62,41 +68,67 @@ const trackingData = {
   video_id: "VIDEO_ID", // Unique identifier for the video
   viewer_id: "VIEWER_ID", // Unique identifier for the viewer
 
-  // Add any additional metadata
+  // Add any additional dimensions
 };
 
 // Pass both `hlsPlayerInstance` and `Hls` to the FastPix tracker for correct tracking
 fastpixMetrix.tracker(videoPlayerElement, {
   debug: false, // Set to true to enable debug logs in the console
   hlsjs: hlsPlayerInstance, // Pass the `hlsPlayerInstance` created above
-  Hls, // Pass the `Hls` constructor (imported)
+  Hls: Hls, // Pass the `Hls` constructor (imported)
   data: trackingData, // Attach custom metadata for analytics and tracking
 });
+```
 
-// To stop monitoring call when destroying the HLS player
-// videoPlayerElement.fp.destroy();
+## DASH.js Integration
+
+```javascript
+// Import DASH.js library for video streaming
+import dashjs from "dashjs";
+import fastpixMetrix from "@fastpix/video-data-core";
+
+// Reference to the video element
+const videoPlayerElement = document.getElementById("video-player");
+const initializationTime = fastpixMetrix.utilityMethods.now();
+
+// Create a new DASH.js instance
+const dashPlayerInstance = dashjs.MediaPlayer().create();
+dashPlayerInstance.initialize(videoPlayerElement, "YOUR_DASH_URL", false);
+
+// Custom metadata for tracking
+const trackingData = {
+  workspace_id: "WORKSPACE_KEY", // Unique key to identify your workspace (replace with your actual workspace key)
+  player_name: "Main Video Player", // A custom name or identifier for this video player instance
+  player_init_time: initializationTime, // Timestamp of when the player was initialized (useful for tracking performance metrics)
+  video_title: "VIDEO_TITLE", // Title of the video being played for analytics
+  video_id: "VIDEO_ID", // Unique identifier for the video
+  viewer_id: "VIEWER_ID", // Unique identifier for the viewer
+
+  // Add any additional metadata
+};
+
+// Pass both `dashPlayerInstance` and `dashjs` to the FastPix tracker for correct tracking
+fastpixMetrix.tracker(videoPlayerElement, {
+  debug: false, // Set to true to enable debug logs in the console
+  dashPlayer: dashPlayerInstance, // Pass the `dashPlayerInstance` created above
+  dashjs: dashjs, // Pass the `dashjs` constructor (imported)
+  data: trackingData, // Attach custom metadata for analytics and tracking
+});
 ```
 
-After successfully completing Step 3, you can track viewer metrics in the FastPix dashboard once playback ends. Steps 4, 5, and 6 are optional and can be utilized as needed to enhance your integration.
+Once the player has loaded the URL and playback has started, the SDK will begin tracking the analytics. After playback ends, you can view the complete analytics report on your [FastPix dashboard](https://dashboard.fastpix.io).
 
 # Step 4: Enhance Tracking with User Passable Metadata
 
-Check out the [user-passable metadata](https://docs.fastpix.io/docs/user-passable-metadata) documentation to see the metadata supported by FastPix. You can use custom metadata fields like `custom_1` to `custom_10` for your business logic, giving you the flexibility to pass any required values. Named attributes, such as `video_title` and `video_id`, can be passed directly as they are.
+Check out the [user-passable metadata](https://docs.fastpix.io/docs/user-passable-metadata-1) documentation to see the metadata supported by FastPix. You can use custom metadata fields like `custom_1` to `custom_10` for your business logic, giving you the flexibility to pass any required values. Named attributes, such as `video_title` and `video_id`, can be passed directly as they are.
 
 ```javascript
-// Import HLS.js library for video streaming
-import Hls from "hls.js";
 import fastpixMetrix from "@fastpix/video-data-core";
 
 // Reference to the video element
 const videoPlayerElement = document.getElementById("video-player");
 const initializationTime = fastpixMetrix.utilityMethods.now();
 
-// Create a new HLS instance
-const hlsPlayerInstance = new Hls();
-hlsPlayerInstance.loadSource(""); // Load the video stream
-hlsPlayerInstance.attachMedia(videoPlayerElement);
-
 // Custom metadata for tracking
 const trackingData = {
   workspace_id: "WORKSPACE_KEY", // Unique key to identify your workspace (replace with your actual workspace key)
@@ -118,18 +150,16 @@ const trackingData = {
 // Pass both `hlsPlayerInstance` and `Hls` to the FastPix tracker for correct tracking
 fastpixMetrix.tracker(videoPlayerElement, {
   debug: false, // Set to true to enable debug logs in the console
-  hlsjs: hlsPlayerInstance, // Pass the `hlsPlayerInstance` created above
-  Hls, // Pass the `Hls` constructor (imported)
   data: trackingData, // Attach custom metadata for analytics and tracking
 });
 
-// To stop monitoring call when destroying the HLS player
+// To stop monitoring
 // videoPlayerElement.fp.destroy();
 ```
 
 ### Note:
 
-Keep metadata consistent across different video loads to make comparison easier in your analytics dashboard.
+Keep metadata consistent across different video loads to make comparison easier in the dashboard.
 
 # Step 5: Advanced Customization with FastPix Data SDK
 
@@ -147,8 +177,6 @@ const videoPlayerElement = document.getElementById("video-player");
 // Configuration for FastPix tracker
 const trackingData = {
   debug: true, // Set to true to enable debug logs in the console
-  hlsjs: hls, // Pass the HLS.js instance
-  Hls: Hls, // Pass the Hls constructor (imported)
   disableCookies: true, // Set to true to disable cookies for tracking sessions and unique viewers
   respectDoNotTrack: true, // Set to true to honor users' 'Do Not Track' preferences
   automaticErrorTracking: false, // Set to false to disable automatic tracking of fatal errors
@@ -182,7 +210,7 @@ videoPlayerElement.fp.dispatch("error", {
 
 ### Changing video streams in player
 
-When your application plays multiple videos back-to-back in the same player, it’s essential to notify the FastPix SDK whenever a new video starts; possibly in scenarios like playlist content/ video series or any other video that user wants to play.
+When your application plays multiple videos back-to-back in the same player, it's essential to notify the FastPix SDK whenever a new video starts; possibly in scenarios like playlist content/ video series or any other video that user wants to play.
 
 ```javascript
 // videoPlayerElement is the HTML5 <video> element representing your video player. 
@@ -199,4 +227,6 @@ videoPlayerElement.fp.dispatch("videoChange", {
 
 # Detailed Usage:
 
-For more detailed steps and advanced usage, please refer to the official [FastPix Documentation](https://docs.fastpix.io/docs/monitor-hlsjs).
+For more detailed steps and advanced usage, please refer to our official documentation:
+- [HLS.js Monitoring Documentation](https://docs.fastpix.io/docs/monitor-hlsjs)
+- [DASH.js Monitoring Documentation](https://docs.fastpix.io/docs/monitor-dashjs)

src/IdGenerationMethod/index.ts

@@ -1,13 +1,15 @@
 import { v4 as uuidv4 } from "uuid";
 
+const idCharacter = "000000";
+
 // Returns 6 characters id
 const generateIdToken: () => string = function () {
   const idPart: string = Math.random()
     .toString(36)
     .replace("0.", "")
     .slice(0, 6);
 
-  return "000000".slice(idPart.length) + idPart;
+  return idCharacter.slice(idPart.length) + idPart;
 };
 
 // Returns unique UUID
@@ -16,8 +18,9 @@ const buildUUID: () => string = function () {
 };
 
 const generateRandomIdentifier: () => string = function () {
+  
   return (
-    "000000" + ((Math.random() * Math.pow(36, 6)) << 0).toString(36)
+    idCharacter + ((Math.random() * Math.pow(36, 6)) << 0).toString(36)
   ).slice(-6);
 };
 

src/MonitorMetrics/PlayerEventHandler.ts

@@ -94,7 +94,6 @@ export class PlaybackEventHandler {
 
   sendData(event: string, obj: EventMetaData): void {
     if (!event || !obj?.view_id) return;
-
     if (this.shouldRespectDoNotTrack(event)) return;
     if (!this.validateEventData(obj)) return;
     if (
@@ -109,6 +108,7 @@ export class PlaybackEventHandler {
       return;
     }
     const data = this.prepareEventData(event, obj);
+    
     this.eventQueue.scheduleEvent(data);
 
     if (event === "viewCompleted") {

src/MonitorMetrics/RequestMetricsMonitor.ts

@@ -51,12 +51,11 @@ export class RequestMetricsMonitor {
     const responseStart: number = reqData?.request_response_start ?? 0;
     const responseEnd: number = reqData?.request_response_end ?? 0;
     const loadedBytes: number = reqData?.request_bytes_loaded ?? 0;
-
-    this.requestCount++;
-
     const latency = responseStart - requestStart;
     const duration = responseEnd - (responseStart ?? requestStart);
 
+    this.requestCount++;
+
     if (duration > 0 && loadedBytes > 0) {
       this.processedChunks++;
       this.totalBytes += loadedBytes;

src/MonitorMetrics/VideoBufferMonitor.ts

@@ -93,6 +93,7 @@ class BufferProcessor {
       this.params.data.view_watch_time &&
       this.params.data.view_watch_time >= 0
     ) {
+      
       if (
         this.params.data.view_rebuffer_count &&
         this.params.data.view_rebuffer_count > 0

src/MonitorMetrics/index.ts

@@ -53,7 +53,6 @@ function nucleusState(
   const defaultConfig = {
     debug: actionableData?.debug ?? false,
     beaconDomain: actionableData.configDomain ?? "metrix.ws",
-    sampleRate: 1,
     disableCookies: actionableData.disableCookies ?? false,
     respectDoNotTrack: actionableData.respectDoNotTrack ?? false,
     allowRebufferTracking: false,
@@ -85,7 +84,6 @@ function nucleusState(
   );
   fileInstance.data = {
     player_instance_id: buildUUID(),
-    fastpix_sample_rate: actionableData.sampleRate,
     beacon_domain:
       actionableData.beaconCollectionDomain ?? actionableData.beaconDomain,
   };

src/StreamMonitoring/DashMonitoring.ts

@@ -247,7 +247,7 @@ export const setupDashMonitoring = (
     const { mediaType, newRepresentation, newQuality } = event;
 
     if (mediaType === "video" && typeof newRepresentation === "object") {
-      (videoContainer as any)?.fp?.dispatch("variantChanged", {
+      videoContainer?.fp?.dispatch("variantChanged", {
         video_source_bitrate: newRepresentation.bandwidth,
         video_source_height: newRepresentation.height,
         video_source_width: newRepresentation.width,
@@ -276,7 +276,7 @@ export const setupDashMonitoring = (
 
       const bitrateData = parseMediaData();
       if (bitrateData) {
-        (videoContainer as any)?.fp?.dispatch("variantChanged", bitrateData);
+        videoContainer?.fp?.dispatch("variantChanged", bitrateData);
       }
     }
   };
@@ -288,7 +288,7 @@ export const setupDashMonitoring = (
     const requesturl = mediaRequest?.url;
     const requestHostName = requesturl ? getHostName(requesturl) : "";
 
-    (videoContainer as any)?.fp?.dispatch("requestCanceled", {
+    videoContainer?.fp?.dispatch("requestCanceled", {
       request_event_type: eventType,
       request_url: requesturl,
       request_type: mediaType,
@@ -307,7 +307,7 @@ export const setupDashMonitoring = (
     const key = data?.response ?? {};
 
     if (error.code === 27) {
-      (videoContainer as any)?.fp.dispatch("requestFailed", {
+      videoContainer?.fp.dispatch("requestFailed", {
         request_error: `${options.type}_${options.action}`,
         request_url: options.url,
         request_hostname: options.url ? getHostName(options.url) : "",
@@ -328,23 +328,23 @@ export const setupDashMonitoring = (
     }
 
     if (errorTracking?.automaticErrorTracking) {
-      (videoContainer as any)?.fp.dispatch("error", {
+      videoContainer?.fp.dispatch("error", {
         player_error_code: error.code,
         player_error_message: error.message,
         player_error_context: errorContext,
       });
     }
   };
 
-  if ((videoContainer as any)?.fp) {
-    (videoContainer as any).fp.destroyDashMonitoring = () => {
+  if (videoContainer?.fp) {
+    videoContainer.fp.destroyDashMonitoring = () => {
       dashTag.off("error", handleErrorEvent);
       dashTag.off("fragmentLoadingAbandoned", handleCanceledRequest);
       dashTag.off("qualityChangeRendered", handleQualityChange);
       dashTag.off("manifestLoaded", handleManifestLoaded);
       dashTag.off("initFragmentLoaded", handleInitFragmentV4);
       dashTag.off("mediaFragmentLoaded", handleMediaFragmentV4);
-      delete (videoContainer as any).fp?.destroyDashMonitoring;
+      delete videoContainer.fp?.destroyDashMonitoring;
     };
   }