Monitor React Native (Mobile)

The FastPix Video Data SDK for React Native lets you track and analyze video playback in real time within your mobile application. It automatically captures key performance metrics, helping you improve playback, reduce errors, and create a better viewer experience. All the data is sent directly to the FastPix Dashboard, where you can monitor and analyze it in depth.

Key features:

Gain insights into user interactions with your videos.
Track real-time metrics like bitrate, buffering, startup time, render quality, and playback failures.
Identify and resolve video delivery bottlenecks for smoother playback.
Access detailed error logs to quickly pinpoint and fix playback issues.
Customize tracking with relevant metadata to fit your business needs.
Visualize and compare metrics to make informed, data-driven decisions.

Step 1

Install and setup

Step 2

Import the SDK

Step 3

Pass video component

Step 4

Basic integration

Step 5

Advanced customization

Prerequisites

Before integrating the FastPix React Native Video Data SDK, ensure that your project meets the following requirements:

React native compatibility
Your project must use React version 18.1.0 or 19.x, and React Native version 0.72.0 or higher. These versions are required to ensure proper SDK functionality. Using outdated versions may lead to compatibility issues or degraded performance.
react-native-video Integration
You must have react-native-video installed and properly configured. Since the FastPix SDK builds on top of this library to track video playback analytics, it’s essential for the SDK to function correctly.
Get you workspace key
To track and analyze video performance, initialize the FastPix Data SDK with your Workspace key. This key is essential for client-side monitoring and must be included in your Android application's code wherever you want to track video performance.

Step 1: Install and setup

Start by installing the FastPix React Native Video Data SDK via your preferred package manager:

npm i @fastpix/react-native-video-data

This will add the necessary dependencies to your project.

Step 2: Import the SDK

Once the SDK is installed, import it into your component file:

import { fastpixReactNativeVideo } from "@fastpix/react-native-video-data";

This makes the fastpixReactNativeVideo function available to wrap your video component for tracking.

Step 3: Pass video component

The SDK exposes a wrapper function fastpixReactNativeVideo that takes your existing react-native-video component and returns a new instrumented component.

This Higher-Order Component (HOC) automatically attaches tracking logic - no manual event tracking is needed during playback.

Replace your original <Video> component with the newly instrumented FastPixVideo component:

import Video from "react-native-video"; 
import { fastpixReactNativeVideo } from "@fastpix/react-native-video-data"; 

const FastPixVideo = fastpixReactNativeVideo(Video);

Step 4: Basic integration example

Now that you’ve wrapped your video component using fastpixReactNativeVideo, you can use it just like any other React Native component. Make sure to pass all the necessary metadata and props.

You will need to include the workspace_id, as it is a required field for integrating with FastPix. This unique identifier links your playback data to the correct workspace, ensuring your analytics are accurately captured and displayed in the FastPix system.

FastPix automatically tracks playback behavior - no manual tracking code is needed after integration.

PLEASE NOTE

Both Platform and Dimensions from react-native are required. FastPix uses them to accurately gather device-specific information and calculate playback dimension metrics.

import React, { useRef } from "react";
import {
  SafeAreaView,
  StyleSheet,
  View,
  StatusBar,
  Platform,
  Dimensions,
  Text,
} from "react-native";
import Video from "react-native-video";
import { version as videoVersion } from "react-native-video/package.json";
import { fastpixReactNativeVideo } from "@fastpix/react-native-video-data";
import app from "./package.json";

const FastPixVideo = fastpixReactNativeVideo(Video);

// Video Metadata
const VIDEO_SOURCE = {
  uri: "https://stream.fastpix.io/1f3d3b7b-dfc2-4b29-a9ff-9e71c36acc64.m3u8", // Replace with your source Playback URL
  title: "My Video",
  id: "your-video-id",
  poster: "https://placehold.co/600x400/000000/FFF?text=FastPix+Demo",
  category: "Demo",
};

export default function App() {
  const videoRef = useRef(null);

  return (
    <SafeAreaView style={styles.safeArea}>
      <StatusBar
        translucent
        backgroundColor="transparent"
        barStyle="dark-content"
      />

      <View style={styles.container}>
        <Text style={styles.title}>FastPix Video Player</Text>
        <Text style={styles.subtitle}>Instrumented with FastPix Analytics</Text>

        <FastPixVideo
          ref={videoRef}
          source={{ uri: VIDEO_SOURCE.uri }}
          poster={VIDEO_SOURCE.poster}
          controls
          resizeMode="contain"
          style={styles.video}
          Platform={Platform}
          Dimensions={Dimensions}
          shouldTrackViewer={false}
          muted={false}
          paused={false}
          reportBandwidth={true}
          showRenditions={true}
          posterResizeMode="cover"
          fastpixData={{
            debug: false,

            // Application metadata — can be imported directly from your package.json
            application_name: app.name, // From package.json: name
            application_version: app.version, // From package.json: version
            data: {
              workspace_id: "WORKSPACE_ID", // REQUIRED: Your FastPix Workspace ID
              video_title: "VIDEO_TITLE", // Title of the video
              video_id: "VIDEO_ID", // Unique identifier for the video
              viewer_id: "VIEWER_ID", // Unique identifier for the viewer
              video_series: "VIDEO_SERIES", // (Optional) Series name
              video_content_type: VIDEO_SOURCE.category, // (Optional) Content category
              video_stream_type: "on-demand", // Type of stream
              player_name: "react-native-video",
              player_version: videoVersion,
              player_software_version: videoVersion, // Redundant but informative

              // Add additional custom dimensions here if needed
            },
          }}
        />
      </View>
    </SafeAreaView>
  );
}

