diff --git a/CHANGELOG.md b/CHANGELOG.md index acb71b4f..a89d31bb 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -10,7 +10,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Added - Lens - - Added the Lens connector, which reports THEOplayer playback to OptiView Lens. It is available through Swift Package Manager only. + - Added the Lens connector, which reports THEOplayer playback to OptiView Lens and links THEOplayer's own CMCD data to the Lens session. It is available through Swift Package Manager only. ## [11.0.7] - 2026-11-05 diff --git a/Code/Lens-Examples/LensExample.xcodeproj/project.pbxproj b/Code/Lens-Examples/LensExample.xcodeproj/project.pbxproj index 305a6c90..0e2af692 100644 --- a/Code/Lens-Examples/LensExample.xcodeproj/project.pbxproj +++ b/Code/Lens-Examples/LensExample.xcodeproj/project.pbxproj @@ -355,7 +355,7 @@ repositoryURL = "https://github.com/Dolby-OptiView/optiview-lens-sdk-swift"; requirement = { kind = upToNextMinorVersion; - minimumVersion = 0.6.2; + minimumVersion = 0.7.0; }; }; /* End XCRemoteSwiftPackageReference section */ diff --git a/Code/Lens-Examples/LensExample/ViewController.swift b/Code/Lens-Examples/LensExample/ViewController.swift index 225dd06c..26c8f471 100644 --- a/Code/Lens-Examples/LensExample/ViewController.swift +++ b/Code/Lens-Examples/LensExample/ViewController.swift @@ -195,7 +195,7 @@ class ViewController: UIViewController, UITableViewDataSource, UITableViewDelega private func showSession() { guard let lensConnector else { return } - sessionLabel.text = lensConnector.handle.session.map { "Lens session \($0.sessionId)" } ?? "No Lens session: load a source and play" + sessionLabel.text = lensConnector.handle.session.map { "Lens session \($0.sessionId)" } ?? "No Lens session: load a source" } // MARK: Scenario and staging diff --git a/Code/Lens/README.md b/Code/Lens/README.md index 85b4c16a..c18edba9 100644 --- a/Code/Lens/README.md +++ b/Code/Lens/README.md @@ -4,7 +4,7 @@ THEOplayer-Connector-Lens reports a THEOplayer to the [OptiView Lens SDK](https: ## Installation -The Lens SDK is distributed with Swift Package Manager only, and so is this connector. +This connector is distributed with Swift Package Manager. It requires the THEOplayer iOS SDK 11.16.0 or later, the Lens SDK 0.7, and Xcode 26.2 or later. In Xcode, go to **File > Add Package Dependencies...** and add: @@ -12,7 +12,7 @@ In Xcode, go to **File > Add Package Dependencies...** and add: https://github.com/THEOplayer/iOS-Connector ``` -Then select the `THEOplayerConnectorLens` product. To call the Lens SDK from your app, for example to configure it or to report events of your own, also add `https://github.com/Dolby-OptiView/optiview-lens-sdk-swift` and select its `LensSDK` product. +Then select the `THEOplayerConnectorLens` product. To call the Lens SDK from your app, for example to configure it or to report events of your own, also add `https://github.com/Dolby-OptiView/optiview-lens-sdk-swift` and select its `LensSDK` product. The Lens SDK is a prebuilt dynamic framework: the connector links it, and your app embeds it once, which Xcode does for an app target, so every Lens-based SDK in the app shares that copy. ## Usage @@ -24,7 +24,9 @@ import THEOplayerConnectorLens let lensConnector = try LensConnector(player: player) ``` -Lens starts a session at the first play request on each source, and ends it when the source is replaced or removed. Lens keeps the player alive while the connector is joined: destroy the connector before you release the player (see Destroying). +Lens decides a session when a source is set, starts reporting it at the first play request, and ends it when the source is replaced or removed. Lens keeps the player alive while the connector is joined: destroy the connector before you release the player (see Destroying). + +The connector also links the CMCD data THEOplayer sends itself to the Lens session: while the connector is joined, that data carries the current Lens session ID as `lsid`. Lens reports to the OptiView ingest by default. The configuration takes the options of `Lens.join`, except the namespace and the player, for example to add destinations of your own: diff --git a/Code/Lens/Source/LensConnector.swift b/Code/Lens/Source/LensConnector.swift index 7bd6d59d..dc06b158 100644 --- a/Code/Lens/Source/LensConnector.swift +++ b/Code/Lens/Source/LensConnector.swift @@ -3,7 +3,7 @@ // import LensSDK -import THEOplayerSDK +@_spi(Core) import THEOplayerSDK /// The configuration of a `LensConnector`: the options of `Lens.join`, without the namespace and the player, which the /// connector provides. @@ -38,7 +38,8 @@ public struct LensConfiguration { /// The connector between a THEOplayer and Dolby OptiView Lens. /// /// The connector joins Lens with a player adapter for the given player, in the `theoplayer` namespace, so Lens reports -/// playback on its own: sessions, playback states, errors and the player's CMCD keys. +/// playback on its own: sessions, playback states, errors and the player's CMCD keys. While joined, the CMCD data the +/// player sends itself carries the Lens session ID, linking it to the Lens session. /// /// - Important: Lens keeps the player alive while the connector is joined. Call `destroy()` when you are done with the /// player, before you release it. @@ -50,6 +51,8 @@ public final class LensConnector { /// The Lens player adapter for the player. public let adapter: THEOplayerLensAdapter + private let sessionLink: SessionLink + /// Creates a connector for the given player and joins Lens. /// /// - Parameters: @@ -68,10 +71,28 @@ public final class LensConnector { ) if let heartbeatMs = configuration.heartbeatMs { options.heartbeatMs = heartbeatMs } handle = try Lens.join(options) + sessionLink = SessionLink(player: player) + handle.addSessionDelegate(sessionLink) + player.cmcd.linkedSessionId = handle.session?.sessionId } /// Ends the session, stops reporting the player, and lets Lens release it. public func destroy() { + handle.removeSessionDelegate(sessionLink) + sessionLink.player?.cmcd.linkedSessionId = nil handle.dispose() } } + +/// Keeps the player's linked CMCD session ID on the Lens session the handle is in. +private final class SessionLink: LensSessionDelegate { + weak var player: THEOplayer? + + init(player: THEOplayer) { + self.player = player + } + + func lensHandle(_ handle: LensHandle, didChangeSession session: LensSession?) { + player?.cmcd.linkedSessionId = session?.sessionId + } +} diff --git a/Code/Lens/Tests/THEOplayerLensAdapterTests.swift b/Code/Lens/Tests/THEOplayerLensAdapterTests.swift index 4ef8e6e6..d3a20e93 100644 --- a/Code/Lens/Tests/THEOplayerLensAdapterTests.swift +++ b/Code/Lens/Tests/THEOplayerLensAdapterTests.swift @@ -1,7 +1,7 @@ import LensSDK import XCTest @testable import THEOplayerConnectorLens -import THEOplayerSDK +@_spi(Core) import THEOplayerSDK @MainActor final class THEOplayerLensAdapterTests: XCTestCase { @@ -318,16 +318,53 @@ final class THEOplayerLensAdapterTests: XCTestCase { XCTAssertFalse(isLowLatency(source("application/x-mpegurl"))) } - func testTheConnectorStartsASessionAtTheFirstPlayRequest() throws { + func testTheConnectorDecidesTheSessionWithTheSourceAndKeepsItAtPlay() throws { let player = THEOplayer() let connector = try connect(player) defer { connector.destroy() } - load(mp4Source, into: player) XCTAssertNil(connector.handle.session) + load(mp4Source, into: player) + waitForSession(of: connector.handle) + let decided = connector.handle.session?.sessionId - player.play() + waitForNext(PlayerEventTypes.PLAYING, on: player) { player.play() } + XCTAssertEqual(connector.handle.session?.sessionId, decided) + } + + func testThePlayersLinkedSessionIdFollowsTheLensSession() throws { + let player = THEOplayer() + let connector = try connect(player) + XCTAssertNil(player.cmcd.linkedSessionId) + + load(mp4Source, into: player) waitForSession(of: connector.handle) + let first = connector.handle.session?.sessionId + XCTAssertNotNil(first) + XCTAssertEqual(player.cmcd.linkedSessionId, first) + + load(SourceDescription(source: TypedSource(src: TestMedia.mp4.absoluteString, type: "video/mp4")), into: player) + wait(for: [XCTNSPredicateExpectation(predicate: NSPredicate { _, _ in connector.handle.session?.sessionId != first }, object: nil)], timeout: 5) + XCTAssertNotNil(connector.handle.session) + XCTAssertEqual(player.cmcd.linkedSessionId, connector.handle.session?.sessionId) + + connector.destroy() + + XCTAssertNil(player.cmcd.linkedSessionId) + } + + func testTheLinkedSessionIdIsSetWhenJoiningASessionInProgress() throws { + let player = THEOplayer() + try Lens.configure(LensConfigureOptions(backend: .disabled)) + let other = try Lens.join(LensJoinOptions(namespace: "other_sdk", player: player)) + defer { other.dispose() } + let session = other.startSession() + + let connector = try LensConnector(player: player) + defer { connector.destroy() } + + XCTAssertEqual(connector.handle.session?.sessionId, session.sessionId) + XCTAssertEqual(player.cmcd.linkedSessionId, session.sessionId) } func testAnSDKJoiningWithThePlayerSharesTheSession() throws { @@ -386,6 +423,16 @@ final class THEOplayerLensAdapterTests: XCTestCase { wait(for: [XCTNSPredicateExpectation(predicate: NSPredicate { _, _ in handle.session != nil }, object: nil)], timeout: 5) } + /// Runs `action`, then waits for the player's next event of `type`. + private func waitForNext(_ type: EventType, on player: THEOplayer, after action: () -> Void) { + let fired = expectation(description: type.name) + fired.assertForOverFulfill = false + let listener = player.addEventListener(type: type) { _ in fired.fulfill() } + action() + wait(for: [fired], timeout: 5) + player.removeEventListener(type: type, listener: listener) + } + /// Lens releases its subscription once its last handle on the player is disposed. private func waitForRelease(of adapter: THEOplayerLensAdapter) { wait(for: [XCTNSPredicateExpectation(predicate: NSPredicate { _, _ in !adapter.subscribed }, object: nil)], timeout: 5) diff --git a/Package.swift b/Package.swift index 58f77501..371b670d 100644 --- a/Package.swift +++ b/Package.swift @@ -26,12 +26,12 @@ let package = Package( ], dependencies: [ .package(name: "ConvivaSDK", url: "https://github.com/Conviva/conviva-ios-sdk-spm", "4.3.1"..<"4.4.0"), - .package(name: "THEOplayerSDK", url: "https://github.com/THEOplayer/theoplayer-sdk-apple", "11.0.0"..<"12.0.0"), + .package(name: "THEOplayerSDK", url: "https://github.com/THEOplayer/theoplayer-sdk-apple", "11.16.0"..<"12.0.0"), .package(name: "NielsenAppApi", url: "https://github.com/NielsenDigitalSDK/nielsenappsdk-ios-dynamic-spm-global", "10.0.0"..<"11.0.0"), .package(name: "Swifter", url: "https://github.com/httpswift/swifter.git", .exactItem("1.5.0")), .package(name: "SwiftSubtitles", url: "https://github.com/dagronf/SwiftSubtitles.git", .exactItem("0.9.1")), .package(name: "ComScore", url: "https://github.com/comScore/Comscore-Swift-Package-Manager", "6.10.0"..<"6.11.0"), - .package(url: "https://github.com/Dolby-OptiView/optiview-lens-sdk-swift", "0.6.2"..<"0.7.0"), + .package(url: "https://github.com/Dolby-OptiView/optiview-lens-sdk-swift", "0.7.0"..<"0.8.0"), ], targets: [ .target(