Monitor DASH.js

Explore how the FastPix SDK powers DASH.js players with detailed playback analytics, bitrate and error tracking, and audience insights.

FastPix Video Data SDK for dash.js helps you track and analyze video playback metrics in real time. It gives you clear insights to improve performance, reduce errors, and deliver a smooth viewing experience.


Key features:

  • Get insights into how users interact with your videos.
  • Track real-time metrics like bitrate, buffering, startup, render quality, and failures.
  • Identify and fix video delivery bottlenecks.
  • Get detailed error logs to quickly identify and fix issues that interrupt playback.
  • Customize tracking to match your specific business needs.
  • View and compare metrics to make data-driven decisions.

Step 1

Install and setup

Step 2

Import the SDK

Step 3

Basic integration

Step 4

Include metadata

Step 5

Advance customization

Step 6

Emit custom events

Detailed example

Configure SDK


PREREQUISITES

Before integrating the SDK, you need a Workspace Key to enable tracking and analytics.
Learn about Workspaces.

  • Log in and navigate to the Workspaces section.
  • Copy the Workspace Key for client-side monitoring. Include this key in your JavaScript integration wherever video tracking is required.


Step 1: Installation and setup

You can install the package using npm, a CDN, or any tool you prefer.

View GitHub repo.

Using npm:

NPM
1npm install "@fastpix-core"

Using CDN:

CDN
1<script src="https://cdn.jsdelivr.net/npm/@fastpix-core@latest"></script>

PLEASE NOTE

Ensure that a package based on DASH Player is installed or accessible via a CDN.



Step 2: Import the SDK

Import
1 import fastpixMetrix from "@fastpix-core"


Step 3: Basic integration

The workspace_id is required and must be included. To get started, install the dash.js package, import the dashjs constructor, and use it to initialize the player and attach it to your HTML5 video element. Then, pass both the dashjs player instance and constructor along with your custom metadata to the fastpixMetrix.tracker function.

Once the player loads the video URL and playback begins, the FastPix SDK will automatically start tracking analytics.


1// Import DASH.js library for video streaming
2
3import dashjs from "dashjs";
4import fastpixMetrix from "@fastpix-core";
5
6// Reference to the video element
7const videoPlayerElement = document.getElementById("video-player");
8const initializationTime = fastpixMetrix.utilityMethods.now();
9
10// Create a new DASH.js instance
11const dashPlayerInstance = dashjs.MediaPlayer().create();
12dashPlayerInstance.initialize(videoPlayerElement, "YOUR_DASH_URL", false);
13
14// Custom dimensions for tracking
15const trackingData = {
16 workspace_id: "WORKSPACE_KEY", // Unique key to identify your workspace (replace with your actual workspace key)
17 player_name: "Main Video Player", // A custom name or identifier for this video player instance
18 player_init_time: initializationTime, // Timestamp of when the player was initialized (useful for tracking performance metrics)
19 video_title: "VIDEO_TITLE", // Title of the video being played for analytics
20 video_id: "VIDEO_ID", // Unique identifier for the video
21 viewer_id: "VIEWER_ID", // Unique identifier for the viewer
22 // Add any additional dimension
23
24};
25
26// Pass both `dashPlayerInstance` and `dashjs` to the FastPix tracker for correct tracking
27fastpixMetrix.tracker(videoPlayerElement, {
28 debug: false, // Set to true to enable debug logs in the console
29 dashPlayer: dashPlayerInstance, // Pass the `dashPlayerInstance` created above
30 dashjs: dashjs, // Pass the `dashjs` constructor (imported)
31 data: trackingData, // Attach custom metadata for analytics and tracking
32});

After completing Step 3, FastPix will automatically start capturing viewer metrics, which will appear in your Video Data dashboard once playback ends.

You can further enhance your integration by following Steps 4, 5, and 6 — these are optional but recommended for advanced tracking and customization.



Step 4: Enhance tracking with metadata

Check out the user-passable metadata documentation to see what metadata FastPix supports. You can use custom fields like custom_1 to custom_10 for your specific needs, or directly pass standard attributes like video_title, video_id, etc.


