Guides
Login
Start typing to search…

Monitor DASH.js (Web)

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 install "@fastpix/video-data-core"

Using CDN:

<script src="https://cdn.jsdelivr.net/npm/@fastpix/video-data-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 fastpixMetrix from "@fastpix/video-data-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.


// 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 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
  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 dimension

};

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


// 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: "Test Content", // Title of the video being played (replace with the actual title of your video)
  video_id: "f01a98s76t90p88i67x", // A unique identifier for the video (replace with your actual video ID for tracking purposes)
  viewer_id: "user12345", // A unique identifier for the viewer (e.g., user ID, session ID, or any other unique value)
  video_content_type: "series", // Type of content being played (e.g., series, movie, etc.)
  video_stream_type: "on-demand", // Type of streaming (e.g., live, on-demand)

  // Custom fields for additional business logic
  custom_1: "", // Use this field to pass any additional data needed for your specific business logic
  custom_2: "", // Use this field to pass any additional data needed for your specific business logic
  // Add any additional metadata here if needed

};

// 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
});

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:

// Reference to the video element

const videoPlayerElement = document.getElementById("video-player");

// Configuration for FastPix tracker
const trackingData = {
  debug: true, // Set to true to enable debug logs in the console
  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
  data: {
    workspace_id: "WORKSPACE_KEY", // Replace with your actual workspace key

    // ... add other metadata as needed
  },
};

// Initialize the FastPix tracker with the configuration
fastpixMetrix.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.


// videoPlayerElement is the HTML5 <video> element representing your video player.

const videoPlayerElement = document.getElementById("video-player");
videoPlayerElement.fp.dispatch("error", {
  player_error_code: 1024, // Custom error code
  player_error_message: "Description of error", // Generalized error message
  player_error_context: "Additional context for the error", // Instance-specific information
});

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.

// videoPlayerElement is the HTML5 <video> element representing your video player.

const videoPlayerElement = document.getElementById("#my-player");
videoPlayerElement.fp.dispatch("videoChange", {
  video_id: "abc345", // Unique identifier for the new video
  video_title: "My Other Great Video", // Title of the new video
  video_series: "Weekly Great Videos", // Series name if applicable

  // Additional metadata can be included here
});

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:


import React, { useEffect, useRef } from "react";
import dashjs from "dashjs";
import fastpixMetrix from "@fastpix/video-data-core";

export default function VideoPlayer() {
  const videoElementRef = useRef(null);

  // Replace with your actual stream URL
  const videoSourceUrl = "https://example.com/your-dash-stream.mpd"; // Your DASH stream URL

  useEffect(() => {
    let dashPlayerInstance;

    // Check if the videoElementRef.current is available before proceeding
    if (videoElementRef.current) {
      const videoElement = videoElementRef.current;
      const playerInitTime = fastpixMetrix.utilityMethods.now(); // Get player initialization time

      // Initialize DASH.js player
      dashPlayerInstance = dashjs.MediaPlayer().create();
      dashPlayerInstance.initialize(videoElement, videoSourceUrl, false);

      // Custom metadata to be passed for tracking
      const customData = {
        workspace_id: "WORKSPACE_KEY", // Replace with your workspace key
        player_name: "Main Player", // Identifier for the player instance
        player_init_time: playerInitTime, // Player initialization time
        video_title: "Sample Video", // Title of the video
        video_id: "VIDEO_ID", // Unique identifier for the video
        viewer_id: "VIEWER_ID", // Unique identifier for the viewer
        video_content_type: "on-demand", // Type of content
        video_stream_type: "on-demand", // Stream type

        // Add any additional metadata here
      };

      // Pass both `dashPlayerInstance` and `dashjs` to the FastPix tracker for correct tracking
      fastpixMetrix.tracker(videoElement, {
        debug: false,
        dashPlayer: dashPlayerInstance, // Pass the DASH.js instance
        dashjs: dashjs, // Pass the DASH.js constructor
        data: customData,
      });
    }

    // Cleanup on component unmount
    return () => {
      if (dashPlayerInstance) {
        dashPlayerInstance.reset(); // Reset the DASH.js player
      }

      if (videoElementRef.current && videoElementRef.current.fp) {
        videoElementRef.current.fp.destroy(); // Clean up FastPix tracking
      }
    };
  }, [videoElementRef]);

  return (
    <video
      controls
      ref={videoElementRef}
      style={{ width: "100%", maxWidth: "800px" }}
    />
  );
}
import dashjs from "dashjs";
import fastpixMetrix from "@fastpix/video-data-core";