// Styling
const styles = StyleSheet.create({
  safeArea: {
    flex: 1,
    backgroundColor: "#f2f4f7",
    paddingTop: Platform.OS === "android" ? StatusBar.currentHeight : 0,
  },
  container: {
    flex: 1,
    padding: 16,
    justifyContent: "flex-start",
  },
  title: {
    fontSize: 22,
    fontWeight: "800",
    color: "#1e2a3a",
    textAlign: "center",
    marginBottom: 6,
  },
  subtitle: {
    fontSize: 14,
    color: "#7b8194",
    textAlign: "center",
    marginBottom: 20,
  },
  video: {
    width: "100%",
    aspectRatio: 16 / 9,
    borderRadius: 12,
    backgroundColor: "#000",
    overflow: "hidden",
    elevation: 8,
    shadowColor: "#000",
    shadowOffset: { width: 0, height: 4 },
    shadowOpacity: 0.1,
    shadowRadius: 6,
  },
});

FastPix will begin collecting and sending data as soon as playback starts - with no additional tracking code required during runtime.

For enhanced tracking, refer to the User-Passable Metadata documentation to explore all supported metadata fields. FastPix supports both named attributes like video_title and video_id, as well as custom fields (custom_1 to custom_10) that let you pass application-specific values. These flexible options allow you to align playback analytics with your unique business logic.

Step 5: Advanced customization

FastPix allows for advanced customization in how you track playback data and metadata. You can fine-tune tracking for viewer identity, device information, and bandwidth performance.

1. Viewer ID tracking

FastPix supports two methods of managing viewer identity:

Option A: Manual viewer ID

If your app already handles user sessions, pass a viewer ID directly:

fastpixData.data.viewer_id = "YOUR_CUSTOM_VIEWER_ID"

To disable automatic tracking, set shouldTrackViewer={false}.

Example usage:

<FastPixVideo
  source={{ uri: "https://your-stream-url.m3u8" }}
  controls
  shouldTrackViewer={false} // Disable SDK-managed viewer ID
  fastpixData={{
    data: {
      workspace_id: "YOUR_WORKSPACE_ID",
      viewer_id: "user_12345", // Your own custom viewer ID

      // Additional Metadata (optional)
      video_title: "Sample Video",
      video_id: "video_001",
      video_stream_type: "on-demand",
    },
  }}
/>

Option B: SDK-managed viewer ID (Auto-generation)

Let FastPix generate a unique viewer ID for you. This is useful if you don’t manage sessions yourself.

Step 1: Install persistent storage

FastPix requires AsyncStorage to store the auto-generated ID

npm install @react-native-async-storage/async-storage

Then enable automatic tracking by setting shouldTrackViewer={true}.

Example usage:

<FastPixVideo
  source={{ uri: "https://your-stream-url.m3u8" }}
  controls
  shouldTrackViewer={true} // Enable SDK-managed viewer ID
  fastpixData={{
    data: {
      workspace_id: "YOUR_WORKSPACE_ID",
      viewer_id: "user_12345", // Your own custom viewer ID

      // Additional Metadata (optional)
      video_title: "Sample Video",
      video_id: "video_001",
      video_stream_type: "on-demand",
    },
  }}
/>

Step 2: Rebuild Your App

Android:

./gradlew clean && ./gradlew build

iOS:

cd ios && pod install && cd ..

2. Pass platform and dimensions for device analytics

To capture accurate device-specific metrics (e.g., screen size, OS, orientation), you must pass Platform and Dimensions from React Native:

Note: These props are mandatory. FastPix uses them to associate playback metrics with real device environments and calculate visual dimensions accurately.

Platform = { Platform }; 
Dimensions = { Dimensions };

Example usage:

<FastPixVideo
  source={{ uri: "https://your-stream-url.m3u8" }}
  controls
  Platform={Platform} // Mandatory
  Dimensions={Dimensions} // Mandatory
  fastpixData={{
    data: {
      workspace_id: "YOUR_WORKSPACE_ID",

      // Additional Metadata (optional)
      video_title: "Sample Video",
      video_id: "video_001",
      video_stream_type: "on-demand",
    },
  }}
/>

3. Track bitrate changes

To track bitrate switching (for adaptive streams like HLS/DASH), enable bandwidth reporting using reportBandwidth={true}.

Example usage:

<FastPixVideo
  source={{ uri: "https://your-stream-url.m3u8" }}
  controls
  Platform={Platform} // Mandatory
  Dimensions={Dimensions} // Mandatory
  reportBandwidth={true} // Track bitrate/variant changes
  fastpixData={{
    data: {
      workspace_id: "YOUR_WORKSPACE_ID",

      // Additional Metadata (optional)
      video_title: "Sample Video",
      video_id: "video_001",
      video_stream_type: "on-demand",
    },
  }}
/>