From d47cf00863e3dbfc049af68d4354f5e1465e8bf9 Mon Sep 17 00:00:00 2001 From: ashutoshkhainar33-star Date: Fri, 4 Sep 2026 17:07:30 +0530 Subject: [PATCH 1/2] Revise README for FastPix Video Data Core SDK Updated README to enhance clarity and organization of SDK documentation. --- README.md | 137 ++++++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 128 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index f649e43..631f0bc 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,18 @@ +# FastPix Video Data Core SDK for iOS - player analytics core (Swift) -# Introduction: +[![SwiftPM compatible](https://img.shields.io/badge/SwiftPM-compatible-brightgreen?logo=swift)](https://swift.org/package-manager/) +[![Swift](https://img.shields.io/badge/Swift-5.9-F05138?logo=swift&logoColor=white)](https://swift.org) +[![Platform: iOS | tvOS](https://img.shields.io/badge/platform-iOS%20%7C%20tvOS-000000?logo=apple&logoColor=white)](https://developer.apple.com/ios/) +[![Latest release](https://img.shields.io/github/v/release/FastPix/iOS-core-data-sdk?sort=semver)](https://github.com/FastPix/iOS-core-data-sdk/releases) +[![license](https://img.shields.io/github/license/FastPix/iOS-core-data-sdk)](https://github.com/FastPix/iOS-core-data-sdk/blob/main/LICENSE) **FastPix Video Data Core SDK** for iOS is the official Swift-based SDK designed for integration with iOS supported video players. It serves as a foundation for collecting and processing player analytics when used with FastPix supported iOS Player Analytics SDKs. This SDK facilitates the gathering of video performance metrics, which can be accessed on the FastPix dashboard for monitoring and analysis. While the SDK is developed in Swift, the currently published SPM package includes only Swift support. -# Key Features: +**Works with:** iOS · tvOS · Swift 5.9 · Swift Package Manager · player-agnostic (any AVPlayer-based player) + +📖 **Docs:** https://fastpix.com/docs/ios-and-cross-platform-players/monitor-avplayer  ·  🚀 **Dashboard:** https://dashboard.fastpix.com + +## Key Features - **Track Viewer Engagement:** Gain insights into how users interact with your videos. - **Monitor Playback Quality:** Ensure video streaming by monitoring real-time metrics, including bitrate, buffering, startup performance, render quality, and playback failure errors. @@ -12,7 +21,36 @@ - **Centralized Dashboard:** Visualize and compare metrics on the [FastPix dashboard](https://dashboard.fastpix.com) to make data-driven decisions. - **Compatible with tvOS:** Monitor and track video playback and analytics specifically on Apple TV, just like on iOS. -# Step 1: Installation and Setup: +## Start here + +If you are using the FastPix Video Data Core SDK for the first time, follow these steps in order: + +1. [Install the SDK](#install-the-sdk) +2. [Get your Workspace Key](#get-your-workspace-key) +3. [Import the SDK](#import-the-sdk) +4. [Configure the SDK](#configure-the-sdk) +5. [Dispatch events](#dispatch-events) +6. [See a complete example](#complete-example) +7. [Verify your integration](#verify-your-integration) +8. [Understand the data flow](#understand-the-data-flow) + +Do not skip the verification steps. If an install, workspace-key, or configuration problem occurs, fix it before continuing. + +--- + +### Before you begin + +To use the SDK, make sure you have: + +- **Xcode** and an iOS (or tvOS) app with a video player (typically `AVPlayer`). +- A **FastPix account** and a **Workspace Key** (see [Get your Workspace Key](#get-your-workspace-key)). +- A way to read your player's **playhead time** (in milliseconds) and **video state** - the SDK reads these through two closures you provide. + +> **Using AVPlayer?** This is the low-level core SDK. If you play with `AVPlayer`, the ready-made [iOS-data-avplayer-sdk](https://github.com/FastPix/iOS-data-avplayer-sdk) wraps this core and wires AVPlayer for you - most apps should start there. + +--- + +## Install the SDK To get started with this SDK, you can integrate it into your project using **Swift Package Manager (SPM)**. Follow these steps to add the package to your iOS project. @@ -30,11 +68,16 @@ To get started with this SDK, you can integrate it into your project using **Swi 4. **Select the target** where you want to use the SDK and click `Add Package`. -# Step 2: Basic Integration +## Get your Workspace Key + +The SDK tags analytics with your **Workspace Key**, which you pass as `workspace_id` in the metadata. + +1. Log in to the [FastPix Dashboard](https://dashboard.fastpix.com) and open the **Workspaces** section. +2. Copy your **Workspace Key** and use it as the `workspace_id` value in `passableMetadata` (see [Configure the SDK](#configure-the-sdk)). -To integrate the SDK into your project, follow these steps: +Learn more in [Set up a workspace](https://fastpix.com/docs/getting-started/set-up-a-workspace). -## Import the SDK: +## Import the SDK First, import the SDK into your Swift project: @@ -42,7 +85,7 @@ First, import the SDK into your Swift project: import FastpixiOSVideoDataCore ``` -## Initialize and Configure the SDK: +## Configure the SDK Create an instance of `FastpixMetrix` and `configure` it. The SDK is **player-agnostic** — it does not observe a player itself. You supply: @@ -81,7 +124,7 @@ fpMetrix.configure( } ) ``` -## Dispatch Events: +## Dispatch events As the player's state changes, call `dispatch` to report events to FastPix. It takes: @@ -92,7 +135,7 @@ As the player's state changes, call `dispatch` to report events to FastPix. It t ```swift fpMetrix.dispatch(key: "player1", event: "EVENT_NAME", metadata: eventMetadata) ``` -## Example Usage: +## Complete example ```swift import FastpixiOSVideoDataCore @@ -142,3 +185,79 @@ fpMetrix.dispatch(key: "player1", event: "error", metadata: ["player_error_code" > **Full working examples:** see [`Examples/`](Examples) for runnable UIKit and > SwiftUI apps that wire an `AVPlayer` to this SDK end to end. +## Verify your integration + +Run your app and play a video. As the player changes state and you call `dispatch`, the SDK sends analytics beacons to FastPix. To confirm it is working: + +1. Play the video and let a few events fire (`playing`, `pause`, `seeking`, `ended`). +2. Open the [FastPix Dashboard](https://dashboard.fastpix.com) and go to **Video Data → Views**. +3. After a short delay, a new view/session should appear for the workspace whose Workspace Key you used, showing playback metrics for the video (identified by the `video_title` / `video_id` you passed). + +If nothing appears, check that: + +- Your `workspace_id` is the correct Workspace Key for that workspace. +- `configure` was called (with a given `key`) before you `dispatch` events using the same `key`. +- `fetchPlayheadTime` returns the position in milliseconds, and `fetchVideoState` returns a non-empty state dictionary. +- The device has network access. + +## Understand the data flow + +The SDK is **player-agnostic**: you configure it with your player's identity and two closures that read the current playhead time and video state, then dispatch events as the player's state changes. The SDK turns those into analytics beacons that appear on the FastPix dashboard. + +![FastPix iOS Video Data flow: your video player reports playhead time and state to FastpixMetrix through configure and dispatch; the SDK sends analytics beacons to FastPix Video Data, which surfaces QoE metrics on the FastPix dashboard.](https://static.fastpix.com/ios-core-data-workflow.png) + +## Supported events + +Dispatch these event names as your player's state changes (pass `[:]` for `metadata` when there are no extra fields): + +`playerReady`, `play`, `playing`, `pause`, `seeking`, `seeked`, `buffering`, `buffered`, `variantChanged`, `error`, `requestCompleted`, `requestFailed`, `ended`, `videoChange`. + +For `error`, pass details in `metadata` (for example `["player_error_code": "404", "player_error_message": "Video not found"]`). Use `videoChange` when the same player loads a new video. + +## FAQ + +**What is this SDK for?** +It collects video playback analytics (QoE) from an iOS player and reports them to the FastPix dashboard. See [Key Features](#key-features). + +**Which package do I install?** +Add `https://github.com/FastPix/iOS-core-data-sdk.git` in Xcode, then `import FastpixiOSVideoDataCore`. See [Install the SDK](#install-the-sdk). + +**I use AVPlayer - do I need this directly?** +Usually no. Use [iOS-data-avplayer-sdk](https://github.com/FastPix/iOS-data-avplayer-sdk), which wraps this core and wires AVPlayer for you. This core SDK is for custom or non-AVPlayer players. + +**Where do I get my Workspace Key?** +From the Workspaces section of the [FastPix Dashboard](https://dashboard.fastpix.com). See [Get your Workspace Key](#get-your-workspace-key). + +**How does the SDK read player state?** +You provide two closures at `configure` time: `fetchPlayheadTime` (current position in ms) and `fetchVideoState` (a state dictionary). The SDK does not observe the player itself. See [Configure the SDK](#configure-the-sdk). + +**Which events can I dispatch?** +See [Supported events](#supported-events). + +**Is there runnable example code?** +Yes - UIKit and SwiftUI AVPlayer examples under [`Examples/`](Examples). + +## Which FastPix repo do I need? + +This is the low-level analytics core. Most integrations use a higher-level SDK: + +| I want to... | Repo | +|---|---| +| Add analytics to an AVPlayer app (wraps this core) | [iOS-data-avplayer-sdk](https://github.com/FastPix/iOS-data-avplayer-sdk) | +| Play FastPix video in an iOS app | [iOS-player](https://github.com/FastPix/iOS-player) | +| Collect playback analytics on Roku | [Roku-data-core-SDK](https://github.com/FastPix/Roku-data-core-SDK) | +| Play FastPix video on the web | [web-player-component](https://github.com/FastPix/web-player-component) | +| Add resumable uploads to an iOS app | [iOS-Uploads](https://github.com/FastPix/iOS-Uploads) | + +Browse everything in the [FastPix organization](https://github.com/orgs/FastPix/repositories). + +## References + +- **Monitor AVPlayer (iOS and tvOS)**: [fastpix.com/docs/ios-and-cross-platform-players/monitor-avplayer](https://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](https://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](https://fastpix.com/docs/getting-started/set-up-a-workspace) +- **AVPlayer analytics SDK (built on this core)**: [github.com/FastPix/iOS-data-avplayer-sdk](https://github.com/FastPix/iOS-data-avplayer-sdk) + +## License + +This SDK is released under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details. From 73efff5441aa24051d15ab8702f2e33590308ae4 Mon Sep 17 00:00:00 2001 From: ashutoshkhainar33-star Date: Fri, 4 Sep 2026 17:53:02 +0530 Subject: [PATCH 2/2] Revise README for FastPix Video Data Core SDK Updated README to reflect new features and installation instructions. --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 631f0bc..fcddb4b 100644 --- a/README.md +++ b/README.md @@ -42,7 +42,7 @@ Do not skip the verification steps. If an install, workspace-key, or configurati To use the SDK, make sure you have: -- **Xcode** and an iOS (or tvOS) app with a video player (typically `AVPlayer`). +- **Xcode 15 or later** (the package uses `swift-tools-version: 5.9`), and an iOS (or tvOS) app with a video player (typically `AVPlayer`). - A **FastPix account** and a **Workspace Key** (see [Get your Workspace Key](#get-your-workspace-key)). - A way to read your player's **playhead time** (in milliseconds) and **video state** - the SDK reads these through two closures you provide.