Monitor React Native

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.

Prerequisites

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

1. 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.

2. 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.

3. 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:

1
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:

1
import Video from "react-native-video"; 
2
import { fastpixReactNativeVideo } from "@fastpix/react-native-video-data"; 
3
4
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.

1
import React, { useRef } from "react";
2
import {
3
  SafeAreaView,
4
  StyleSheet,
5
  View,
6
  StatusBar,
7
  Platform,
8
  Dimensions,
9
  Text,
10
} from "react-native";
11
import Video from "react-native-video";
12
import { version as videoVersion } from "react-native-video/package.json";
13
import { fastpixReactNativeVideo } from "@fastpix/react-native-video-data";
14
import app from "./package.json";
15
16
const FastPixVideo = fastpixReactNativeVideo(Video);
17
18
// Video Metadata
19
const VIDEO_SOURCE = {
20
  uri: "https://stream.fastpix.com/1f3d3b7b-dfc2-4b29-a9ff-9e71c36acc64.m3u8", // Replace with your source Playback URL
21
  title: "My Video",
22
  id: "your-video-id",
23
  poster: "https://placehold.co/600x400/000000/FFF?text=FastPix+Demo",
24
  category: "Demo",
25
};
26
27
export default function App() {
28
  const videoRef = useRef(null);
29
30
  return (
31
    <SafeAreaView style={styles.safeArea}>
32
      <StatusBar
33
        translucent
34
        backgroundColor="transparent"
35
        barStyle="dark-content"
36
      />
37
38
      <View style={styles.container}>
39
        <Text style={styles.title}>FastPix Video Player</Text>
40
        <Text style={styles.subtitle}>Instrumented with FastPix Analytics</Text>
41
42
        <FastPixVideo
43
          ref={videoRef}
44
          source={{ uri: VIDEO_SOURCE.uri }}
45
          poster={VIDEO_SOURCE.poster}
46
          controls
47
          resizeMode="contain"
48
          style={styles.video}
49
          Platform={Platform}
50
          Dimensions={Dimensions}
51
          shouldTrackViewer={false}
52
          muted={false}
53
          paused={false}
54
          reportBandwidth={true}
55
          showRenditions={true}
56
          posterResizeMode="cover"
57
          fastpixData={{
58
            debug: false,
59
60
            // Application metadata — can be imported directly from your package.json
61
            application_name: app.name, // From package.json: name
62
            application_version: app.version, // From package.json: version
63
            data: {
64
              workspace_id: "WORKSPACE_ID", // REQUIRED: Your FastPix Workspace ID
65
              video_title: "VIDEO_TITLE", // Title of the video
66
              video_id: "VIDEO_ID", // Unique identifier for the video
67
              viewer_id: "VIEWER_ID", // Unique identifier for the viewer
68
              video_series: "VIDEO_SERIES", // (Optional) Series name
69
              video_content_type: VIDEO_SOURCE.category, // (Optional) Content category
70
              video_stream_type: "on-demand", // Type of stream
71
              player_name: "react-native-video",
72
              player_version: videoVersion,
73
              player_software_version: videoVersion, // Redundant but informative
74
75
              // Add additional custom dimensions here if needed
76
            },
77
          }}
78
        />
79
      </View>
80
    </SafeAreaView>
81
  );
82
}
83
84
// Styling
85
const styles = StyleSheet.create({
86
  safeArea: {
87
    flex: 1,
88
    backgroundColor: "#f2f4f7",
89
    paddingTop: Platform.OS === "android" ? StatusBar.currentHeight : 0,
90
  },
91
  container: {
92
    flex: 1,
93
    padding: 16,
94
    justifyContent: "flex-start",
95
  },
96
  title: {
97
    fontSize: 22,
98
    fontWeight: "800",
99
    color: "#1e2a3a",
100
    textAlign: "center",
101
    marginBottom: 6,
102
  },
103
  subtitle: {
104
    fontSize: 14,
105
    color: "#7b8194",
106
    textAlign: "center",
107
    marginBottom: 20,
108
  },
109
  video: {
110
    width: "100%",
111
    aspectRatio: 16 / 9,
112
    borderRadius: 12,
113
    backgroundColor: "#000",
114
    overflow: "hidden",
115
    elevation: 8,
116
    shadowColor: "#000",
117
    shadowOffset: { width: 0, height: 4 },
118
    shadowOpacity: 0.1,
119
    shadowRadius: 6,
120
  },
121
});

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:

1
fastpixData.data.viewer_id = "YOUR_CUSTOM_VIEWER_ID"

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

Example usage:

