Integrate FastPix Data SDK with Shaka Player for Advanced Video Analytics

The FastPix Data SDK with Shaka Player helps you track key video metrics like user interactions, playback quality, and performance to enhance the viewing experience. It lets you customize data tracking, monitor streaming quality, and securely send insights for better optimization and error resolution.

Key features:

User engagement metrics: Capture detailed viewer interaction data.
Playback quality monitoring: Real-time performance analysis of your video streams.
Web performance insights: Identify and resolve bottlenecks affecting video delivery.
Customizable tracking: Flexible configuration to match your specific monitoring needs.
Error management: Robust error handling and reporting.
Streaming diagnostics: Gain deep insights into the performance of your video streaming.

Prerequisites

To track and analyze video performance, initialize the FastPix Data SDK with your Workspace key.

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.

Workspace key

Step 1: Installation and setup

To install the Data SDK, you can use npm or your favourite node package manager 😉:

npm install @fastpix/data-shakaplayer

Import:

import loadShakaPlayer from "@fastpix/data-shakaplayer";

Initialization:

Make sure Shaka Player is installed and integrated with your project as part of the FastPix data setup. You can inititate Shaka Player with an HTML5 video element to enable seamless functionality.

Use the following React or JavaScript or HTML code in your application to configure Shaka Player with FastPix.

import React, { useEffect, useRef } from "react";
import loadShakaPlayer from "@fastpix/data-shakaplayer";
import shaka from "shaka-player"; // Import Shaka Player 

const ShakaPlayer = () => {
    const videoElementRef = useRef(null); // Ref to the video element 
    useEffect(() => {

        // Ensure Shaka Player is initialized and FastPix data is configured when the component mounts 
        // Initialize player setup 
        const initTime = loadShakaPlayer.utilityMethods.now(); // Captures the player initialization time 
        const videoElement = videoElementRef.current; // Access video element through ref 
        const player = new shaka.Player(videoElement); // Shaka Player instance bound to the video element 

        // Define player metadata 
        const playerMetadata = {
            workspace_id: "WORKSPACE_KEY", // Replace with your workspace key 
            player_name: "PLAYER_NAME", // A unique identifier for the player instance 
            player_init_time: initTime, // The time the player was initialized 

            // Additional metadata can be added here 
        };

        // Configure FastPix data integration 
        const fastPixShakaIntegration = loadShakaPlayer(
            player,
            {
                debug: false, // Set to true to enable debug logs 
                data: playerMetadata, // Pass metadata object 
            },
            shaka // The Shaka Player instance (mandatory field) 
        );

        // Load the video content 
        const videoUrl = "https://stream.fastpix.io/027a90e4-f5e2-433d-81e5-b99ee864c3f6.m3u8"; // Replace with your video manifest URL 

        player
            .load(videoUrl) // Load the video manifest into the Shaka Player 
            .then(() => {
                // Successfully loaded the manifest. FastPix data will begin tracking. 
            })
            .catch((error) => {
                fastPixShakaIntegration.handleLoadError(error);
            });

        // Cleanup: Destroy the player instance and stop FastPix data tracking when the component unmounts 
        return () => {
            player.fp.destroy(); // Ends FastPix tracking 
            player.destroy(); // Destroys the Shaka Player instance 
        };
    }, []); // Empty dependency array ensures this runs only once when the component mounts 

    return (
        <div>
            <video
                ref={videoElementRef}
                id="my-player"
                width="100%"
                controls
            ></video>
        </div>
    );
};

export default ShakaPlayer;

import loadShakaPlayer from "@fastpix/data-shakaplayer";
import shaka from "shaka-player"; // Import Shaka Player 

// Initialize player setup 
const initTime = loadShakaPlayer.utilityMethods.now(); // Captures the player initialization time 
const videoElement = document.querySelector("#my-player"); // HTML5 video element for Shaka Player 
const player = new shaka.Player(videoElement); // Shaka Player instance bound to the video element 

// Define player metadata 
const playerMetadata = {
    workspace_id: "WORKSPACE_KEY", // Replace with your workspace key 
    player_name: "PLAYER_NAME", // A unique identifier for the player instance 
    player_init_time: initTime, // The time the player was initialized 

    // Additional metadata can be added here 
};

