Monitor AVPlayer (iOS)

FastPix Video Data SDK with AVPlayer enables tracking of key video performance metrics, making the data readily available on the FastPix dashboard for monitoring and analysis. While the SDK is developed in Swift, the published SPM package currently includes only the Swift output.

Key features:

See how users interact with your videos.
Track real-time metrics like bitrate, buffering, startup, render quality, and failures.
Identify and fix video delivery bottlenecks on iOS.
Get detailed error reports to quickly identify and fix playback issues.
Customize tracking to match your specific business needs.
Handle errors with robust reporting and diagnostics.
View and compare metrics to make data-driven decisions.

Step 1

Install and setup

Step 2

Import the SDK

Step 3

Basic integration

Step 4

Include metadata

Step 5

Emit custom events

Detailed example

Configure AVPlayer

Prerequisites

To track and analyze video performance, initialize the SDK with your Workspace key. Learn about Workspaces.

Access the FastPix Dashboard: Log in and navigate to the Workspaces section.
Locate Your Workspace Key: Copy the Workspace Key for client-side monitoring. Include this key in your Swift code on every page where you want to track video performance.

Step 1: Install and setup

You can integrate the SDK into your project using Swift Package Manager (SPM). Follow these steps to add the package to your iOS project.

Open your Xcode project and navigate to:

File → Add Packages
Enter the repository URL for the FastPix SDK: https://github.com/FastPix/iOS-data-avplayer-sdk
Choose the latest stable version and click Add Package.
Select the target where you want to use the SDK and click Add Package.

Step 2: Import the SDK

import FastpixVideoDataAVPlayer

Step 3: Basic integration

Ensure that the workspace_id is provided, as it is a mandatory field for FastPix integration, uniquely identifying your workspace. Install and import AVFoundation into your project, and create an avplayer instance to bind it to. If you are using any other custom player then create an instance of that player.

Next, create an instance of initAvPlayerTracking for tracking the analytics. Once the video URL is loaded and playback has started, the SDK will begin tracking the analytics.

import FastpixVideoDataAVPlayer

let fpDataSDK = initAvPlayerTracking()
let customMetadata = [
  "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
  customMetadata: customMetadata
 )

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

Step 4: Include metadata for tracking

Check out the 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.

let customMetadata = [
  "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
  ]
]

DEVELOPMENT TIP

Keep metadata consistent across different video loads to make comparison easier in your analytics dashboard.

Step 5: Emit custom events

Changing video streams in player

When playing multiple videos back-to-back, it's essential to notify the FastPix SDK whenever a new video starts to ensure accurate tracking. You should signal a new source in the following scenarios:

The player advances to the next video in a playlist.
The user selects a different video to play.

To inform the FastPix SDK of a new view, emit a videoChange event immediately after loading the new video source:

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: "My Great Video", // Title of the new video
  video_series: "Weekly Great Videos", // Series name if applicable
  // ... and other metadata
])

PLEASE NOTE

Always ensure that this event is dispatched right after the new source is loaded to maintain accurate tracking.

Detailed example to configure AVPlayer

Here’s an example to help you integrate the FastPix Data SDK with AVPlayer.
You can use this code in your application:

// import the SDK
import FastpixVideoDataAVPlayer   
// create reference to the sdk 
let fpDataSDK = initAvPlayerTracking()


//  Function to integrate SDK into your iOS Project
func getVideoFPData() {
  let customMetadata: [String: Any] = [
    "video_title": videoTitle,
    "video_id": movieID,
    "workspace_id": “workspace_key”,
    "video_source_url" : videoUrlStrng,
    "player_name": "AVPlayer",
    "video_content_type": Videotype,
    "player_poster": playerPosterURL,
    "custom_1": Videotype,  
    "custom_2": videoContentAvailability,
    "custom_3": videoUrlStrng,
    "custom_4": movieID,
    "custom_5": playerPosterURL,
    "custom_6": skipIntroStart,
    "custom_7": skipIntroEnd
  ]
  let userPassableData = ["configDomain": "beacon_domain", "data": customMetadata] as [String : Any]
        fpDataSDK.trackAvPlayerLayer(playerLayer: playerView.renderingView.playerLayer, customMetadata: userPassableData)
    }

//  Example to integrate getVideoFPData()  where the player is being initialized in your iOS Project
func initiatePlayer(videourl:String) {
       
        if let url = URL.init(string:videourl) {
            subtitlesLanguages.removeAll()
            let item = VersaPlayerItem(url: url)
            item.isEncrypted = true
            controls.handler.decryptionDelegate = self
            playerView.set(item: item)
            if resumeTime > 0 {
                playerView.player.seek(to: CMTime(seconds: Double(resumeTime), preferredTimescale: 1))
            }
            if let group = playerView.player?.currentItem?.asset.mediaSelectionGroup(forMediaCharacteristic: .legible) {
                // Print its options.
                print(group.options)
                for option in group.options {
                    subtitlesLanguages.append(option.displayName)
                    print("Option: \(option.displayName)")
                }
                if subtitlesLanguages.count > 0 {
                    if subtitlesLanguages.count == 1 && subtitlesLanguages[0] == "CC"{
                        controls.button_subtitles?.isHidden = true
                    }else{
                        controls.button_subtitles?.isHidden = false
                    }
                }else{
                    controls.button_subtitles?.isHidden = true
                }
            }
            getVideoFPData()
            displaySubtitles()
           }
    }