Merge pull request #49 from THEOplayer/feature/yospace-release

Feature/yospace release

.github/workflows/bump-and-release.yml

@@ -23,6 +23,7 @@ on:
           - Comscore
           - Conviva
           - SideloadedSubtitle
+          - Yospace
 jobs:
   Bump-And-Release:
     runs-on: macos-14

CHANGELOG.md

@@ -5,6 +5,13 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## Unreleased
+
+### Added
+
+- Yospace
+  - Added Yospace integration with THEOplayer to allow playback of server-side ad inserted streams.
+
 ## [7.5.0] - 2024-06-06
 
 ### Fixed

Code/Yospace/README.md

@@ -0,0 +1,96 @@
+# THEOPlayer 🤝 Yospace
+
+THEOplayer-Connector-Yospace provides an integration between the THEOplayerSDK and Yospace to allow playback of server-side ad inserted streams.
+
+## Installation
+
+### [Swift Package Manager](https://swift.org/package-manager/)
+
+1. In Xcode, install the Yospace connector by navigating to **File > Add Packages**
+2. In the prompt that appears, select the iOS-Connector GitHub repository: `https://github.com/THEOplayer/iOS-Connector`
+3. Select the version you want to use.
+4. Choose the Connector libraries you want to include in your app.
+
+To support custom feature builds of THEOplayerSDK perform the following steps:
+
+1. Clone this repository to your computer.
+2. Use a [local override](https://developer.apple.com/documentation/xcode/editing-a-package-dependency-as-a-local-package) of the `theoplayer-sdk-ios` package by selecting the folder `../../Helpers/TheoSPM/theoplayer-sdk-ios` in Finder and dragging it into the Project navigator of your Xcode project.
+3. Place your custom THEOplayerSDK.xcframework at `../../Helpers/TheoSPM/theoplayer-sdk-ios/THEOplayerSDK.xcframework`. (It is also possible to place your xcframework somewhere else. In that case make sure to update the [Package.swift](../../Helpers/TheoSPM/theoplayer-sdk-ios/Package.swift) manifest inside the your local override so that it points to your custom THEOplayer build)
+4. If Xcode complains about a missing xcframework
+   1. Choose `File` > `Packages` > `Reset Package Caches` from the menu bar.
+   2. If it is still not working, make sure to remove any `THEOplayerSDK.xcframework` inclusions that you manually installed before installing this connector package.
+
+### [Cocoapods](https://guides.cocoapods.org/using/getting-started.html#getting-started)
+
+1. Create a Podfile if you don't already have one. From the root of your project directory, run the following command: `pod init`
+2. To your Podfile, add the Yospace connector pods that you want to use in your app: `pod 'THEOplayer-Connector-Yospace'`
+3. Install the pods using `pod install` , then open your `.xcworkspace` file to see the project in Xcode.
+
+To support custom feature builds of THEOplayerSDK perform the following steps:
+
+1. Clone this repository to your computer.
+2. Use a [local override](https://guides.cocoapods.org/using/the-podfile.html#using-the-files-from-a-folder-local-to-the-machine) of the `THEOplayerSDK-basic` pod by adding the following line to your projects Podfile: `pod 'THEOplayerSDK-basic', :path => 'iOS-Connector/Helpers/TheoPod'` and make sure the path points to the [TheoPod folder](../../Helpers/TheoPod).
+
+## Dependencies
+
+The THEOPlayer Yospace connector has two dependency frameworks: THEOplayerSDK and YOAdManagement.
+
+THEOplayerSDK is added as a dependency on both Cocoapods and SPM and will be fetched by each dependency manager.
+YOAdManagement is published as a private pod hosted on Artifactory by jfrog. In order to get the framework you will need to:
+1. Setup a Yospace developer account at https://www.yospace.com/developer
+2. Login to the Yospace Apple docs https://developer.yospace.com/sdk-documentation/apple/userguide/latest/en/index-en.html
+3. Follow the instructions to setup the artifactory, authenticate, and fetch the framework at https://developer.yospace.com/sdk-documentation/apple/userguide/latest/en/prerequisites.html
+
+## Usage
+
+Import the `THEOplayerConnectorYospace` module
+
+```swift
+import THEOplayerConnectorYospace
+```
+
+Create a `SourceDescription` that defines the Yospace stream:
+
+```swift
+let streamType: YospaceStreamType = .live
+let typedSource: TypedSource = .init(
+    src: "yospace_live_stream_url",
+    type: "application/x-mpegurl",
+    ssai: YospaceServerSideAdInsertionConfiguration(streamType: streamType)
+)
+let source: SourceDescription = SourceDescription(source: typedSource)
+```
+
+Create a `YospaceConnector` that uses a `THEOplayer` instance:
+
+```swift
+let theoplayer: THEOplayer = .init()
+let connector: YospaceConnector = .init(player: theoplayer)
+```
+
+**Note:** Hold a reference to your connector instance by storing it as a property. Keeping it inline will get it auto-released from memory. Once the connector is released from memory it will reset and unload autonomously.
+
+Set the source and play. There are 2 ways to set a Yospace source:
+
+1. Through the API provided by the YospaceConnector:
+
+```swift
+connector.setupYospaceSession(sourceDescription: source)
+```
+
+The connector will then fire a `SESSION_AVAILABLE` event once the setup is successful. The client can track this event to start playback:
+
+```swift
+_ = connector.addEventListener(type: YospaceEventTypes.SESSION_AVAILABLE, listener: { event in
+    theoplayer.play()
+})
+```
+
+When using the `setupYospaceSession` API, the connector will throw an error in case the `TypedSource` is not of type `YospaceServerSideAdInsertionConfiguration`.
+
+2. Through the player:
+
+```swift
+theoplayer.source = source
+theoplayer.play()
+```

Package.swift

@@ -16,6 +16,8 @@ let package = Package(
         .library(name: "THEOplayerConnectorUtilities", targets: ["THEOplayerConnectorUtilities"]),
 
         .library(name: "THEOplayerConnectorSideloadedSubtitle", targets: ["THEOplayerConnectorSideloadedSubtitle"]),
+
+        .library(name: "THEOplayerConnectorYospace", targets: ["THEOplayerConnectorYospace"]),
     ],
     dependencies: [
         .package(name: "ConvivaSDK", url: "https://github.com/Conviva/conviva-ios-sdk-spm", from: "4.0.30"),
@@ -75,5 +77,13 @@ let package = Package(
             path: "Code/Sideloaded-TextTracks/Sources/THEOplayerConnectorSideloadedSubtitle" 
         ),
 
+        // Yospace \\
+        .target(
+            name: "THEOplayerConnectorYospace",
+            dependencies: [
+                "THEOplayerSDK",
+            ],
+            path: "Code/Yospace/Source"
+        ),
     ]
 )

Readme.md

@@ -6,6 +6,7 @@ A collection of components that connect third party software with THEOplayer for
 -   [THEOplayer-Connector-**Nielsen**](./Code/Nielsen)
 -   [THEOplayer-Connector-**Comscore**](./Code/Comscore)
 -   [THEOplayer-Connector-**SideloadedSubtitle**](./Code/Sideloaded-TextTracks)
+-   [THEOplayer-Connector-**Yospace**](./Code/Yospace)
 
 ## Other platforms
 

THEOplayer-Connector-Yospace.podspec

@@ -0,0 +1,23 @@
+require_relative './THEOplayer-Connector-Version'
+
+Pod::Spec.new do |s|
+  s.name             = 'THEOplayer-Connector-Yospace'
+  s.module_name      = 'THEOplayerConnectorYospace'
+  s.version          = theoplayer_connector_version
+  s.summary          = 'Integration between the THEOplayerSDK and Yospace'
+
+  s.description      = 'This pod gives you access to classes that help integrate Yospace with THEOplayer to allow playback of server-side ad inserted streams.'
+
+  s.homepage         = 'https://github.com/THEOplayer/iOS-Connector'
+  s.license          = { :type => 'MIT', :file => 'LICENSE' }
+  s.author           = "THEO technologies"
+  s.source           = { :git => 'https://github.com/THEOplayer/iOS-Connector.git', :tag => s.version.to_s }
+
+  s.platforms    = { :ios => "12.0", :tvos => "12.0" }
+
+  s.source_files = 'Code/Yospace/Source/**/*'
+
+  s.static_framework = true
+  s.swift_versions = ['5.3', '5.4', '5.5', '5.6', '5.7']
+  s.dependency 'THEOplayerSDK-core', "~> 7.7"
+end