FastPix Video Data for AVPlayer - iOS and tvOS video analytics and QoE monitoring SDK (Swift)

The FastPix Video Data SDK for AVPlayer adds real-time video analytics and Quality of Experience (QoE) monitoring to any AVPlayer, AVPlayerLayer, or AVPlayerViewController in your iOS or tvOS app. It automatically collects viewer engagement, playback quality (bitrate, buffering, startup time, render quality), and playback errors, and surfaces them on the FastPix dashboard for monitoring and analysis.

Works with: iOS 13+ · tvOS · Swift 5.9 · Swift Package Manager · AVPlayer / AVPlayerLayer / AVPlayerViewController

📖 Monitor AVPlayer docs: https://fastpix.com/docs/ios-and-cross-platform-players/monitor-avplayer  ·  🚀 Dashboard: https://dashboard.fastpix.com

What you can track

• Viewer engagement - understand how users interact with your videos.
• Playback quality - real-time bitrate, buffering, startup performance, render quality, and playback-failure metrics.
• Error management - detailed error reports to diagnose playback failures quickly.
• Custom metadata - attach your own fields (custom_1 to custom_10, plus named attributes like video_title and video_id) to every view.
• Centralized dashboard - visualize and compare metrics on the FastPix dashboard.
• iOS and tvOS - the same tracking works on Apple TV apps using AVPlayer.

Start here

If you are adding this SDK for the first time, follow these steps in order:

1. Get your Workspace Key
2. Install the SDK with Swift Package Manager
3. Import the SDK
4. Initialize and attach the SDK to your player
5. Pass custom metadata
6. Handle video changes in the same player
7. Verify it works

Before you begin

Make sure you have the following ready:

Requirement	Details
Xcode	With an app project targeting iOS 13.0 or later.
A FastPix account	Free to create at the FastPix Dashboard.
A Workspace Key	Your client-side monitoring key. Get it in step 1.
An AVPlayer to monitor	An existing AVPlayer, AVPlayerLayer, or AVPlayerViewController in your app.

1. Get your Workspace Key

You initialize the SDK with your Workspace Key (learn more about Workspaces):

1. Log in to the FastPix Dashboard and open the Workspaces section.
2. Copy the Workspace Key for client-side monitoring. You pass this key as workspace_id in the metadata (shown below).

2. Install the SDK with Swift Package Manager

This SDK is distributed via Swift Package Manager.

1. In Xcode, go to File → Add Package Dependencies…

2. Enter the repository URL:

   https://github.com/FastPix/iOS-data-avplayer-sdk.git
   

3. Choose the latest stable version and click Add Package.

4. Select the target where you want to use the SDK and click Add Package.

Xcode resolves the package and its dependency (FastpixiOSVideoDataCore) automatically. To confirm resolution from the command line, run this in your project directory:

xcodebuild -resolvePackageDependencies

The output lists the resolved packages, including FastpixVideoDataAVPlayer and FastpixiOSVideoDataCore.

3. Import the SDK

import FastpixVideoDataAVPlayer

4. Initialize and attach the SDK to your player

Create an instance of initAvPlayerTracking, build your metadata (all fields go under a "data" key), and attach it to your player. Hold a strong reference to the SDK instance so tracking lives for the whole playback session.

import FastpixVideoDataAVPlayer

let fpDataSDK = initAvPlayerTracking()

let customMetadata: [String: Any] = [
  "data": [
        "workspace_id": "WORKSPACE_KEY", // Unique key to identify your workspace (replace with your actual workspace key)
        "video_title": "Test Content", // Title of the video being played (replace with the actual title of your video)
        "video_id": "f01a98s76t90p88i67x", // A unique identifier for the video (replace with your actual video ID for tracking purposes)
  ]
]

// Track AVPlayer Layer
fpDataSDK.trackAvPlayerLayer(
    playerLayer: playerLayer,   // The AVPlayerLayer instance managing the playback
    customMetadata: customMetadata
)

// Track AVPlayer
fpDataSDK.trackAvPlayer(
    player: player,   // The AVPlayer instance managing the playback
    playerLayer: playerLayer,   // The AVPlayerLayer for the player, or nil if you don't have one
    customMetadata: customMetadata
)

// Track AVPlayer Controller
fpDataSDK.trackAvPlayerController(
    playerController: playerController,   // The AVPlayerViewController instance managing the playback
    customMetadata: customMetadata
)

Use whichever track… method matches how you present video: trackAvPlayerLayer for a raw AVPlayerLayer, trackAvPlayer for an AVPlayer, or trackAvPlayerController for an AVPlayerViewController. You do not need to call all three.

