@npaw/forge-react-native 9.6.1

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

@@ -0,0 +1,191 @@
+/**
+ * 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 network request observation model forwarded to the Rust runtime.
+ */
+
+import Foundation
+
+public enum NetworkRequestOutcome: String {
+    case success
+    case httpError = "http_error"
+    case networkError = "network_error"
+    case cancelled
+    case timeout
+    case blocked
+    case unknown
+}
+
+public enum NetworkRequestSource: String {
+    case automaticURLSession = "automatic_urlsession"
+    case automaticNSURLConnection = "automatic_nsurlconnection"
+    case manual
+}
+
+public struct NetworkRequestRecord: Equatable {
+    public var eventId: String
+    public var source: NetworkRequestSource
+    public var targetUrl: String
+    public var method: String
+    public var timestampMs: Int64
+    public var durationMs: Int64
+    public var responseStatusCode: Int
+    public var outcome: NetworkRequestOutcome
+    public var responseStatusText: String?
+    public var errorMessage: String?
+    public var traceparent: String?
+    public var dnsDurationMs: Int64?
+    public var connectDurationMs: Int64?
+    public var sslDurationMs: Int64?
+    public var requestDurationMs: Int64?
+    public var timeToFirstByteMs: Int64?
+    public var responseDownloadDurationMs: Int64?
+    public var redirectDurationMs: Int64?
+    public var redirectCount: Int64?
+    public var networkProtocol: String?
+    /// Request body size in bytes (measured uploaded byte count, request
+    /// `Content-Length` fallback). Body content is never captured; only this
+    /// size is reported.
+    public var requestBytes: Int64?
+    /// Response body size in bytes (measured downloaded byte count, response
+    /// `Content-Length` fallback). Body content is never captured; only this
+    /// size is reported.
+    public var responseBytes: Int64?
+    public var requestQuery: [String: String]
+    public var requestHeaders: [String: String]
+    public var responseHeaders: [String: String]
+
+    public init(
+        targetUrl: String,
+        method: String,
+        responseStatusCode: Int,
+        durationMs: Int64,
+        outcome: NetworkRequestOutcome,
+        eventId: String = UUID().uuidString,
+        source: NetworkRequestSource = .manual,
+        timestampMs: Int64 = 0
+    ) {
+        self.eventId = eventId
+        self.source = source
+        self.targetUrl = targetUrl
+        self.method = method
+        self.timestampMs = timestampMs
+        self.durationMs = max(0, durationMs)
+        self.responseStatusCode = max(0, responseStatusCode)
+        self.outcome = outcome
+        self.requestQuery = [:]
+        self.requestHeaders = [:]
+        self.responseHeaders = [:]
+    }
+
+    public func sanitized(configuration: NetworkPrivacyConfiguration) -> NetworkRequestRecord {
+        var copy = self
+        copy.targetUrl = configuration.sanitizeUrl(targetUrl)
+        copy.requestQuery = configuration.filterMap(requestQuery, allowlist: configuration.queryAllowlist)
+        copy.requestHeaders = configuration.filterMap(requestHeaders, allowlist: configuration.requestHeaderAllowlist)
+        copy.responseHeaders = configuration.filterMap(responseHeaders, allowlist: configuration.responseHeaderAllowlist)
+        copy.errorMessage = errorMessage.map(configuration.sanitizeText)
+        return copy
+    }
+}
+
+public struct NetworkPrivacyConfiguration: Equatable {
+    public var queryAllowlist: Set<String>
+    public var requestHeaderAllowlist: Set<String>
+    public var responseHeaderAllowlist: Set<String>
+    public var redactionKeys: Set<String>
+    public var maxStringLength: Int
+
+    public init(
+        queryAllowlist: Set<String> = [],
+        requestHeaderAllowlist: Set<String> = [],
+        responseHeaderAllowlist: Set<String> = [],
+        redactionKeys: Set<String> = Self.defaultRedactionKeys,
+        maxStringLength: Int = 512
+    ) {
+        self.queryAllowlist = queryAllowlist.map(Self.normalizeKey).asSet
+        self.requestHeaderAllowlist = requestHeaderAllowlist.map(Self.normalizeKey).asSet
+        self.responseHeaderAllowlist = responseHeaderAllowlist.map(Self.normalizeKey).asSet
+        self.redactionKeys = redactionKeys.map(Self.normalizeKey).asSet
+        self.maxStringLength = max(1, maxStringLength)
+    }
+
+    public static let defaultRedactionKeys: Set<String> = [
+        "authorization",
+        "proxy-authorization",
+        "cookie",
+        "set-cookie",
+        "api-key",
+        "x-api-key",
+        "token",
+        "access-token",
+        "refresh-token",
+        "password",
+        "passwd",
+        "credential",
+        "secret",
+        "email",
+        "phone",
+        "payment",
+        "card",
+    ]
+
+    public func sanitizeUrl(_ value: String) -> String {
+        guard var components = URLComponents(string: value) else {
+            return String(value.split(separator: "?").first.map(String.init) ?? value).prefixString(maxStringLength)
+        }
+        components.user = nil
+        components.password = nil
+        components.query = nil
+        components.fragment = nil
+        return (components.string ?? value).prefixString(maxStringLength)
+    }
+
+    public func filterMap(_ value: [String: String], allowlist: Set<String>) -> [String: String] {
+        guard !allowlist.isEmpty else { return [:] }
+        var output: [String: String] = [:]
+        for (key, rawValue) in value {
+            guard output.count < 32 else { break }
+            let normalized = Self.normalizeKey(key)
+            guard allowlist.contains(normalized), !key.isEmpty, !rawValue.isEmpty else { continue }
+            output[key] = isSensitive(normalized) ? "[REDACTED]" : rawValue.prefixString(maxStringLength)
+        }
+        return output
+    }
+
+    public func sanitizeText(_ value: String) -> String {
+        let normalized = Self.normalizeKey(value)
+        if redactionKeys.contains(where: { normalized.contains($0) }) {
+            return "[REDACTED]"
+        }
+        return value.prefixString(maxStringLength)
+    }
+
+    private func isSensitive(_ key: String) -> Bool {
+        redactionKeys.contains(where: { key.contains($0) })
+    }
+
+    private static func normalizeKey(_ value: String) -> String {
+        value.trimmingCharacters(in: .whitespacesAndNewlines)
+            .lowercased()
+            .replacingOccurrences(of: "_", with: "-")
+    }
+}
+
+private extension Array where Element == String {
+    var asSet: Set<String> { Set(self) }
+}
+
+private extension String {
+    func prefixString(_ length: Int) -> String {
+        String(prefix(length))
+    }
+}

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