// Configure FastPix data integration 
const fastPixShakaIntegration = loadShakaPlayer(
    player,
    {
        debug: false, // Set to true to enable debug logs 
        data: playerMetadata, // Pass metadata object 
    },
    shaka, // The Shaka Player instance (mandatory field) 
);

// Load the video content 
const videoUrl = "https://stream.fastpix.io/027a90e4-f5e2-433d-81e5-b99ee864c3f6.m3u8"; // Replace with your video manifest URL 

player
    .load(videoUrl) // Load the video manifest into the Shaka Player 
    .then(() => {
        // Successfully loaded the manifest. FastPix data will begin tracking. 
    })
    .catch((error) => {
        fastPixShakaIntegration.handleLoadError(error);
    });

// Ensure to call the following methods to clean up resources when needed: 
// player.destroy() - Destroys the Shaka Player instance and releases associated resources 
// player.fp.destroy() - Ends FastPix tracking and properly terminates the session

<div>
    <video id="my-player" controls></video>
</div>

<script>
    // Wait for the Shaka Player and FastPix Data SDK to be ready 
    document.addEventListener('DOMContentLoaded', function () {

        // Initialize player setup 
        const initTime = loadShakaPlayer.utilityMethods.now(); // Captures the player initialization time 
        const videoElement = document.querySelector("#my-player"); // HTML5 video element for Shaka Player 
        const player = new shaka.Player(videoElement); // Shaka Player instance bound to the video element 

        // Define player metadata 
        const playerMetadata = {
            workspace_id: "WORKSPACE_KEY", // Replace with your workspace key 
            player_name: "PLAYER_NAME", // A unique identifier for the player instance 
            player_init_time: initTime, // The time the player was initialized 
            // Additional metadata can be added here 
        };

        // Configure FastPix data integration 
        const fastPixShakaIntegration = loadShakaPlayer(
            player,
            {
                debug: false, // Set to true to enable debug logs 
                data: playerMetadata, // Pass metadata object 
            },
            shaka // The Shaka Player instance (mandatory field) 
        );

        // Load the video content 
        const videoUrl = "https://stream.fastpix.io/027a90e4-f5e2-433d-81e5-b99ee864c3f6.m3u8"; // Replace with your video manifest URL 

        player
            .load(videoUrl) // Load the video manifest into the Shaka Player 
            .then(() => {
                // Successfully loaded the manifest. FastPix data will begin tracking. 
            })
            .catch((error) => {
                fastPixShakaIntegration.handleLoadError(error);
            });

        // Cleanup: Destroy the player instance and stop FastPix data tracking when the page is reloaded or navigated 
        window.onbeforeunload = function () {
            player.fp.destroy(); // Ends FastPix tracking 
            player.destroy(); // Destroys the Shaka Player instance 
        };
    });
</script>

PLEASE NOTE

To stop FastPix data tracking, always call player.fp.destroy() when calling player.destroy() (Shaka Player instance). This ensures proper cleanup of both Shaka Player and FastPix data tracking.

// player is the instance returned by `new shaka.Player` 
player.fp.destroy(); // Ends FastPix tracking 
player.destroy(); // Destroys the Shaka Player instance

Passing the Shaka global object

When using the loadShakaPlayer function, it's essential to provide the global shaka object as the third argument. If you're employing a module bundler and have imported Shaka using require or import, you must explicitly pass the shaka object.

PLEASE NOTE

Failing to pass the shaka object will cause loadShakaPlayer to look for it on the global window object, which may lead to unexpected behavior in your application.

Step 2: Including custom metadata:

PLEASE NOTE

workspace_id is the only mandatory field. Providing additional metadata can greatly enhance analytics and reporting.

Here’s how to structure your initialization:

// Initialize the Shaka Player with essential configurations 
loadShakaPlayer(
    player,
    {
        debug: false, // Set to true for debugging information in the console 
        data: {
            workspace_id: "WORKSPACE_KEY", // Replace with your workspace key 
            viewer_id: "", // Unique identifier for the viewer 
            experiment_name: "", // Name of the experiment if applicable 
            sub_property_id: "", // Identifier for the sub-property 

            // Player Metadata 
            player_name: "", // Name of the player instance 
            player_version: "", // Version of the player 
            player_init_time: loadShakaPlayer.utilityMethods.now(), // Current time or specify a timestamp 

            // Video Metadata 
            video_id: "", // Unique identifier for the video 
            video_title: "", // Title of the video 
            video_series: "", // Series name if applicable 
            video_duration: 120000, // Duration in milliseconds 
            video_stream_type: "on-demand", // Specify 'live' or 'on-demand' 
            video_cdn: "", // CDN used for streaming 
        },
    },
    shaka,
);