1
<FastPixVideo
2
  source={{ uri: "https://your-stream-url.m3u8" }}
3
  controls
4
  shouldTrackViewer={false} // Disable SDK-managed viewer ID
5
  fastpixData={{
6
    data: {
7
      workspace_id: "YOUR_WORKSPACE_ID",
8
      viewer_id: "user_12345", // Your own custom viewer ID
9
10
      // Additional Metadata (optional)
11
      video_title: "Sample Video",
12
      video_id: "video_001",
13
      video_stream_type: "on-demand",
14
    },
15
  }}
16
/>

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:

1
<FastPixVideo
2
  source={{ uri: "https://your-stream-url.m3u8" }}
3
  controls
4
  shouldTrackViewer={true} // Enable SDK-managed viewer ID
5
  fastpixData={{
6
    data: {
7
      workspace_id: "YOUR_WORKSPACE_ID",
8
      viewer_id: "user_12345", // Your own custom viewer ID
9
10
      // Additional Metadata (optional)
11
      video_title: "Sample Video",
12
      video_id: "video_001",
13
      video_stream_type: "on-demand",
14
    },
15
  }}
16
/>

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.

1
Platform = { Platform }; 
2
Dimensions = { Dimensions }; 

Example usage:

1
<FastPixVideo
2
  source={{ uri: "https://your-stream-url.m3u8" }}
3
  controls
4
  Platform={Platform} // Mandatory
5
  Dimensions={Dimensions} // Mandatory
6
  fastpixData={{
7
    data: {
8
      workspace_id: "YOUR_WORKSPACE_ID",
9
10
      // Additional Metadata (optional)
11
      video_title: "Sample Video",
12
      video_id: "video_001",
13
      video_stream_type: "on-demand",
14
    },
15
  }}
16
/>

3. Track bitrate changes

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

Example usage:

1
<FastPixVideo
2
  source={{ uri: "https://your-stream-url.m3u8" }}
3
  controls
4
  Platform={Platform} // Mandatory
5
  Dimensions={Dimensions} // Mandatory
6
  reportBandwidth={true} // Track bitrate/variant changes
7
  fastpixData={{
8
    data: {
9
      workspace_id: "YOUR_WORKSPACE_ID",
10
11
      // Additional Metadata (optional)
12
      video_title: "Sample Video",
13
      video_id: "video_001",
14
      video_stream_type: "on-demand",
15
    },
16
  }}
17
/>

Changelog

All notable changes to this project will be documented in this file.

[1.0.3]

⚠️ Important — FastPix is migrating from .io to .com

All FastPix-owned hosts and documentation links are being moved from the .io TLD to .com. The .io hosts continue to serve traffic during the transition, but they are slated to be suspended soon — please update any hard-coded references in your application as part of your next deploy.

What this means for users of @fastpix/react-native-video-data:

• This SDK doesn’t hard-code any FastPix host — playback telemetry is forwarded via @fastpix/video-data-core, which has already been pointed at the .com ingest endpoint. Bump to 1.0.3 (and re-run npm install) to pick up the updated transitive dependency; no code change is required on your side.
• If your app code references FastPix URLs directly — playback URLs (stream.fastpix.io/...), image CDN (images.fastpix.io/...), dashboard deep links, or doc links in your own README — update them to the .com equivalents before the .io hosts are decommissioned.
• We strongly recommend upgrading every FastPix SDK in your stack to its latest release as part of the same change; every official FastPix SDK is being rolled out with the same migration.

Changed

• README and developer guide updated end-to-end from dashboard.fastpix.io / docs.fastpix.io/... to dashboard.fastpix.com / fastpix.com/docs/... so every link in the package points at the post-migration host structure.
• Reference links (Homepage, Dashboard, API Reference, “Detailed Usage”) repointed to fastpix.com.
• Sample playback URL in code examples updated from stream.fastpix.io to stream.fastpix.com.

[1.0.2]

Changed

• Patch release: package.json version aligned to 1.0.2.

[1.0.1]

Changed

• Documentation: README updates.

[1.0.0]

Added

• Initial release of the FastPix React Native Video Data SDK for Android and iOS.
• fastpixReactNativeVideo HOC to wrap react-native-video and forward playback telemetry via @fastpix/video-data-core.
• Playback and quality-oriented events (e.g. play, pause, buffering, errors, time updates, variant / bandwidth where supported).
• Optional SDK-managed viewer and session identifiers using @react-native-async-storage/async-storage when shouldTrackViewer is enabled.
• Support for passing Platform and Dimensions for device metadata and fullscreen-aware layout.