|
| 1 | +# Introduction: |
| 2 | + |
| 3 | +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. |
| 4 | + |
| 5 | +# Key Features: |
| 6 | + |
| 7 | +- **Track Viewer Engagement:** Gain insights into how users interact with your videos. |
| 8 | +- **Monitor Playback Quality:** Ensure video streaming by monitoring real-time metrics, including bitrate, buffering, startup performance, render quality, and playback failure errors. |
| 9 | +- **Error Management:** Identify and resolve playback failures quickly with detailed error reports. |
| 10 | +- **Customizable Tracking:** Flexible configuration to match your specific monitoring needs. |
| 11 | +- **Centralized Dashboard:** Visualize and compare metrics on the [FastPix dashboard](https://dashboard.fastpix.io) to make data-driven decisions. |
| 12 | + |
| 13 | +# Prerequisites: |
| 14 | + |
| 15 | +## Getting started with FastPix: |
| 16 | + |
| 17 | +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)): |
| 18 | + |
| 19 | +1. **[Access the FastPix Dashboard](https://dashboard.fastpix.io)**: Log in and navigate to the Workspaces section. |
| 20 | +2. **Locate Your Workspace Key**: Copy the Workspace Key for client-side monitoring. |
| 21 | + |
| 22 | +# Step 1: Installation and Setup: |
| 23 | + |
| 24 | +To get started with the SDK, install using npm or your favourite node package manager 😉: |
| 25 | + |
| 26 | +```bash |
| 27 | +npm i @fastpix/video-data-core |
| 28 | +``` |
| 29 | + |
| 30 | +# Step 2: Import |
| 31 | + |
| 32 | +```javascript |
| 33 | +import fastpixMetrix from "@fastpix/video-data-core"; |
| 34 | +``` |
| 35 | + |
| 36 | +# Step 3: Basic Integration |
| 37 | + |
| 38 | +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. |
| 39 | + |
| 40 | +Once the player has loaded the URL and playback has started, the SDK will then begin tracking the analytics. |
| 41 | + |
| 42 | +```javascript |
| 43 | +// Import HLS.js library for video streaming |
| 44 | +import Hls from "hls.js"; |
| 45 | +import fastpixMetrix from "@fastpix/video-data-core"; |
| 46 | + |
| 47 | +// Reference to the video element |
| 48 | +const videoPlayerElement = document.getElementById("video-player"); |
| 49 | +const initializationTime = fastpixMetrix.utilityMethods.now(); |
| 50 | + |
| 51 | +// Create a new HLS instance |
| 52 | +const hlsPlayerInstance = new Hls(); |
| 53 | +hlsPlayerInstance.loadSource(""); // Load the video stream |
| 54 | +hlsPlayerInstance.attachMedia(videoPlayerElement); |
| 55 | + |
| 56 | +// Custom metadata for tracking |
| 57 | +const trackingData = { |
| 58 | + workspace_id: "WORKSPACE_KEY", // Unique key to identify your workspace (replace with your actual workspace key) |
| 59 | + player_name: "Main Video Player", // A custom name or identifier for this video player instance |
| 60 | + player_init_time: initializationTime, // Timestamp of when the player was initialized (useful for tracking performance metrics) |
| 61 | + video_title: "VIDEO_TITLE", // Title of the video being played for analytics |
| 62 | + video_id: "VIDEO_ID", // Unique identifier for the video |
| 63 | + viewer_id: "VIEWER_ID", // Unique identifier for the viewer |
| 64 | + |
| 65 | + // Add any additional metadata |
| 66 | +}; |
| 67 | + |
| 68 | +// Pass both `hlsPlayerInstance` and `Hls` to the FastPix tracker for correct tracking |
| 69 | +fastpixMetrix.tracker(videoPlayerElement, { |
| 70 | + debug: false, // Set to true to enable debug logs in the console |
| 71 | + hlsjs: hlsPlayerInstance, // Pass the `hlsPlayerInstance` created above |
| 72 | + Hls, // Pass the `Hls` constructor (imported) |
| 73 | + data: trackingData, // Attach custom metadata for analytics and tracking |
| 74 | +}); |
| 75 | + |
| 76 | +// To stop monitoring call when destroying the HLS player |
| 77 | +// hlsPlayerInstance.fp.destroy(); |
| 78 | +``` |
| 79 | + |
| 80 | +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. |
| 81 | + |
| 82 | +# Step 4: Enhance Tracking with User Passable Metadata |
| 83 | + |
| 84 | +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. |
| 85 | + |
| 86 | +```javascript |
| 87 | +// Import HLS.js library for video streaming |
| 88 | +import Hls from "hls.js"; |
| 89 | +import fastpixMetrix from "@fastpix/video-data-core"; |
| 90 | + |
| 91 | +// Reference to the video element |
| 92 | +const videoPlayerElement = document.getElementById("video-player"); |
| 93 | +const initializationTime = fastpixMetrix.utilityMethods.now(); |
| 94 | + |
| 95 | +// Create a new HLS instance |
| 96 | +const hlsPlayerInstance = new Hls(); |
| 97 | +hlsPlayerInstance.loadSource(""); // Load the video stream |
| 98 | +hlsPlayerInstance.attachMedia(videoPlayerElement); |
| 99 | + |
| 100 | +// Custom metadata for tracking |
| 101 | +const trackingData = { |
| 102 | + workspace_id: "WORKSPACE_KEY", // Unique key to identify your workspace (replace with your actual workspace key) |
| 103 | + player_name: "Main Video Player", // A custom name or identifier for this video player instance |
| 104 | + player_init_time: initializationTime, // Timestamp of when the player was initialized (useful for tracking performance metrics) |
| 105 | + video_title: "Test Content", // Title of the video being played (replace with the actual title of your video) |
| 106 | + video_id: "f01a98s76t90p88i67x", // A unique identifier for the video (replace with your actual video ID for tracking purposes) |
| 107 | + viewer_id: "user12345", // A unique identifier for the viewer (e.g., user ID, session ID, or any other unique value) |
| 108 | + video_content_type: "series", // Type of content being played (e.g., series, movie, etc.) |
| 109 | + video_stream_type: "on-demand", // Type of streaming (e.g., live, on-demand) |
| 110 | + |
| 111 | + // Custom fields for additional business logic |
| 112 | + custom_1: "", // Use this field to pass any additional data needed for your specific business logic |
| 113 | + custom_2: "", // Use this field to pass any additional data needed for your specific business logic |
| 114 | + |
| 115 | + // Add any additional metadata |
| 116 | +}; |
| 117 | + |
| 118 | +// Pass both `hlsPlayerInstance` and `Hls` to the FastPix tracker for correct tracking |
| 119 | +fastpixMetrix.tracker(videoPlayerElement, { |
| 120 | + debug: false, // Set to true to enable debug logs in the console |
| 121 | + hlsjs: hlsPlayerInstance, // Pass the `hlsPlayerInstance` created above |
| 122 | + Hls, // Pass the `Hls` constructor (imported) |
| 123 | + data: trackingData, // Attach custom metadata for analytics and tracking |
| 124 | +}); |
| 125 | + |
| 126 | +// To stop monitoring call when destroying the HLS player |
| 127 | +// hlsPlayerInstance.fp.destroy(); |
| 128 | +``` |
| 129 | + |
| 130 | +### Note: |
| 131 | + |
| 132 | +Keep metadata consistent across different video loads to make comparison easier in your analytics dashboard. |
| 133 | + |
| 134 | +# Step 5: Advanced Customization with FastPix Data SDK |
| 135 | + |
| 136 | +| Attribute | Description | Type | Example Usage | |
| 137 | +| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------- | ------------------------------- | |
| 138 | +| `disableCookies` | FastPix Data SDK uses cookies by default to track playback across page views and to identify unique viewers. If your application is not intended to collect cookies, you can disable this feature by setting `disableCookies: true`. This ensures that no cookies are set during the user's session, enhancing privacy and compliance with user preferences. | Boolean | `disableCookies: true` | |
| 139 | +| `respectDoNotTrack` | Set to true to honor users' privacy preferences regarding the 'Do Not Track' setting. | Boolean | `respectDoNotTrack: true` | |
| 140 | +| `automaticErrorTracking` | FastPix automatically tracks errors that occur during playback failures. To disable this feature, set `automaticErrorTracking` to false. This allows you to have more control over errors which are considered fatal and helps you manage error reporting according to your application's needs. | Boolean | `automaticErrorTracking: false` | |
| 141 | +| `debug` | Set to true to enable debug logs in the console for troubleshooting purposes. | Boolean | `debug: true` | |
| 142 | + |
| 143 | +```javascript |
| 144 | +// Reference to the video element |
| 145 | +const videoPlayerElement = document.getElementById("video-player"); |
| 146 | + |
| 147 | +// Configuration for FastPix tracker |
| 148 | +const trackingData = { |
| 149 | + debug: true, // Set to true to enable debug logs in the console |
| 150 | + hlsjs: hls, // Pass the HLS.js instance |
| 151 | + Hls: Hls, // Pass the Hls constructor (imported) |
| 152 | + disableCookies: true, // Set to true to disable cookies for tracking sessions and unique viewers |
| 153 | + respectDoNotTrack: true, // Set to true to honor users' 'Do Not Track' preferences |
| 154 | + automaticErrorTracking: false, // Set to false to disable automatic tracking of fatal errors |
| 155 | + data: { |
| 156 | + workspace_id: "WORKSPACE_KEY", // Replace with your actual workspace key |
| 157 | + |
| 158 | + // ... add other metadata as needed |
| 159 | + }, |
| 160 | +}; |
| 161 | + |
| 162 | +// Initialize the FastPix tracker with the configuration |
| 163 | +fastpixMetrix.tracker(videoPlayerElement, trackingData); |
| 164 | +``` |
| 165 | + |
| 166 | +# Step 6: Emit Custom Events |
| 167 | + |
| 168 | +### Advanced Error Reporting and Contextual Tracking |
| 169 | + |
| 170 | +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. |
| 171 | + |
| 172 | +```javascript |
| 173 | +// videoPlayerElement is the HTML5 <video> element representing your video player. |
| 174 | +const videoPlayerElement = document.getElementById("video-player"); |
| 175 | + |
| 176 | +videoPlayerElement.fp.dispatch("error", { |
| 177 | + player_error_code: 1024, // Custom error code |
| 178 | + player_error_message: "Description of error", // Generalized error message |
| 179 | + player_error_context: "Additional context for the error", // Instance-specific information |
| 180 | +}); |
| 181 | +``` |
| 182 | + |
| 183 | +### Changing video streams in player |
| 184 | + |
| 185 | +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. |
| 186 | + |
| 187 | +```javascript |
| 188 | +// videoPlayerElement is the HTML5 <video> element representing your video player. |
| 189 | +const videoPlayerElement = document.getElementById("video-player"); |
| 190 | + |
| 191 | +videoPlayerElement.fp.dispatch("videoChange", { |
| 192 | + video_id: "abc345", // Unique identifier for the new video |
| 193 | + video_title: "My Other Great Video", // Title of the new video |
| 194 | + video_series: "Weekly Great Videos", // Series name if applicable |
| 195 | + |
| 196 | + // Additional metadata can be included here |
| 197 | +}); |
| 198 | +``` |
| 199 | + |
| 200 | +# Detailed Usage: |
| 201 | + |
| 202 | +For more detailed steps and advanced usage, please refer to the official [FastPix Documentation](https://docs.fastpix.io/docs/monitor-hlsjs). |
0 commit comments