Monitor HLS.js
The FastPix Data SDK for HLS.js monitors and analyzes key HLS player metrics, providing actionable insights to optimize video streaming performance and deliver a smoother viewing experience.
Key features:
- 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 analytics: Configure tracking attributes to meet your business requirements, providing flexibility and scalability.
- Centralized dashboard: Visualize and compare metrics on the FastPix dashboard to make data-driven decisions.
Installation and setup
Import the SDK
Basic integration
Enhance tracking with metadata
Advanced configurations
Emit custom events
Step 1
Installation and setup
Step 2
Import the SDK
Step 3
Basic integration
Step 4
Enhance tracking with metadata
Step 5
Advanced configurations
Step 6
Emit custom events
Step 1: Installation and setup
This package can be installed using npm, a CDN, or your preferred package manager.
using npm:
Using CDN:
PLEASE NOTE
Ensure that a package based on HLS Player is installed or accessible via a CDN.
Initialize FastPix Data SDK
To start tracking and analyzing video performance using FastPix, you need to initialize the FastPix Data SDK with your unique Workspace key. Follow these steps:
- Log into your FastPix Dashboard and go to the Workspaces section.
- Once you’ve identified the correct workspace, copy the Workspace Key associated with it. This key is essential for client-side monitoring and should be included in the JavaScript code on every webpage where you want to track video performance and analytics.
Understand what is a Workspace.

Step 2: Import the SDK
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.
Once the player has loaded the URL and playback has started, the SDK will then begin tracking the analytics.
PLEASE NOTE
When configuring the SDK, include both the hls instance and the Hls constructor in the options.
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.
Step 4: Enhance tracking with user passable metadata
Check out the 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.
DEVELOPMENT TIP
Keep metadata consistent across different video loads to make comparison easier in your analytics dashboard.
Step 5: Advanced configurations with HLS.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 HLS.js player instance.
Example:
Step 6: Emit custom events
Advanced error reporting and contextual tracking
By default, FastPix tracks errors that occur during playback failures. However, you can also emit a custom error event for non-severe issues that arise outside of these failures, allowing you to provide additional context for tracking purposes.
TIP
Use custom error codes and messages that are meaningful for your debugging process to streamline troubleshooting.
Changing video streams in player
Effective video view tracking is crucial to track multiple videos back-to-back in the same player in your application. You can reset tracking when loading a new source, such as in video series or episodic content or in cases where the user wants to play any other video.
Emitting avideoChange event:
To inform the FastPix SDK of a new view, emit a videoChange event immediately after loading the new video source. Include relevant metadata about the new video:
PLEASE NOTE
Always ensure that this event is dispatched right after the new source is loaded to maintain accurate tracking.
Example to configure HLS with FastPix Data SDK
Here are platform-specific examples to help you integrate the FastPix Data SDK with your HLS player. Use the following React or JavaScript or HTML code into your application:
Changelog
All notable changes to the HLS Player Video Data SDK is documented below.
Current version
v1.0.8
Changed:
- Switched to native
cryptoAPIs for random number and UUID generation, removing the externaluuiddependency 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_nameandplayer_software_versionvia user-passable data.
v1.0.4
- Added
request_urlto capture each video chunk URL in hls and dash players. - Implemented strict checks for
documentandwindowobjects to ensure execution only in browser environments. - Fixed bug where
destroyHlsMonitoringcould throw a runtime error. - Updated UUID generation method to work seamlessly across both web and mobile applications.
v1.0.3
- Updated
package.jsonto 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 Tracksettings, 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
videoChangeto handle metadata updates during playback transitions.