To explore all the additional metadata options supported by the FastPix Data SDK, check out the User-Passable Metadata section.

DEVELOPMENT TIP

Keep metadata consistent across different video loads to make comparison easier in FastPix video data dashboard.

Step 3: Changing video streams in player

Effective video view tracking is crucial to track multiple videos in the same player in your application. You can reset tracking in two key scenarios: when loading a new source, such as in video series or episodic content, and when switching programs within a continuous live stream.

Handling new source loading

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.

Emitting a videoChange 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:

// player is the instance returned by `new shaka.Player` 
player.fp.dispatch("videochange", {
    video_id: "NEW_SOURCE_VIDEO_ID", // Unique identifier for the new video 
    video_title: "NEW_SOURCE_VIDEO_TITLE", // Title of the new video 
    video_series: "NEW_SERIES", // Series name if applicable 

    // Additional metadata can be added here 
});

PLEASE NOTE

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

Managing program changes in live streams

In scenarios where the program changes within a continuous stream (e.g., live broadcasts), tracking each program as its own view can provide more granular analytics.

Emitting a programChange event:

When a program change occurs, emit a programChange event with updated metadata.

// player is the instance returned by `new shaka.Player` 
player.fp.dispatch("programChange", { 
    video_id: "NEW_PROGRAM_VIDEO_ID", // Unique identifier for the new video 
    video_title: "NEW_PROGRAM_VIDEO_TITLE", // Title of the new video 
    video_series: "NEW_SERIES_SERIES", // Series name if applicable 
    
    // Additional metadata can be added here 
    });

PLEASE NOTE

The programChange event should only be emitted when the player is not paused. Emitting this event while paused can lead to inaccurate tracking of video startup time and watch time.

Step 4: Advanced configurations with Shaka Player

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 Shaka Player instance.

1. Disable cookies:

FastPix uses cookies by default to track playback across page views. If your application is not supposed to collect cookies or if you prefer not to use cookies, you can disable this feature by setting disableCookies: true.

// player is the instance returned by `new shaka.Player` 
loadShakaPlayer(
    player,
    {
        debug: false,
        disableCookies: true,
        data: {
            workspace_id: "WORKSPACE_KEY", // Replace with your workspace key 

            // ... and other metadata 
        },
    },
    shaka, // The Shaka Player instance (mandatory field) 
);

2. Bypass "do not track" settings

FastPix does not respect the Do Not Track setting by default. If you want to honor users' privacy preferences, enable this feature by passing respectDoNotTrack: true.

// player is the instance returned by `new shaka.Player` 
loadShakaPlayer(
    player,
    {
        debug: false,
        respectDoNotTrack: true,
        data: {
            workspace_id: "WORKSPACE_KEY", // Replace with your workspace key 

            // ... and other metadata 
        },
    },
    shaka // Shaka Player instance (mandatory field), 
);

3. Configure error tracking preferences

Errors tracked by FastPix are considered fatal. If you encounter non-fatal errors that should not be captured, you can emit a custom error event to provide more context.

// player is the instance returned by `new shaka.Player` 
player.fp.dispatch(
    "error",
    {
        player_error_code: 108, // Custom error code 
        player_error_message: "Description of error", // Generalized error message 
        player_error_context: "Additional context for the error", // Instance-specific information 
    }
);

DEVELOPMENT TIP

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

4. Stop automatic error tracking

For complete control over which errors are counted as fatal, consider disabling automatic error tracking by setting automaticErrorTracking: false.

// player is the instance returned by `new shaka.Player` 
loadShakaPlayer(
    player,
    {
        debug: false,
        automaticErrorTracking: false,
        data: {
            workspace_id: "WORKSPACE_KEY", // Replace with your workspace key 

            // ... and other metadata 
        },
    },
    shaka, // Shaka Player instance (mandatory field) 
);