1// Import DASH.js library for video streaming
2
3import dashjs from "dashjs";
4import fastpixMetrix from "@fastpix-core";
5
6// Reference to the video element
7const videoPlayerElement = document.getElementById("video-player");
8const initializationTime = fastpixMetrix.utilityMethods.now();
9
10// Create a new DASH.js instance
11const dashPlayerInstance = dashjs.MediaPlayer().create();
12dashPlayerInstance.initialize(videoPlayerElement, "YOUR_DASH_URL", false);
13
14// Custom metadata for tracking
15const trackingData = {
16 workspace_id: "WORKSPACE_KEY", // Unique key to identify your workspace (replace with your actual workspace key)
17 player_name: "Main Video Player", // A custom name or identifier for this video player instance
18 player_init_time: initializationTime, // Timestamp of when the player was initialized (useful for tracking performance metrics)
19 video_title: "Test Content", // Title of the video being played (replace with the actual title of your video)
20 video_id: "f01a98s76t90p88i67x", // A unique identifier for the video (replace with your actual video ID for tracking purposes)
21 viewer_id: "user12345", // A unique identifier for the viewer (e.g., user ID, session ID, or any other unique value)
22 video_content_type: "series", // Type of content being played (e.g., series, movie, etc.)
23 video_stream_type: "on-demand", // Type of streaming (e.g., live, on-demand)
24
25 // Custom fields for additional business logic
26 custom_1: "", // Use this field to pass any additional data needed for your specific business logic
27 custom_2: "", // Use this field to pass any additional data needed for your specific business logic
28 // Add any additional metadata here if needed
29
30};
31
32// Pass both `dashPlayerInstance` and `dashjs` to the FastPix tracker for correct tracking
33fastpixMetrix.tracker(videoPlayerElement, {
34 debug: false, // Set to true to enable debug logs in the console
35 dashPlayer: dashPlayerInstance, // Pass the `dashPlayerInstance` created above
36 dashjs: dashjs, // Pass the `dashjs` constructor (imported)
37 data: trackingData, // Attach custom metadata for analytics and tracking
38});

DEVELOPMENT TIP

Keep metadata consistent across different video loads to make comparison easier in your analytics dashboard.



Step 5: Advanced customization with Dash.js

Enhancing your video player with advanced options can significantly improve user experience and data tracking. Below are key configurations you can implement when using the FastPix SDK with your dash.js player instance.


AttributeDescriptionTypeExample Usage
disableCookiesBy default, the FastPix Data SDK uses cookies to track playback across page views and identify unique viewers. Set to true to disable cookies for better privacy.BooleandisableCookies: true
respectDoNotTrackSet this to true to respect users’ privacy preferences and honor the ‘Do Not Track’ setting.BooleanrespectDoNotTrack: true
automaticErrorTrackingFastPix automatically tracks errors during playback. Set to false to manage error reporting manually.BooleanautomaticErrorTracking: false
debugSet to true to activate debug logs in the console for easier troubleshooting.Booleandebug: true

Example:

1// Reference to the video element
2
3const videoPlayerElement = document.getElementById("video-player");
4
5// Configuration for FastPix tracker
6const trackingData = {
7 debug: true, // Set to true to enable debug logs in the console
8 disableCookies: true, // Set to true to disable cookies for tracking sessions and unique viewers
9 respectDoNotTrack: true, // Set to true to honor users' 'Do Not Track' preferences
10 automaticErrorTracking: false, // Set to false to disable automatic tracking of fatal errors
11 data: {
12 workspace_id: "WORKSPACE_KEY", // Replace with your actual workspace key
13
14 // ... add other metadata as needed
15 },
16};
17
18// Initialize the FastPix tracker with the configuration
19fastpixMetrix.tracker(videoPlayerElement, trackingData);


Step 6: Emit custom events

Custom error reporting and contextual tracking

By default, FastPix tracks playback failure errors. However, for non-critical issues that occur outside of these failures, you can trigger custom error events. This allows you to provide additional context, offering deeper insights into the playback experience and improving overall tracking accuracy.


1// videoPlayerElement is the HTML5 <video> element representing your video player.
2
3const videoPlayerElement = document.getElementById("video-player");
4videoPlayerElement.fp.dispatch("error", {
5 player_error_code: 1024, // Custom error code
6 player_error_message: "Description of error", // Generalized error message
7 player_error_context: "Additional context for the error", // Instance-specific information
8});

TIP

Use custom error codes and messages that are meaningful for your debugging process to streamline troubleshooting.


Handling Video Stream Changes

