This guide assumes you have already added InkryptVideos.xcframework to your project. If not, see Setting Up the SDK first.
How the SDK Works
The SDK has three main types you will use in almost every integration:
| Type | Role |
|---|---|
InkPlayerParams | Tells the player which video to load (Video ID + OTP) |
InkryptVideoPlayerView | The SwiftUI view that renders the video player UI |
InkPlayerState | Provides live playback state and programmatic controls |
The typical flow is:
1. Create InkPlayerParams with a Video ID and OTP
↓
2. Pass it to InkryptVideoPlayerView
↓
3. Player loads, authenticates, and begins playback
↓
4. (Optional) Receive InkPlayerState via callback to read state or issue commands
Displaying the Player
Step 1: Import the SDK
At the top of your Swift file, add:
import SwiftUI
import InkryptVideos
Step 2: Declare InkPlayerParams
InkPlayerParamsInkPlayerParams controls which video the player loads. Declare it as a @StateObject so SwiftUI owns it and keeps it alive for the lifetime of the view:
@StateObject private var params = InkPlayerParams(
videoId: "YOUR_VIDEO_ID",
otp: "YOUR_OTP"
)
What is a Video ID?
Each video you upload to InkryptVideos gets a unique identifier. You will find it in the InkryptVideos dashboard.What is an OTP?
An OTP (One-Time Password) is a short-lived token that grants playback access to a specific video. OTPs are generated from the InkryptVideos dashboard and passed directly toInkPlayerParams. The OTP system prevents unauthorized access to your video content.
Step 3: Add the Player View
Pass params to InkryptVideoPlayerView. The view takes care of loading, buffering, the player controls UI, quality selection, and error display - everything.
import SwiftUI
import InkryptVideos
struct ContentView: View {
@StateObject private var params = InkPlayerParams(
videoId: "YOUR_VIDEO_ID",
otp: "YOUR_OTP",
autoPlay: false
)
var body: some View {
InkryptVideoPlayerView(params: params)
}
}
Run the app on a physical device. The player will appear, load the video, and display the built-in playback controls.
InkPlayerParams Options
InkPlayerParams Options| Parameter | Type | Default | Description |
|---|---|---|---|
videoId | String | required | The unique ID of the video to load |
otp | String | required | One-time password for authentication |
autoPlay | Bool | false | Start playback automatically when the video is ready |
aspectRatio | Float | 16/9 | The width-to-height ratio of the player frame |
Example: auto-play with a 4:3 aspect ratio:
@StateObject private var params = InkPlayerParams(
videoId: "YOUR_VIDEO_ID",
otp: "YOUR_OTP",
autoPlay: true,
aspectRatio: 4 / 3
)
Loading a Different Video
To switch videos, for example, when the user taps a "next video" button - call params.update(...):
func loadNextVideo() {
params.update(
videoId: "NEXT_VIDEO_ID",
otp: "NEXT_VIDEO_OTP",
autoPlay: true
)
}
The player automatically stops the current video, resets its state, and begins loading the new one. You do not need to recreate InkPlayerParams or the view.
Accessing Playback State
Pass the onPlayerStateReady callback to receive an InkPlayerState reference once the player has initialized. This object exposes live playback data and control methods.
import SwiftUI
import InkryptVideos
struct ContentView: View {
@StateObject private var params = InkPlayerParams(
videoId: "YOUR_VIDEO_ID",
otp: "YOUR_OTP"
)
@State private var playerState: InkPlayerState?
var body: some View {
InkryptVideoPlayerView(
params: params,
onPlayerStateReady: { state in
self.playerState = state
}
)
// Example: show a custom pause button outside the player
Button("Pause") {
playerState?.pausePlayer()
}
}
}
When is
onPlayerStateReadycalled?
It is called once, after the player has initialized and is ready to accept commands. TheInkPlayerStatereference remains valid for the lifetime of the current video session. When you callparams.update(...)to load a new video, a new state object is created andonPlayerStateReadyis called again.
Once you hold a reference to playerState, you can use it anywhere:
// Check playback status
let isPlaying = playerState?.isPlaying // Bool
let isBuffering = playerState?.isLoading // Bool
// Get position and duration
let position = playerState?.seekDuration // Float64 (seconds)
let duration = playerState?.videoLength // CMTime?
// Playback controls
playerState?.play()
playerState?.pausePlayer()
playerState?.seek(to: 120.0) // Seek to 2:00
// Full screen
playerState?.isFullScreen = true
Handling Errors
Pass onError and onReloadPressed to respond to playback errors:
InkryptVideoPlayerView(
params: params,
onReloadPressed: { errorCode, errorMessage in
// Called when the user taps "Retry" on the error screen.
// Return new InkPlayerParams to reload with a different video or OTP.
// Return nil to retry with the same params.
return nil
},
onError: { errorCode, errorMessage in
// Called when an error occurs — use this for logging or alerts.
print("Playback error \(errorCode ?? -1): \(errorMessage ?? "unknown")")
}
)
For a detailed breakdown of error codes and recovery strategies, see the Errors Guide.
UIKit Integration
The player is a SwiftUI view, but it can be embedded into any UIViewController using Apple's standard UIHostingController bridge.
import UIKit
import SwiftUI
import InkryptVideos
class VideoViewController: UIViewController {
private var params: InkPlayerParams!
override func viewDidLoad() {
super.viewDidLoad()
// 1. Create params
params = InkPlayerParams(
videoId: "YOUR_VIDEO_ID",
otp: "YOUR_OTP",
autoPlay: false
)
// 2. Wrap InkryptVideoPlayerView in a UIHostingController
let playerVC = UIHostingController(
rootView: InkryptVideoPlayerView(params: params)
)
// 3. Add as a child view controller (required for lifecycle events)
addChild(playerVC)
view.addSubview(playerVC.view)
playerVC.view.translatesAutoresizingMaskIntoConstraints = false
// 4. Pin to safe area edges (adjust to your layout needs)
NSLayoutConstraint.activate([
playerVC.view.topAnchor.constraint(equalTo: view.safeAreaLayoutGuide.topAnchor),
playerVC.view.bottomAnchor.constraint(equalTo: view.safeAreaLayoutGuide.bottomAnchor),
playerVC.view.leadingAnchor.constraint(equalTo: view.leadingAnchor),
playerVC.view.trailingAnchor.constraint(equalTo: view.trailingAnchor),
])
// 5. Notify the child that embedding is complete
playerVC.didMove(toParent: self)
}
// Change the video from a UIKit action (IBAction, gesture, etc.)
@IBAction func onNextVideoTapped(_ sender: UIButton) {
params.update(
videoId: "NEXT_VIDEO_ID",
otp: "NEXT_VIDEO_OTP",
autoPlay: true
)
}
}
Important: Always call
addChild(playerVC)beforeview.addSubview(playerVC.view), and always callplayerVC.didMove(toParent: self)after. Skipping these calls can cause memory leaks and incorrect lifecycle behavior.