@@ -0,0 +1,191 @@
+/**
+ * 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: Objective-C compatible wrappers for core Apple binding use cases.
+ */
+
+import Foundation
+
+@objc(NPAWForgeObjCBuilder)
+public final class NPAWForgeObjCBuilder: NSObject {
+    private let builder: NPAWForge.Builder
+
+    @objc public init(accountCode: String) {
+        self.builder = NPAWForge.Builder(accountCode: accountCode)
+    }
+
+    @discardableResult
+    @objc(setAppName:)
+    public func setAppName(_ value: String?) -> NPAWForgeObjCBuilder {
+        builder.setAppName(value)
+        return self
+    }
+
+    @discardableResult
+    @objc(setAppReleaseVersion:)
+    public func setAppReleaseVersion(_ value: String?) -> NPAWForgeObjCBuilder {
+        builder.setAppReleaseVersion(value)
+        return self
+    }
+
+    @discardableResult
+    @objc(setLmaEndpoint:)
+    public func setLmaEndpoint(_ value: String?) -> NPAWForgeObjCBuilder {
+        builder.setLmaEndpoint(value)
+        return self
+    }
+
+    @discardableResult
+    @objc(setLogLevelName:)
+    public func setLogLevelName(_ value: String?) -> NPAWForgeObjCBuilder {
+        builder.setLogLevel(value)
+        return self
+    }
+
+    @discardableResult
+    @objc(setStartSessionOnInitialize:)
+    public func setStartSessionOnInitialize(_ enabled: Bool) -> NPAWForgeObjCBuilder {
+        builder.setStartSessionOnInitialize(enabled)
+        return self
+    }
+
+    @objc public func build() -> NPAWForgeObjC {
+        NPAWForgeObjC(swiftForge: builder.build())
+    }
+}
+
+@objc(NPAWForgeObjC)
+public final class NPAWForgeObjC: NSObject {
+    public let swiftForge: NPAWForge
+
+    public init(swiftForge: NPAWForge) {
+        self.swiftForge = swiftForge
+    }
+
+    @objc public func startSession() -> ForgeOutcome {
+        swiftForge.startSession()
+    }
+
+    @objc(startSessionWithMetadata:)
+    public func startSession(metadata: NSDictionary?) -> ForgeOutcome {
+        swiftForge.startSession(metadata.toStringAnyMap())
+    }
+
+    @objc public func endSession() -> ForgeOutcome {
+        swiftForge.endSession()
+    }
+
+    @objc(endSessionWithMetadata:)
+    public func endSession(metadata: NSDictionary?) -> ForgeOutcome {
+        swiftForge.endSession(metadata.toStringAnyMap())
+    }
+
+    @objc(trackSessionEventWithName:metadata:)
+    public func trackSessionEvent(name: String, metadata: NSDictionary?) -> ForgeOutcome {
+        swiftForge.trackSessionEvent(name: name, metadata: metadata.toStringAnyMap())
+    }
+
+    @objc(trackSessionErrorWithCode:message:metadata:)
+    public func trackSessionError(code: String, message: String, metadata: NSDictionary?) -> ForgeOutcome {
+        swiftForge.trackSessionError(errorCode: code, errorMessage: message, metadata: metadata.toStringAnyMap())
+    }
+
+    @objc(trackRawEventWithName:params:)
+    public func trackRawEvent(name: String, params: NSDictionary?) -> ForgeOutcome {
+        swiftForge.trackRawEvent(name: name, params: params.toStringAnyMap())
+    }
+
+    @objc(trackSearchWithQuery:resultCount:)
+    public func trackSearch(query: String, resultCount: NSNumber?) -> ForgeOutcome {
+        swiftForge.trackSearch(query: query, resultCount: resultCount?.intValue)
+    }
+
+    @objc(trackSearchResultClickWithQuery:contentId:position:)
+    public func trackSearchResultClick(query: String, contentId: String?, position: NSNumber?) -> ForgeOutcome {
+        swiftForge.trackSearchResultClick(
+            query: query,
+            options: ForgeSearchResultClickOptions(contentId: contentId, position: position?.intValue)
+        )
+    }
+
+    @objc(trackBusinessEventWithName:attributes:)
+    public func trackBusinessEvent(name: String, attributes: NSDictionary?) -> ForgeOutcome {
+        swiftForge.trackBusinessEvent(name: name, attributes: attributes.toStringAnyMap())
+    }
+
+    @objc(trackAttributionWithOptions:)
+    public func trackAttribution(options: NSDictionary?) -> ForgeOutcome {
+        let values = options.toStringStringMap()
+        return swiftForge.trackAttribution(options: ForgeAttributionOptions(
+            utmSource: values["utmSource"],
+            utmMedium: values["utmMedium"],
+            utmCampaign: values["utmCampaign"],
+            utmTerm: values["utmTerm"],
+            utmContent: values["utmContent"],
+            utmUrl: values["utmUrl"]
+        ))
+    }
+
+    @objc(loginSuccessWithUserId:options:)
+    public func loginSuccess(userId: String, options: NSDictionary?) -> ForgeOutcome {
+        swiftForge.loginSuccess(userId: userId, options: options.toStringStringMap())
+    }
+
+    @objc(loginFailedWithOptions:)
+    public func loginFailed(options: NSDictionary?) -> ForgeOutcome {
+        swiftForge.loginFailed(options: options.toStringStringMap())
+    }
+
+    @objc(logoutWithOptions:)
+    public func logout(options: NSDictionary?) -> ForgeOutcome {
+        swiftForge.logout(options: options.toStringStringMap())
+    }
+
+    @objc(profileCreatedWithProfileId:options:)
+    public func profileCreated(profileId: String, options: NSDictionary?) -> ForgeOutcome {
+        swiftForge.profileCreated(profileId: profileId, options: options.toStringStringMap())
+    }
+
+    @objc(profileSelectedWithProfileId:options:)
+    public func profileSelected(profileId: String, options: NSDictionary?) -> ForgeOutcome {
+        swiftForge.profileSelected(profileId: profileId, options: options.toStringStringMap())
+    }
+
+    @objc(profileDeletedWithProfileId:)
+    public func profileDeleted(profileId: String) -> ForgeOutcome {
+        swiftForge.profileDeleted(profileId: profileId)
+    }
+
+    @objc(setLogLevelName:)
+    public func setLogLevelName(_ value: String?) -> ForgeOutcome {
+        swiftForge.setLogLevel(value)
+    }
+
+    @objc public func destroy() -> ForgeOutcome {
+        swiftForge.destroy()
+    }
+}
+
+private extension Optional where Wrapped == NSDictionary {
+    func toStringAnyMap() -> [String: Any] {
+        guard let dictionary = self else { return [:] }
+        var output: [String: Any] = [:]
+        for (key, value) in dictionary {
+            guard let key = key as? String else { continue }
+            output[key] = value
+        }
+        return output
+    }
+
+    func toStringStringMap() -> [String: String] {
+        toStringAnyMap().mapValues { String(describing: $0) }
+    }
+}

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