When playing multiple videos consecutively, it’s essential to inform the FastPix SDK each time a new video begins to ensure precise tracking. You should notify the SDK in these situations:

  • The player moves to the next video in a playlist.
  • The user chooses a different video to play.
  • To notify the FastPix SDK of a new video, trigger a videoChange event right after the new video source is loaded.

1// videoPlayerElement is the HTML5 <video> element representing your video player.
2
3const videoPlayerElement = document.getElementById("#my-player");
4videoPlayerElement.fp.dispatch("videoChange", {
5 video_id: "abc345", // Unique identifier for the new video
6 video_title: "My Other Great Video", // Title of the new video
7 video_series: "Weekly Great Videos", // Series name if applicable
8
9 // Additional metadata can be included here
10});

PLEASE NOTE

Always ensure that this event is dispatched right after the new source is loaded to maintain accurate tracking.


Example to configure DASH with FastPix Data SDK

Here are platform-specific examples to help you integrate the FastPix Data SDK with your dash.js player. Use the following React or JavaScript or HTML code into your application:


React
1import React, { useEffect, useRef } from "react";
2import dashjs from "dashjs";
3import fastpixMetrix from "@fastpix-core";
4
5export default function VideoPlayer() {
6 const videoElementRef = useRef(null);
7
8 // Replace with your actual stream URL
9 const videoSourceUrl = "https://example.com/your-dash-stream.mpd"; // Your DASH stream URL
10
11 useEffect(() => {
12 let dashPlayerInstance;
13
14 // Check if the videoElementRef.current is available before proceeding
15 if (videoElementRef.current) {
16 const videoElement = videoElementRef.current;
17 const playerInitTime = fastpixMetrix.utilityMethods.now(); // Get player initialization time
18
19 // Initialize DASH.js player
20 dashPlayerInstance = dashjs.MediaPlayer().create();
21 dashPlayerInstance.initialize(videoElement, videoSourceUrl, false);
22
23 // Custom metadata to be passed for tracking
24 const customData = {
25 workspace_id: "WORKSPACE_KEY", // Replace with your workspace key
26 player_name: "Main Player", // Identifier for the player instance
27 player_init_time: playerInitTime, // Player initialization time
28 video_title: "Sample Video", // Title of the video
29 video_id: "VIDEO_ID", // Unique identifier for the video
30 viewer_id: "VIEWER_ID", // Unique identifier for the viewer
31 video_content_type: "on-demand", // Type of content
32 video_stream_type: "on-demand", // Stream type
33
34 // Add any additional metadata here
35 };
36
37 // Pass both `dashPlayerInstance` and `dashjs` to the FastPix tracker for correct tracking
38 fastpixMetrix.tracker(videoElement, {
39 debug: false,
40 dashPlayer: dashPlayerInstance, // Pass the DASH.js instance
41 dashjs: dashjs, // Pass the DASH.js constructor
42 data: customData,
43 });
44 }
45
46 // Cleanup on component unmount
47 return () => {
48 if (dashPlayerInstance) {
49 dashPlayerInstance.reset(); // Reset the DASH.js player
50 }
51
52 if (videoElementRef.current && videoElementRef.current.fp) {
53 videoElementRef.current.fp.destroy(); // Clean up FastPix tracking
54 }
55 };
56 }, [videoElementRef]);
57
58 return (
59 <video
60 controls
61 ref={videoElementRef}
62 style={{ width: "100%", maxWidth: "800px" }}
63 />
64 );
65}
1import dashjs from "dashjs";
2import fastpixMetrix from "@fastpix-core";
3
4const videoElement = document.getElementById("video-player"); // Video element reference
5const videoSourceUrl = "https://example.com/your-dash-stream.mpd"; // Your DASH stream URL
6
7// Ensure the video element is available
8if (videoElement) {
9 const playerInitTime = fastpixMetrix.utilityMethods.now(); // Get player initialization time
10
11 // Initialize DASH.js player
12 const dashPlayerInstance = dashjs.MediaPlayer().create();
13 dashPlayerInstance.initialize(videoElement, videoSourceUrl, false);
14
15 // Custom metadata to be passed for tracking
16 const customData = {
17 workspace_id: "WORKSPACE_KEY", // Replace with your workspace key
18 player_name: "Main Player", // Identifier for the player instance
19 player_init_time: playerInitTime, // Player initialization time
20 video_title: "Sample Video", // Title of the video
21 video_id: "VIDEO_ID", // Unique identifier for the video
22 viewer_id: "VIEWER_ID", // Unique identifier for the viewer
23 video_content_type: "on-demand", // Type of content
24 video_stream_type: "dash", // Stream type
25
26 // Add any additional metadata here
27 };
28
29 // Pass both `dashPlayerInstance` and `dashjs` to the FastPix tracker for correct tracking
30
31 fastpixMetrix.tracker(videoElement, {
32 debug: false,
33 dashPlayer: dashPlayerInstance, // Pass the DASH.js instance
34 dashjs: dashjs, // Pass the DASH.js constructor
35 data: customData,
36 });
37}
1<!DOCTYPE html>
2<html lang="en">
3
4<head>
5 <meta charset="UTF-8">
6 <meta name="viewport" content="width=device-width, initial-scale=1.0">
7 <script src="https://cdn.jsdelivr.net/npm/@fastpix-core@latest"></script>
8 <script src="https://cdn.jsdelivr.net/npm/dashjs@latest"></script>
9 <title>FastPix DASH.js Analytics</title>
10</head>
11
12<body>
13 <video id="video-player" controls width="660" height="380"></video>
14
15 <script>
16
17 // Get the video element reference
18 const videoElement = document.getElementById('video-player');
19 const videoSourceUrl = "https://example.com/your-dash-stream.mpd"; // Your DASH stream URL
20
21 // Ensure the video element is available and FastPix is loaded
22 if (videoElement && window.fastpixMetrix) {
23 const playerInitTime = window.fastpixMetrix.utilityMethods.now(); // Get player initialization time
24
25 // Initialize DASH.js player
26 const dashPlayerInstance = dashjs.MediaPlayer().create();
27 dashPlayerInstance.initialize(videoElement, videoSourceUrl, false);
28
29 // Custom metadata to be passed for tracking
30 const customData = {
31 workspace_id: "WORKSPACE_KEY", // Replace with your workspace key
32 player_name: "Main Player", // Identifier for the player instance
33 player_init_time: playerInitTime, // Player initialization time
34 video_title: "Sample Video", // Title of the video
35 video_id: "VIDEO_ID", // Unique identifier for the video
36 viewer_id: "VIEWER_ID", // Unique identifier for the viewer
37 video_content_type: "on-demand", // Type of content
38 video_stream_type: "dash" // Stream type
39 };
40
41 // Pass both `dashPlayerInstance` and `dashjs` to the FastPix tracker for correct tracking
42 window.fastpixMetrix.tracker(videoElement, {
43 debug: false,
44 dashPlayer: dashPlayerInstance, // Pass the DASH.js instance
45 dashjs: dashjs, // Pass the DASH.js constructor
46 data: customData,
47 });
48
49 } else {
50 console.error('FastPix SDK not loaded or video element not found');
51 }
52 </script>
53</body>
54</html>