5. Pass custom metadata

See the user-passable metadata documentation for every field FastPix supports. Named attributes such as video_title and video_id are passed directly, and you can use custom_1 to custom_10 for your own business logic. All fields go under the "data" key:

let customMetadata: [String: Any] = [
    "data": [
        "workspace_id": "WORKSPACE_KEY", // Unique key to identify your workspace (replace with your actual workspace key)
        "video_title": "Test Content", // Title of the video being played (replace with the actual title of your video)
        "video_id": "f01a98s76t90p88i67x", // A unique identifier for the video (replace with your actual video ID for tracking purposes)
        "viewer_id": "user12345", // A unique identifier for the viewer (e.g., user ID, session ID, or any other unique value)
        "video_content_type": "series", // Type of content being played (e.g., series, movie, etc.)
        "video_stream_type": "on-demand", // Type of streaming (e.g., live, on-demand)

        // Custom fields for additional business logic
        "custom_1": "", // Use this field to pass any additional data needed for your specific business logic
        "custom_2": "", // Use this field to pass any additional data needed for your specific business logic

        // Add any additional metadata
    ]
]

Tip: Keep metadata consistent across video loads so comparisons are easy in your analytics dashboard.

6. Handle video changes in the same player

When your app plays multiple videos back-to-back in the same player (playlists, a video series, or "up next"), notify the SDK when a new video starts so it begins a fresh view. The dispatchEvent metadata is a flat dictionary (no "data" wrapper):

import FastpixVideoDataAVPlayer

let fpDataSDK = initAvPlayerTracking()

fpDataSDK.trackAvPlayerLayer(
    playerLayer: playerView.renderingView.playerLayer,
    customMetadata: customMetadata
)

fpDataSDK.dispatchEvent(event: "videoChange", metadata: [
    "video_id": "123def", // Unique identifier for the new video
    "video_title": "Daalcheeni", // Title of the new video
    "video_series": "Comedy Capsule", // Series name if applicable

    // ... and other metadata
])

7. Verify it works

1. Build and run your app, then play a video through the AVPlayer you attached the SDK to.
2. Log in to the FastPix Dashboard and open the Video Data section.
3. Within a few minutes of playback, your view appears with its metrics (startup time, bitrate, buffering) and any custom metadata you passed, such as video_title and video_id.

If no data appears, confirm that workspace_id is set to your real Workspace Key, that you kept a strong reference to the initAvPlayerTracking() instance for the whole playback session, and that the device has network access.

tvOS support

The SDK also works on tvOS, so you can collect the same playback analytics from your Apple TV apps using AVPlayer: viewer engagement, playback quality, errors, and custom events, just as on iOS. If you run into any issues on tvOS, reach out to FastPix support.

Which FastPix repo do I need?

This SDK collects analytics from AVPlayer. For playback, uploads, and other platforms:

I want to...	Repo
Play FastPix video in an iOS app	iOS-player
Use the shared iOS data core this SDK builds on	iOS-core-data-sdk
Collect playback analytics on Roku	Roku-data-core-SDK
Play FastPix video on the web	web-player-component
Add resumable uploads to an iOS app	iOS-Uploads

Browse everything in the FastPix organization.

FAQ

What does this SDK do? It collects real-time video analytics and QoE metrics (engagement, bitrate, buffering, startup time, errors) from AVPlayer and reports them to the FastPix dashboard. See What you can track.

Which package URL do I add in Xcode? https://github.com/FastPix/iOS-data-avplayer-sdk.git. See Install the SDK.

What is the module name to import? import FastpixVideoDataAVPlayer (note the lowercase "p" in "Fastpix").

Where do I get my Workspace Key? From the Workspaces section of the FastPix Dashboard. See Get your Workspace Key.

Why must metadata keys be quoted, and what is the "data" wrapper? customMetadata is a [String: Any] dictionary, so keys are string literals like "workspace_id". For the track… methods, all fields are nested under a top-level "data" key; for dispatchEvent, the metadata is a flat dictionary. This matches the SDK's own example app.

Which platforms and versions are supported? iOS 13.0+ and tvOS, Swift 5.9. See Before you begin.

Does it support tvOS? Yes - see tvOS support.

Documentation

• Monitor AVPlayer (iOS and tvOS): fastpix.com/docs/ios-and-cross-platform-players/monitor-avplayer
• Pass custom metadata to metrics: fastpix.com/docs/working-with-video-data/pass-custom-metadata-to-metrics
• Set up a workspace: fastpix.com/docs/getting-started/set-up-a-workspace
• Runnable example app: example/

License

This SDK is released under the Apache License 2.0 - see the LICENSE file for details.