@@ -0,0 +1,299 @@
+/**
+ * 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 player adapter base class and public manual fire API.
+ */
+
+import Foundation
+
+open class PlayerAdapter: NSObject {
+    public let adapterInstanceId = UUID()
+    open var descriptor = AdapterDescriptor(
+        adapterId: "generic-player",
+        category: .player,
+        playerFamily: "Generic Player",
+        version: "unknown"
+    )
+
+    /// Adapter-level default for the kernel `waitForMetadata` start gate.
+    /// Adapters whose players report duration/liveness/rendition only after
+    /// the first start signal (for example AVPlayer before the HLS playlist
+    /// is parsed) override this to `true` so `/start` waits for those facts.
+    /// An explicit `VideoOptions.waitForMetadata` value always wins over this
+    /// default, and the kernel default stays `false`.
+    open var defaultWaitForMetadata: Bool { false }
+    open var playerObject: AnyObject? {
+        didSet {
+            if oldValue === playerObject { return }
+            if isBound { unregisterListeners() }
+            if isBound, playerObject != nil { registerListeners() }
+        }
+    }
+    private var isBound = false
+    public private(set) weak var videoAdapter: VideoAdapter?
+
+    /// True between an accepted pause and the accepted resume/stop/error/
+    /// destroy that clears it (mirrors the Android base adapter contract).
+    public private(set) var isPaused = false
+    private var adPlaybackActive = false
+
+    public init(player: AnyObject? = nil) {
+        self.playerObject = player
+        super.init()
+    }
+
+    /// Marks whether ad playback owns the player right now; called by
+    /// companion ad adapters around break start/stop (mirrors the Android
+    /// base adapter contract).
+    public func setIsPlayingAd(_ playingAd: Bool) {
+        adPlaybackActive = playingAd
+    }
+
+    public func isPlayingAd() -> Bool { adPlaybackActive }
+
+    func bindToVideoAdapter(_ videoAdapter: VideoAdapter) {
+        self.videoAdapter = videoAdapter
+        isBound = true
+        if playerObject != nil { registerListeners() }
+    }
+
+    func unbindFromVideoAdapter() {
+        if isBound { unregisterListeners() }
+        isBound = false
+        videoAdapter = nil
+    }
+
+    open func registerListeners() {}
+    open func unregisterListeners() {}
+
+    /// Remote behavior hints from the latest kernel capture plan (`bh.v`), or
+    /// `nil` before the first plan or while unbound. Adapters read this once
+    /// at view start (`registerListeners`); hints are applied at the next
+    /// view start only, never hot-swapped mid-view.
+    public var capturePlanBehaviorHints: ForgeCapturePlan.Behavior? {
+        videoAdapter?.capturePlanBehavior()
+    }
+
+    open func metadata() -> [String: String] {
+        [
+            "adapterId": descriptor.adapterId,
+            "category": descriptor.category.rawValue,
+            "playerFamily": descriptor.playerFamily,
+            "version": descriptor.version,
+        ]
+    }
+
+    open func snapshotMetadata(
+        timemarkMs: Int64 = ForgeClock.nowMs(),
+        elapsedRealtimeMs: Int64 = ForgeClock.elapsedRealtimeMs()
+    ) -> PlayerMetadataSnapshot {
+        defaultMetadata(nil)
+    }
+
+    /// Optional QoS sample (throughput, dropped frames, total bytes, latency,
+    /// frame rate). Adapters that can read these from their player override
+    /// this; the default returns nil so the runtime omits QoS for adapters
+    /// that do not measure it (mirrors the Android base adapter contract).
+    open func snapshotQos(
+        timemarkMs: Int64 = ForgeClock.nowMs(),
+        elapsedRealtimeMs: Int64 = ForgeClock.elapsedRealtimeMs()
+    ) -> QosSnapshot? {
+        nil
+    }
+
+    open func onPlayerEvent(
+        _ event: PlayerEvent,
+        timestampMs: Int64 = 0,
+        metadata: PlayerMetadataSnapshot? = nil
+    ) -> ForgeOutcome {
+        let resolved = metadata ?? PlayerMetadataSnapshot(playerName: descriptor.playerFamily)
+        switch event {
+        case .initEvent: return fireInit(metadata: resolved, timestampMs: timestampMs)
+        case .start: return fireStart(metadata: resolved, timestampMs: timestampMs)
+        case .join: return fireJoin(metadata: resolved, timestampMs: timestampMs)
+        case .pause: return firePause(metadata: resolved, timestampMs: timestampMs)
+        case .resume: return fireResume(metadata: resolved, timestampMs: timestampMs)
+        case .seekBegin: return fireSeekBegin(metadata: resolved, timestampMs: timestampMs)
+        case .seekEnd: return fireSeekEnd(metadata: resolved, timestampMs: timestampMs)
+        case .bufferBegin: return fireBufferBegin(metadata: resolved, timestampMs: timestampMs)
+        case .bufferEnd: return fireBufferEnd(metadata: resolved, timestampMs: timestampMs)
+        case .stop: return fireStop(metadata: resolved, timestampMs: timestampMs)
+        case .error: return fireError(errorCode: resolved.errorCode, errorMessage: resolved.errorMessage, errorMetadata: resolved.errorMetadata, timestampMs: timestampMs)
+        case .fatalError: return fireFatalError(errorCode: resolved.errorCode, errorMessage: resolved.errorMessage, errorMetadata: resolved.errorMetadata, timestampMs: timestampMs)
+        case .destroy: return fireDestroy(timestampMs: timestampMs)
+        case .customVideoEvent: return fireEvent(timestampMs: timestampMs)
+        case .customVideoEventEnd: return fireEventEnd(timestampMs: timestampMs)
+        case .metadataUpdate: return fireMetadataUpdate(metadata: resolved, timestampMs: timestampMs)
+        }
+    }
+
+    open func fireInit(params: [String: String]? = [:], metadata: PlayerMetadataSnapshot? = nil, timestampMs: Int64 = 0) -> ForgeOutcome {
+        record(.initEvent, metadata ?? defaultMetadata(params), timestampMs)
+    }
+
+    open func fireStart(params: [String: String]? = [:], forceInit: Bool? = false, metadata: PlayerMetadataSnapshot? = nil, timestampMs: Int64 = 0) -> ForgeOutcome {
+        var snapshot = metadata ?? defaultMetadata(params)
+        snapshot.forceInit = forceInit ?? false
+        return record(.start, snapshot, timestampMs)
+    }
+
+    open func fireJoin(params: [String: String]? = [:], metadata: PlayerMetadataSnapshot? = nil, timestampMs: Int64 = 0) -> ForgeOutcome {
+        record(.join, metadata ?? defaultMetadata(params), timestampMs)
+    }
+
+    open func firePause(params: [String: String]? = [:], metadata: PlayerMetadataSnapshot? = nil, timestampMs: Int64 = 0) -> ForgeOutcome {
+        record(.pause, metadata ?? defaultMetadata(params), timestampMs)
+    }
+
+    open func fireResume(params: [String: String]? = [:], metadata: PlayerMetadataSnapshot? = nil, timestampMs: Int64 = 0) -> ForgeOutcome {
+        record(.resume, metadata ?? defaultMetadata(params), timestampMs)
+    }
+
+    open func fireSeekBegin(convertFromBuffer: Bool? = true, params: [String: String]? = [:], metadata: PlayerMetadataSnapshot? = nil, timestampMs: Int64 = 0) -> ForgeOutcome {
+        var snapshot = metadata ?? defaultMetadata(params)
+        snapshot.convertFromBuffer = convertFromBuffer ?? true
+        return record(.seekBegin, snapshot, timestampMs)
+    }
+
+    open func fireSeekEnd(params: [String: String]? = [:], metadata: PlayerMetadataSnapshot? = nil, timestampMs: Int64 = 0) -> ForgeOutcome {
+        record(.seekEnd, metadata ?? defaultMetadata(params), timestampMs)
+    }
+
+    open func fireBufferBegin(convertFromSeek: Bool? = false, params: [String: String]? = [:], metadata: PlayerMetadataSnapshot? = nil, timestampMs: Int64 = 0) -> ForgeOutcome {
+        var snapshot = metadata ?? defaultMetadata(params)
+        snapshot.convertFromSeek = convertFromSeek ?? false
+        return record(.bufferBegin, snapshot, timestampMs)
+    }
+
+    open func fireBufferEnd(params: [String: String]? = [:], metadata: PlayerMetadataSnapshot? = nil, timestampMs: Int64 = 0) -> ForgeOutcome {
+        record(.bufferEnd, metadata ?? defaultMetadata(params), timestampMs)
+    }
+
+    open func fireStop(params: [String: String]? = [:], metadata: PlayerMetadataSnapshot? = nil, timestampMs: Int64 = 0) -> ForgeOutcome {
+        record(.stop, metadata ?? defaultMetadata(params), timestampMs)
+    }
+
+    open func fireError(errorCode: String? = nil, errorMessage: String? = nil, errorMetadata: String? = nil, timestampMs: Int64 = 0) -> ForgeOutcome {
+        var metadata = defaultMetadata(nil)
+        metadata.errorCode = errorCode
+        metadata.errorMessage = errorMessage
+        metadata.errorMetadata = errorMetadata
+        return record(.error, metadata, timestampMs)
+    }
+
+    open func fireFatalError(errorCode: String? = nil, errorMessage: String? = nil, errorMetadata: String? = nil, timestampMs: Int64 = 0) -> ForgeOutcome {
+        var metadata = defaultMetadata(nil)
+        metadata.errorCode = errorCode
+        metadata.errorMessage = errorMessage
+        metadata.errorMetadata = errorMetadata
+        metadata.errorLevel = "fatal"
+        return record(.fatalError, metadata, timestampMs)
+    }
+
+    open func fireDestroy(timestampMs: Int64 = 0) -> ForgeOutcome {
+        record(.destroy, defaultMetadata(nil), timestampMs)
+    }
+
+    open func fireEvent(
+        eventName: String = "",
+        dimensions: [String: String] = [:],
+        values: [String: Double] = [:],
+        topLevelDimensions: [String: String] = [:],
+        hasEndDatetime: Bool = false,
+        timestampMs: Int64 = 0
+    ) -> ForgeOutcome {
+        var metadata = defaultMetadata(nil)
+        metadata.customEvent = CustomVideoEventPayload(
+            name: eventName,
+            dimensions: dimensions,
+            values: values,
+            topLevel: topLevelDimensions,
+            hasEndDatetime: hasEndDatetime
+        )
+        return record(.customVideoEvent, metadata, timestampMs)
+    }
+
+    open func fireEventEnd(
+        eventName: String = "",
+        dimensions: [String: String] = [:],
+        values: [String: Double] = [:],
+        topLevelDimensions: [String: String] = [:],
+        timestampMs: Int64 = 0
+    ) -> ForgeOutcome {
+        var metadata = defaultMetadata(nil)
+        metadata.customEvent = CustomVideoEventPayload(
+            name: eventName,
+            dimensions: dimensions,
+            values: values,
+            topLevel: topLevelDimensions
+        )
+        return record(.customVideoEventEnd, metadata, timestampMs)
+    }
+
+    open func fireMetadataUpdate(metadata: PlayerMetadataSnapshot? = nil, timestampMs: Int64 = 0) -> ForgeOutcome {
+        record(.metadataUpdate, metadata ?? defaultMetadata(nil), timestampMs)
+    }
+
+    open func defaultMetadata(_ params: [String: String]?) -> PlayerMetadataSnapshot {
+        PlayerMetadataSnapshot(
+            playerName: params?["player"] ?? descriptor.playerFamily,
+            playerVersion: params?["playerVersion"] ?? descriptor.version,
+            adapterVersion: descriptor.version,
+            resourceUrl: params?["resource"],
+            parsedResource: params?["parsedResource"] ?? params?["urlToParse"],
+            title: params?["title"],
+            contentType: (params?["contentType"] ?? params?["content_type"]).flatMap(ContentType.from) ?? .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 record(_ event: PlayerEvent, _ metadata: PlayerMetadataSnapshot, _ timestampMs: Int64) -> ForgeOutcome {
+        let outcome = videoAdapter?.recordPlayerEvent(event: event, timestampMs: timestampMs, metadata: metadata) ?? .ignoredInvalidState
+        if outcome.isAccepted { updatePlaybackState(event) }
+        return outcome
+    }
+
+    private func updatePlaybackState(_ event: PlayerEvent) {
+        switch event {
+        case .pause:
+            isPaused = true
+        case .resume, .stop, .error, .fatalError, .destroy:
+            isPaused = false
+        default:
+            break
+        }
+    }
+
+    private static func secondsToMillis(_ value: String) -> Int64? {
+        Double(value).map { Int64($0 * 1000.0) }
+    }
+}
+
+private extension ContentType {
+    static func from(_ value: String) -> ContentType {
+        switch value.lowercased() {
+        case "live": return .live
+        case "vod": return .vod
+        case "audio": return .audio
+        default: return .unknown
+        }
+    }
+}