diff --git a/theoads/api/ads-client.swagger.json b/theoads/api/ads-client.swagger.json
index 909e8fe4c29..1df1754d314 100644
--- a/theoads/api/ads-client.swagger.json
+++ b/theoads/api/ads-client.swagger.json
@@ -6,6 +6,13 @@
"requestBodies": {},
"responses": {},
"schemas": {
+ "MonetizedStreamType": {
+ "enum": [
+ "LIVE",
+ "VOD"
+ ],
+ "type": "string"
+ },
"MonetizedStreamLayout": {
"enum": [
"SINGLE",
@@ -26,6 +33,9 @@
"streamId": {
"type": "string"
},
+ "streamType": {
+ "$ref": "#/components/schemas/MonetizedStreamType"
+ },
"origin": {
"type": "string"
},
@@ -100,6 +110,9 @@
"version": {
"type": "string"
},
+ "streamType": {
+ "$ref": "#/components/schemas/MonetizedStreamType"
+ },
"origin": {
"type": "string"
},
@@ -152,6 +165,15 @@
},
"assetURI": {
"type": "string"
+ },
+ "asset_key": {
+ "type": "string"
+ },
+ "network_code": {
+ "type": "string"
+ },
+ "backdropURI": {
+ "type": "string"
}
},
"required": [
@@ -403,6 +425,41 @@
"type": "object",
"additionalProperties": false
},
+ "IOverlaysApiResponse": {
+ "properties": {
+ "id": {
+ "type": "string"
+ },
+ "state": {
+ "type": "string",
+ "enum": [
+ "created",
+ "deleted"
+ ]
+ },
+ "type": {
+ "type": "string",
+ "enum": [
+ "overlay"
+ ],
+ "nullable": false
+ },
+ "payload": {
+ "items": {
+ "$ref": "#/components/schemas/IOverlay"
+ },
+ "type": "array"
+ }
+ },
+ "required": [
+ "id",
+ "state",
+ "type",
+ "payload"
+ ],
+ "type": "object",
+ "additionalProperties": false
+ },
"IStatus": {
"properties": {
"status": {
@@ -445,7 +502,7 @@
},
"info": {
"title": "THEOads Api",
- "version": "24.11.6",
+ "version": "25.2.0",
"description": "The THEOads REST API allows you to create and manage monetized streams, which are deployments of signaling services. Each monetized stream corresponds to an origin stream that is monetized using THEOads (SGAI). For detailed information on the various parameters and their usage, please refer to the getting started guide.",
"license": {
"name": "UNLICENSED"
@@ -620,6 +677,59 @@
]
}
},
+ "/monetized-streams/{monetizedStreamId}/layout": {
+ "patch": {
+ "operationId": "UpdateMonetizedStreamLayout",
+ "responses": {
+ "200": {
+ "description": "OK",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/IMonetizedStreamApiResponse"
+ }
+ }
+ }
+ }
+ },
+ "description": "Updates the default layout for an existing monetized stream (signaling service).",
+ "tags": [
+ "Monetized-Stream"
+ ],
+ "security": [],
+ "parameters": [
+ {
+ "description": "The Monetized stream identifier.",
+ "in": "path",
+ "name": "monetizedStreamId",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "requestBody": {
+ "description": "The layout configuration",
+ "required": true,
+ "content": {
+ "application/json": {
+ "schema": {
+ "properties": {
+ "layout": {
+ "$ref": "#/components/schemas/MonetizedStreamLayout"
+ }
+ },
+ "required": [
+ "layout"
+ ],
+ "type": "object",
+ "description": "The layout configuration"
+ }
+ }
+ }
+ }
+ }
+ },
"/monetized-streams/{monetizedStreamId}/break": {
"post": {
"operationId": "CreateMonetizedStreamBreak",
@@ -678,7 +788,7 @@
}
}
},
- "description": "Retrieves all adbreaks linked to the monetized sctream",
+ "description": "Retrieves all adbreaks linked to the monetized stream",
"tags": [
"Monetized-Stream"
],
@@ -711,7 +821,7 @@
}
}
},
- "description": "Deletes an adbreaks linked to the monetized sctream",
+ "description": "Deletes an adbreak linked to the monetized stream",
"tags": [
"Monetized-Stream"
],
@@ -737,22 +847,22 @@
]
}
},
- "/monetized-streams/{monetizedStreamId}/layout": {
- "patch": {
- "operationId": "UpdateMonetizedStreamLayout",
+ "/monetized-streams/{monetizedStreamId}/overlay": {
+ "post": {
+ "operationId": "CreateMonetizedStreamOverlay",
"responses": {
- "200": {
- "description": "OK",
+ "201": {
+ "description": "Created",
"content": {
"application/json": {
"schema": {
- "$ref": "#/components/schemas/IMonetizedStreamApiResponse"
+ "$ref": "#/components/schemas/IOverlayApiResponse"
}
}
}
}
},
- "description": "Updates the default layout for an existing monetized stream (signaling service).",
+ "description": "Creates an overlay on an existing monetized stream (signaling service).",
"tags": [
"Monetized-Stream"
],
@@ -769,33 +879,56 @@
}
],
"requestBody": {
- "description": "The layout configuration",
+ "description": "The overlay configuration",
"required": true,
"content": {
"application/json": {
"schema": {
- "properties": {
- "layout": {
- "$ref": "#/components/schemas/MonetizedStreamLayout"
- }
- },
- "required": [
- "layout"
- ],
- "type": "object",
- "description": "The layout configuration"
+ "$ref": "#/components/schemas/IOverlay",
+ "description": "The overlay configuration"
}
}
}
}
+ },
+ "get": {
+ "operationId": "GetMonetizedStreamOverlays",
+ "responses": {
+ "200": {
+ "description": "A monetized stream",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/IOverlaysApiResponse"
+ }
+ }
+ }
+ }
+ },
+ "description": "Retrieves all overlays linked to the monetized stream",
+ "tags": [
+ "Monetized-Stream"
+ ],
+ "security": [],
+ "parameters": [
+ {
+ "description": "The Monetized stream identifier.",
+ "in": "path",
+ "name": "monetizedStreamId",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ]
}
},
- "/monetized-streams/{monetizedStreamId}/overlay": {
- "post": {
- "operationId": "CreateMonetizedStreamOverlay",
+ "/monetized-streams/{monetizedStreamId}/overlay/{overlayId}": {
+ "delete": {
+ "operationId": "DeleteMonetizedStreamOverlay",
"responses": {
- "201": {
- "description": "Created",
+ "200": {
+ "description": "A monetized stream",
"content": {
"application/json": {
"schema": {
@@ -805,7 +938,7 @@
}
}
},
- "description": "Creates an overlay on an existing monetized stream (signaling service).",
+ "description": "Deletes an overlay linked to the monetized stream",
"tags": [
"Monetized-Stream"
],
@@ -819,20 +952,16 @@
"schema": {
"type": "string"
}
- }
- ],
- "requestBody": {
- "description": "The overlay configuration",
- "required": true,
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/IOverlay",
- "description": "The overlay configuration"
- }
+ },
+ {
+ "in": "path",
+ "name": "overlayId",
+ "required": true,
+ "schema": {
+ "type": "string"
}
}
- }
+ ]
}
},
"/status": {
diff --git a/theoads/api/signaling/sidebar.ts b/theoads/api/signaling/sidebar.ts
index d89c45e96a5..f5e871f99ed 100644
--- a/theoads/api/signaling/sidebar.ts
+++ b/theoads/api/signaling/sidebar.ts
@@ -34,6 +34,12 @@ const sidebar: SidebarsConfig = {
label: "UpdateMonetizedStream",
className: "api-method patch",
},
+ {
+ type: "doc",
+ id: "api/signaling/update-monetized-stream-layout",
+ label: "UpdateMonetizedStreamLayout",
+ className: "api-method patch",
+ },
{
type: "doc",
id: "api/signaling/delete-monetized-stream",
@@ -46,6 +52,18 @@ const sidebar: SidebarsConfig = {
label: "CreateMonetizedStreamBreak",
className: "api-method post",
},
+ {
+ type: "doc",
+ id: "api/signaling/get-monetized-stream-breaks",
+ label: "GetMonetizedStreamBreak",
+ className: "api-method get",
+ },
+ {
+ type: "doc",
+ id: "api/signaling/delete-monetized-stream-breaks",
+ label: "DeleteMonetizedStreamBreak",
+ className: "api-method delete",
+ },
{
type: "doc",
id: "api/signaling/create-monetized-stream-overlay",
@@ -54,9 +72,15 @@ const sidebar: SidebarsConfig = {
},
{
type: "doc",
- id: "api/signaling/update-monetized-stream-layout",
- label: "UpdateMonetizedStreamLayout",
- className: "api-method patch",
+ id: "api/signaling/get-monetized-stream-overlays",
+ label: "GetMonetizedStreamOverlay",
+ className: "api-method get",
+ },
+ {
+ type: "doc",
+ id: "api/signaling/delete-monetized-stream-overlay",
+ label: "DeleteMonetizedStreamOverlay",
+ className: "api-method delete",
},
],
},
diff --git a/theoads/assets/img/theoads-ios-swiftpm-menu-google.png b/theoads/assets/img/theoads-ios-swiftpm-menu-google.png
new file mode 100644
index 00000000000..924ad0000c4
Binary files /dev/null and b/theoads/assets/img/theoads-ios-swiftpm-menu-google.png differ
diff --git a/theoads/assets/img/theoads-ios-swiftpm-menu.png b/theoads/assets/img/theoads-ios-swiftpm-menu.png
new file mode 100644
index 00000000000..4a2528560f1
Binary files /dev/null and b/theoads/assets/img/theoads-ios-swiftpm-menu.png differ
diff --git a/theoads/assets/img/theoads-ios-swiftpm-product-selection-google.png b/theoads/assets/img/theoads-ios-swiftpm-product-selection-google.png
new file mode 100644
index 00000000000..04a01bcd364
Binary files /dev/null and b/theoads/assets/img/theoads-ios-swiftpm-product-selection-google.png differ
diff --git a/theoads/assets/img/theoads-ios-swiftpm-product-selection.png b/theoads/assets/img/theoads-ios-swiftpm-product-selection.png
new file mode 100644
index 00000000000..350c0e91dda
Binary files /dev/null and b/theoads/assets/img/theoads-ios-swiftpm-product-selection.png differ
diff --git a/theoads/assets/img/theoads-ios-xcode-file-menu.png b/theoads/assets/img/theoads-ios-xcode-file-menu.png
new file mode 100644
index 00000000000..fe6a617c34e
Binary files /dev/null and b/theoads/assets/img/theoads-ios-xcode-file-menu.png differ
diff --git a/theoads/getting-started/00-getting-started-ios.mdx b/theoads/getting-started/00-getting-started-ios.mdx
new file mode 100644
index 00000000000..2337d4065b9
--- /dev/null
+++ b/theoads/getting-started/00-getting-started-ios.mdx
@@ -0,0 +1,151 @@
+---
+sidebar_position: 0.3
+sidebar_label: iOS
+sidebar_custom_props: { 'icon': 'apple' }
+---
+
+# Getting started with THEOads on iOS
+
+This guide will get you started to integrate THEOads in your THEOplayer iOS SDK: configure the license, update dependencies and set the source description.
+
+## Prerequisites
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+1. You need to have a THEOplayer license which is compatible with THEOads.
+ This can be done through [https://portal.theoplayer.com](https://portal.theoplayer.com).
+2. You need a working [THEOads signaling service](00-getting-started-signaling-service.mdx).
+3. Add the THEOplayer iOS SDK to your project by following our [Getting started](/theoplayer/getting-started/sdks/ios/getting-started) guide.
+ Make sure to [set up a THEOads-compatible license](/theoplayer/getting-started/sdks/ios/getting-started/#theoplayer-license)
+ in your app.
+4. Add the THEOads integration as a dependency to your project:
+
+
+
+ 1. Add the `THEOplayer-Integration-THEOads` pod to your Podfile:
+ ```sh
+ pod 'THEOplayer-Integration-THEOads', '~> 8.10.0'
+ ```
+ 2. Install the new pod:
+ ```sh
+ pod install
+ ```
+
+
+ 1. Open your Xcode project and navigate to File > Add Package Dependencies...
+
+ 
+
+ 2. Add `theoplayer-sdk-apple` package by entering the following url:
+ ```sh
+ https://github.com/THEOplayer/theoplayer-sdk-apple
+ ```
+ 
+
+ 3. Select `THEOplayerTHEOadsIntegration` from the package products list and add it to your target.
+
+ 
+
+
+
+
+
+5. Add Google IMA SDK as a dependency to your project:
+
+
+
+ 1. The `THEOplayer-Integration-THEOads` pod has a dependency on `GoogleAds-IMA-iOS-SDK` which should be installed automatically.
+
+
+ 1. Open your Xcode project and navigate to File > Add Package Dependencies...
+
+ 
+
+ 2. Add `swift-package-manager-google-interactive-media-ads-ios` package by entering the following url:
+ ```sh
+ https://github.com/googleads/swift-package-manager-google-interactive-media-ads-ios
+ ```
+ 
+
+ 3. Select `GoogleInteractiveMediaAds` from the package products list and add it to your target.
+
+ 
+
+
+
+
+
+## Integration
+
+To make use of the THEOads integration, create and add the `THEOadsIntegration` to your `THEOplayer` instance:
+
+```swift
+import UIKit
+import THEOplayerSDK
+import THEOplayerTHEOadsIntegration
+
+class ViewController: UIViewController {
+ var theoplayer: THEOplayer!
+ var theoads: THEOadsIntegration!
+
+ override func viewDidLoad() {
+ super.viewDidLoad()
+ self.theoplayer = THEOplayer(configuration: THEOplayerConfigurationBuilder().build())
+ self.theoplayer.frame = view.bounds
+ self.theoplayer.addAsSubview(of: view)
+ self.theoads = THEOadsIntegrationFactory.createIntegration(on: self.theoplayer)
+ self.theoplayer.addIntegration(self.theoads)
+ }
+
+}
+```
+
+Then, configure a source containing a `THEOAdDescription`:
+
+```swift
+import UIKit
+import THEOplayerSDK
+import THEOplayerTHEOadsIntegration
+
+class ViewController: UIViewController {
+ var theoplayer: THEOplayer!
+ var theoads: THEOadsIntegration!
+
+ override func viewDidLoad() {
+ super.viewDidLoad()
+ self.theoplayer = THEOplayer(configuration: THEOplayerConfigurationBuilder().build())
+ self.theoplayer.frame = view.bounds
+ self.theoplayer.addAsSubview(of: view)
+ self.theoads = THEOadsIntegrationFactory.createIntegration(on: self.theoplayer)
+ self.theoplayer.addIntegration(self.theoads)
+
+ let source = "PATH-TO-SIGNALING-SERVER/hls/MANIFEST-URI"
+ let typedSource = TypedSource(
+ src: source,
+ type: "application/x-mpegurl",
+ hlsDateRange: true
+ )
+ let theoad = THEOAdDescription(
+ networkCode: "NETWORK-CODE",
+ customAssetKey: "CUSTOM-ASSET-KEY"
+ )
+ let sourceDescription = SourceDescription(source: typedSource, ads: [theoad])
+ self.theoplayer.source = sourceDescription
+ self.theoplayer.play()
+ }
+
+}
+```
+
+- Notice that the `src` is different as usual. For THEOads, a signaling server needs to be set up which acts as a proxy to parse the given manifest and insert the ad interstitials.
+ More information can be found [here](00-getting-started-signaling-service.mdx).
+- The `hlsDateRange` flag needs to be set to `true` as the ad markers are done using `EXT-X-DATERANGE` tags.
+- The `ads` array needs to contain a `THEOAdDescription`. Furthermore, the `networkCode` and `customAssetKey` needs to be set according to your configured Google account.
+
+## More information
+
+- [What is THEOads?](https://www.theoplayer.com/product/theoads/)
+- [The Advantages of Server-Guided Ad Insertion](https://www.theoplayer.com/solutions/server-guided-ad-insertion-sgai/)
+- [Flexible, Usage-Based Pricing](https://www.theoplayer.com/product/theoads/pricing/)
+- [Is Server-Guided Ad-Insertion (SGAI) revolutionizing streaming monetization? (blog)](https://www.theoplayer.com/blog/server-guided-ad-insertion-sgai-revolutionizing-streaming-monetization/)
diff --git a/theoads/getting-started/00-getting-started-signaling-service.mdx b/theoads/getting-started/00-getting-started-signaling-service.mdx
index 2cc720f2c9d..32bb528210c 100644
--- a/theoads/getting-started/00-getting-started-signaling-service.mdx
+++ b/theoads/getting-started/00-getting-started-signaling-service.mdx
@@ -37,6 +37,7 @@ The monetized stream holds the following information:
- `networkCode`: Google DAI Network-Code, see [Google DAI](https://support.google.com/admanager/topic/7062524?hl=en).
- `assetURI`: Optional custom asset URI which is to be used during ad breaks. If not set it will request an adbreak through Google Pod Serving.
- `backdropURI`: Optional URI containing the back-drop to be used during the double box or L-shape ad.
+- `streamType`: Optional property to specify this stream's type to be either 'LIVE' (the default) or 'VOD'. Note: this is only relevant for scheduling overlays for now.
```json
{
diff --git a/theoads/how-to-guides/ad-tag-parameters.md b/theoads/how-to-guides/ad-tag-parameters.md
index cad39aa2fd3..f58bcc3d54f 100644
--- a/theoads/how-to-guides/ad-tag-parameters.md
+++ b/theoads/how-to-guides/ad-tag-parameters.md
@@ -89,7 +89,20 @@ theoPlayerView.player.source = SourceDescription.Builder(
## iOS SDK
-This API is currently under development and will become available soon.
+For the iOS SDK, you can set your desired ad tag parameters via `adTagParameters` in the `THEOAdDescription` as followed:
+
+```swift
+let theoad = THEOAdDescription(
+ networkCode: "NETWORK-CODE",
+ customAssetKey: "CUSTOM-ASSET-KEY",
+ adTagParameters: [
+ "YOUR-AD-TAG-PARAMETER-1" : "VALUE-1",
+ "YOUR-AD-TAG-PARAMETER-2" : "VALUE-2"
+ ]
+)
+let sourceDescription = SourceDescription(source: typedSource, ads: [theoad])
+self.theoplayer.source = sourceDescription
+```
## More information
diff --git a/theoads/how-to-guides/override-layout.md b/theoads/how-to-guides/override-layout.md
index a3ce1a9fef4..d2837f84a68 100644
--- a/theoads/how-to-guides/override-layout.md
+++ b/theoads/how-to-guides/override-layout.md
@@ -87,7 +87,7 @@ player.source = {
integration: 'theoads',
networkCode: 'NETWORK-CODE',
customAssetKey: 'CUSTOM-ASSET-KEY',
- overrideLayout: 'YOUR-DESIRED-LAYOUT',
+ overrideLayout: 'single', //"l-shape", "double", "single-if-mobile"
},
],
};
@@ -112,14 +112,50 @@ theoPlayerView.player.source = SourceDescription.Builder(
TheoAdsDescription(
networkCode = "NETWORK-CODE",
customAssetKey = "CUSTOM-ASSET-KEY",
- overrideLayout = "YOUR-DESIRED-LAYOUT"
+ overrideLayout = "single", //"l-shape", "double"
)
).build()
```
### iOS SDK
-This API is currently under development and will become available soon.
+For the iOS SDK, you can override the default layout by setting `overrideLayout` in the `THEOAdDescription` object as follows:
+
+```swift
+import UIKit
+import THEOplayerSDK
+import THEOplayerTHEOadsIntegration
+
+class ViewController: UIViewController {
+ var theoplayer: THEOplayer!
+ var theoads: THEOadsIntegration!
+
+ override func viewDidLoad() {
+ super.viewDidLoad()
+ self.theoplayer = THEOplayer(configuration: THEOplayerConfigurationBuilder().build())
+ self.theoplayer.frame = view.bounds
+ self.theoplayer.addAsSubview(of: view)
+ self.theoads = THEOadsIntegrationFactory.createIntegration(on: self.theoplayer)
+ self.theoplayer.addIntegration(self.theoads)
+
+ let source = "PATH-TO-SIGNALING-SERVER/hls/MANIFEST-URI"
+ let typedSource = TypedSource(
+ src: source,
+ type: "application/x-mpegurl",
+ hlsDateRange: true
+ )
+ let theoad = THEOAdDescription(
+ networkCode: "NETWORK-CODE",
+ customAssetKey: "CUSTOM-ASSET-KEY",
+ overrideLayout: .single // .double or .lshape
+ )
+ let sourceDescription = SourceDescription(source: typedSource, ads: [theoad])
+ self.theoplayer.source = sourceDescription
+ self.theoplayer.play()
+ }
+
+}
+```
## More information