Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
2 changes: 1 addition & 1 deletion Code/Lens-Examples/LensExample.xcodeproj/project.pbxproj
Original file line number Diff line number Diff line change
Expand Up @@ -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 */
Expand Down
2 changes: 1 addition & 1 deletion Code/Lens-Examples/LensExample/ViewController.swift
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
8 changes: 5 additions & 3 deletions Code/Lens/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,15 +4,15 @@ 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:

```
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

Expand All @@ -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:

Expand Down
25 changes: 23 additions & 2 deletions Code/Lens/Source/LensConnector.swift
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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.
Expand All @@ -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:
Expand All @@ -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
}
}
55 changes: 51 additions & 4 deletions Code/Lens/Tests/THEOplayerLensAdapterTests.swift
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
import LensSDK
import XCTest
@testable import THEOplayerConnectorLens
import THEOplayerSDK
@_spi(Core) import THEOplayerSDK

@MainActor
final class THEOplayerLensAdapterTests: XCTestCase {
Expand Down Expand Up @@ -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 {
Expand Down Expand Up @@ -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<E: EventProtocol>(_ type: EventType<E>, 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)
Expand Down
4 changes: 2 additions & 2 deletions Package.swift
Original file line number Diff line number Diff line change
Expand Up @@ -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(
Expand Down
Loading