@npaw/forge-react-native 9.6.1

package/ios/ForgeApple/Sources/NPAWForgeCore/VideoAdapter.swift

@@ -0,0 +1,478 @@
+/**
+ * Copyright (C) NPAW - All Rights Reserved
+ *
+ * This source code is protected under international copyright law. All rights
+ * reserved and protected by the copyright holders.
+ * This file is confidential and only available to authorized individuals with the
+ * permission of the copyright holders. If you encounter this file and do not have
+ * permission, please contact the copyright holders and delete this file.
+ *
+ *
+ * @author: Victor Soto <victor.soto@nicepeopleatwork.com>
+ * @description: Apple video adapter lifecycle and runtime view owner.
+ */
+
+import Foundation
+
+public final class VideoBuilder {
+    private weak var forge: NPAWForge?
+    private var identifier = NPAWForge.defaultVideoAdapterIdentifier
+    private var options = VideoOptions()
+    private var playerAdapter: PlayerAdapter?
+    private var adAdapter: AdAdapter?
+
+    init(forge: NPAWForge) {
+        self.forge = forge
+    }
+
+    @discardableResult public func setIdentifier(_ identifier: String?) -> VideoBuilder {
+        if let identifier = identifier?.trimmingCharacters(in: .whitespacesAndNewlines), !identifier.isEmpty {
+            self.identifier = identifier
+        }
+        return self
+    }
+
+    @discardableResult public func setOptions(_ options: VideoOptions?) -> VideoBuilder {
+        self.options = options ?? self.options
+        return self
+    }
+
+    @discardableResult public func setPlayerAdapter(_ playerAdapter: PlayerAdapter?) -> VideoBuilder {
+        self.playerAdapter = playerAdapter
+        return self
+    }
+
+    @discardableResult public func setAdAdapter(_ adAdapter: AdAdapter?) -> VideoBuilder {
+        self.adAdapter = adAdapter
+        return self
+    }
+
+    public func build() -> VideoAdapter {
+        guard let forge else {
+            return VideoAdapter.unavailable(identifier: identifier, options: options)
+        }
+        return forge.buildVideoAdapter(
+            identifier: identifier,
+            options: options,
+            playerAdapter: playerAdapter,
+            adAdapter: adAdapter
+        )
+    }
+}
+
+public final class VideoAdapter: RuntimeContentMetadataProvider {
+    weak var forge: NPAWForge?
+    public let identifier: String
+    public let options: VideoOptions
+    /// Options used for runtime event recording: the integrator options plus
+    /// the bound player adapter's `defaultWaitForMetadata` when the integrator
+    /// did not choose explicitly (mirrors the Android `effectiveOptions`).
+    private var effectiveOptions: VideoOptions
+    private let runtimeView: RuntimeVideoView
+    private var destroyed = false
+    private var willSendRequestListener: ((String, VideoAdapter, inout [String: String]) -> Void)?
+
+    public private(set) var playerAdapter: PlayerAdapter?
+    public private(set) var adAdapter: AdAdapter?
+
+    public var isDestroyed: Bool { destroyed }
+
+    init(forge: NPAWForge, identifier: String, options: VideoOptions) {
+        self.forge = forge
+        self.identifier = identifier
+        self.options = options
+        self.effectiveOptions = options
+        self.runtimeView = forge.kernel.createVideoView(timestampMs: 0, options: options)
+    }
+
+    private init(identifier: String, options: VideoOptions) {
+        self.identifier = identifier
+        self.options = options
+        self.effectiveOptions = options
+        self.runtimeView = RuntimeVideoView(id: -1)
+    }
+
+    static func unavailable(identifier: String, options: VideoOptions) -> VideoAdapter {
+        VideoAdapter(identifier: identifier, options: options)
+    }
+
+    public func setPlayerAdapter(_ playerAdapter: PlayerAdapter?) -> ForgeOutcome {
+        replacePlayerAdapter(playerAdapter, checkDuplicates: true)
+    }
+
+    public func setAdAdapter(_ adAdapter: AdAdapter?) -> ForgeOutcome {
+        replaceAdAdapter(adAdapter, checkDuplicates: true)
+    }
+
+    public func setWillSendRequestListener(_ listener: ((String, VideoAdapter, inout [String: String]) -> Void)?) -> ForgeOutcome {
+        guard !destroyed else { return .ignoredInvalidState }
+        willSendRequestListener = listener
+        let hook = listener.map { callback in
+            VideoPreSendHook { [weak self] eventName, _, _, params in
+                guard let self else { return }
+                callback(eventName, self, &params)
+            }
+        }
+        return forge?.kernel.registerVideoPreSendHook(view: runtimeView, hook: hook) ?? .ignoredInvalidState
+    }
+
+    public func fireInit(
+        metadata: PlayerMetadataSnapshot? = nil,
+        params: [String: String]? = [:],
+        timestampMs: Int64 = 0
+    ) -> ForgeOutcome {
+        recordPlayerEvent(event: .initEvent, timestampMs: timestampMs, metadata: metadata ?? playerMetadataFromParams(params))
+    }
+
+    public func fireStart(
+        forceInit: Bool? = false,
+        metadata: PlayerMetadataSnapshot? = nil,
+        params: [String: String]? = [:],
+        timestampMs: Int64 = 0
+    ) -> ForgeOutcome {
+        var snapshot = metadata ?? playerMetadataFromParams(params)
+        snapshot.forceInit = forceInit ?? false
+        return recordPlayerEvent(event: .start, timestampMs: timestampMs, metadata: snapshot)
+    }
+
+    public func fireJoin(
+        metadata: PlayerMetadataSnapshot? = nil,
+        params: [String: String]? = [:],
+        timestampMs: Int64 = 0
+    ) -> ForgeOutcome {
+        recordPlayerEvent(event: .join, timestampMs: timestampMs, metadata: metadata ?? playerMetadataFromParams(params))
+    }
+
+    public func firePause(
+        metadata: PlayerMetadataSnapshot? = nil,
+        params: [String: String]? = [:],
+        timestampMs: Int64 = 0
+    ) -> ForgeOutcome {
+        recordPlayerEvent(event: .pause, timestampMs: timestampMs, metadata: metadata ?? playerMetadataFromParams(params))
+    }
+
+    public func fireResume(
+        metadata: PlayerMetadataSnapshot? = nil,
+        params: [String: String]? = [:],
+        timestampMs: Int64 = 0
+    ) -> ForgeOutcome {
+        recordPlayerEvent(event: .resume, timestampMs: timestampMs, metadata: metadata ?? playerMetadataFromParams(params))
+    }
+
+    public func fireSeekBegin(
+        convertFromBuffer: Bool? = true,
+        metadata: PlayerMetadataSnapshot? = nil,
+        params: [String: String]? = [:],
+        timestampMs: Int64 = 0
+    ) -> ForgeOutcome {
+        var snapshot = metadata ?? playerMetadataFromParams(params)
+        snapshot.convertFromBuffer = convertFromBuffer ?? true
+        return recordPlayerEvent(event: .seekBegin, timestampMs: timestampMs, metadata: snapshot)
+    }
+
+    public func fireSeekEnd(
+        metadata: PlayerMetadataSnapshot? = nil,
+        params: [String: String]? = [:],
+        timestampMs: Int64 = 0
+    ) -> ForgeOutcome {
+        recordPlayerEvent(event: .seekEnd, timestampMs: timestampMs, metadata: metadata ?? playerMetadataFromParams(params))
+    }
+
+    public func fireBufferBegin(
+        convertFromSeek: Bool? = false,
+        metadata: PlayerMetadataSnapshot? = nil,
+        params: [String: String]? = [:],
+        timestampMs: Int64 = 0
+    ) -> ForgeOutcome {
+        var snapshot = metadata ?? playerMetadataFromParams(params)
+        snapshot.convertFromSeek = convertFromSeek ?? false
+        return recordPlayerEvent(event: .bufferBegin, timestampMs: timestampMs, metadata: snapshot)
+    }
+
+    public func fireBufferEnd(
+        metadata: PlayerMetadataSnapshot? = nil,
+        params: [String: String]? = [:],
+        timestampMs: Int64 = 0
+    ) -> ForgeOutcome {
+        recordPlayerEvent(event: .bufferEnd, timestampMs: timestampMs, metadata: metadata ?? playerMetadataFromParams(params))
+    }
+
+    public func fireStop(
+        metadata: PlayerMetadataSnapshot? = nil,
+        params: [String: String]? = [:],
+        timestampMs: Int64 = 0
+    ) -> ForgeOutcome {
+        recordPlayerEvent(event: .stop, timestampMs: timestampMs, metadata: metadata ?? playerMetadataFromParams(params))
+    }
+
+    public func fireError(
+        errorCode: String? = nil,
+        errorMessage: String? = nil,
+        errorMetadata: String? = nil,
+        timestampMs: Int64 = 0
+    ) -> ForgeOutcome {
+        var metadata = manualPlayerMetadata()
+        metadata.errorCode = errorCode
+        metadata.errorMessage = errorMessage
+        metadata.errorMetadata = errorMetadata
+        return recordPlayerEvent(event: .error, timestampMs: timestampMs, metadata: metadata)
+    }
+
+    public func fireFatalError(
+        errorCode: String? = nil,
+        errorMessage: String? = nil,
+        errorMetadata: String? = nil,
+        timestampMs: Int64 = 0
+    ) -> ForgeOutcome {
+        var metadata = manualPlayerMetadata()
+        metadata.errorCode = errorCode
+        metadata.errorMessage = errorMessage
+        metadata.errorMetadata = errorMetadata
+        metadata.errorLevel = "fatal"
+        return recordPlayerEvent(event: .fatalError, timestampMs: timestampMs, metadata: metadata)
+    }
+
+    public func fireDestroy(timestampMs: Int64 = 0) -> ForgeOutcome {
+        recordPlayerEvent(event: .destroy, timestampMs: timestampMs, metadata: manualPlayerMetadata())
+    }
+
+    public func fireEvent(
+        eventName: String = "",
+        dimensions: [String: String] = [:],
+        values: [String: Double] = [:],
+        topLevelDimensions: [String: String] = [:],
+        hasEndDatetime: Bool = false,
+        timestampMs: Int64 = 0
+    ) -> ForgeOutcome {
+        var metadata = manualPlayerMetadata()
+        metadata.customEvent = CustomVideoEventPayload(
+            name: eventName,
+            dimensions: dimensions,
+            values: values,
+            topLevel: topLevelDimensions,
+            hasEndDatetime: hasEndDatetime
+        )
+        return recordPlayerEvent(event: .customVideoEvent, timestampMs: timestampMs, metadata: metadata)
+    }
+
+    public func fireEventEnd(
+        eventName: String = "",
+        dimensions: [String: String] = [:],
+        values: [String: Double] = [:],
+        topLevelDimensions: [String: String] = [:],
+        timestampMs: Int64 = 0
+    ) -> ForgeOutcome {
+        var metadata = manualPlayerMetadata()
+        metadata.customEvent = CustomVideoEventPayload(
+            name: eventName,
+            dimensions: dimensions,
+            values: values,
+            topLevel: topLevelDimensions
+        )
+        return recordPlayerEvent(event: .customVideoEventEnd, timestampMs: timestampMs, metadata: metadata)
+    }
+
+    public func fireMetadataUpdate(
+        metadata: PlayerMetadataSnapshot? = nil,
+        params: [String: String]? = [:],
+        timestampMs: Int64 = 0
+    ) -> ForgeOutcome {
+        recordPlayerEvent(event: .metadataUpdate, timestampMs: timestampMs, metadata: metadata ?? playerMetadataFromParams(params))
+    }
+
+    public func createAdReporter(adapterVersion: String? = nil) -> ManualAdReporter {
+        ManualAdReporter(videoAdapter: self, adapterVersion: adapterVersion)
+    }
+
+    /// Remote behavior hints from the latest kernel capture plan (`bh.v`),
+    /// or `nil` before the first plan. Player adapters snapshot these at view
+    /// start; hints are never hot-swapped mid-view.
+    public func capturePlanBehavior() -> ForgeCapturePlan.Behavior? {
+        guard !destroyed else { return nil }
+        return forge?.capturePlan()?.behavior
+    }
+
+    public func destroy() -> ForgeOutcome {
+        guard !destroyed else { return .ignoredDuplicate }
+        let destroyOutcome = forge?.kernel.recordPlayerEvent(
+            view: runtimeView,
+            event: .destroy,
+            timestampMs: 0,
+            metadata: manualPlayerMetadata(),
+            options: effectiveOptions
+        ) ?? .ignoredInvalidState
+        destroyed = true
+        playerAdapter?.unbindFromVideoAdapter()
+        adAdapter?.unbindFromVideoAdapter()
+        playerAdapter = nil
+        adAdapter = nil
+        willSendRequestListener = nil
+        _ = forge?.kernel.registerContentMetadataProvider(view: runtimeView, provider: nil)
+        _ = forge?.kernel.registerVideoPreSendHook(view: runtimeView, hook: nil)
+        _ = forge?.kernel.destroyVideoView(runtimeView)
+        forge?.onVideoAdapterDestroyed(self)
+        return destroyOutcome.isAccepted ? .accepted : destroyOutcome
+    }
+
+    func replacePlayerAdapter(_ playerAdapter: PlayerAdapter?, checkDuplicates: Bool) -> ForgeOutcome {
+        guard !destroyed else { return .ignoredInvalidState }
+        if checkDuplicates {
+            forge?.onPlayerAdapterRegistered(owner: self, playerAdapter: playerAdapter)
+        }
+        self.playerAdapter?.unbindFromVideoAdapter()
+        self.playerAdapter = playerAdapter
+        effectiveOptions = playerAdapter?.defaultWaitForMetadata == true
+            ? options.withAdapterWaitForMetadataDefault()
+            : options
+        playerAdapter?.bindToVideoAdapter(self)
+        return forge?.kernel.registerContentMetadataProvider(view: runtimeView, provider: self) ?? .ignoredInvalidState
+    }
+
+    func replaceAdAdapter(_ adAdapter: AdAdapter?, checkDuplicates: Bool) -> ForgeOutcome {
+        guard !destroyed else { return .ignoredInvalidState }
+        if checkDuplicates {
+            forge?.onAdAdapterRegistered(owner: self, adAdapter: adAdapter)
+        }
+        self.adAdapter?.unbindFromVideoAdapter()
+        self.adAdapter = adAdapter
+        adAdapter?.bindToVideoAdapter(self)
+        return .accepted
+    }
+
+    func recordPlayerEvent(event: PlayerEvent, timestampMs: Int64, metadata: PlayerMetadataSnapshot) -> ForgeOutcome {
+        guard !destroyed else { return .ignoredInvalidState }
+        return forge?.kernel.recordPlayerEvent(
+            view: runtimeView,
+            event: event,
+            timestampMs: timestampMs,
+            metadata: metadata,
+            options: effectiveOptions
+        ) ?? .ignoredInvalidState
+    }
+
+    func recordAdEvent(
+        event: AdEvent,
+        timestampMs: Int64,
+        metadata: AdMetadataSnapshot,
+        adapterVersion: String? = nil
+    ) -> ForgeOutcome {
+        guard !destroyed else { return .ignoredInvalidState }
+        return forge?.kernel.recordAdEvent(
+            view: runtimeView,
+            event: event,
+            timestampMs: timestampMs,
+            metadata: metadata,
+            options: effectiveOptions,
+            adapterVersion: adapterVersion ?? adAdapter?.descriptor.version
+        ) ?? .ignoredInvalidState
+    }
+
+    func usesAdapterOrPlayer(_ candidate: AnyObject) -> Bool {
+        if playerAdapter === candidate || adAdapter === candidate { return true }
+        if let playerAdapter, playerAdapter.playerObject === candidate { return true }
+        if let adAdapter, adAdapter.playerObject === candidate { return true }
+        return false
+    }
+
+    public func metadataSnapshot(timemarkMs: Int64, elapsedRealtimeMs: Int64) -> MetadataSnapshot? {
+        guard !destroyed,
+              let snapshot = playerAdapter?.snapshotMetadata(timemarkMs: timemarkMs, elapsedRealtimeMs: elapsedRealtimeMs) else {
+            return nil
+        }
+        return MetadataSnapshot(
+            content: snapshot,
+            qos: playerAdapter?.snapshotQos(timemarkMs: timemarkMs, elapsedRealtimeMs: elapsedRealtimeMs)
+        )
+    }
+
+    private func manualPlayerMetadata() -> PlayerMetadataSnapshot {
+        PlayerMetadataSnapshot(playerName: "Manual Player")
+    }
+
+    private func playerMetadataFromParams(_ params: [String: String]?) -> PlayerMetadataSnapshot {
+        PlayerMetadataSnapshot(
+            playerName: params?["player"] ?? "Manual Player",
+            playerVersion: params?["playerVersion"],
+            resourceUrl: params?["resource"],
+            parsedResource: params?["parsedResource"] ?? params?["urlToParse"],
+            title: params?["title"],
+            contentType: (params?["contentType"] ?? params?["content_type"]).flatMap(ContentType.fromAdapterlessValue) ?? .unknown,
+            playheadMs: params?["playhead"].flatMap(Self.secondsToMillis),
+            durationMs: params?["mediaDuration"].flatMap(Self.secondsToMillis),
+            bitrate: params?["bitrate"].flatMap(Int64.init),
+            rendition: params?["rendition"],
+            videoCodec: params?["videoCodec"],
+            audioCodec: params?["audioCodec"],
+            codecProfile: params?["codecProfile"],
+            containerFormat: params?["containerFormat"],
+            errorMetadata: params?["errorMetadata"],
+            errorLevel: params?["errorLevel"],
+            program: params?["program"]
+        )
+    }
+
+    func adMetadataFromParams(_ params: [String: String]?) -> AdMetadataSnapshot {
+        AdMetadataSnapshot(
+            adId: params?["adId"] ?? params?["ad_id"],
+            creativeId: params?["adCreativeId"] ?? params?["creative_id"],
+            adUrl: params?["adUrl"] ?? params?["ad_url"],
+            adTitle: params?["adTitle"],
+            adDurationMs: params?["adDurationMs"].flatMap(Int64.init) ?? params?["adDuration"].flatMap(Self.secondsToMillis),
+            adPlayheadMs: params?["adPlayheadMs"].flatMap(Int64.init) ?? params?["adPlayhead"].flatMap(Self.secondsToMillis),
+            adBitrate: params?["adBitrate"].flatMap(Int64.init),
+            position: params?["position"].flatMap(AdPosition.fromAdapterlessValue),
+            quartile: params?["quartile"].flatMap(Int.init),
+            insertionType: (params?["adInsertionType"] ?? params?["insertion_type"]).flatMap(AdInsertionType.fromAdapterlessValue) ?? .unknown,
+            errorMetadata: params?["errorMetadata"],
+            errorLevel: params?["errorLevel"]
+        )
+    }
+
+    private static func secondsToMillis(_ value: String) -> Int64? {
+        Double(value).map { Int64($0 * 1000.0) }
+    }
+}
+
+private extension ContentType {
+    static func fromAdapterlessValue(_ value: String) -> ContentType {
+        switch value.lowercased() {
+        case "live": return .live
+        case "vod": return .vod
+        case "audio": return .audio
+        default: return .unknown
+        }
+    }
+}
+
+private extension AdPosition {
+    static func fromAdapterlessValue(_ value: String) -> AdPosition {
+        switch value.lowercased() {
+        case "pre", "preroll": return .pre
+        case "mid", "midroll": return .mid
+        case "post", "postroll": return .post
+        default: return .unknown
+        }
+    }
+}
+
+private extension AdInsertionType {
+    static func fromAdapterlessValue(_ value: String) -> AdInsertionType {
+        switch value.lowercased() {
+        case "csai", "client", "client_side": return .clientSide
+        case "ssai", "server", "server_side": return .serverSide
+        default: return .unknown
+        }
+    }
+}
+
+private final class VideoPreSendHook: RuntimeVideoPreSendHook {
+    private let callback: (String, RuntimeVideoView, String, inout [String: String]) -> Void
+
+    init(callback: @escaping (String, RuntimeVideoView, String, inout [String: String]) -> Void) {
+        self.callback = callback
+    }
+
+    func willSendRequest(eventName: String, view: RuntimeVideoView, serviceName: String, params: inout [String: String]) {
+        callback(eventName, view, serviceName, &params)
+    }
+}