FastPix Developer Documentation

User Passable Dimensions (metadata) refers to the customizable data fields that users can provide during the initialization of a video playback session. This metadata enhances the tracking and analysis of viewer interactions by allowing the inclusion of specific identifiers and contextual information related to the video content, viewer, and playback environment.

To ensure that users benefit from meaningful data during video playback sessions, it is essential for developers to pass relevant metadata values during SDK integration. Please follow the links to know how to integrate in web, android and iOS.

While our system automatically detects certain metadata in the background, there are situations where specific values may not be captured. In these cases, user input from the front end becomes crucial.

Types of dimensions

1. Required fields

workspace_id is a crucial metadata that ensures the data flows to the intended environment.

In order to get the workspace_key, click here.

Parameter	Unit	Definition
`workspace_id`	Unique ID	A unique identifier for the workspace where video content and associated data are stored. This ID helps in organizing and managing content across different projects or teams within the platform.

PLEASE NOTE
Passing metadata such as video_id, video_title, and viewer_id alongside workspace_id is crucial for providing a comprehensive context to video views. This practice significantly enhances the ability to identify who is watching which content, thereby improving analytics and user engagement.

2. Overridable dimensions

This includes parameters like browser_name, browser_version,  video_cdn, os_name, os_version, device_manufacturer, device_type, device_model, and device_name. Although these can be detected automatically, there are instances where detection may fail. When developers pass this information, it enhances segmentation and allows for more meaningful analysis.

Parameter	Unit	Definition
`video_cdn`	Text	The Content Delivery Network used to deliver the video stream, providing insights into delivery performance and reliability. Understanding CDN performance can help optimize streaming quality and reduce buffering times. <br /> Eg., Cloudflare, Akamai
`browser_name`	Text	The browser used to access the video content; useful for understanding viewer environment.
`browser_version`	Version	The specific version of the browser being used, aiding in compatibility analysis.
`os_name`	Text	The operating system on which the viewer is accessing the content; important for performance insights.
`os_version`	Version	The version of the operating system being used; helps identify compatibility issues.
`device_manufacturer`	Text	The manufacturer of the device used to access the content; useful for segmentation and analysis.
`device_type`	Text	The type of device (e.g., mobile, desktop, tablet) being used; important for understanding user behavior.
`device_model`	Text	The specific model of the device being used; aids in detailed analysis of performance across different devices.
`device_name`	Text	The name of the device being used; useful for identifying trends in device usage among viewers.

3. Optional configurable dimensions

These fields can be included at the developer’s discretion and may encompass various attributes related to the playback environment.

Parameter	Unit	Definition
`viewer_id`	Unique ID	An optional unique identifier for the viewer accessing the content, useful for personalized analytics.
`video_id`	Text	A unique identifier for the specific video being viewed, used to correlate metrics with the video content.
`video_title`	Text	The title of the video content being viewed, providing context for analytics and reporting.
`page_context`	Text	Contextual information about the page where the video is embedded or viewed, helping to understand user behavior more effectively. <br /> Eg., watchpage, iframe
`player_init_time`	Milliseconds since Epoch	The time taken to initialize the video player, measured in milliseconds; crucial for assessing startup performance.
`sub_property_id`	Text	An identifier for any sub-properties associated with this view, useful for tracking specific segments of content.
`video_content_type`	Text	The type of content being viewed (e.g., movie, series, documentary), important for categorizing analytics effectively.
`video_drm_type`	Text	The type of Digital Rights Management applied to the video content, which can influence accessibility and playback options.
`video_duration`	Milliseconds	The total duration of the video content in seconds; valuable for calculating engagement metrics.
`video_encoding_variant`	Text	The specific encoding variant used for delivering the video stream; important for assessing quality and compatibility.
`video_language_code`	Text	The language code representing the language in which the video is presented; aids in localization efforts.
`video_producer`	Text	The name of the producer associated with this video content; useful for branding and attribution analysis.
`video_series`	Text	The series name associated with the video if applicable; helps organize related content for viewers.
`video_stream_type`	Text	The type of stream from which the video is sourced (e.g., live, on-demand); important for understanding delivery methods.
`video_variant_name`	Text	The name of a specific variant of the video being played; useful for tracking different versions or formats.
`video_variant_id`	Text	A unique identifier for a specific variant of the video; essential for detailed analytics on playback options.
`view_session_id`	Unique ID	A unique identifier that links a specific viewing session to upstream services like CDN or origin logs.
`experiment_name`	Text	The name of any experiment linked to this viewing session, aiding in A/B testing and feature validation.
`player_name`	Text	The name of the video player being used, which can assist in identifying compatibility and performance issues.
`player_version`	Version	The version of the video player software being utilized, essential for ensuring compatibility with features and content.

4. Custom dimensions

This feature allows you to define your own dimensions for data segmentation and experimentation purposes. It is an enterprise-level feature that becomes visible only when enabled from the frontend dashboard.

Get more information on how to use Custom dimensions .

Parameter	Unit	Definition
`custom_1`-`custom_10`	Text	Optional fields that allow users to pass additional metadata tailored to filtering and analysis based on specific needs or business logic.

Example: Passing dimensions into Video Data SDK

Below example provides you the insight for configuring user-passable metadata into video data SDK for HLS.js (web). For configuring HLS.js into your application refer this guide.

HLS.js

1 // Define  passable  dimensions for tracking
2 const customDimensions = {
3   workspace_id: "WORKSPACE_KEY", // Unique key to identify your workspace (replace with your actual workspace key)
4   player_name: "Main Video Player", // A custom name or identifier for this video player instance
5   player_init_time: initializationTime, // Timestamp of when the player was initialized (useful for tracking performance metrics)
6   video_title: "Test Content", // Title of the video being played (replace with the actual title of your video)
7   video_id: "f01a98s76t90p88i67x", // A unique identifier for the video (replace with your actual video ID for tracking purposes)
8   viewer_id: "user12345", // A unique identifier for the viewer (e.g., user ID, session ID, or any other unique value)
9   video_content_type: "series", // Type of content being played (e.g., series, movie, etc.)
10   video_stream_type: "on-demand", // Type of streaming (e.g., live, on-demand)
11   
12   // Custom dimension fields for additional business logic
13   custom_1: "", // Use this field to pass any additional data needed for your specific business logic
14   custom_2: "", // Use this field to pass any additional data needed for your specific business logic
15 
16   // Add any additional dimensions here if needed
17 };
18 
19 // Pass both `hlsPlayerInstance` and `Hls` to the FastPix tracker for correct tracking
20 fastpixMetrix.tracker(videoPlayerElement, {
21   debug: false, // Set to true to enable debug logs in the console
22   hlsjs: hlsPlayerInstance, // Pass the `hlsPlayerInstance` created above
23   Hls, // Pass the `Hls` constructor (imported)
24   data: customDimensions, // Attach custom metadata for analytics and tracking
25 });