diff --git a/.prettierignore b/.prettierignore index 9b93b4abaee6..e2f8a2233143 100644 --- a/.prettierignore +++ b/.prettierignore @@ -17,6 +17,7 @@ theoplayer_versioned_docs/*/changelog.md theoplayer_versioned_docs/*/static/theoplayer/*/api-reference ads/api/ads-client.swagger.json ads/api/signaling/ +ads_versioned_docs/*/api/ adengine/static/ad-engine.yaml adengine/reference/ millicast/api/ diff --git a/ads_versioned_docs/version-v1/api/ads-client.swagger.json b/ads_versioned_docs/version-v1/api/ads-client.swagger.json new file mode 100644 index 000000000000..a56eacc2ae37 --- /dev/null +++ b/ads_versioned_docs/version-v1/api/ads-client.swagger.json @@ -0,0 +1,2005 @@ +{ + "components": { + "examples": {}, + "headers": {}, + "parameters": {}, + "requestBodies": {}, + "responses": {}, + "schemas": { + "IStatus": { + "properties": { + "status": { + "type": "string" + }, + "error": { + "type": "string", + "nullable": true + }, + "uptime": { + "type": "number", + "format": "double" + }, + "timestamp": { + "type": "number", + "format": "double" + }, + "version": { + "type": "string" + } + }, + "required": [ + "status", + "error", + "uptime", + "timestamp", + "version" + ], + "type": "object", + "additionalProperties": false + }, + "MonetizedStreamEvent": { + "properties": { + "name": { + "type": "string" + }, + "description": { + "type": "string" + }, + "startDate": { + "type": "string" + }, + "endDate": { + "type": "string" + }, + "id": { + "type": "string" + }, + "monetizedStream": { + "type": "string" + } + }, + "required": [ + "name", + "description", + "startDate", + "endDate", + "id", + "monetizedStream" + ], + "type": "object", + "additionalProperties": false + }, + "PaginationDetails": { + "properties": { + "total_records": { + "type": "number", + "format": "double" + }, + "current_page": { + "type": "number", + "format": "double" + }, + "total_pages": { + "type": "number", + "format": "double" + }, + "next_page": { + "type": "number", + "format": "double", + "nullable": true + }, + "prev_page": { + "type": "number", + "format": "double", + "nullable": true + } + }, + "required": [ + "total_records", + "current_page", + "total_pages", + "next_page", + "prev_page" + ], + "type": "object", + "additionalProperties": false + }, + "StreamEventResponse": { + "properties": { + "monetizedStream": { + "type": "string" + }, + "data": { + "items": { + "$ref": "#/components/schemas/MonetizedStreamEvent" + }, + "type": "array" + }, + "pagination": { + "$ref": "#/components/schemas/PaginationDetails" + } + }, + "required": [ + "monetizedStream", + "data", + "pagination" + ], + "type": "object", + "additionalProperties": false + }, + "ReturnType_typeofStreamEventUpdateSchema.validateSync_": { + "properties": { + "endDate": { + "type": "string" + }, + "startDate": { + "type": "string" + }, + "description": { + "type": "string" + }, + "name": { + "type": "string" + } + }, + "type": "object", + "description": "Obtain the return type of a function type" + }, + "StreamEventUpdate": { + "$ref": "#/components/schemas/ReturnType_typeofStreamEventUpdateSchema.validateSync_" + }, + "IStreamEvent": { + "properties": { + "name": { + "type": "string" + }, + "description": { + "type": "string" + }, + "startDate": { + "type": "string" + }, + "endDate": { + "type": "string" + } + }, + "required": [ + "name", + "description", + "startDate", + "endDate" + ], + "type": "object", + "additionalProperties": false + }, + "ResourceType.MONETIZED_STREAM": { + "enum": [ + "monetized-stream" + ], + "type": "string" + }, + "MonetizedStreamType": { + "enum": [ + "LIVE", + "VOD" + ], + "type": "string" + }, + "MonetizedStreamLayout": { + "enum": [ + "SINGLE", + "DOUBLE", + "LSHAPE_AD", + "LSHAPE_CONTENT" + ], + "type": "string" + }, + "DynamicDetail": { + "properties": {}, + "additionalProperties": { + "type": "string" + }, + "type": "object" + }, + "AssetKeyDetails": { + "properties": { + "podDuration": { + "type": "number", + "format": "double" + }, + "eabnAdTagParameters": { + "$ref": "#/components/schemas/DynamicDetail" + }, + "adBreakSelectionParameters": { + "$ref": "#/components/schemas/DynamicDetail" + }, + "assetKey": { + "type": "string" + } + }, + "required": [ + "assetKey" + ], + "type": "object" + }, + "IGamProperties": { + "properties": { + "iu": { + "type": "string" + }, + "sz": { + "properties": { + "tv": { + "type": "string" + }, + "phone": { + "type": "string" + }, + "default": { + "type": "string" + } + }, + "required": [ + "default" + ], + "type": "object" + } + }, + "required": [ + "iu", + "sz" + ], + "type": "object", + "additionalProperties": false + }, + "EABNVersion": { + "enum": [ + "V1", + "V2" + ], + "type": "string" + }, + "BumperAdDetails": { + "properties": { + "eabnAdTagParameters": { + "$ref": "#/components/schemas/DynamicDetail" + } + }, + "type": "object" + }, + "IMonetizedStream": { + "properties": { + "name": { + "type": "string" + }, + "version": { + "type": "string" + }, + "streamId": { + "type": "string" + }, + "streamType": { + "$ref": "#/components/schemas/MonetizedStreamType" + }, + "origin": { + "type": "string" + }, + "segmentOrigin": { + "type": "string" + }, + "layout": { + "$ref": "#/components/schemas/MonetizedStreamLayout" + }, + "assetKey": { + "type": "string" + }, + "networkCode": { + "type": "string" + }, + "originPath": { + "type": "string" + }, + "assetURI": { + "type": "string" + }, + "backdropURI": { + "type": "string" + }, + "backdropURIGamProperties": { + "$ref": "#/components/schemas/IGamProperties" + } + }, + "required": [ + "streamId", + "layout" + ], + "type": "object", + "additionalProperties": false + }, + "IMonetizedStreamApiResponse": { + "properties": { + "id": { + "type": "string" + }, + "state": { + "type": "string", + "enum": [ + "created", + "deleted" + ] + }, + "type": { + "$ref": "#/components/schemas/ResourceType.MONETIZED_STREAM" + }, + "payload": { + "$ref": "#/components/schemas/IMonetizedStream" + } + }, + "required": [ + "id", + "state", + "type", + "payload" + ], + "type": "object", + "additionalProperties": false + }, + "ResourceType.MONETIZED_STREAM_REFERENCE_TIME": { + "enum": [ + "monetized-stream-reference-time" + ], + "type": "string" + }, + "IMonetizedStreamReferenceTime": { + "properties": { + "date": { + "type": "string" + }, + "pts": { + "type": "number", + "format": "double" + }, + "engineId": { + "type": "string" + } + }, + "required": [ + "date", + "pts" + ], + "type": "object", + "additionalProperties": false + }, + "IMonetizedStreamReferenceTimeApiResponse": { + "properties": { + "id": { + "type": "string" + }, + "type": { + "$ref": "#/components/schemas/ResourceType.MONETIZED_STREAM_REFERENCE_TIME" + }, + "state": { + "type": "string", + "enum": [ + "created", + "deleted", + "updated" + ] + }, + "payload": { + "$ref": "#/components/schemas/IMonetizedStreamReferenceTime" + } + }, + "required": [ + "id", + "type", + "state", + "payload" + ], + "type": "object", + "additionalProperties": false + }, + "ScteParams": { + "properties": { + "uniqueProgramId": { + "type": "number", + "format": "double" + }, + "segmentationTypeId": { + "type": "number", + "format": "double" + }, + "eabnAdTagParameters": { + "$ref": "#/components/schemas/DynamicDetail" + } + }, + "type": "object", + "additionalProperties": false + }, + "IMonetizedStreamEarlyReturn": { + "properties": { + "date": { + "type": "string" + }, + "pts": { + "type": "number", + "format": "double" + }, + "id": { + "type": "string" + }, + "duration": { + "type": "string" + }, + "spliceEvent": { + "$ref": "#/components/schemas/ScteParams" + }, + "engineId": { + "type": "string" + } + }, + "required": [ + "date" + ], + "type": "object", + "additionalProperties": false + }, + "IMonetizedStreamUpdate": { + "properties": { + "name": { + "type": "string" + }, + "version": { + "type": "string" + }, + "streamType": { + "$ref": "#/components/schemas/MonetizedStreamType" + }, + "origin": { + "type": "string" + }, + "segmentOrigin": { + "type": "string" + }, + "layout": { + "$ref": "#/components/schemas/MonetizedStreamLayout" + }, + "originPath": { + "type": "string" + }, + "assetURI": { + "type": "string" + }, + "backdropURI": { + "type": "string" + }, + "backdropURIGamProperties": { + "$ref": "#/components/schemas/IGamProperties" + } + }, + "type": "object", + "additionalProperties": false + }, + "ResourceType.AD_BREAK": { + "enum": [ + "adbreak" + ], + "type": "string" + }, + "AdBreakInsertionType": { + "enum": [ + "REPLACE", + "INSERT" + ], + "type": "string" + }, + "SignaledAdBreakStatus": { + "enum": [ + "new", + "future", + "signaled", + "finished", + "error", + "continuous" + ], + "type": "string" + }, + "AdbreakInternalType": { + "enum": [ + "BUMPER", + "ORIGINAL" + ], + "type": "string" + }, + "LifeCycle": { + "enum": [ + "NEW", + "FUTURE", + "ERROR", + "SCHEDULED", + "DECISIONED", + "COMPLETED", + "ENDED" + ], + "type": "string" + }, + "IAdBreak": { + "properties": { + "id": { + "type": "string" + }, + "startDate": { + "type": "string" + }, + "endDate": { + "type": "string", + "format": "date-time", + "nullable": true + }, + "duration": { + "type": "number", + "format": "double" + }, + "source": { + "type": "string" + }, + "layout": { + "$ref": "#/components/schemas/MonetizedStreamLayout" + }, + "assetURI": { + "type": "string" + }, + "status": { + "$ref": "#/components/schemas/SignaledAdBreakStatus" + }, + "asset_key": { + "type": "string" + }, + "network_code": { + "type": "string" + }, + "backdropURI": { + "type": "string" + }, + "backdropURIGamProperties": { + "$ref": "#/components/schemas/IGamProperties" + }, + "startPts": { + "type": "number", + "format": "double" + }, + "name": { + "type": "string" + } + }, + "required": [ + "id", + "startDate" + ], + "type": "object", + "additionalProperties": false + }, + "IAdBreakApiResponse": { + "properties": { + "payload": { + "$ref": "#/components/schemas/IAdBreak" + }, + "type": { + "$ref": "#/components/schemas/ResourceType.AD_BREAK" + }, + "state": { + "type": "string", + "enum": [ + "created", + "deleted" + ] + }, + "id": { + "type": "string" + } + }, + "required": [ + "payload", + "type", + "state", + "id" + ], + "type": "object" + }, + "IAdBreaksApiResponse": { + "properties": { + "payload": { + "items": { + "$ref": "#/components/schemas/IAdBreak" + }, + "type": "array" + }, + "type": { + "$ref": "#/components/schemas/ResourceType.AD_BREAK" + }, + "state": { + "type": "string", + "enum": [ + "created", + "deleted" + ] + }, + "id": { + "type": "string" + } + }, + "required": [ + "payload", + "type", + "state", + "id" + ], + "type": "object" + }, + "IAdBreakUpdate": { + "properties": { + "startDate": { + "type": "string" + }, + "endDate": { + "type": "string", + "format": "date-time", + "nullable": true + }, + "duration": { + "type": "number", + "format": "double" + }, + "source": { + "type": "string" + }, + "layout": { + "$ref": "#/components/schemas/MonetizedStreamLayout" + }, + "assetURI": { + "type": "string" + }, + "status": { + "$ref": "#/components/schemas/SignaledAdBreakStatus" + }, + "asset_key": { + "type": "string" + }, + "network_code": { + "type": "string" + }, + "backdropURI": { + "type": "string" + }, + "backdropURIGamProperties": { + "$ref": "#/components/schemas/IGamProperties" + }, + "startPts": { + "type": "number", + "format": "double" + }, + "name": { + "type": "string" + } + }, + "type": "object", + "additionalProperties": false + }, + "OverlayTypes": { + "enum": [ + "image" + ], + "type": "string" + }, + "OverlayURITypes": { + "enum": [ + "png", + "svg" + ], + "type": "string" + }, + "IOverlay": { + "properties": { + "name": { + "type": "string" + }, + "id": { + "type": "string" + }, + "startDate": { + "type": "string" + }, + "endDate": { + "type": "string" + }, + "duration": { + "type": "number", + "format": "double" + }, + "type": { + "$ref": "#/components/schemas/OverlayTypes" + }, + "position": { + "properties": { + "bottom": { + "type": "number", + "format": "double" + }, + "top": { + "type": "number", + "format": "double" + }, + "right": { + "type": "number", + "format": "double" + }, + "left": { + "type": "number", + "format": "double" + } + }, + "type": "object" + }, + "size": { + "properties": { + "height": { + "type": "number", + "format": "double" + }, + "width": { + "type": "number", + "format": "double" + } + }, + "required": [ + "height", + "width" + ], + "type": "object" + }, + "opacity": { + "type": "number", + "format": "double" + }, + "gamProperties": { + "$ref": "#/components/schemas/IGamProperties" + }, + "resourceURI": { + "items": { + "properties": { + "tv": { + "type": "string" + }, + "phone": { + "type": "string" + }, + "default": { + "type": "string" + }, + "type": { + "$ref": "#/components/schemas/OverlayURITypes" + } + }, + "required": [ + "default", + "type" + ], + "type": "object" + }, + "type": "array" + }, + "clickThroughURI": { + "type": "string" + } + }, + "required": [ + "id", + "startDate", + "duration", + "type", + "position", + "size" + ], + "type": "object", + "additionalProperties": false + }, + "IOverlayApiResponse": { + "properties": { + "id": { + "type": "string" + }, + "state": { + "type": "string", + "enum": [ + "created", + "deleted" + ] + }, + "type": { + "type": "string", + "enum": [ + "overlay" + ], + "nullable": false + }, + "payload": { + "$ref": "#/components/schemas/IOverlay" + } + }, + "required": [ + "id", + "state", + "type", + "payload" + ], + "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 + }, + "ScteParamsResponse": { + "properties": { + "uniqueProgramId": { + "type": "number", + "format": "double" + }, + "segmentationTypeId": { + "type": "number", + "format": "double" + }, + "eabnAdTagParameters": { + "$ref": "#/components/schemas/DynamicDetail" + }, + "id": { + "type": "string" + } + }, + "required": [ + "id" + ], + "type": "object", + "additionalProperties": false + }, + "IScteParamMappingApiResponse": { + "properties": { + "data": { + "items": { + "$ref": "#/components/schemas/ScteParamsResponse" + }, + "type": "array" + } + }, + "required": [ + "data" + ], + "type": "object", + "additionalProperties": false + }, + "MonetizedStreamApiResponse": { + "properties": { + "data": { + "items": { + "$ref": "#/components/schemas/IMonetizedStream" + }, + "type": "array" + }, + "pagination": { + "$ref": "#/components/schemas/PaginationDetails" + } + }, + "required": [ + "data", + "pagination" + ], + "type": "object", + "additionalProperties": false + }, + "AdbreakApiResponse": { + "properties": { + "data": { + "items": { + "$ref": "#/components/schemas/IAdBreak" + }, + "type": "array" + }, + "pagination": { + "$ref": "#/components/schemas/PaginationDetails" + } + }, + "required": [ + "data", + "pagination" + ], + "type": "object", + "additionalProperties": false + }, + "OverlayApiResponse": { + "properties": { + "data": { + "items": { + "$ref": "#/components/schemas/IOverlay" + }, + "type": "array" + }, + "pagination": { + "$ref": "#/components/schemas/PaginationDetails" + } + }, + "required": [ + "data", + "pagination" + ], + "type": "object", + "additionalProperties": false + }, + "ReturnType_typeofISharedTemplateSchema.validateSync_": { + "properties": { + "metadata": { + "$ref": "#/components/schemas/DynamicDetail" + }, + "backdropURI": { + "type": "string" + }, + "assetURI": { + "type": "string" + }, + "layout": { + "$ref": "#/components/schemas/MonetizedStreamLayout" + }, + "source": { + "type": "string" + }, + "duration": { + "type": "number", + "format": "double" + }, + "name": { + "type": "string" + } + }, + "type": "object", + "description": "Obtain the return type of a function type" + }, + "ISharedTemplateType": { + "$ref": "#/components/schemas/ReturnType_typeofISharedTemplateSchema.validateSync_" + }, + "ReturnType_typeofTemplateAssignmentSchema.validateSync_": { + "properties": { + "templateId": { + "type": "string" + } + }, + "type": "object", + "description": "Obtain the return type of a function type" + }, + "TemplateAssignmentType": { + "$ref": "#/components/schemas/ReturnType_typeofTemplateAssignmentSchema.validateSync_" + }, + "ReturnType_typeofAssignedTemplateDataSchema.validateSync_": { + "properties": { + "notReadyReason": { + "type": "string" + }, + "isReady": { + "type": "boolean" + }, + "metadata": { + "$ref": "#/components/schemas/DynamicDetail" + }, + "backdropURI": { + "type": "string" + }, + "assetURI": { + "type": "string" + }, + "layout": { + "$ref": "#/components/schemas/MonetizedStreamLayout" + }, + "source": { + "type": "string" + }, + "duration": { + "type": "number", + "format": "double" + }, + "name": { + "type": "string" + } + }, + "type": "object", + "description": "Obtain the return type of a function type" + }, + "AssignedTemplateDataType": { + "$ref": "#/components/schemas/ReturnType_typeofAssignedTemplateDataSchema.validateSync_" + }, + "TemplateAssignmentMultipleResponse": { + "properties": { + "eventId": { + "type": "string" + }, + "monetizedStream": { + "type": "string" + }, + "templates": { + "items": { + "$ref": "#/components/schemas/AssignedTemplateDataType" + }, + "type": "array" + }, + "pagination": { + "$ref": "#/components/schemas/PaginationDetails" + } + }, + "required": [ + "eventId", + "monetizedStream", + "templates", + "pagination" + ], + "type": "object", + "additionalProperties": false + }, + "ReturnType_typeofTemplateAssignmentSingleResponseSchema.validateSync_": { + "properties": { + "template": { + "properties": { + "id": { + "type": "string" + }, + "notReadyReason": { + "type": "string" + }, + "isReady": { + "type": "boolean" + }, + "metadata": { + "$ref": "#/components/schemas/DynamicDetail" + }, + "backdropURI": { + "type": "string" + }, + "assetURI": { + "type": "string" + }, + "layout": { + "$ref": "#/components/schemas/MonetizedStreamLayout" + }, + "source": { + "type": "string" + }, + "duration": { + "type": "number", + "format": "double" + }, + "name": { + "type": "string" + } + }, + "type": "object" + }, + "monetizedStream": { + "type": "string" + }, + "eventId": { + "type": "string" + }, + "id": { + "type": "string" + } + }, + "type": "object", + "description": "Obtain the return type of a function type" + }, + "TemplateAssignmentSingleResponseType": { + "$ref": "#/components/schemas/ReturnType_typeofTemplateAssignmentSingleResponseSchema.validateSync_" + }, + "ReturnType_typeofAssignedTemplateDataUpdateSchema.validateSync_": { + "properties": { + "metadata": { + "$ref": "#/components/schemas/DynamicDetail" + }, + "backdropURI": { + "type": "string" + }, + "assetURI": { + "type": "string" + }, + "layout": { + "$ref": "#/components/schemas/MonetizedStreamLayout" + }, + "source": { + "type": "string" + }, + "duration": { + "type": "number", + "format": "double" + }, + "name": { + "type": "string" + } + }, + "type": "object", + "description": "Obtain the return type of a function type" + }, + "AssignedTemplateDataUpdateType": { + "$ref": "#/components/schemas/ReturnType_typeofAssignedTemplateDataUpdateSchema.validateSync_" + }, + "ReturnType_typeofSharedTemplateSchema.validateSync_": { + "properties": { + "id": { + "type": "string" + }, + "notReadyReason": { + "type": "string" + }, + "isReady": { + "type": "boolean" + }, + "metadata": { + "$ref": "#/components/schemas/DynamicDetail" + }, + "backdropURI": { + "type": "string" + }, + "assetURI": { + "type": "string" + }, + "layout": { + "$ref": "#/components/schemas/MonetizedStreamLayout" + }, + "source": { + "type": "string" + }, + "duration": { + "type": "number", + "format": "double" + }, + "name": { + "type": "string" + } + }, + "type": "object", + "description": "Obtain the return type of a function type" + }, + "SharedTemplateType": { + "$ref": "#/components/schemas/ReturnType_typeofSharedTemplateSchema.validateSync_" + }, + "SharedTemplateResponse": { + "properties": { + "data": { + "items": { + "$ref": "#/components/schemas/SharedTemplateType" + }, + "type": "array" + }, + "pagination": { + "$ref": "#/components/schemas/PaginationDetails" + } + }, + "required": [ + "data", + "pagination" + ], + "type": "object", + "additionalProperties": false + }, + "ISharedTemplate": { + "properties": { + "name": { + "type": "string" + }, + "duration": { + "type": "number", + "format": "double" + }, + "source": { + "type": "string" + }, + "layout": { + "$ref": "#/components/schemas/MonetizedStreamLayout" + }, + "assetURI": { + "type": "string" + }, + "backdropURI": { + "type": "string" + }, + "metadata": { + "properties": {}, + "additionalProperties": { + "type": "string" + }, + "type": "object" + } + }, + "required": [ + "name" + ], + "type": "object", + "additionalProperties": false + }, + "ISharedTemplateUpdate": { + "properties": { + "duration": { + "type": "number", + "format": "double" + }, + "source": { + "type": "string" + }, + "layout": { + "$ref": "#/components/schemas/MonetizedStreamLayout" + }, + "assetURI": { + "type": "string" + }, + "backdropURI": { + "type": "string" + }, + "metadata": { + "properties": {}, + "additionalProperties": { + "type": "string" + }, + "type": "object" + } + }, + "type": "object", + "additionalProperties": false + } + }, + "securitySchemes": { + "apiKeyAuth": { + "type": "apiKey", + "name": "X-API-KEY", + "in": "header" + } + } + }, + "info": { + "title": "THEOads Api", + "version": "25.9.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" + }, + "contact": {} + }, + "openapi": "3.0.0", + "paths": { + "/v1/monetized-streams": { + "get": { + "operationId": "GetMonetizedStreams", + "responses": { + "200": { + "description": "List of monetized streams", + "content": { + "application/json": { + "schema": { + "anyOf": [ + { + "items": { + "$ref": "#/components/schemas/IMonetizedStreamApiResponse" + }, + "type": "array" + }, + { + "type": "string" + } + ] + } + } + } + } + }, + "description": "Retrieves all created and deployed monetized streams (signaling services) along with their configurations.", + "tags": [ + "Monetized-Stream" + ], + "security": [], + "parameters": [] + }, + "post": { + "operationId": "CreateMonetizedStream", + "responses": { + "201": { + "description": "Created", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/IMonetizedStreamApiResponse" + } + } + } + } + }, + "description": "Creates and deploys a new monetized stream in the environment, resulting in a deployment of a signaling service.", + "tags": [ + "Monetized-Stream" + ], + "security": [], + "parameters": [], + "requestBody": { + "description": "The monetized stream configuration", + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/IMonetizedStream", + "description": "The monetized stream configuration" + } + } + } + } + } + }, + "/v1/monetized-streams/{monetizedStreamId}": { + "get": { + "operationId": "GetMonetizedStream", + "responses": { + "200": { + "description": "A monetized stream", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/IMonetizedStreamApiResponse" + } + } + } + } + }, + "description": "Retrieves a single monetized stream (signaling service) based on its identifier, along with its configuration details.", + "tags": [ + "Monetized-Stream" + ], + "security": [], + "parameters": [ + { + "description": "The Monetized stream identifier.", + "in": "path", + "name": "monetizedStreamId", + "required": true, + "schema": { + "type": "string" + } + } + ] + }, + "patch": { + "operationId": "UpdateMonetizedStream", + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/IMonetizedStreamApiResponse" + } + } + } + } + }, + "description": "Updates a single monetized stream (signaling service) based on its identifier, along with its configuration update.", + "tags": [ + "Monetized-Stream" + ], + "security": [], + "parameters": [ + { + "description": "The Monetized stream identifier.", + "in": "path", + "name": "monetizedStreamId", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "description": "The monetized stream configuration update", + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/IMonetizedStreamUpdate", + "description": "The monetized stream configuration update" + } + } + } + } + }, + "delete": { + "operationId": "DeleteMonetizedStream", + "responses": { + "200": { + "description": "Ok", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/IMonetizedStreamApiResponse" + } + } + } + } + }, + "description": "Deletes a single monetized stream (signaling service) based on its identifier.", + "tags": [ + "Monetized-Stream" + ], + "security": [], + "parameters": [ + { + "description": "The Monetized stream identifier.", + "in": "path", + "name": "monetizedStreamId", + "required": true, + "schema": { + "type": "string" + } + } + ] + } + }, + "/v1/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" + } + } + } + } + } + }, + "/v1/monetized-streams/{monetizedStreamId}/break": { + "post": { + "operationId": "CreateMonetizedStreamBreak", + "responses": { + "201": { + "description": "Created", + "content": { + "application/json": { + "schema": { + "anyOf": [ + { + "$ref": "#/components/schemas/IAdBreakApiResponse" + }, + { + "type": "string" + } + ] + } + } + } + } + }, + "description": "Creates an ad break on 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 ad break configuration", + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/IAdBreak", + "description": "The ad break configuration" + } + } + } + } + }, + "get": { + "operationId": "GetMonetizedStreamBreaks", + "responses": { + "200": { + "description": "A monetized stream", + "content": { + "application/json": { + "schema": { + "anyOf": [ + { + "$ref": "#/components/schemas/IAdBreaksApiResponse" + }, + { + "type": "string" + } + ] + } + } + } + } + }, + "description": "Retrieves all adbreaks linked to the monetized sctream", + "tags": [ + "Monetized-Stream" + ], + "security": [], + "parameters": [ + { + "description": "The Monetized stream identifier.", + "in": "path", + "name": "monetizedStreamId", + "required": true, + "schema": { + "type": "string" + } + } + ] + } + }, + "/v1/monetized-streams/{monetizedStreamId}/break/{adbreakId}": { + "delete": { + "operationId": "DeleteMonetizedStreamBreaks", + "responses": { + "200": { + "description": "An abreak", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/IAdBreakApiResponse" + } + } + } + } + }, + "description": "Deletes an adbreak linked to the monetized sctream", + "tags": [ + "Monetized-Stream" + ], + "security": [], + "parameters": [ + { + "description": "The Monetized stream identifier.", + "in": "path", + "name": "monetizedStreamId", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "The adbreak identifier.", + "in": "path", + "name": "adbreakId", + "required": true, + "schema": { + "type": "string" + } + } + ] + }, + "patch": { + "operationId": "UpdateMonetizedStreamBreaks", + "responses": { + "200": { + "description": "An adbreak", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/IAdBreakApiResponse" + } + } + } + } + }, + "description": "Patches an adbreak linked to the monetized sctream", + "tags": [ + "Monetized-Stream" + ], + "security": [], + "parameters": [ + { + "description": "The Monetized stream identifier.", + "in": "path", + "name": "monetizedStreamId", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "The adbreak identifier.", + "in": "path", + "name": "adbreakId", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/IAdBreakUpdate" + } + } + } + } + } + }, + "/v1/monetized-streams/{monetizedStreamId}/overlay": { + "post": { + "operationId": "CreateMonetizedStreamOverlay", + "responses": { + "201": { + "description": "Created", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/IOverlayApiResponse" + } + } + } + } + }, + "description": "Creates an overlay on 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 overlay configuration", + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/IOverlay", + "description": "The overlay configuration" + } + } + } + } + }, + "get": { + "operationId": "GetMonetizedStreamOverlays", + "responses": { + "200": { + "description": "A monetized stream", + "content": { + "application/json": { + "schema": { + "anyOf": [ + { + "$ref": "#/components/schemas/IOverlaysApiResponse" + }, + { + "type": "string" + } + ] + } + } + } + } + }, + "description": "Retrieves all overlays linked to the monetized sctream", + "tags": [ + "Monetized-Stream" + ], + "security": [], + "parameters": [ + { + "description": "The Monetized stream identifier.", + "in": "path", + "name": "monetizedStreamId", + "required": true, + "schema": { + "type": "string" + } + } + ] + } + }, + "/v1/monetized-streams/{monetizedStreamId}/overlay/{overlayId}": { + "delete": { + "operationId": "DeleteMonetizedStreamOverlay", + "responses": { + "200": { + "description": "A monetized stream", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/IOverlayApiResponse" + } + } + } + } + }, + "description": "Deletes an overlay linked to the monetized sctream", + "tags": [ + "Monetized-Stream" + ], + "security": [], + "parameters": [ + { + "description": "The Monetized stream identifier.", + "in": "path", + "name": "monetizedStreamId", + "required": true, + "schema": { + "type": "string" + } + }, + { + "in": "path", + "name": "overlayId", + "required": true, + "schema": { + "type": "string" + } + } + ] + } + }, + "/v2/monetized-streams": { + "get": { + "operationId": "GetMonetizedStreamsPaginated", + "responses": { + "200": { + "description": "Ok", + "content": { + "application/json": { + "schema": { + "anyOf": [ + { + "$ref": "#/components/schemas/MonetizedStreamApiResponse" + }, + { + "type": "string" + } + ] + } + } + } + } + }, + "tags": [ + "Monetized-Stream-V2" + ], + "security": [], + "parameters": [ + { + "in": "query", + "name": "limit", + "required": false, + "schema": { + "format": "double", + "type": "number" + } + }, + { + "in": "query", + "name": "skip", + "required": false, + "schema": { + "format": "double", + "type": "number" + } + } + ] + } + }, + "/v2/monetized-streams/{monetizedStreamId}/break": { + "get": { + "operationId": "GetMonetizedStreamBreaksPaginated", + "responses": { + "200": { + "description": "A monetized stream", + "content": { + "application/json": { + "schema": { + "anyOf": [ + { + "$ref": "#/components/schemas/AdbreakApiResponse" + }, + { + "type": "string" + } + ] + } + } + } + } + }, + "description": "Retrieves all adbreaks linked to the monetized stream", + "tags": [ + "Monetized-Stream-V2" + ], + "security": [], + "parameters": [ + { + "description": "The Monetized stream identifier.", + "in": "path", + "name": "monetizedStreamId", + "required": true, + "schema": { + "type": "string" + } + }, + { + "in": "query", + "name": "limit", + "required": false, + "schema": { + "format": "double", + "type": "number" + } + }, + { + "in": "query", + "name": "skip", + "required": false, + "schema": { + "format": "double", + "type": "number" + } + } + ] + } + }, + "/v2/monetized-streams/{monetizedStreamId}/overlay": { + "get": { + "operationId": "GetMonetizedStreamOverlaysPaginated", + "responses": { + "200": { + "description": "A monetized stream", + "content": { + "application/json": { + "schema": { + "anyOf": [ + { + "$ref": "#/components/schemas/OverlayApiResponse" + }, + { + "type": "string" + } + ] + } + } + } + } + }, + "description": "Retrieves all overlays linked to the monetized sctream", + "tags": [ + "Monetized-Stream-V2" + ], + "security": [], + "parameters": [ + { + "description": "The Monetized stream identifier.", + "in": "path", + "name": "monetizedStreamId", + "required": true, + "schema": { + "type": "string" + } + }, + { + "in": "query", + "name": "limit", + "required": false, + "schema": { + "format": "double", + "type": "number" + } + }, + { + "in": "query", + "name": "skip", + "required": false, + "schema": { + "format": "double", + "type": "number" + } + } + ] + } + } + }, + "servers": [ + { + "url": "/ads-client/api" + } + ] +} \ No newline at end of file diff --git a/ads_versioned_docs/version-v1/api/signaling/.gitignore b/ads_versioned_docs/version-v1/api/signaling/.gitignore new file mode 100644 index 000000000000..7c5ca8c38d5f --- /dev/null +++ b/ads_versioned_docs/version-v1/api/signaling/.gitignore @@ -0,0 +1,3 @@ +# Auto-generated by `docusaurus gen-api-docs` +**/*.mdx +**/sidebar.ts diff --git a/ads_versioned_docs/version-v1/assets/img/ads_formats.svg b/ads_versioned_docs/version-v1/assets/img/ads_formats.svg new file mode 100644 index 000000000000..b9fe8733afe1 --- /dev/null +++ b/ads_versioned_docs/version-v1/assets/img/ads_formats.svg @@ -0,0 +1,89 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/ads_versioned_docs/version-v1/assets/img/backdrop-doublebox-template.png b/ads_versioned_docs/version-v1/assets/img/backdrop-doublebox-template.png new file mode 100644 index 000000000000..59b5a2e07ccd Binary files /dev/null and b/ads_versioned_docs/version-v1/assets/img/backdrop-doublebox-template.png differ diff --git a/ads_versioned_docs/version-v1/assets/img/backdrop-lshape-template.png b/ads_versioned_docs/version-v1/assets/img/backdrop-lshape-template.png new file mode 100644 index 000000000000..f960848aae70 Binary files /dev/null and b/ads_versioned_docs/version-v1/assets/img/backdrop-lshape-template.png differ diff --git a/ads_versioned_docs/version-v1/assets/img/gam_image_1.png b/ads_versioned_docs/version-v1/assets/img/gam_image_1.png new file mode 100644 index 000000000000..6dcde35ad0ee Binary files /dev/null and b/ads_versioned_docs/version-v1/assets/img/gam_image_1.png differ diff --git a/ads_versioned_docs/version-v1/assets/img/gam_image_2.png b/ads_versioned_docs/version-v1/assets/img/gam_image_2.png new file mode 100644 index 000000000000..2cdf534adf21 Binary files /dev/null and b/ads_versioned_docs/version-v1/assets/img/gam_image_2.png differ diff --git a/ads_versioned_docs/version-v1/assets/img/gam_image_3.png b/ads_versioned_docs/version-v1/assets/img/gam_image_3.png new file mode 100644 index 000000000000..ec0b4c6288cc Binary files /dev/null and b/ads_versioned_docs/version-v1/assets/img/gam_image_3.png differ diff --git a/ads_versioned_docs/version-v1/assets/img/gam_image_4.png b/ads_versioned_docs/version-v1/assets/img/gam_image_4.png new file mode 100644 index 000000000000..7cbe66748fbc Binary files /dev/null and b/ads_versioned_docs/version-v1/assets/img/gam_image_4.png differ diff --git a/ads_versioned_docs/version-v1/assets/img/gam_image_5.png b/ads_versioned_docs/version-v1/assets/img/gam_image_5.png new file mode 100644 index 000000000000..8a819acf8a63 Binary files /dev/null and b/ads_versioned_docs/version-v1/assets/img/gam_image_5.png differ diff --git a/ads_versioned_docs/version-v1/assets/img/impressions.png b/ads_versioned_docs/version-v1/assets/img/impressions.png new file mode 100644 index 000000000000..b914182bc340 Binary files /dev/null and b/ads_versioned_docs/version-v1/assets/img/impressions.png differ diff --git a/ads_versioned_docs/version-v1/assets/img/ios-swiftpm-menu-google.png b/ads_versioned_docs/version-v1/assets/img/ios-swiftpm-menu-google.png new file mode 100644 index 000000000000..924ad0000c48 Binary files /dev/null and b/ads_versioned_docs/version-v1/assets/img/ios-swiftpm-menu-google.png differ diff --git a/ads_versioned_docs/version-v1/assets/img/ios-swiftpm-menu.png b/ads_versioned_docs/version-v1/assets/img/ios-swiftpm-menu.png new file mode 100644 index 000000000000..4a2528560f16 Binary files /dev/null and b/ads_versioned_docs/version-v1/assets/img/ios-swiftpm-menu.png differ diff --git a/ads_versioned_docs/version-v1/assets/img/ios-swiftpm-product-selection-google.png b/ads_versioned_docs/version-v1/assets/img/ios-swiftpm-product-selection-google.png new file mode 100644 index 000000000000..04a01bcd3644 Binary files /dev/null and b/ads_versioned_docs/version-v1/assets/img/ios-swiftpm-product-selection-google.png differ diff --git a/ads_versioned_docs/version-v1/assets/img/ios-swiftpm-product-selection.png b/ads_versioned_docs/version-v1/assets/img/ios-swiftpm-product-selection.png new file mode 100644 index 000000000000..350c0e91ddaf Binary files /dev/null and b/ads_versioned_docs/version-v1/assets/img/ios-swiftpm-product-selection.png differ diff --git a/ads_versioned_docs/version-v1/assets/img/ios-xcode-file-menu.png b/ads_versioned_docs/version-v1/assets/img/ios-xcode-file-menu.png new file mode 100644 index 000000000000..fe6a617c34ed Binary files /dev/null and b/ads_versioned_docs/version-v1/assets/img/ios-xcode-file-menu.png differ diff --git a/ads_versioned_docs/version-v1/assets/img/optiview_ads_architecture.png b/ads_versioned_docs/version-v1/assets/img/optiview_ads_architecture.png new file mode 100644 index 000000000000..d17ff66cc8f7 Binary files /dev/null and b/ads_versioned_docs/version-v1/assets/img/optiview_ads_architecture.png differ diff --git a/ads_versioned_docs/version-v1/assets/img/web-ui.png b/ads_versioned_docs/version-v1/assets/img/web-ui.png new file mode 100644 index 000000000000..2b24e27dd9dc Binary files /dev/null and b/ads_versioned_docs/version-v1/assets/img/web-ui.png differ diff --git a/ads_versioned_docs/version-v1/assets/img/workflow-optiview-ads-after.png b/ads_versioned_docs/version-v1/assets/img/workflow-optiview-ads-after.png new file mode 100644 index 000000000000..70f376574b2a Binary files /dev/null and b/ads_versioned_docs/version-v1/assets/img/workflow-optiview-ads-after.png differ diff --git a/ads_versioned_docs/version-v1/assets/img/workflow-optiview-ads-before.png b/ads_versioned_docs/version-v1/assets/img/workflow-optiview-ads-before.png new file mode 100644 index 000000000000..8f2f57dd07b0 Binary files /dev/null and b/ads_versioned_docs/version-v1/assets/img/workflow-optiview-ads-before.png differ diff --git a/ads_versioned_docs/version-v1/callouts/_rebranding_notice.md b/ads_versioned_docs/version-v1/callouts/_rebranding_notice.md new file mode 100644 index 000000000000..fc5195a85b22 --- /dev/null +++ b/ads_versioned_docs/version-v1/callouts/_rebranding_notice.md @@ -0,0 +1,5 @@ +:::info OptiView Rebranding + +OptiView Ads is the new name for THEOads as part of the OptiView product suite. During the transition, you may still see references to THEOads. OptiView Ads and THEOads refer to the same product. + +::: diff --git a/ads_versioned_docs/version-v1/getting-started/android.mdx b/ads_versioned_docs/version-v1/getting-started/android.mdx new file mode 100644 index 000000000000..46230eda55d1 --- /dev/null +++ b/ads_versioned_docs/version-v1/getting-started/android.mdx @@ -0,0 +1,133 @@ +--- +sidebar_position: 3 +sidebar_label: Android +sidebar_custom_props: { 'icon': 'android' } +--- + +# Getting started with OptiView Ads on Android + +This guide will get you started to integrate OptiView Ads in your OptiView Player Android 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 an OptiView Player license which is compatible with OptiView Ads. This can be done through the [player portal](https://portal.theoplayer.com). +2. You need a correctly deployed [OptiView Ads signaling service](signaling-service.mdx). +3. Add the OptiView Player Android SDK to your project by following our [Getting started](/theoplayer/getting-started/sdks/android/getting-started) guide. Make sure to [set up an OptiView Ads-compatible license](/theoplayer/getting-started/sdks/android/getting-started/#setting-up-the-license) in your app. +4. Add the OptiView Ads integration as a dependency in your module-level `build.gradle` file: + + + + ```groovy + dependencies { + implementation "com.theoplayer.theoplayer-sdk-android:core:9.+" + // highlight-next-line + implementation "com.theoplayer.theoplayer-sdk-android:integration-ads-theoads:9.+" + } + ``` + + + ```kotlin + dependencies { + implementation("com.theoplayer.theoplayer-sdk-android:core:9.+") + // highlight-next-line + implementation("com.theoplayer.theoplayer-sdk-android:integration-theoads:9.+") + } + ``` + + + + +## Integration + +To make use of the OptiView Ads integration, create and add the `TheoAdsIntegration` to your `THEOplayerView`: + +```kotlin +import com.theoplayer.android.api.THEOplayerView +import com.theoplayer.android.api.ads.theoads.TheoAdsIntegration +import com.theoplayer.android.api.ads.theoads.TheoAdsIntegrationFactory.createTheoAdsIntegration + +class MyActivity : Activity() { + private lateinit var theoPlayerView: THEOplayerView + private lateinit var theoAdsIntegration: TheoAdsIntegration + + override fun onCreate(savedInstanceState: Bundle?) { + super.onCreate(savedInstanceState) + setContentView(R.layout.activity_main) + + theoPlayerView = findViewById(R.id.theoplayer) + + theoAdsIntegration = createTheoAdsIntegration(theoPlayerView) + theoPlayerView.player.addIntegration(theoAdsIntegration) + } +} +``` + +Then, configure a source containing a `TheoAdDescription`: + +```kotlin +import com.theoplayer.android.api.ads.theoads.TheoAdDescription +import com.theoplayer.android.api.source.SourceDescription +import com.theoplayer.android.api.source.SourceType +import com.theoplayer.android.api.source.TypedSource + +theoPlayerView.player.source = SourceDescription.Builder( + TypedSource.Builder("PATH-TO-SIGNALING-SERVER/hls/MANIFEST-URI") + .type(SourceType.HLS) + .hlsDateRange(true) + .build() +).ads( + TheoAdDescription( + networkCode = "NETWORK-CODE", + customAssetKey = "CUSTOM-ASSET-KEY" + ) +).build() +``` + +- Notice that the `src` is different as usual. For OptiView Ads, 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](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` object needs to be a `TheoAdDescription`. Furthermore, the `networkCode` and `customAssetKey` needs to be set according to your configured Google account. + +## Integrating with Open Video UI + +When using the [Open Video UI for Android](/open-video-ui/android/), you need to create and add the `TheoAdsIntegration` before creating your `DefaultUI` or `UIController`. You can then create an OptiView Ads-enabled source and set it as `player.source`: + +```kotlin +import androidx.activity.compose.setContent +import com.theoplayer.android.ui.rememberPlayer + +setContent { + val player = rememberPlayer() + LaunchedEffect(player) { + player.theoplayerView?.let { theoPlayerView -> + val theoAdsIntegration = createTheoAdsIntegration(theoPlayerView) + theoPlayerView.player.addIntegration(theoAdsIntegration) + } + + player.source = SourceDescription.Builder( + TypedSource.Builder("PATH-TO-SIGNALING-SERVER/hls/MANIFEST-URI") + .type(SourceType.HLS) + .hlsDateRange(true) + .build() + ).ads( + TheoAdDescription( + networkCode = "NETWORK-CODE", + customAssetKey = "CUSTOM-ASSET-KEY" + ) + ).build() + } + + DefaultUI( + player = player + ) +} +``` + +## More information + +- [API references](pathname:///theoplayer/v8/api-reference/android/com/theoplayer/android/api/ads/theoads/package-summary.html) +- [What is OptiView Ads?](https://optiview.dolby.com/products/server-guided-ad-insertion/) +- [The Advantages of Server-Guided Ad Insertion](https://optiview.dolby.com/solutions/personalized-advertising/) +- [Is Server-Guided Ad Insertion (SGAI) revolutionizing streaming monetization? (blog)](https://optiview.dolby.com/resources/blog/advertising/what-is-sgai-server-guided-ad-insertion-in-streaming/) diff --git a/ads_versioned_docs/version-v1/getting-started/chromecast.mdx b/ads_versioned_docs/version-v1/getting-started/chromecast.mdx new file mode 100644 index 000000000000..7e6a45999ebf --- /dev/null +++ b/ads_versioned_docs/version-v1/getting-started/chromecast.mdx @@ -0,0 +1,74 @@ +--- +sidebar_position: 6 +sidebar_label: Chromecast CAF +sidebar_custom_props: { 'icon': 'web' } +--- + +# Getting started with OptiView Ads on Chromecast CAF + +This guide will get you started with OptiView Ads using the OptiView Player Chromecast CAF SDK. +! NOTE: Currently the Chromecast CAF SDK only supports image overlays from OptiView Ads. + +## Prerequisites + +1. You need to have an OptiView Player license which is compatible with OptiView Ads. This can be done through the [player portal](https://portal.theoplayer.com). +2. You need a correctly deployed [OptiView Ads signaling service](signaling-service.mdx). +3. Your THEOplayer SDK needs to have the `theoads` feature enabled. + + As of OptiView Player version 8.2.0, this feature is enabled by default in the main `theoplayer` package so we recommend to use at least this version, preferably the latest available version. + You can install this package with the following command: + + ```bash + npm install theoplayer + ``` + +4. You need to have a Chromecast Developer account to deploy your custom CAF receiver. + +## Integration + +### Configuring the Chromecast receiver + +OptiView Ads is supported using the default Chromecast Shaka player for HLS on Chromecast CAF. To enable this, before starting the Chromecast application, configure it to use Shaka. +Also, you need to load the OptiView Player Chromecast CAF SDK. + +Here is an example of a bare-bones CAF receiver app you can use as a starting point for basic playback without any custom UI: + +```html + + + Optiview Chromecast Receiver App + + + + + + + + + + + + +``` + +! NOTE: We recommend to self-host the THEOplayer Chromecast CAF SDK to avoid dependency issues and lock the version you are using. More information on self-hosting can be found [here](https://optiview.dolby.com/docs/theoplayer/faq/self-hosting-theoplayer/). + +### Configuring the Chromecast sender + +The Optiview Chromecast features are only available through our own player SDK. Setting up the Chromecast functionality is documented on our main documentation portal: +https://optiview.dolby.com/docs/theoplayer/how-to-guides/cast/chromecast/introduction/ + +Our player SDKs will take care of handling the communication between the Chromecast sender and receiver. + +## More information + +- [API references](pathname:///theoplayer/v11/api-reference/web/interfaces/TheoAdDescription.html) +- [What is OptiView Ads?](https://optiview.dolby.com/products/server-guided-ad-insertion/) +- [The Advantages of Server-Guided Ad Insertion](https://optiview.dolby.com/solutions/personalized-advertising/) +- [Is Server-Guided Ad-Insertion (SGAI) revolutionizing streaming monetization? (blog)](https://optiview.dolby.com/resources/blog/advertising/what-is-sgai-server-guided-ad-insertion-in-streaming/) diff --git a/ads_versioned_docs/version-v1/getting-started/index.mdx b/ads_versioned_docs/version-v1/getting-started/index.mdx new file mode 100644 index 000000000000..3bcac379b49a --- /dev/null +++ b/ads_versioned_docs/version-v1/getting-started/index.mdx @@ -0,0 +1,16 @@ +--- +sidebar_position: 1 +sidebar_label: Getting Started +--- + +# Getting started with OptiView Ads + +import RebrandingNotice from '../callouts/_rebranding_notice.md'; + + + +These guides provide the steps required to get started with OptiView Ads. They cover the deployment and API integration of the Signaling Service into your existing workflow, as well as the integration of OptiView Ads into your application using various OptiView Player SDKs. + +import DocCardList from '@theme/DocCardList'; + + diff --git a/ads_versioned_docs/version-v1/getting-started/ios.mdx b/ads_versioned_docs/version-v1/getting-started/ios.mdx new file mode 100644 index 000000000000..477bb1e134d2 --- /dev/null +++ b/ads_versioned_docs/version-v1/getting-started/ios.mdx @@ -0,0 +1,147 @@ +--- +sidebar_position: 3 +sidebar_label: iOS +sidebar_custom_props: { 'icon': 'apple' } +--- + +# Getting started with OptiView Ads on iOS + +This guide will get you started to integrate OptiView Ads in your OptiView Player 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 an OptiView Player license which is compatible with OptiView Ads. This can be done through the [player portal](https://portal.theoplayer.com). +2. You need a correctly deployed [OptiView Ads signaling service](signaling-service.mdx). +3. Add the OptiView Player iOS SDK to your project by following our [Getting started](/theoplayer/getting-started/sdks/ios/getting-started) guide. Make sure to [set up an OptiView Ads-compatible license](/theoplayer/getting-started/sdks/ios/getting-started/#theoplayer-license) in your app. +4. Add the OptiView Ads integration as a dependency to your project: + + + + 1. Add the `THEOplayer-Integration-THEOads` pod to your Podfile: + ```sh + pod 'THEOplayer-Integration-THEOads', '~> ' + ``` + 2. Install the new pod: + ```sh + pod install + ``` + + + 1. Open your Xcode project and navigate to File > Add Package Dependencies... + + ![Screenshot of Xcode file menu](../assets/img/ios-xcode-file-menu.png) + + 2. Add `theoplayer-sdk-apple` package by entering the following url: + ```sh + https://github.com/THEOplayer/theoplayer-sdk-apple + ``` + ![Screenshot of SwiftPM menu](../assets/img/ios-swiftpm-menu.png) + + 3. Select `THEOplayerTHEOadsIntegration` from the package products list and add it to your target. + + ![Screenshot of SwiftPM product selection](../assets/img/ios-swiftpm-product-selection.png) + + + + + +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... + + ![Screenshot of Xcode file menu](../assets/img/ios-xcode-file-menu.png) + + 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 + ``` + ![Screenshot of SwiftPM menu](../assets/img/ios-swiftpm-menu-google.png) + + 3. Select `GoogleInteractiveMediaAds` from the package products list and add it to your target. + + ![Screenshot of SwiftPM product selection](../assets/img/ios-swiftpm-product-selection-google.png) + + + + + +## Integration + +To make use of the OptiView Ads 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 OptiView Ads, 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](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 OptiView Ads?](https://optiview.dolby.com/products/server-guided-ad-insertion/) +- [The Advantages of Server-Guided Ad Insertion](https://optiview.dolby.com/solutions/personalized-advertising/) +- [Is Server-Guided Ad Insertion (SGAI) revolutionizing streaming monetization? (blog)](https://optiview.dolby.com/resources/blog/advertising/what-is-sgai-server-guided-ad-insertion-in-streaming/) diff --git a/ads_versioned_docs/version-v1/getting-started/react-native.mdx b/ads_versioned_docs/version-v1/getting-started/react-native.mdx new file mode 100644 index 000000000000..8170943a1a97 --- /dev/null +++ b/ads_versioned_docs/version-v1/getting-started/react-native.mdx @@ -0,0 +1,82 @@ +--- +sidebar_position: 5 +sidebar_label: React Native +sidebar_custom_props: { 'icon': 'react' } +--- + +# Getting started with OptiView Ads on React Native + +This guide will get you started with OptiView Ads in your OptiView Player React Native 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 an OptiView Player license which is compatible with OptiView Ads. This can be done through the [player portal](https://portal.theoplayer.com). +2. You need a correctly deployed [OptiView Ads signaling service](signaling-service.mdx). +3. Enable the OptiView Ads integration based on the target platform: + + + + The Android SDK is modular-based, so to enable OptiView Ads, simply include the extension by setting this flag in your gradle.properties: + ```groovy + # Enable THEOplayer Extensions (default: disabled) + THEOplayer_extensionTHEOads = true + ``` + + + To enable OptiView Ads you can add the "THEOADS" feature flag to react-native-theoplayer.json (or theoplayer-config.json) + + + Add a dependency to an OptiView Ads-enabled THEOplayer package: + ```bash + $ npm i theoplayer@npm:@theoplayer/theoads + ``` + + In addition, since OptiView Ads integrates with Google DAI Pod Serving, it is required to load the Google DAI script on your page: + + ```html + + ``` + + + + + +## Integration + +This guide assumes you know how to set up React Native with OptiView Player. +For more information regarding this check out the [OptiView Player getting started](/theoplayer/getting-started/frameworks/react-native/getting-started/). + +### Player configuration + +To make use of the OptiView Ads integration, only a specific source needs to be set: + +```javascript +player.source = { + sources: { + src: 'PATH-TO-SIGNALING-SERVER/hls/MANIFEST-URI', + type: 'application/x-mpegurl', + hlsDateRange: true, + }, + ads: [ + { + integration: 'theoads', + networkCode: 'NETWORK-CODE', + customAssetKey: 'CUSTOM-ASSET-KEY', + }, + ], +}; +``` + +- Notice that the `src` is different as usual. For OptiView Ads, 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](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` object needs to have its integration set to `theoads`. Furthermore, the `networkCode` and `customAssetKey` needs to be set according to your configured Google account. + +## More information + +- [What is OptiView Ads?](https://optiview.dolby.com/products/server-guided-ad-insertion/) +- [The Advantages of Server-Guided Ad Insertion](https://optiview.dolby.com/solutions/personalized-advertising/) +- [Is Server-Guided Ad Insertion (SGAI) revolutionizing streaming monetization? (blog)](https://optiview.dolby.com/resources/blog/advertising/what-is-sgai-server-guided-ad-insertion-in-streaming/) diff --git a/ads_versioned_docs/version-v1/getting-started/signaling-service.mdx b/ads_versioned_docs/version-v1/getting-started/signaling-service.mdx new file mode 100644 index 000000000000..af904930bb28 --- /dev/null +++ b/ads_versioned_docs/version-v1/getting-started/signaling-service.mdx @@ -0,0 +1,263 @@ +--- +sidebar_position: 2 +sidebar_label: Signaling service +sidebar_custom_props: { 'icon': '🛜' } +--- + +# Signaling service + +import ThemedImage from '@theme/ThemedImage'; +import useBaseUrl from '@docusaurus/useBaseUrl'; + +The Signaling Service is provided as a service and can be integrated into any existing content management workflow through its APIs, enabling seamless adoption without significant changes to your current setup. + +Developed and provided by Dolby OptiView, this service operates on your infrastructure, integrated between your CDN and media origin. It performs manifest manipulation to insert ad breaks and additional metadata for the player. Additionally, it ensures scalability of the end-to-end system through early ad break notifications to ad decisioning servers. + + + +## Infrastructure integration + +The service is deployed and operated by Dolby OptiView within the customer’s infrastructure. This setup ensures smooth integration into the existing video workflow with minimal disruption. During onboarding, Dolby OptiView provides the specific infrastructure and network requirements. Once set up, Dolby OptiView bootstraps the service, after which the customer can manage their streams and monitor the service through the REST API. + +In collaboration with the customer and Dolby OptiView's solutions team, the integration of the service into the existing video workflow is designed. Deploying the Signaling Service between the CDN and Origin ensures that regionalization, security, and localization features remain unaffected. + +> To ensure high availability, we recommend maintaining the original origin stream on a CDN as a backup, while the Signaling Service provides redundancy and failover capabilities to further enhance reliability. + +## Monetized streams + +After deployment of the Signaling Service has been completed, the next step is the creation of monetized streams. A monetized stream represents an instance of a origin stream that is processed by the Signaling Service to enable OptiView Ads for this origin stream. Created via the locally deployed REST API, it exposes a standardized HTTPS (or HTTP) endpoint for the CDN to fetch the augmented manifest. This setup ensures seamless ad insertion without needing CDN reconfiguration, even if the monetized stream is stopped and recreated. + +The monetized stream holds the following information: + +- `streamId`: Unique identifier for the monetized stream within the environment. +- `name`: Self defined descriptive name for the monetized stream. +- `description`: Optional descriptive information for the monetized stream. +- `labels`: Array of self defined labels (string). +- `layout`: Default experience layout, see [ad experience layout](/ads/how-to-guides/override-layout/). +- `origin`: Your media origin host from where the origin manifests are loaded. +- `segmentOrigin`: Your publicly available segments origin host from where the stream's video and audio segments are hosted. In most cases this is identical to the `origin` parameter. +- `assetKey`: Optional Google DAI Asset-Key linked to this stream, see [Google DAI](https://support.google.com/admanager/topic/7062524?hl=en). +- `networkCode`: Optional Google DAI Network-Code, see [Google DAI](https://support.google.com/admanager/topic/7062524?hl=en). +- `assetURI`: Optional default custom asset URI which is to be used during ad breaks. If not set it will request an ad break through Google Pod Serving using the `assetKey` and `networkCode` parameters. +- `backdropURI`: Optional URI containing the default backdrop to be used during the Double Box or L-shape ads. +- `backdropURIGamProperties`: Optional property with configuration values for a dynamic backdrop loaded via GAM to be used during the Double Box or L-shape ads. This property has priority over `backdropURI`. +- `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 and mostly takes care of expiry of scheduled ad breaks for 'LIVE'. + +```json +{ + "streamId": "optiview-ads-demo", + "name": "OptiView Ads Demo", + "description": "SGAI OptiView Ads Demo", + "labels": [], + "layout": "DOUBLE", + "origin": "https://domain.com", + "segmentOrigin": "https://segment-domain.com", + "assetKey": "google-sgai-demo", + "networkCode": "12345", + "assetURI": "https://asset.m3u8", + "backdropURI": "https://backdrop.svg" +} +``` + +### Creating a new monetized stream + +The following API endpoint creates a bare minimal new monetized stream with GAM360 Pod serving for the ad breaks using the 'SINGLE' layout: + +```bash +curl -L 'https:///ads-client/api/v1/monetized-streams' \ + -H 'Content-Type: application/json' \ + -H 'Accept: application/json' \ + -d '{ + "streamId": "string", + "name": "string", + "layout": "SINGLE", + "origin": "string", + "segmentOrigin": "string", + "assetKey": "string", + "networkCode": "string", + }' +``` + +Alternatively, you can use the assetURI variant when GAM360 Pod serving is not required: + +```bash +curl -L 'https:///ads-client/api/v1/monetized-streams' \ + -H 'Content-Type: application/json' \ + -H 'Accept: application/json' \ + -d '{ + "streamId": "string", + "name": "string", + "layout": "SINGLE", + "origin": "string", + "segmentOrigin": "string", + "assetURI": "string" + }' +``` + +### Updating an existing monetized stream + +The following API endpoint updates the properties of an existing monetized stream based on its `streamId`: + +```bash +curl -L -X PATCH 'https:///ads-client/api/v1/monetized-streams/:streamId' \ + -H 'Content-Type: application/json' \ + -H 'Accept: application/json' \ + -d '{ + "streamId": "string", + "name": "string", + "description": "string", + "labels": [ + "string" + ], + "origin": "string", + "segmentOrigin": "string", + "assetKey": "string", + "networkCode": "string", + "assetURI": "string" + }' +``` + +### Deleting an existing monetized stream + +The following API endpoint deletes an existing monetized stream based on its `streamId`. + +```bash +curl -L -X DELETE 'https:///ads-client/api/v1/monetized-streams/:streamId' \ + -H 'Accept: application/json' +``` + +### Retrieving all monetized streams + +The following API endpoint returns all existing monetized streams in the deployed environment. + +```bash +curl -X GET 'https:///ads-client/api/v1/monetized-streams' \ + -H 'accept: application/json' +``` + +The response is an array of the existing monetized stream resources. + +```json +[ + { + "id": "optiview-ads-demo", + "payload": { + "streamId": "optiview-ads-demo", + "name": "OptiView Ads Demo", + "description": "SGAI OptiView Ads Demo", + "labels": [], + "layout": "DOUBLE", + "origin": "https://domain.com", + "segmentOrigin": "https://segment-domain.com", + "assetKey": "google-sgai-demo", + "networkCode": "12345" + }, + "state": "created", + "type": "monetized-stream" + } +] +``` + +### Retrieving an individual monetized stream + +The following API endpoint returns an existing monetized stream based on its identifier (`streamId`). + +```bash +curl -L 'https:///ads-client/api/v1/monetized-streams/:streamId' \ + -H 'Accept: application/json' +``` + +The response is the monetized stream resource. + +```json +{ + "id": "optiview-ads-demo", + "payload": { + "streamId": "optiview-ads-demo", + "name": "OptiView Ads Demo", + "description": "SGAI OptiView Ads Demo", + "labels": [], + "layout": "DOUBLE", + "origin": "https://domain.com", + "segmentOrigin": "https://segment-domain.com", + "assetKey": "google-sgai-demo", + "networkCode": "12345" + }, + "state": "created", + "type": "monetized-stream" +} +``` + +Please refer to the [API reference](/ads/api/signaling/theoads-api/) for even more detailed information on the REST API. + +### Player source + +When playing an OptiView Ads source corresponding to a monetized stream, it is expected to pass a source that looks like this: + +```js +src: 'https:///signaling-service/api/v1//hls/MANIFEST-URI'; +``` + +In this URI, the `` points to the network endpoint where the OptiView Ads service is deployed, preferably a DNS entry pointing to the service IP endpoint and reachable from the CDN. +Secondly, the `` corresponds to the `streamId` for the monetized stream. +Finally, the `MANIFEST-URI` part points to the origin's manifest relative to the configured `origin` property of the monetized stream. The signaling service will concatenate the `origin` property and the MANIFEST-URI to build the origin manifest URI. +For example: + +```js +src: 'https:///signaling-service/api/v1//hls/manifest.m3u8'; +``` + +Segment URLs in the media playlists should be absolute URLs however. Segment requests don't need to pass through the Signaling Service but should be fetched directly from the CDN to the origin so as to keep the benefit of scaling via the CDN. +The `segmentOrigin` parameter should contain this publicly available endpoint to fetch the segments directly. The signaling service will concatenate the `segmentOrigin` parameter with the segment URIs in the playlists to build an absolute segment URI. + +## Scheduling ad breaks + +Once all the required monetized streams are configured, the next step is scheduling ad breaks for these monetized streams. +To accurately schedule ad breaks, the origin manifest must be valid and include date and time indications. +For HLS, this means the `EXT-X-PROGRAM-DATE-TIME` tag must be present. +Ad breaks can be signaled through either the provided REST API or by including the relevant information in the manifest itself. + +### Manifest + +When using manifest signaling, the following tags are supported: + +- `#EXT-X-DATERANGE` tag + - this is recommended because of its standardization and ability to provide more comprehensive data for improved integration. +- `#EXT-X-OATCLS-SCTE35` tag +- `#EXT-X-CUE-OUT` and `#EXT-X-CUE-OUT-CONT` tags + +Optionally, SCTE markers can be included with the tags for extra metadata. + +### REST API + +For scheduling ad breaks through the REST API, please refer to the [API definitions](/ads/api/signaling/create-monetized-stream-break/) and the example below. + +```bash +curl --location 'https:///ads-client/api/v1/monetized-streams/stream-1/break' \ +--header 'Content-Type: application/json' \ +--header 'Accept: application/json' \ +--data '{ + "id": "626cd35a-4fbf-48b8-b0cd-acc246266f88", + "startDate": "2024-09-03T08:00:00.000Z", + "duration": 60, + "source": "", + "layout": "LSHAPE_AD" +}' +``` + +For more in depth information on scheduling ad breaks we refer to our [How-to guide: Scheduling breaks](/ads/how-to-guides/scheduling-breaks/) + +For more information on this topic we refer to our [workflow integration](/ads/how-to-guides/workflow-integration/). + +# More information + +- [API reference](/ads/api/signaling/theoads-api/) +- [What is OptiView Ads?](https://optiview.dolby.com/products/server-guided-ad-insertion/) +- [The Advantages of Server-Guided Ad Insertion](https://optiview.dolby.com/solutions/personalized-advertising/) +- [Is Server-Guided Ad-Insertion (SGAI) revolutionizing streaming monetization? (blog)](https://optiview.dolby.com/resources/blog/advertising/what-is-sgai-server-guided-ad-insertion-in-streaming/) diff --git a/ads_versioned_docs/version-v1/getting-started/web.mdx b/ads_versioned_docs/version-v1/getting-started/web.mdx new file mode 100644 index 000000000000..ec585bfb2553 --- /dev/null +++ b/ads_versioned_docs/version-v1/getting-started/web.mdx @@ -0,0 +1,114 @@ +--- +sidebar_position: 2 +sidebar_label: Web +sidebar_custom_props: { 'icon': 'web' } +--- + +# Getting started with OptiView Ads on Web + +This guide will get you started with OptiView Ads in your OptiView Player Web SDK: configure the license, update dependencies and set the source description. + +## Prerequisites + +1. You need to have an OptiView Player license which is compatible with OptiView Ads. This can be done through the [player portal](https://portal.theoplayer.com). +2. You need a correctly deployed [OptiView Ads signaling service](signaling-service.mdx). +3. Your THEOplayer SDK needs to have the `theoads` feature enabled. + + As of OptiView Player version 8.2.0, this feature is enabled by default in the main `theoplayer` package so we recommend to use at least this version, preferably the latest available version. + You can install this package with the following command: + + ```bash + npm install theoplayer + ``` + +## Integration + +This guide assumes you know how to set up OptiView Player. For more information regarding this, check out the [OptiView Player getting started](/theoplayer/getting-started/sdks/web/getting-started/). + +### Google DAI library + +Since OptiView Ads integrates with Google DAI Pod Serving, it is required to load the Google DAI script on your page: + +```html + +``` + +### Player configuration + +To make use of the OptiView Ads integration, first enable the feature in your player configuration: + +```javascript +const player = new THEOplayer.Player(element, { + libraryLocation: 'YOUR-LIBRARY-LOCATION', + license: 'YOUR-LICENSE-WITH-OPTIVIEW-ADS', + ads: { + theoads: true, + }, +}); +``` + +Then, specify a source with an OptiView Ads-enabled ad description: + +```javascript +player.source = { + sources: { + src: 'PATH-TO-SIGNALING-SERVER/hls/MANIFEST-URI', + type: 'application/x-mpegurl', + hlsDateRange: true, + }, + ads: [ + { + integration: 'theoads', + networkCode: 'NETWORK-CODE', + customAssetKey: 'CUSTOM-ASSET-KEY', + }, + ], +}; +``` + +- Notice that the `src` is different as usual. For OptiView Ads, 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](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` object needs to have its integration set to `theoads`. Furthermore, the `networkCode` and `customAssetKey` needs to be set according to your configured Google account. + +## Integrating with Open Video UI + +OptiView Ads works seamlessly together with [Open Video UI for Web](/open-video-ui/web/). You can pass your OptiView Ads-enabled source directly to the UI's `source` property: + +```html + + +``` + +It should look something like this: + +![Screenshot of Open Video UI playing an OptiView Ads stream](../assets/img/web-ui.png) + +## More information + +- [API references](pathname:///theoplayer/v11/api-reference/web/interfaces/TheoAdDescription.html) +- [What is OptiView Ads?](https://optiview.dolby.com/products/server-guided-ad-insertion/) +- [The Advantages of Server-Guided Ad Insertion](https://optiview.dolby.com/solutions/personalized-advertising/) +- [Is Server-Guided Ad-Insertion (SGAI) revolutionizing streaming monetization? (blog)](https://optiview.dolby.com/resources/blog/advertising/what-is-sgai-server-guided-ad-insertion-in-streaming/) diff --git a/ads_versioned_docs/version-v1/how-to-guides/ad-impressions.md b/ads_versioned_docs/version-v1/how-to-guides/ad-impressions.md new file mode 100644 index 000000000000..0eb26f798c83 --- /dev/null +++ b/ads_versioned_docs/version-v1/how-to-guides/ad-impressions.md @@ -0,0 +1,22 @@ +--- +sidebar_position: 2 +--- + +# Ad impression tracking + +When inserting an ad experience using OptiView Ads, the player sends a beacon to OptiView's server to track the ad impression usage. An ad impression refers to each ad experience inserted into the content and presented to the viewer using OptiView Ads, counted from the first presentation of the experience. + +:::note +The ad impression is beaconed simultaneously with the firing of the player's `adbreakbegin` event. +::: + +## Information tracked + +The information passed only contains an identifier of the OptiView Player license build so the impressions are linked to the customer. It also includes the ad experience type. +No information about the viewers is passed along. + +## View my impression usage + +You can view your ad impressions on the portal dashboard underneath the OptiView Player license impressions. + +![Portal dashboard](../assets/img/impressions.png) diff --git a/ads_versioned_docs/version-v1/how-to-guides/ad-tag-parameters.md b/ads_versioned_docs/version-v1/how-to-guides/ad-tag-parameters.md new file mode 100644 index 000000000000..5cb6d7e534b5 --- /dev/null +++ b/ads_versioned_docs/version-v1/how-to-guides/ad-tag-parameters.md @@ -0,0 +1,109 @@ +--- +sidebar_position: 3 +--- + +# Ad targeting parameters + +With the Google DAI Pod Serving, there is the possibility to pass [a limited set of ad targeting parameters](https://support.google.com/admanager/answer/7320899) on your stream request to personalize your streams. +In the player you can easily pass these parameters as key-value pairs via the `TheoAdDescription`. + +:::note +The player will automatically add the custom parameter `theoads_slot` in the `cust_params` field when requesting an ad. +The value of this parameter will be determined by the layout mode. +::: + +## Web SDK + +For the Web SDK, you can set your desired ad tag parameters via `adTagParameters` in the `TheoAdDescription` as followed: + +```javascript +player.source = { + sources: { + src: 'PATH-TO-SIGNALING-SERVER/hls/MANIFEST-URI', + type: 'application/x-mpegurl', + hlsDateRange: true, + }, + ads: [ + { + integration: 'theoads', + networkCode: 'NETWORK-CODE', + customAssetKey: 'CUSTOM-ASSET-KEY', + adTagParameters: { + "YOUR-AD-TAG-PARAMETER-1" : "VALUE-1", // e.g. "cust_params" : "YOUR-CUSTOM-PARAMETERS", + "YOUR-AD-TAG-PARAMETER-2" : "VALUE-2", + ... + } + }, + ], +}; +``` + +## React Native SDK + +For the React Native SDK, you can set your desired ad tag parameters via `adTagParameters` in the `TheoAdDescription` as followed: + +```javascript +player.source = { + sources: { + src: 'PATH-TO-SIGNALING-SERVER/hls/MANIFEST-URI', + type: 'application/x-mpegurl', + hlsDateRange: true, + }, + ads: [ + { + integration: 'theoads', + networkCode: 'NETWORK-CODE', + customAssetKey: 'CUSTOM-ASSET-KEY', + adTagParameters: { + "YOUR-AD-TAG-PARAMETER-1" : "VALUE-1", // e.g. "cust_params" : "YOUR-CUSTOM-PARAMETERS", + "YOUR-AD-TAG-PARAMETER-2" : "VALUE-2", + ... + } + }, + ], +}; +``` + +## Android SDK + +For the Android SDK, you can set your desired ad tag parameters via `adTagParameters` in the `TheoAdDescription` as followed: + +```kotlin +theoPlayerView.player.source = SourceDescription.Builder( + TypedSource.Builder("PATH-TO-SIGNALING-SERVER/hls/MANIFEST-URI") + .type(SourceType.HLS) + .hlsDateRange(true) + .build() +).ads( + TheoAdDescription( + networkCode = "NETWORK-CODE", + customAssetKey = "CUSTOM-ASSET-KEY", + adTagParameters = mapOf( + "YOUR-AD-TAG-PARAMETER-1" to "VALUE-1", + "YOUR-AD-TAG-PARAMETER-2" to "VALUE-2" + ) + ) +) +.build() +``` + +## iOS SDK + +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 + +- [Supply targeting parameters to your stream](https://support.google.com/admanager/answer/7320899) diff --git a/ads_versioned_docs/version-v1/how-to-guides/create-backdrop-layout.md b/ads_versioned_docs/version-v1/how-to-guides/create-backdrop-layout.md new file mode 100644 index 000000000000..d3d56d2c7253 --- /dev/null +++ b/ads_versioned_docs/version-v1/how-to-guides/create-backdrop-layout.md @@ -0,0 +1,47 @@ +--- +sidebar_position: 7 +--- + +# Create backdrop images + +A backdrop is an companion image that is shown along with the player during an ad. +This image is intended to provide either some additional information about an advertisement or a companion advertisement next to the main content. + +## Backdrop Layout Options + +There are two primary backdrop layout options, each serving a specific purpose in presenting ads effectively: + +### 1. Double Box Layout + +The **Double Box** layout places the video content and advertisement side by side, allowing viewers to see both elements simultaneously. + +- **Screen Ratio**: 16:9 for optimal viewing on widescreen displays. +- **Border**: A fixed 20px border is applied around the video elements, ensuring a clean, defined separation between the content and the ad. + +#### Example Template + +Below is a template for the Double Box layout tailored for 1080p resolution: + +![Double box Template.png](../assets/img/backdrop-doublebox-template.png) + +### 2. L-shape Layouts + +The **L-shape** layout positions the video player in the top-left corner of the screen, scaling it down to create space for the backdrop image. +This configuration allows viewers to see the content or an ad and the backdrop image simultaneously. + +- **Screen Ratio**: 16:9, ensuring compatibility with most screens. +- **Positioning**: The player is moved to the top-left corner, with the backdrop image filling the remaining space. + +#### Example Template + +Below is a template for the L-shape layout: + +![L-shape Template.png](../assets/img/backdrop-lshape-template.png) + +## Considerations and Limitations + +While both layouts serve distinct purposes, certain limitations should be considered: + +- **Device Compatibility**: Most Smart TVs do not support the Double Box layout due to the lack of capability to show multiple video streams at the same time. For these devices, the L-shape layout is a better option, as it displays only one active video stream along with the backdrop image. We currently disable Double Box for Smart TVs for this reason and fallback to Single layout. +- **Resolution Adaptability**: Templates are made for 1080p resolution, but scaling considerations should be taken into account for lower or higher resolutions to maintain the quality and layout proportions. +- **File Size and Load Times**: To ensure smooth playback and quick loading times, backdrop images should be optimized, especially for mobile and lower-capability devices. diff --git a/ads_versioned_docs/version-v1/how-to-guides/dynamic-backdrops.md b/ads_versioned_docs/version-v1/how-to-guides/dynamic-backdrops.md new file mode 100644 index 000000000000..6fef2a7b4f21 --- /dev/null +++ b/ads_versioned_docs/version-v1/how-to-guides/dynamic-backdrops.md @@ -0,0 +1,41 @@ +--- +sidebar_position: 8 +--- + +# Dynamic backdrops + +Some layouts, such as L-shape and Double Box, make use of a backdrop. These can be specified on both the monetized stream and the ad break in 2 ways: + +- `backdropURI`: Optional URI containing the default backdrop to be used during the Double Box or L-shape ads. +- `backdropURIGamProperties`: Optional property with configuration values for a dynamic backdrop loaded via GAM to be used during the Double Box or L-shape ads. This property has priority over `backdropURI`. + +## Using the OptiView Ads service REST API + +The way to specify backdrops is through the OptiView Ads service API when creating or updating both monetized streams and adbreaks. + +The body of the post request for both monetized streams and ad breaks can have the following properties: + +```ts +{ + ... + backdropURI: string | undefined; + backdropURIGamProperties: { + iu: string; + sz: { + default: string; + phone: string | undefined; + tv: string | undefined; + } + } | undefined; + ... +} +``` + +- `backdropURI` can optionally be used to specify a URI that returns the actual backdrop image to be used. +- `backdropURIGamProperties` can optionally be used to specify the values required for requesting a pre-configured custom creative from GAM (See below). It follows the [specifications](https://support.google.com/admanager/answer/2623168#zippy=%2Crequired-parameters) for a tagless request to load a creative. If `backdropURIGamProperties` is not defined, you need to specify `backdropURI`. + - `iu` specifies the Google Ad Manager ad unit code, including your Google Ad Manager network code. + - `sz` specifies the creative size configured in GAM. Aside from the required `default` value, you can optionally specify alternative values for either `phone` or `tv` devices. + +Please refer to [Custom GAM Creatives](../gam-custom-creatives) for information on how to setup your own custom creatives in GAM. + +That's it! You should now be able to configure dynamic backdrops for L-shape and Double Box ad breaks. diff --git a/ads_versioned_docs/version-v1/how-to-guides/gam-custom-creatives.md b/ads_versioned_docs/version-v1/how-to-guides/gam-custom-creatives.md new file mode 100644 index 000000000000..afa8d2174f13 --- /dev/null +++ b/ads_versioned_docs/version-v1/how-to-guides/gam-custom-creatives.md @@ -0,0 +1,51 @@ +--- +sidebar_position: 9 +--- + +# Custom GAM Creatives + +When using GAM for delivering dynamic backdrops or overlays respectively through the `backdropURIGamProperties` or `gamProperties` properties, you need to first configure corresponding Creatives in the GAM console. + +First off, you need to define a custom creative template specifically for OptiView Ads as documented [here](https://support.google.com/admanager/answer/1138308#custom-templates). + +You can either import this [pre-defined template](pathname:///ads/templates/OptiView_Ads_gam_template.json), or follow the steps below. + +Apart from assigning a `Name` and optional `Description`, you need to perform the following changes: + +- Configure a File type variable `Image`, optionally limiting the allowed file types: + +![Configure a File type variable `Image`](../assets/img/gam_image_1.png) + +- Optionally configure a URL type variable `ClickThrough`: + +![Configure a URL type variable `ClickThrough`](../assets/img/gam_image_2.png) + +- Configure the `Code snippet` as follows: + +```json +{ + "image": "[%Image%]", + "clickThrough": "[%ClickThrough%]", + "impression": "%%VIEW_URL_ESC%%" +} +``` + +Note the `impression` field which is needed for the player to properly handle impression tracking. The special macro `%%VIEW_URL_ESC%%` is supplied by GAM and will contain a GAM specific impression URL which is called when the backdrop is shown on the client. + +In the end it should look like this: + +![Create custom creative template](../assets/img/gam_image_3.png) + +Now that the template is set up, you can start adding creatives as you would otherwise when using standard image creatives, except you need to select this Custom creative template when adding the new creatives: + +![Create custom creative template](../assets/img/gam_image_4.png) + +When editing the creative itself, make sure to select an appropriate `Target ad unit size` as you would with a standard image creative also. This size corresponds to the `sz` property values inside the `gamProperties`. + +Besides that, you need to at least also upload or select a suitable image for display. + +![Create custom creative template](../assets/img/gam_image_5.png) + +Now that the creatives are defined, make sure to add them to a line item that is at least in status 'Ready' so delivery can commence (Ref GAM [documentation](https://support.google.com/admanager/answer/82991?hl=en&ref_topic=7506394&sjid=17311913585360515246-EU)). + +That's it! You should now be able to add dynamic backdrops and image overlays which should show up inside the player at the appropriate time and location. diff --git a/ads_versioned_docs/version-v1/how-to-guides/index.mdx b/ads_versioned_docs/version-v1/how-to-guides/index.mdx new file mode 100644 index 000000000000..ee230a5c7b5f --- /dev/null +++ b/ads_versioned_docs/version-v1/how-to-guides/index.mdx @@ -0,0 +1,12 @@ +--- +sidebar_position: 2 +sidebar_label: How-to guides +--- + +# How-to guides + +These guides provide detailed information on specific features of OptiView Ads (SGAI). They cover how ad impressions are tracked, how custom ad tag parameters can be included in the ad decisioning request, how ad formats can be overridden client-side, and how breaks can be signaled. + +import DocCardList from '@theme/DocCardList'; + + diff --git a/ads_versioned_docs/version-v1/how-to-guides/override-layout.md b/ads_versioned_docs/version-v1/how-to-guides/override-layout.md new file mode 100644 index 000000000000..4eaf568ab2cc --- /dev/null +++ b/ads_versioned_docs/version-v1/how-to-guides/override-layout.md @@ -0,0 +1,154 @@ +--- +sidebar_position: 4 +--- + +# Override ad experience layout + +OptiView Ads is able to insert ad breaks into your content via the signaling server. The layout that is used while playing is usually determined by the signaling server. Currently, you can have the following layout modes : + +- `SINGLE`: Replaces the content with an advertisement. +- `DOUBLE`: Allows content to continue playing side-by-side with an advertisement and its companion background. +- `LSHAPE_AD`: Displays advertisements in a scaled window alongside a companion background. +- `LSHAPE_CONTENT`: Displays the original content video in a scaled window alongside a companion background. + +When your signaling service is created, the default layout should be defined. Look at our [API references](/ads/api/signaling/create-monetized-stream/) for more information. + +The rest of this page will go over how to override this initial chosen layout in the [signaling service](#override-layout-through-the-signaling-service) itself, +or override it on the [player side](#override-the-layout-through-the-player). + +## Override layout through the signaling service + +There are two ways to update the layout in the signaling service. + +### Setting a new default layout + +It is possible to update the default layout value on the signaling service. This can be done by making an [UpdateMonetizedStreamLayout](/ads/api/signaling/update-monetized-stream-layout/) API request to the signaling service with the new layout. The updated layout value will be the new default for all ad breaks. + +### Signaling an ad break through the API + +When scheduling ad breaks through the signaling service API it is possible to choose the layout of the ad break. The passed layout will be used, unless it is left `undefined`. In this case the default layout is still used. + +For more information on the scheduling API refer to the following section: [Scheduling breaks through the signaling service](/ads/how-to-guides/scheduling-breaks/#using-the-optiview-ads-service-rest-api). + +## Override the layout through the player + +You might not always want to show the default layout mode as provided by the signaling server. For example, if you are watching content on a mobile device, the `DOUBLE` layout mode might not be the ideal user experience. + +Via the player, you can pass the following values to `TheoAdDescription.overrideLayout` to override the layout: + +- `single`: This will override the default layout and plays all the ad breaks using the "single" layout mode. +- `l-shape`: This will override the default layout mode and plays all the ad breaks using the "l-shape" layout mode. +- `double`: This will override the default layout mode and plays all the ad breaks using the "double" layout mode. +- `single-if-mobile`: This will override the default layout mode to play all ad breaks using the "single" layout mode only when on mobile. + +### Web SDK + +For the Web SDK, you can override the default layout by setting `overrideLayout` in the `TheoAdDescription` object as followed: + +```javascript +player.source = { + sources: { + src: 'PATH-TO-SIGNALING-SERVER/hls/MANIFEST-URI', + type: 'application/x-mpegurl', + hlsDateRange: true, + }, + ads: [ + { + integration: 'theoads', + networkCode: 'NETWORK-CODE', + customAssetKey: 'CUSTOM-ASSET-KEY', + overrideLayout: 'YOUR-DESIRED-LAYOUT', + }, + ], +}; +``` + +:::note +There is a limitation that Double Box (`DOUBLE`) is not supported on Chromecast and older smart TVs. These revert to the single layout automatically. +::: + +### React Native SDK + +For the React Native SDK, you can override the default layout by setting `overrideLayout` in the `TheoAdDescription` object as followed: + +```javascript +player.source = { + sources: { + src: 'PATH-TO-SIGNALING-SERVER/hls/MANIFEST-URI', + type: 'application/x-mpegurl', + hlsDateRange: true, + }, + ads: [ + { + integration: 'theoads', + networkCode: 'NETWORK-CODE', + customAssetKey: 'CUSTOM-ASSET-KEY', + overrideLayout: 'single', // "l-shape", "double", "single-if-mobile" + }, + ], +}; +``` + +### Android SDK + +For the Android SDK, you can override the default layout by setting `overrideLayout` in the `TheoAdDescription` object as follows: + +```kotlin +import com.theoplayer.android.api.ads.theoads.TheoAdsDescription +import com.theoplayer.android.api.source.SourceDescription +import com.theoplayer.android.api.source.SourceType +import com.theoplayer.android.api.source.TypedSource + +theoPlayerView.player.source = SourceDescription.Builder( + TypedSource.Builder("PATH-TO-SIGNALING-SERVER/hls/MANIFEST-URI") + .type(SourceType.HLS) + .hlsDateRange(true) + .build() +).ads( + TheoAdsDescription( + networkCode = "NETWORK-CODE", + customAssetKey = "CUSTOM-ASSET-KEY", + overrideLayout = "single", // "l-shape", "double" + ) +).build() +``` + +### iOS SDK + +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() + } + +} +``` diff --git a/ads_versioned_docs/version-v1/how-to-guides/scheduling-breaks.md b/ads_versioned_docs/version-v1/how-to-guides/scheduling-breaks.md new file mode 100644 index 000000000000..5a13e63c8415 --- /dev/null +++ b/ads_versioned_docs/version-v1/how-to-guides/scheduling-breaks.md @@ -0,0 +1,130 @@ +--- +sidebar_position: 5 +--- + +# Scheduling breaks + +OptiView Ads can insert ad breaks into your content, but it requires placement information to do so. This page will outline the various options for scheduling ad breaks. + +## Using the manifest + +There are multiple ways to provide the general ad break information in the manifest itself. +In this section we'll go through the different options and the minimal requirements. + +:::note +For HLS live streams, we require the `#EXT-X-PROGRAM-DATE-TIME` tag to be present. +This is necessary to have a clear timeline for each viewer and allows accurate scheduling of the ad breaks. +::: + +As mentioned it is possible to schedule the start time and duration of the ad breaks inside of the manifest. +The signaling service will recognize this information and will translate it so that the player can request the correct ads and layout for the ad break. + +There are several options for achieving this: + +### DATERANGE (Manifest) {#daterange} + +The `#EXT-X-DATERANGE` tag is the recommended approach to signal an ad break due to its standardization. +OptiView Ads will recognize any `#EXT-X-DATERANGE` tag as long as the `CLASS` attribute is undefined. + +The required attributes for this are: + +- `ID`: a unique identifier of the daterange in the playlist. +- `START-DATE`: A quoted string containing the date/time at which the daterange begins. +- `DURATION` or `PLANNED-DURATION` of the daterange. + - Optionally `SCTE35-OUT` could contain the duration instead. + +An example snippet can be found below: + +``` +#EXTINF:10 +1.ts +#EXT-X-DATERANGE:ID="1",START-DATE="2022-09-27T18:00:00.000Z",PLANNED-DURATION=30 +#EXTINF:10 +2.ts +``` + +### CUE-OUT (Manifest) {#cue-out} + +Inside the manifest the ad break start can be signaled by adding an `#EXT-X-CUE-OUT` tag. The duration of the ad break should be specified after it. The end of the ad break and start of content would be signaled by an `#EXT-X-CUE-IN` tag. The `CUE-OUT` tag can be accompanied by a [daterange](#daterange). This is relevant if the ad break start does not correspond with the start of a new segment. + +It is also recommended to add `#EXT-X-CUE-OUT-CONT` tags for each segment inside of the ad break. +This enables the tune-in feature which is able to show parts of the ad break even if the viewer joins in the middle of one. + +Similar to the daterange, `SCTE35` markers could optionally be added containing the duration and the ID of the ad break. + +An example manifest with these tags can be found below: + +``` +#EXTINF:10 +1.ts +#EXT-X-CUE-OUT:30 +#EXTINF:10 +2.ts +#EXT-X-CUE-OUT-CONT:ElapsedTime=10,Duration=30 +#EXTINF:10 +3.ts +#EXT-X-CUE-OUT-CONT:ElapsedTime=20,Duration=30 +#EXTINF:10 +4.ts +#EXT-X-CUE-IN +#EXTINF:10 +5.ts +``` + +### OATCLS-SCTE35 (Manifest) {#oatcls-scte35} + +The `#EXT-OATCLS-SCTE35` tag is a non-standard tag which contains a SCTE marker. +The Signaling Service will parse the information in the SCTE marker such as the duration and ID. + +An example snippet for an `#EXT-OATCLS-SCTE35` tag can be found below: + +``` +#EXTINF:10, +1.ts +#EXT-OATCLS-SCTE35:/DBFAAAAAAAAAP/wFAUAAAI+f+/+yuN1kH4Azf5gAAAAAAAgAh5DVUVJAAABy3//AADN/mAOCk5GTF9saW5lYXIwAACyYCjX +#EXTINF:10, +2.ts +``` + +## Using the OptiView Ads service REST API + +If the ad information won't be present in the provided manifest, it is possible to schedule one through the OptiView Ads service API. + +This can be done by a POST request to `{path}/break` where path is the usual url to interact with the OptiView Ads service for a specific monetized stream: `{optiview-ads-host}/ads-client/api/v1/monetized-streams/:monetizedStreamId`. Please see [CreateMonetizedStreamBreak](/ads/api/signaling/create-monetized-stream-break/). + +The body of the post request can have the following properties: + +```ts +{ + id: string; + startDate: string; + duration: string; + source: string | undefined; + layout: string | undefined; + assetURI: string | undefined; + backdropURI: string | undefined; + backdropURIGamProperties: string | undefined; +} +``` + +- The `id` corresponds to the ID of the DATERANGE which corresponds to the ad break request. +- `startDate` denotes when the ad break should start. It should be in a Program Date Time format such as such as `YYYY-MM-DDThh:mm:ss.SSSZ`. +- `duration` is the total duration of the ad break (seconds). +- `source` is the optional identifier of the source for which the ad needs to be scheduled. The signaling service will only insert the ad for playlists containing part of this in their URL. If not set the ad is scheduled in every playlist. +- `layout` is the optional OptiView Ads layout, which can be set to `SINGLE`, `DOUBLE`, `LSHAPE_AD` or `LSHAPE_CONTENT`. If it is `undefined` the default layout of the signaling service will be chosen. +- `assetURI` is the optional manifest URI of an alternative ad source. If set it will use this URI during the scheduled ad break instead of Google Pod Serving. +- `backdropURI`: Optional URI containing the backdrop to be used for this ad break. +- `backdropURIGamProperties`: Optional property with configuration values for a dynamic backdrop loaded via GAM to be used for this ad break. This property has priority over `backdropURI`. + +Note: for properties that are set on both the monetized stream and the ad break, the values on the ad break have priority. + +An example of a schedule ad break request body can be found below: + +```json +{ + "id": "1", + "startDate": "YYYY-MM-DDTHH:MM:SS.000Z", + "duration": "10", + "layout": "DOUBLE" +} +``` diff --git a/ads_versioned_docs/version-v1/how-to-guides/scheduling-overlays.md b/ads_versioned_docs/version-v1/how-to-guides/scheduling-overlays.md new file mode 100644 index 000000000000..6bd3dc330522 --- /dev/null +++ b/ads_versioned_docs/version-v1/how-to-guides/scheduling-overlays.md @@ -0,0 +1,137 @@ +--- +sidebar_position: 6 +--- + +# Scheduling overlays + +OptiView Ads can insert overlays into your content, but it requires placement information to do so. This page will outline the various options for scheduling overlays. + +## Using the OptiView Ads service REST API + +The recommended way to schedule overlays is through the OptiView Ads service API. + +This can be done by a POST request to `{path}/overlay` where path is the usual url to interact with the OptiView Ads service for a specific monetized stream: `{optiview-ads-host}/ads-client/api/v1/monetized-streams/:monetizedStreamId`. Please see [CreateMonetizedStreamOverlay](/ads/api/signaling/create-monetized-stream-overlay/). + +The body of the post request can have the following properties: + +```ts +{ + id: string; + name: string | undefined; + startDate: string; + duration: string; + type: string; + position: { + left: number | undefined; + right: number | undefined; + top: number | undefined; + bottom: number | undefined; + }; + size: { + width: number; + height: number; + }; + opacity: number | undefined; + gamProperties: { + iu: string; + sz: { + default: string; + phone: string | undefined; + tv: string | undefined; + } + } | undefined; + resourceURI: { + type: string; + default: string; + phone: string | undefined; + tv: string | undefined; + }[] | undefined; + clickThroughURI: string | undefined; +} +``` + +- The `id` uniquely identifies the overlay inside the monetized stream. +- `name` is used to optionally identify the overlay presentation with a human-friendly name. +- `startDate` denotes when the overlay presentation should start. It should be in a Program Date Time format such as `YYYY-MM-DDThh:mm:ss.SSSZ`. +- `duration` is the total duration of the overlay presentation (in seconds). +- `type` can only be 'image' for now. In the future we might extend this. +- `position` is required to know where the overlay needs to be presented on top of the video content. It requires a combination of either one of `left` or `right` and `top` or `bottom`. All values are percentage based and non-zero. The values denote the location from the specified side. For example: `left: 10` denotes `10% from the left edge of the video`. +- `size` is required to know what the overlay presentation's width and height need to be relative to the video content display size. All values are percentage based and non-zero. For example: `width: 20` denotes 20% of the current video display width. +- `opacity` can optionally be used to make the overlay less opaque. This value is percentage based and non-zero. The default is `100`. +- `gamProperties` can optionally be used to specify the values required for requesting a pre-configured custom creative from GAM (See below). It follows the [specifications](https://support.google.com/admanager/answer/2623168#zippy=%2Crequired-parameters) for a tagless request to load a creative. If `gamProperties` is not defined, you need to specify at least one `resourceURI`. + - `iu` specifies the Google Ad Manager ad unit code, including your Google Ad Manager network code. + - `sz` specifies the creative size configured in GAM. Aside from the required `default` value, you can optionally specify alternative values for either `phone` or `tv` devices. +- `resourceURI` can optionally be used to specify one or more types required for requesting a custom overlay via a URI. If `resourceURI` is not defined, you need to specify `gamProperties`. + - `type` is used to specify the resource type. Currently, only `png` and `svg` are supported. Based on the underlying platform, the suitable format will be chosen. + - `default`, `phone` and `tv` can be used to specify the corresponding resource URI to load when presenting the overlay. While `default` is required, `phone` and `tv` are optional. +- `clickThroughURI` is an optional field used to enable the clickthrough function on the overlay for both the `gamProperties` and `resourceURI` options. + +An example of a schedule overlay request body for a GAM based image overlay can be found below: + +```json +{ + "id": "1", + "name": "Test overlay 1", + "startDate": "2024-12-09T07:30:11.274Z", + "duration": "30", + "type": "image", + "position": { + "left": 5, + "top": 5 + }, + "size": { + "width": 10, + "height": 10 + }, + "opacity": 50, + "gamProperties": { + "iu": "/12345678/overlay_1", + "sz": { + "default": "400x225", + "phone": "400x225", + "tv": "400x225" + } + }, + "clickThroughURI": "https://optiview.dolby.com" +} +``` + +An example of a schedule overlay request body for a custom image overlay can be found below: + +```json +{ + "id": "2", + "name": "Test overlay 2", + "startDate": "2024-12-09T07:30:11.274Z", + "duration": "30", + "type": "image", + "position": { + "left": 5, + "top": 5 + }, + "size": { + "width": 10, + "height": 10 + }, + "opacity": 50, + "resourceURI": [ + { + "type": "svg", + "default": "https:///image.svg", + "phone": "https:///image_phone.svg", + "tv": "https:///image_tv.svg" + }, + { + "type": "png", + "default": "https:///image.png", + "phone": "https:///image_phone.png", + "tv": "https:///image_tv.png" + } + ], + "clickThroughURI": "https://optiview.dolby.com" +} +``` + +Please refer to [Custom GAM Creatives](../gam-custom-creatives) for information on how to setup your own custom creatives in GAM. + +That's it! You should now be able to add image overlays which should show up inside the player at the appropriate time and location. diff --git a/ads_versioned_docs/version-v1/how-to-guides/workflow-integration.md b/ads_versioned_docs/version-v1/how-to-guides/workflow-integration.md new file mode 100644 index 000000000000..fb93c260ed0e --- /dev/null +++ b/ads_versioned_docs/version-v1/how-to-guides/workflow-integration.md @@ -0,0 +1,32 @@ +--- +sidebar_position: 1 +--- + +# Workflow integration + +For implementing OptiView Ads, the Signaling Service must be integrated within your existing video workflow. This service acts as an intermediary between the media origin and the CDN, enabling ad insertion and metadata enrichment. + +## Existing Video Workflow + +In a typical video delivery workflow, the CDN fetches the manifest directly from the media origin, and all subsequent requests for video segments are also routed from the CDN to the origin. + +![Video workflow before](../assets/img/workflow-optiview-ads-before.png). + +## Integrating the Signaling Service + +By introducing the Signaling Service, the manifest requests from the CDN are intercepted before reaching the origin. The Signaling Service augments the manifest with ad break signals and any necessary metadata. Notably, video segment requests bypass the Signaling Service and continue to be fetched directly from the CDN to the origin, ensuring minimal impact on content delivery performance. + +![Video workflow after](../assets/img/workflow-optiview-ads-after.png). + +## Configuring the Signaling Service + +To integrate the Signaling Service with your workflow, the properties origin and segmentOrigin are crucial when setting up a new monetized stream: + +- `origin`: This property specifies where the original manifest should be fetched from. It points to the media origin that provides the main content. +- `segmentOrigin`: This property ensures that the segment URLs within the augmented manifest are absolute. It defines the path from which the segments should be requested, typically directly from the origin or CDN. + By configuring these properties, the Signaling Service seamlessly inserts ad breaks without affecting the video segment delivery flow. + +## More information + +- [Getting Started](/ads/getting-started/index.mdx) +- [API reference](/ads/api/signaling/theoads-api/) diff --git a/ads_versioned_docs/version-v1/index.mdx b/ads_versioned_docs/version-v1/index.mdx new file mode 100644 index 000000000000..c1e2ca8c9997 --- /dev/null +++ b/ads_versioned_docs/version-v1/index.mdx @@ -0,0 +1,55 @@ +--- +sidebar_position: 0 +sidebar_label: Introduction +--- + +# Dolby OptiView Ads Introduction + +import SidebarDocCardList from '@site/src/components/SidebarDocCardList'; +import RebrandingNotice from './callouts/_rebranding_notice.md'; +import ThemedImage from '@theme/ThemedImage'; +import useBaseUrl from '@docusaurus/useBaseUrl'; + + + +OptiView Ads is an ad insertion service for LIVE content (VoD support coming soon), utilizing Server-Guided Ad Insertion (SGAI). On these pages, you'll learn how to get started with OptiView Ads, how to configure the player and integrate the signaling service APIs. + +By logically redistributing responsibilities in the advertisement workflow, OptiView Ads: + +- Creates a seamless viewer experience across platforms. +- Simplifies the workflow by reducing complexity, which results in easier implementation and lower operational risk. +- Introduces innovative ad formats, creating more diverse and less intrusive ad opportunities. +- Maximizes workflow efficiency by reducing prefetching and over-allocation of inventory. +- Enables more relevant ads through a high degree of personalization. + +OptiView Ads is an advanced ad insertion service consisting of two key components: + +1. **Signaling Service**: This back-end component enriches the manifest from your existing origin with advanced ad break signaling. It integrates seamlessly with OptiView Player, the second component, to create a smooth and cohesive workflow. + +2. **OptiView Player**: The player fetches and replaces ads within the content, working closely with the Signaling Service to optimize the viewer experience across platforms. + + + +The Signaling Service is provided as a service and can be integrated into any existing content management workflow through its APIs, allowing for seamless adoption without significant changes to your current setup. + +To ensure high availability, we recommend maintaining the original origin stream on a CDN as a backup, while the Signaling Service provides redundancy and failover capabilities to further enhance reliability. + +OptiView Ads is tightly integrated with [Google Ad Manager](https://developers.google.com/ad-manager/dynamic-ad-insertion 'Google DAI') for ad decisioning, transcoding, and serving, ensuring a streamlined process for ad delivery and management. + +OptiView Ads enables innovative ad formats through OptiView Player, providing new ways to monetize content in a less intrusive manner. The out-of-the-box formats include, but are not limited to: + +- **Default Full Screen Ad Insertion**: Replaces the content with an advertisement. +- **Double Box**: Allows content to continue playing side-by-side with an advertisement and its companion background. +- **L-shape**: Displays content or advertisements in a scaled window alongside a companion background. + +![OptiView Ads experiences](./assets/img/ads_formats.svg) + +**Note**: Every OptiView Player comes with the functionality to enable OptiView Ads by default. However, an OptiView Ads-enabled OptiView Player license is required to activate this functionality. + + diff --git a/ads_versioned_docs/version-v1/limitations/index.mdx b/ads_versioned_docs/version-v1/limitations/index.mdx new file mode 100644 index 000000000000..180b63468104 --- /dev/null +++ b/ads_versioned_docs/version-v1/limitations/index.mdx @@ -0,0 +1,15 @@ +--- +sidebar_position: 3 +sidebar_label: Limitations and known issues +--- + +# Limitations and known issues + +This page lists the current limitations and known issues of OptiView Ads. + +## Using OptiView Ads with Picture-in-Picture (PiP) on Firefox for Web + +Using OptiView Ads with Picture-in-Picture (PiP) on Firefox for Web is currently not supported. During playback, the default PiP button +will be hidden to discourage usage. + +Note that users will still be able to trigger PiP using the button in the browser's address bar. diff --git a/ads_versioned_docs/version-v1/static/ads/img/how_ads_works-dark.svg b/ads_versioned_docs/version-v1/static/ads/img/how_ads_works-dark.svg new file mode 100644 index 000000000000..69cb4fc4107d --- /dev/null +++ b/ads_versioned_docs/version-v1/static/ads/img/how_ads_works-dark.svg @@ -0,0 +1,197 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/ads_versioned_docs/version-v1/static/ads/img/how_ads_works-light.svg b/ads_versioned_docs/version-v1/static/ads/img/how_ads_works-light.svg new file mode 100644 index 000000000000..702ccf6c1e47 --- /dev/null +++ b/ads_versioned_docs/version-v1/static/ads/img/how_ads_works-light.svg @@ -0,0 +1,197 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/ads_versioned_docs/version-v1/static/ads/templates/OptiView_Ads_gam_template.json b/ads_versioned_docs/version-v1/static/ads/templates/OptiView_Ads_gam_template.json new file mode 100644 index 000000000000..e13d88d29a4d --- /dev/null +++ b/ads_versioned_docs/version-v1/static/ads/templates/OptiView_Ads_gam_template.json @@ -0,0 +1,31 @@ +{ + "name": "OptiView Ads Image", + "description": "OptiView Ads Image", + "variables": [ + { + "mimeTypes": [], + "label": "Image", + "uniqueName": "Image", + "description": "The image to use", + "isRequired": true, + "variableType": "ASSET" + }, + { + "isTrackingUrl": false, + "urlType": "STANDARD_HTTP", + "label": "ClickThrough", + "uniqueName": "ClickThrough", + "description": "The clickthrough URL for this creative", + "isRequired": false, + "variableType": "URL" + } + ], + "formatter": "{\n\t\"image\": \"[%Image%]\",\n\t\"clickThrough\": \"[%ClickThrough%]\",\n \"impression\": \"%%VIEW_URL_ESC%%\"\n}", + "omidPartnerName": "", + "type": "USER_DEFINED", + "isInterstitial": false, + "isNativeEligible": false, + "isNativeVideoEligible": false, + "isNewsletterEligible": false, + "isSafeFrameCompatible": true +} diff --git a/ads_versioned_sidebars/version-v1-sidebars.json b/ads_versioned_sidebars/version-v1-sidebars.json new file mode 100644 index 000000000000..27c4bc2f9e39 --- /dev/null +++ b/ads_versioned_sidebars/version-v1-sidebars.json @@ -0,0 +1,225 @@ +{ + "ads": [ + "index", + { + "type": "category", + "label": "Getting started", + "description": "Set up your first stream with OptiView Ads!", + "collapsed": false, + "customProps": { + "icon": "🚀" + }, + "link": { + "type": "doc", + "id": "getting-started/index" + }, + "items": [ + { + "type": "autogenerated", + "dirName": "getting-started" + } + ] + }, + { + "type": "category", + "label": "How-to guides", + "description": "Learn how to integrate OptiView Ads with your setup", + "customProps": { + "icon": "📖" + }, + "link": { + "type": "doc", + "id": "how-to-guides/index" + }, + "items": [ + { + "type": "autogenerated", + "dirName": "how-to-guides" + } + ] + }, + { + "type": "category", + "label": "Limitations and known issues", + "description": "Take notice of the limitations and known issues when using OptiView Ads.", + "customProps": { + "icon": "⚠️" + }, + "link": { + "type": "doc", + "id": "limitations/index" + }, + "items": [ + { + "type": "autogenerated", + "dirName": "limitations" + } + ] + }, + { + "type": "category", + "label": "API references", + "description": "Discover all functions of OptiView Ads.", + "customProps": { + "icon": "*️⃣" + }, + "link": { + "type": "generated-index", + "slug": "api" + }, + "items": [ + { + "type": "link", + "label": "Signaling Service", + "customProps": { + "icon": "🛜" + }, + "href": "/ads/v1/api/signaling/theoads-api" + }, + { + "type": "link", + "label": "Web", + "customProps": { + "icon": "web" + }, + "href": "pathname:///theoplayer/v9/api-reference/web/interfaces/TheoAdDescription.html" + }, + { + "type": "link", + "label": "Android", + "customProps": { + "icon": "android" + }, + "href": "pathname:///theoplayer/v9/api-reference/android/com/theoplayer/android/api/ads/theoads/package-summary.html" + }, + { + "type": "link", + "label": "React Native", + "customProps": { + "icon": "react" + }, + "href": "https://theoplayer.github.io/react-native-theoplayer/api/interfaces/TheoAdDescription.html" + } + ] + } + ], + "signalingApi": [ + { + "type": "link", + "label": "« Back", + "href": "/ads/v1/" + }, + { + "type": "doc", + "id": "api/signaling/theoads-api" + }, + { + "type": "category", + "label": "Monetized-Stream", + "items": [ + { + "type": "doc", + "id": "api/signaling/get-monetized-streams", + "label": "GetMonetizedStreams", + "className": "api-method get" + }, + { + "type": "doc", + "id": "api/signaling/create-monetized-stream", + "label": "CreateMonetizedStream", + "className": "api-method post" + }, + { + "type": "doc", + "id": "api/signaling/get-monetized-stream", + "label": "GetMonetizedStream", + "className": "api-method get" + }, + { + "type": "doc", + "id": "api/signaling/update-monetized-stream", + "label": "UpdateMonetizedStream", + "className": "api-method patch" + }, + { + "type": "doc", + "id": "api/signaling/delete-monetized-stream", + "label": "DeleteMonetizedStream", + "className": "api-method delete" + }, + { + "type": "doc", + "id": "api/signaling/update-monetized-stream-layout", + "label": "UpdateMonetizedStreamLayout", + "className": "api-method patch" + }, + { + "type": "doc", + "id": "api/signaling/create-monetized-stream-break", + "label": "CreateMonetizedStreamBreak", + "className": "api-method post" + }, + { + "type": "doc", + "id": "api/signaling/get-monetized-stream-breaks", + "label": "GetMonetizedStreamBreaks", + "className": "api-method get" + }, + { + "type": "doc", + "id": "api/signaling/delete-monetized-stream-breaks", + "label": "DeleteMonetizedStreamBreaks", + "className": "api-method delete" + }, + { + "type": "doc", + "id": "api/signaling/update-monetized-stream-breaks", + "label": "UpdateMonetizedStreamBreaks", + "className": "api-method patch" + }, + { + "type": "doc", + "id": "api/signaling/create-monetized-stream-overlay", + "label": "CreateMonetizedStreamOverlay", + "className": "api-method post" + }, + { + "type": "doc", + "id": "api/signaling/get-monetized-stream-overlays", + "label": "GetMonetizedStreamOverlays", + "className": "api-method get" + }, + { + "type": "doc", + "id": "api/signaling/delete-monetized-stream-overlay", + "label": "DeleteMonetizedStreamOverlay", + "className": "api-method delete" + } + ] + }, + { + "type": "category", + "label": "Monetized-Stream-V2", + "items": [ + { + "type": "doc", + "id": "api/signaling/get-monetized-streams-paginated", + "label": "GetMonetizedStreamsPaginated", + "className": "api-method get" + }, + { + "type": "doc", + "id": "api/signaling/get-monetized-stream-breaks-paginated", + "label": "GetMonetizedStreamBreaksPaginated", + "className": "api-method get" + }, + { + "type": "doc", + "id": "api/signaling/get-monetized-stream-overlays-paginated", + "label": "GetMonetizedStreamOverlaysPaginated", + "className": "api-method get" + } + ] + } + ] +} diff --git a/ads_versions.json b/ads_versions.json new file mode 100644 index 000000000000..868a38e32ae6 --- /dev/null +++ b/ads_versions.json @@ -0,0 +1 @@ +["v1"] diff --git a/docusaurus.config.ts b/docusaurus.config.ts index 0f5464139e29..5be3015ffc40 100644 --- a/docusaurus.config.ts +++ b/docusaurus.config.ts @@ -211,6 +211,16 @@ const config: Config = { routeBasePath: '/ads', sidebarPath: './sidebarsAds.ts', docItemComponent: '@theme/ApiItem', + lastVersion: 'current', + versions: { + current: { + label: 'v2', + }, + v1: { + label: 'v1', + banner: 'none', + }, + }, async sidebarItemsGenerator(args) { const sidebarItems = await sidebarItemsGenerator(args); return removeDocIndexItems(sidebarItems); @@ -332,6 +342,8 @@ const config: Config = { docsPluginId: 'ads', config: { signaling: { + version: 'v2', + label: 'v2', specPath: 'ads/api/ads-client.swagger.json', outputDir: 'ads/api/signaling', hideSendButton: true, @@ -339,6 +351,16 @@ const config: Config = { groupPathsBy: 'tag', }, }, + signalingV1: { + version: 'v1', + label: 'v1', + specPath: 'ads_versioned_docs/version-v1/api/ads-client.swagger.json', + outputDir: 'ads_versioned_docs/version-v1/api/signaling', + hideSendButton: true, + sidebarOptions: { + groupPathsBy: 'tag', + }, + }, }, } satisfies OpenApiPlugin.PluginOptions, ], @@ -411,6 +433,8 @@ const config: Config = { return [existingPath.replace('/theoplayer/how-to-guides/web/uplynk/', '/theoplayer/how-to-guides/miscellaneous/verizon-media/')]; } else if (existingPath.startsWith('/theolive/v1/api/')) { return [existingPath.replace('/theolive/v1/api/', '/theolive/api/')]; + } else if (existingPath.startsWith('/ads/v1/')) { + return [existingPath.replace('/ads/v1/', '/ads/')]; } else if (existingPath === '/theolive/channel/metadata-insertion') { return ['/theolive/contribution/sei-messages']; } @@ -619,6 +643,11 @@ const config: Config = { docsPluginId: 'theoplayer', position: 'right', }, + { + type: 'docsVersionDropdown', + docsPluginId: 'ads', + position: 'right', + }, { type: 'docsVersionDropdown', docsPluginId: 'theolive', diff --git a/package.json b/package.json index 66fbdf1dc949..fc580234d62d 100644 --- a/package.json +++ b/package.json @@ -13,8 +13,8 @@ "serve": "node serve.js", "write-translations": "docusaurus write-translations", "write-heading-ids": "docusaurus write-heading-ids", - "gen-api-docs": "docusaurus gen-api-docs all --plugin-id ads-api && docusaurus gen-api-docs all --plugin-id ad-engine-api && docusaurus gen-api-docs all --plugin-id millicast-api && docusaurus gen-api-docs all --plugin-id theolive-api --all-versions", - "clean-api-docs": "docusaurus clean-api-docs all --plugin-id ads-api && docusaurus clean-api-docs all --plugin-id ad-engine-api && docusaurus clean-api-docs all --plugin-id millicast-api && docusaurus clean-api-docs all --plugin-id theolive-api --all-versions", + "gen-api-docs": "docusaurus gen-api-docs all --plugin-id ads-api --all-versions && docusaurus gen-api-docs all --plugin-id ad-engine-api && docusaurus gen-api-docs all --plugin-id millicast-api && docusaurus gen-api-docs all --plugin-id theolive-api --all-versions", + "clean-api-docs": "docusaurus clean-api-docs all --plugin-id ads-api --all-versions && docusaurus clean-api-docs all --plugin-id ad-engine-api && docusaurus clean-api-docs all --plugin-id millicast-api && docusaurus clean-api-docs all --plugin-id theolive-api --all-versions", "typecheck": "tsc", "check-format": "prettier --check .", "format": "prettier --write .",