From 396850a5a5a006f735851a9cd9de06790c895414 Mon Sep 17 00:00:00 2001 From: Gilles Moris Date: Tue, 17 Nov 2026 00:20:09 +0100 Subject: [PATCH 1/4] Link THEOplayer's own CMCD data to the Lens session with Lens SDK 0.7.0 The connector keeps player.cmcd.linkedSessionId equal to its handle's Lens session ID through the session delegate Lens 0.7.0 adds: set after join, updated on every session change, cleared on destroy. Lens 0.7.0 ships LensSDK as a prebuilt dynamic framework, which the connector links and the app embeds once, and decides the session when a source is set. THEOplayer gains cmcd.linkedSessionId in 11.16.0 (theoplayer-next PR 8186), hence the new minimum. Generated with [Devin](https://devin.ai) Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com> --- Code/Lens/Source/LensConnector.swift | 23 +++++++- .../Tests/THEOplayerLensAdapterTests.swift | 53 +++++++++++++++++-- Package.swift | 4 +- 3 files changed, 74 insertions(+), 6 deletions(-) diff --git a/Code/Lens/Source/LensConnector.swift b/Code/Lens/Source/LensConnector.swift index 7bd6d59d..0675056f 100644 --- a/Code/Lens/Source/LensConnector.swift +++ b/Code/Lens/Source/LensConnector.swift @@ -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. It keeps the player's +/// `cmcd.linkedSessionId` equal to the Lens session ID, so the player's own CMCD data links 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..d337dc36 100644 --- a/Code/Lens/Tests/THEOplayerLensAdapterTests.swift +++ b/Code/Lens/Tests/THEOplayerLensAdapterTests.swift @@ -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( From 33a530a3ddd14369c48e8f786fcfc915c928cac9 Mon Sep 17 00:00:00 2001 From: Gilles Moris Date: Tue, 17 Nov 2026 00:20:09 +0100 Subject: [PATCH 2/4] Document the linked CMCD session and the Lens 0.7 framework, and require it in the example Generated with [Devin](https://devin.ai) Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com> --- CHANGELOG.md | 2 +- Code/Lens-Examples/LensExample.xcodeproj/project.pbxproj | 2 +- Code/Lens-Examples/LensExample/ViewController.swift | 2 +- Code/Lens/README.md | 8 +++++--- 4 files changed, 8 insertions(+), 6 deletions(-) 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..13882665 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 keeps the player's `cmcd.linkedSessionId` equal to the Lens session ID, so the CMCD data THEOplayer sends itself carries it as `lsid` and links to the Lens session. It sets it when it joins, updates it on every session change, and clears it when destroyed. 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: From d490ca0fc626be7747063a8f3a92400b1abf0b08 Mon Sep 17 00:00:00 2001 From: Gilles Moris Date: Tue, 17 Nov 2026 09:34:52 +0100 Subject: [PATCH 3/4] Import THEOplayerSDK with SPI Core where the connector sets linkedSessionId THEOplayer.cmcd and the CMCD protocol moved behind @_spi(Core) in theoplayer-next PR 8186. Generated with [Devin](https://devin.ai) Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com> --- Code/Lens/Source/LensConnector.swift | 2 +- Code/Lens/Tests/THEOplayerLensAdapterTests.swift | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/Code/Lens/Source/LensConnector.swift b/Code/Lens/Source/LensConnector.swift index 0675056f..7f4d13c6 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. diff --git a/Code/Lens/Tests/THEOplayerLensAdapterTests.swift b/Code/Lens/Tests/THEOplayerLensAdapterTests.swift index d337dc36..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 { From 72d561b3105b929bb67a10d98cd2c0529e82cbcd Mon Sep 17 00:00:00 2001 From: Gilles Moris Date: Tue, 17 Nov 2026 09:35:01 +0100 Subject: [PATCH 4/4] Describe the linked CMCD session without the internal player API Generated with [Devin](https://devin.ai) Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com> --- Code/Lens/README.md | 2 +- Code/Lens/Source/LensConnector.swift | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/Code/Lens/README.md b/Code/Lens/README.md index 13882665..c18edba9 100644 --- a/Code/Lens/README.md +++ b/Code/Lens/README.md @@ -26,7 +26,7 @@ let lensConnector = try LensConnector(player: player) 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 keeps the player's `cmcd.linkedSessionId` equal to the Lens session ID, so the CMCD data THEOplayer sends itself carries it as `lsid` and links to the Lens session. It sets it when it joins, updates it on every session change, and clears it when destroyed. +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 7f4d13c6..dc06b158 100644 --- a/Code/Lens/Source/LensConnector.swift +++ b/Code/Lens/Source/LensConnector.swift @@ -38,8 +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. It keeps the player's -/// `cmcd.linkedSessionId` equal to the Lens session ID, so the player's own CMCD data links to the Lens session. +/// 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.