Changelog

All notable changes to the DASH Player Video Data SDK is documented below.


Current version

v1.0.8

Changed:

  • Switched to native crypto APIs for random number and UUID generation, removing the external uuid dependency and reducing bundle size.
  • Updated the default metrics collection endpoint domain.
  • Added local test pages for HLS and DASH player integration.
  • General code sanitization and hygiene improvements across the SDK internals to enhance reliability and long-term maintainability.

Previous versions

v1.0.7

Changed:

  • Updated the SDK’s default metrics collection domain to improve endpoint reliability and alignment with current infrastructure.
  • Explicitly configured custom domains continue to be respected.

v1.0.6

Changed:

  • Updated npm authentication from Classic token to Granular token for improved security and fine-grained permissions.

v1.0.5

  • Added support for accepting user-provided player_software_name and player_software_version via user-passable data.

v1.0.4

  • Added request_url to capture each video chunk URL in hls and dash players.
  • Implemented strict checks for document and window objects to ensure execution only in browser environments.
  • Fixed bug where destroyHlsMonitoring could throw a runtime error.
  • Updated UUID generation method to work seamlessly across both web and mobile applications.

v1.0.3

  • Updated package.json to include additional keywords related to video analytics, HLS, and DASH players.

v1.0.2

  • Added support for DASH.js video player monitoring
  • Enhanced analytics collection for DASH streams
  • Improved error tracking for DASH.js players

v1.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.

v1.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.