Monitor AVPlayer (iOS)

Learn how the FastPix AVPlayer SDK tracks playback, buffer events, and quality metrics on iOS and tvOS.

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.

Alongside iOS, the FastPix Video Data Core SDK also supports tvOS, allowing you to collect detailed playback analytics from your Apple TV apps when using AVPlayer. You can track viewer engagement, playback quality, errors, and custom events on Apple TV just as you do on iOS.

We’ve tested the SDK on tvOS to ensure a smooth experience, but if you encounter any issues or have questions, feel free to reach out to us.


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.

  1. Access the FastPix Dashboard: Log in and navigate to the Workspaces section.
  2. 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

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


1import FastpixVideoDataAVPlayer
2
3let fpDataSDK = initAvPlayerTracking()
4let customMetadata = [
5 "data": [
6 workspace_id: "WORKSPACE_KEY", // Unique key to identify your workspace (replace with your actual workspace key)
7 video_title: "Test Content", // Title of the video being played (replace with the actual title of your video)
8 video_id: "f01a98s76t90p88i67x", // A unique identifier for the video (replace with your actual video ID for tracking purposes)
9 ]
10]
11
12// Track AVPlayer Layer
13fpDataSDK.trackAvPlayerLayer(
14 playerLayer: playerLayer, // The AVPlayerLayer instance managing the playback
15 customMetadata: customMetadata
16 )
17
18// Track AVPlayer
19 fpDataSDK.trackAvPlayer(
20 player: player, // The AVPlayer instance managing the playback
21 customMetadata: customMetadata
22 )
23
24// Track AVPlayer Controller
25fpDataSDK.trackAvPlayerController(
26 playerController: playerController, // The AVPlayerViewController instance managing the playback
27 customMetadata: customMetadata
28)

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.


1let customMetadata = [
2 "data": [
3 workspace_id: "WORKSPACE_KEY", // Unique key to identify your workspace (replace with your actual workspace key)
4 video_title: "Test Content", // Title of the video being played (replace with the actual title of your video)
5 video_id: "f01a98s76t90p88i67x", // A unique identifier for the video (replace with your actual video ID for tracking purposes)
6 viewer_id: "user12345", // A unique identifier for the viewer (e.g., user ID, session ID, or any other unique value)
7 video_content_type: "series", // Type of content being played (e.g., series, movie, etc.)
8 video_stream_type: "on-demand", // Type of streaming (e.g., live, on-demand)
9 // Custom fields for additional business logic
10 custom_1: "", // Use this field to pass any additional data needed for your specific business logic
11 custom_2: "", // Use this field to pass any additional data needed for your specific business logic
12 // Add any additional metadata
13 ]
14]

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:


1import FastpixVideoDataAVPlayer
2
3let fpDataSDK = initAvPlayerTracking()
4 fpDataSDK.trackAvPlayerLayer(
5 playerLayer: playerView.renderingView.playerLayer,
6 customMetadata: customMetadata
7 )
8 fpDataSDK.dispatchEvent(event: "videoChange", metadata: [
9 video_id: "123def", // Unique identifier for the new video
10 video_title: "My Great Video", // Title of the new video
11 video_series: "Weekly Great Videos", // Series name if applicable
12 // ... and other metadata
13])

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:


1// import the SDK
2import FastpixVideoDataAVPlayer
3// create reference to the sdk
4let fpDataSDK = initAvPlayerTracking()
5
6
7// Function to integrate SDK into your iOS Project
8func getVideoFPData() {
9 let customMetadata: [String: Any] = [
10 "video_title": videoTitle,
11 "video_id": movieID,
12 "workspace_id": “workspace_key”,
13 "video_source_url" : videoUrlStrng,
14 "player_name": "AVPlayer",
15 "video_content_type": Videotype,
16 "player_poster": playerPosterURL,
17 "custom_1": Videotype,
18 "custom_2": videoContentAvailability,
19 "custom_3": videoUrlStrng,
20 "custom_4": movieID,
21 "custom_5": playerPosterURL,
22 "custom_6": skipIntroStart,
23 "custom_7": skipIntroEnd
24 ]
25 let userPassableData = ["configDomain": "beacon_domain", "data": customMetadata] as [String : Any]
26 fpDataSDK.trackAvPlayerLayer(playerLayer: playerView.renderingView.playerLayer, customMetadata: userPassableData)
27 }
28
29// Example to integrate getVideoFPData() where the player is being initialized in your iOS Project
30func initiatePlayer(videourl:String) {
31
32 if let url = URL.init(string:videourl) {
33 subtitlesLanguages.removeAll()
34 let item = VersaPlayerItem(url: url)
35 item.isEncrypted = true
36 controls.handler.decryptionDelegate = self
37 playerView.set(item: item)
38 if resumeTime > 0 {
39 playerView.player.seek(to: CMTime(seconds: Double(resumeTime), preferredTimescale: 1))
40 }
41 if let group = playerView.player?.currentItem?.asset.mediaSelectionGroup(forMediaCharacteristic: .legible) {
42 // Print its options.
43 print(group.options)
44 for option in group.options {
45 subtitlesLanguages.append(option.displayName)
46 print("Option: \(option.displayName)")
47 }
48 if subtitlesLanguages.count > 0 {
49 if subtitlesLanguages.count == 1 && subtitlesLanguages[0] == "CC"{
50 controls.button_subtitles?.isHidden = true
51 }else{
52 controls.button_subtitles?.isHidden = false
53 }
54 }else{
55 controls.button_subtitles?.isHidden = true
56 }
57 }
58 getVideoFPData()
59 displaySubtitles()
60 }
61 }


Changelog

All notable changes to the AVPlayer (iOS) Video Data SDK is documented below.


Current version

[1.0.7]

  • Updated iOS Data Core SDK.
  • Code standardization updates applied across the SDK to align with best practices and strengthen overall stability.

Previous versions

[1.0.6]

  • Updated iOS Data Core SDK by updating the SDK’s default metrics collection domain to improve endpoint reliability and alignment with current infrastructure.

v1.0.5

  • Added support for tvOS, enabling all existing features, including engagement tracking, playback quality monitoring, error reporting, and custom metadata, on Apple TV.
  • Updated iOS Video Data Core.

v1.0.4

  • Added requset_hostname and request_url parameters in the requestFailed event.

v1.0.3

  • Updated iOS Video Data Core.

v1.0.2

  • Updated iOS Video Data Core.

v1.0.0

Added

  • Integration with AVPlayer:
    • Enabled video performance tracking using FastPix Data SDK, supporting user engagement metrics, playback quality monitoring, and real-time streaming diagnostics.
    • Provides robust error management and reporting capabilities for video performance tracking.
    • Includes support for custom metadata, enabling users to pass optional fields such as video_id, video_title, video_duration, and more.
    • Introduced event tracking for videoChange to handle metadata updates during playback transitions.