Signaling service

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 THEO Technologies, 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

The service is deployed and operated by THEO Technologies within the customer’s infrastructure. This setup ensures smooth integration into the existing video workflow with minimal disruption. During onboarding, THEO Technologies provides the infrastructure requirements. Once set up, THEO Technologies bootstraps the service, after which the customer can manage their signaling service deployments and monitor the service through the REST API.

Integration

In collaboration with the customer and THEO'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.

For each Origin stream that needs to be enabled for THEOads, a monetized-stream can be created through the locally deployed REST API from your CMS or other existing orchestration systems. The monetized-stream represents a high-availability Signaling Service deployed on the provided infrastructure. Each active monetized-stream offers an HTTPS (or HTTP) endpoint for the CDN to fetch the augmented manifest. The endpoint path is standardized, so no CDN reconfiguration is required when stopping and recreating the monetized-stream.

Please refer to the API reference for detailed information on the REST API.

Scheduling ad breaks

To accurately schedule 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. Breaks can be scheduled using either the provided REST API or in the manifest itself.

Manifest

When using manifest triggers, 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
• To use the tune-in feature, #EXT-X-CUE-OUT-CONT tags must be present between #EXT-X-CUE-OUT and #EXT-X-CUE-IN markers.

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 and the example below.

curl --location 'http://theoads-host/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

Configuration

When setting up the Signaling Service, a configuration needs to be passed along. It must contain the following parameters:

• origin: The origin URI to use for manifest requests.
• segmentOrigin: The segment origin URI to use for segment requests.
• layout: The default experience layout, see ad experience layout for possible values.
• assetKey: Google DAI Asset-Key representing the stream, see Google DAI.
• networkCode: Google DAI Network-Code, see Google DAI.

Origins

When playing a THEOads source, it is expected to pass a source that looks like this:

src: 'PATH-TO-SIGNALING-SERVER/hls/MANIFEST-URI'

For the MANIFEST-URI part of the src, it can be an absolute URL or a relative one where the origin is not part of it. The relative URL should be used if the origin is a non-public hostname or ip address. Below shows an example for both cases:

// Absolute URL
src: 'PATH-TO-SIGNALING-SERVER/hls/https://domain.com/manifest.m3u8'

// Relative URL
src: 'PATH-TO-SIGNALING-SERVER/hls/manifest.m3u8'

In the case of the absolute URL the Signaling Service uses the whole URL as is. For the relative URL on the other hand, it does not have a valid URL to fetch the manifest yet. Here we will use the origin parameter as provided in the config. By combining both we do get a valid URL and can fetch the manifest.

However, segment URLs in the media playlists should be absolute URLs. Segment requests don't need to pass through the Signaling Service but should be fetched directly from the CDN to the origin. The segmentOrigin parameter should contain this publicly available endpoint to fetch the segments directly.

For more information on this topic we refer to our workflow integration.

Monetized stream

A monetized stream resource represents a high-availability Signaling Service deployed to enable THEOads for an Origin stream. Created via the locally deployed REST API, it provides 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:

• name: Self defined descriptive name for the monetized stream.
• labels: Array of self defined labels (string).
• layout: Default experience layout, see ad experience layout.
• origin: Your media Origin host.
• segmentOrigin: Your publicly available segments origin.
• assetKey: Google DAI Asset-Key representing the stream, see Google DAI.
• streamId: Unique identifier for the monetized stream within the environment.
• description: Additional descriptive information for the monetized stream.
• networkCode: Google DAI Network-Code, see Google DAI.
• assetURI: Optional Asset URI which is to be used during ad breaks. If not set it will request an ad through Google Pod Serving.
• backdropURI: Optional URI containing the back-drop to be used during the double box or L-shape ad.

{
  "name": "THEOads Demo",
  "labels": [],
  "layout": "DOUBLE",
  "origin": "https://domain.com",
  "segmentOrigin": "https://segment-domain.com",
  "assetKey": "google-sgai-demo",
  "streamId": "theoads-demo",
  "description": "SGAI THEOads Demo",
  "networkCode": "89053",
  "assetURI": "https://asset.m3u8",
  "backdropURI": "https://backdrop.svg"
}

Creating a new monetized stream

The following API endpoint creates a new monetized stream (signaling-service) in the environment, mandatory parameters are:

• name: Self defined descriptive name for the monetized stream.
• layout: Default experience layout, see ad experience layout.
• origin: Your media Origin host.
• segmentOrigin: Your publicly available segments origin.
• assetKey: Google DAI Asset-Key representing the stream, see Google DAI.
• streamId: Unique identifier for the monetized stream within the environment.
• description: Additional descriptive information for the monetized stream.
• networkCode: Google DAI Network-Code, see Google DAI.

curl -L '/api/v1/monetized-streams' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{
  "name": "string",
  "layout": "SINGLE",
  "origin": "string",
  "segmentOrigin": "string",
  "assetKey": "string",
  "streamId": "string",
  "description": "string",
  "networkCode": "string"
}'

Updating an existing monetized stream

The following API endpoint updates an existing monetized stream based on it's streamId, mandatory parameters are:

• name: Self defined descriptive name for the monetized stream.
• labels: Array of self defined labels (string).
• layout: Default experience layout, see ad experience layout.
• origin: Your media Origin host.
• segmentOrigin: Your publicly available segments origin.
• assetKey: Google DAI Asset-Key representing the stream, see Google DAI.
• streamId: Unique identifier for the monetized stream within the environment.
• description: Additional descriptive information for the monetized stream.
• networkCode: Google DAI Network-Code, see Google DAI.

curl -L -X PATCH '/api/v1/monetized-streams/:streamId' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{
  "name": "string",
  "labels": [
    "string"
  ],
  "origin": "string",
  "segmentOrigin": "string",
  "assetKey": "string",
  "streamId": "string",
  "description": "string",
  "networkCode": "string"
}'

Deleting an existing monetized stream

The following API endpoint deletes an existing monetized stream based on it's streamId.

curl -L -X DELETE '/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.

curl -X 'GET' \
  '/api/v1/monetized-streams' \
  -H 'accept: application/json'

The response is an array of the existing monetized stream resources.

[
  {
    "id": "theoads-demo",
    "payload": {
      "name": "THEOads Demo",
      "labels": [],
      "layout": "DOUBLE",
      "origin": "https://domain.com",
      "segmentOrigin": "https://segment-domain.com",
      "assetKey": "google-sgai-demo",
      "streamId": "theoads-demo",
      "description": "SGAI THEOads Demo",
      "networkCode": "89053"
    },
    "state": "created",
    "type": "monetized-stream"
  }
]

Retrieving individual monetized stream

The following API endpoint returns an existing monetized stream based on its identifier (streamId).

curl -L '/api/v1/monetized-streams/:streamId' \
-H 'Accept: application/json'

The response is the monetized stream resource.

{
  "id": "theoads-demo",
  "payload": {
    "name": "THEOads Demo",
    "labels": [],
    "layout": "DOUBLE",
    "origin": "https://domain.com",
    "segmentOrigin": "https://segment-domain.com",
    "assetKey": "google-sgai-demo",
    "streamId": "theoads-demo",
    "description": "SGAI THEOads Demo",
    "networkCode": "89053"
  },
  "state": "created",
  "type": "monetized-stream"
}

More information

• API reference
• What is THEOads?
• The Advantages of Server-Guided Ad Insertion
• Flexible, Usage-Based Pricing
• Is Server-Guided Ad-Insertion (SGAI) revolutionizing streaming monetization? (blog)