const videoElement = document.getElementById("video-player"); // Video element reference
const videoSourceUrl = "https://example.com/your-dash-stream.mpd"; // Your DASH stream URL

// Ensure the video element is available
if (videoElement) {
  const playerInitTime = fastpixMetrix.utilityMethods.now(); // Get player initialization time

  // Initialize DASH.js player
  const dashPlayerInstance = dashjs.MediaPlayer().create();
  dashPlayerInstance.initialize(videoElement, videoSourceUrl, false);

  // Custom metadata to be passed for tracking
  const customData = {
    workspace_id: "WORKSPACE_KEY", // Replace with your workspace key
    player_name: "Main Player", // Identifier for the player instance
    player_init_time: playerInitTime, // Player initialization time
    video_title: "Sample Video", // Title of the video
    video_id: "VIDEO_ID", // Unique identifier for the video
    viewer_id: "VIEWER_ID", // Unique identifier for the viewer
    video_content_type: "on-demand", // Type of content
    video_stream_type: "dash", // Stream type

    // Add any additional metadata here
  };

  // Pass both `dashPlayerInstance` and `dashjs` to the FastPix tracker for correct tracking

  fastpixMetrix.tracker(videoElement, {
    debug: false,
    dashPlayer: dashPlayerInstance, // Pass the DASH.js instance
    dashjs: dashjs, // Pass the DASH.js constructor
    data: customData,
  });
}
<!DOCTYPE html>
<html lang="en">

<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <script src="https://cdn.jsdelivr.net/npm/@fastpix/video-data-core@latest"></script>
    <script src="https://cdn.jsdelivr.net/npm/dashjs@latest"></script>
    <title>FastPix DASH.js Analytics</title>
</head>

<body>
    <video id="video-player" controls width="660" height="380"></video>

    <script>

        // Get the video element reference 
        const videoElement = document.getElementById('video-player');
        const videoSourceUrl = "https://example.com/your-dash-stream.mpd"; // Your DASH stream URL 

        // Ensure the video element is available and FastPix is loaded 
        if (videoElement && window.fastpixMetrix) {
            const playerInitTime = window.fastpixMetrix.utilityMethods.now(); // Get player initialization time 

            // Initialize DASH.js player 
            const dashPlayerInstance = dashjs.MediaPlayer().create();
            dashPlayerInstance.initialize(videoElement, videoSourceUrl, false);

            // Custom metadata to be passed for tracking 
            const customData = {
                workspace_id: "WORKSPACE_KEY", // Replace with your workspace key 
                player_name: "Main Player", // Identifier for the player instance 
                player_init_time: playerInitTime, // Player initialization time 
                video_title: "Sample Video", // Title of the video 
                video_id: "VIDEO_ID", // Unique identifier for the video 
                viewer_id: "VIEWER_ID", // Unique identifier for the viewer 
                video_content_type: "on-demand", // Type of content 
                video_stream_type: "dash" // Stream type 
            };

            // Pass both `dashPlayerInstance` and `dashjs` to the FastPix tracker for correct tracking 
            window.fastpixMetrix.tracker(videoElement, {
                debug: false,
                dashPlayer: dashPlayerInstance, // Pass the DASH.js instance 
                dashjs: dashjs, // Pass the DASH.js constructor 
                data: customData,
            });

        } else {
            console.error('FastPix SDK not loaded or video element not found');
        }
    </script>
</body>
</html>

Updated 2 days ago