Basic Usage

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:

TypeRole
InkPlayerParamsTells the player which video to load (Video ID + OTP)
InkryptVideoPlayerViewThe SwiftUI view that renders the video player UI
InkPlayerStateProvides 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

InkPlayerParams 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 to InkPlayerParams. 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

ParameterTypeDefaultDescription
videoIdStringrequiredThe unique ID of the video to load
otpStringrequiredOne-time password for authentication
autoPlayBoolfalseStart playback automatically when the video is ready
aspectRatioFloat16/9The 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 onPlayerStateReady called?
It is called once, after the player has initialized and is ready to accept commands. The InkPlayerState reference remains valid for the lifetime of the current video session. When you call params.update(...) to load a new video, a new state object is created and onPlayerStateReady is 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) before view.addSubview(playerVC.view), and always call playerVC.didMove(toParent: self) after. Skipping these calls can cause memory leaks and incorrect lifecycle behavior.