Using broadpeak.io with a CDN

📘

CDN configuration highlights

• Manifest requests need to be routed to broadpeak.io.
  Caching must be disabled for manifest requests. (all .mpd and .m3u8)
• Media segment requests of the Ad creative transcoded by broadpeak.io must be routed to broadpeak.io. An identifiable pattern is /bpkio-jitt/*. Caching should be enabled.
• Other media segment requests shall be routed to their respective origin. Caching should be enabled.
• There are mandatory system query parameters as well as application specific query parameters which your CDN must forward. CDN should be configured to forward all specific targeting query parameters sent by the client to broadpeak.io.

When building your application(s), it is highly recommended to use broadpeak.io with a Content Delivery Network for several reasons:

• broadpeak.io does not deliver the media segments of your original or replacement content, it only delivers manifests and ad creative media segments generated by the platform. You need a component which routes manifest requests to broadpeak.io while routing media segment requests to the origin. CDNs have this functionality.
• Using a CDN will improve the efficiency of both media segments and manifests delivery. Depending on your type of application, bringing content closer to the end-users will provide a better quality of experience.

Configuring your CDN for Content Replacement and Virtual Channel applications

The following sections show how to use broadpeak.io with your own content distribution network (CDN) in the context of Content Replacement, or Virtual Channel applications. For clarity, we use generic terms that may not always apply to the CDN you are operating, but the principles should remain the same.

1. Defining routing rules for manifest requests

Manifest requests need to be directed to the broadpeak.io platform. To do so, you need to create new routing rules (also called behaviors), one for each streaming format.

MPEG-DASH

• Path(s) to match: *.MPD/*.mpd
  You can be more specific here if you do not want to have a wildcard with ``.
• Origin FQDN: stream.broadpeak.io
• Protocol: HTTPS

HLS

• Path(s) to match: *.M3U8/*.m3u8
  _You can be more specific here if you do not want to have a wildcard with *.
• Origin FQDN: stream.broadpeak.io
• Protocol: HTTPS

🚧

Important!

The URL endpoint generated by broadpeak.io always contains a hashed value within the path.
E.g.: https://stream.broadpeak.io/d3d9446802a/myStream/myOutput/index.mpd.

On the first request, broadpeak.io returns a 307 with a location value where the hashed value is removed from the path, and added into the serviceid query param.
E.g.: HTTP 307 location: /myStream/myOutput/index.mpd?serviceid=d3d9446802a&sessionid=x

When defining your CDN routing rules, it is best practice not to add the hashed value to be matched against, or you would potentially have to create two rules, one for the first request with the hashed value, and a second for the redirection request without the hashed value.
E.g.: the path to match here would be /myStream/myOutput/index.mpd .

2. Defining routing policies for media segment requests

Media Segment requests need to be directed to the component which originates the content, in this case the origin within your ecosystem. To do so, you need to create new routing rules (also called behaviors) per media container extension.

• Path(s) to match:
  Depending on the flexibility of your CDN, you can target all requests which come with a specific media segment extension, such as .ts/.fmp4/.dash/.m4s/.aac etc.
  You can be more specific by specifying the full path of the original and replacement content, for example:
  /myOriginalContent/myOutput/*.ts / /myOriginalContent/myOutput/*.m4s / .....
  /myReplacementContent/myOutput/*.ts / /myReplacementContent/myOutput/*.m4s / .....
  In both cases, do not forget to add routing policies for all media types: Video, Audio, Subtitles, Images (I-Frames, etc.).
• Origin FQDN: It needs to be your own Origin FQDN.
• Protocol: You can follow the request scheme or specify HTTPS and/or HTTP.

📘

Note

If you use several origins for original and replacement content, you need to create different routing policies which route original media segment requests to one origin, and replacement media segment requests to the second origin.

📘

Note about demo streams

If you are using broadpeak.io demo streams, use HTTPS protocol and stream.broadpeak.io as origin FQDN.

3. Defining caching policies for manifest requests

Content Replacement Applications

Because content is contextualized, manifests delivered by broadpeak.io for different Audiences do not contain the same reference. It is mandatory to disable caching on manifest requests for your application to properly operate.

🚧

Disable caching on manifest requests

With broadpeak.io, media content is personalized, so are the generated manifests. Configure your CDN so that it does not cache m3u8s and mpds.

4. Defining caching policies for media segments

Media segments are not originated by broadpeak.io, but by your own origins. Define your own caching policies based on your preferences for all media segment requests.

5. Forwarding query parameters.

🚧

Allow your CDN to forward query parameters from the client requests to broadpeak.io

• Compulsory system query parameters are mm_sp, serviceid and sessionid. The CDN must forward them.
• When working with a conditional Content Replacement application, zip or category must be forwarded.

General system query parameters

For broadpeak.io to operate successfully, some query parameters must be forwarded by the CDN from the client request to broadpeak.io, and carried all the way through the session. See Context Management section for more information.
The following query parameters and their value must be allowed to be forwarded from the client request to broadpeak.io:

• mm_sp
• sessionid=${value}
• serviceid=${value}

📘

Note

If you need to forward specific query parameters to the origin for some reason, please contact us at [email protected] or via the web app chat.

Audience query parameters

If your application does require contextualization based on Audience, your client (player) have to pass some information for broadpeak.io to identify which Audience is requesting the content.

When working with zip code, the CDN must allow forwarding the query parameter zip from the client request to broadpeak.io.
When working with category, the CDN must allow forwarding the query parameter category from the client request to broadpeak.io.

6. Forwarding Request Headers

We recommend to forward the following request header:

• user-agent
• X-Forwarded-For: should contain the client Ip.

Configuring your CDN for Dynamic Ad Insertion application

The following sections show how to use broadpeak.io with your own content distribution network (CDN) in the context of Dynamic Ad Insertion. For clarity, we use generic terms that may not always apply to the CDN you are operating, but the principles should remain the same.

The steps below also reflects the priority order that the routing policies should take when being implemented in the CDN:

1. Policy for manifest requests
2. Policy for ad media segment requests
3. Policy for gap filler media segment request
4. Policy for other media segment requests

1. Defining routing rules for manifest requests

Manifest requests need to be directed to the broadpeak.io platform. To do so, you need to create new routing rules (also called behaviors), one for each streaming format.

MPEG-DASH

• Path(s) to match: *.MPD/*.mpd
  _You can be more specific here if you do not want to have a wildcard with *.
• Origin FQDN: stream.broadpeak.io
• Protocol: HTTPS

HLS

• Path(s) to match: *.M3U8/*.m3u8
  _You can be more specific here if you do not want to have a wildcard with *.
• Origin FQDN: stream.broadpeak.io
• Protocol: HTTPS

🚧

Important!

The URL endpoint generated by broadpeak.io always contains a hashed value within the path.
E.g.: https://stream.broadpeak.io/d3d9446802a/myStream/myOutput/index.mpd.

On the first request, broadpeak.io returns a 307 with a location value where the hashed value is removed from the path, and added into the serviceid query parameter.
E.g.: HTTP 307 location: /myStream/myOutput/index.mpd?serviceid=d3d9446802a&sessionid=x

When defining your CDN routing rules, it is best practice not to add the hashed value to be matched against, or you would potentially have to create two rules, one for the first request with the hashed value, and a second for the redirection request without the hashed value.
E.g.: the path to match here would be /myStream/myOutput/index.mpd.

2. Defining routing policies for Ad creative Media segment request

Creatives prepared and originated by broadpeak.io

This use-case is often associated with the scenario of sales through programmatic where creatives are retrieved in real time, and cannot be prepared in advance. However, it also remains a valid use-case in Direct Sales, whenever creative are not prepared to be delivered over HLS and DASH by another system than broadpeak.io.

This step is relevant only in the context where a transcoding service has been associated to the DAI service

broadpeak.io generates contextualized manifest which refer to transcoded and packaged creatives. All creatives generated from the platform can be retrieved using the following path:
https://stream.broadpeak.io/bpkio-jitt/*

It is necessary that you create a new routing rule which routes all requests with the path /bpkio-jitt/* towards broadpeak.io's streaming FQDN.

Creatives can be cached by the CDN.

• Path(s) to match:: /bpkio-jitt/*
• Origin FQDN: stream.broadpeak.io
• Protocol: HTTPS/HTTP
• Caching Policies: activated

Creatives prepared and originated from an external system

This use-case is often associated with the scenario of direct sales where creatives can be retrieved a long time before air time, and therefore can be prepared in advance.

This step is relevant only in the context where a transcoding service has NOT been associated with the DAI service.

It is necessary that you create a new routing rule which routes all ad media segment requests towards the Ad origin. We recommend to use a common path pattern which ensures that only ad media segment request are being requested to this Origin:

• Path(s) to match: any unique and identifiable pattern
• Origin FQDN: your Ad origin FQDN
• Protocol: HTTPS/HTTP

Server side ad tracking (SSAT) specificities

In the context of Ad insertion where the Ads are conditioned and hosted outside of broadpeak.io, it is still possible to perform Server Side Ad Tracking. As broadpeak.io acts as a redirect proxy on all Ad media segments, the CDN must be configured so Ad media requests go to broadpeak.io and 307 responses from broadpeak.io are not cached.

Every Ad media segment URL contains the string "/bpk-sst/" in their path. Therefore the CDN should be configured to route the requests to broadpeak.io when this pattern is identified. These requests are answered with a 307 HTTP Redirection which must be returned to the Client by the CDN.

Path(s) to match: /bpk-sst/*

• Origin FQDN: stream.broadpeak.io
• Protocol: HTTPS/HTTP
• Caching Policies:
  • deactivated
  • HTTP responses from broadpeak.io must carried forward to the client.

For further detail on SSAT, please visit the Server Side Ad Tracking section

3. Defining routing policies for gap filler media segment requests

In Live DAI, it is possible to use gap-filler to fill the gap between the total duration of all ads combined and the ad break duration, if gap there is. You can either rely on your own gap-filler or use one generated by the platform.

Gap-filler generated by broadpeak.io

This feature is not yet available on the platform. The documentation will be provided once available.

Self generated gap-filler

As for other type of media, a dedicated routing rule shall also be created on the CDN whenever a gap-filler is being used. If the gap-filler origin is the same as the original content origin, then you can implement the step 4, and you pretty much set.

If the gap-filler origin is a different origin, then you must create a new policy:

• Path(s) to match: any unique and identifiable pattern for the gap-filler
• Origin FQDN: your gap-filler origin FQDN
• Protocol: HTTPS/HTTP
• Caching Policies: activated

4. Defining routing policies for media segment requests

Media Segment requests need to be directed to the component which originates the content, in this case the origin within your ecosystem. To do so, you need to create new routing rules (also called behaviors) per media container extension.

• Path(s) to match:
  Depending on the flexibility of your CDN, you can target all requests which come with a specific media segment extension, such as .ts/.fmp4/.dash/.m4s/.aac etc.
  You can be more specific by specifying the full path of the original and replacement content, for example:
  /myOriginalContent/myOutput/*.ts / /myOriginalContent/myOutput/*.m4s / .....
  /myReplacementContent/myOutput/*.ts / /myReplacementContent/myOutput/*.m4s / .....
  In both cases, do not forget to add routing policies for all media types: Video, Audio, Subtitles, Images (I-Frames, etc.).
• Origin FQDN: It needs to be your own Origin FQDN.
• Protocol: You can follow the request scheme or specify HTTPS and/or HTTP.

📘

Note

If you use several origins for original and replacement content, you need to create different routing policies which route original media segment requests to one origin, and replacement media segment requests to the second origin.

5. Defining caching policies for manifest requests

Content Replacement Applications

Because content is contextualized, manifests delivered by broadpeak.io for different Audiences do not contain the same reference. It is mandatory to disable caching on manifest requests for your application to properly operate.

🚧

Disable caching on manifest requests

With broadpeak.io, media content is personalized, so are the generated manifests. Configure your CDN so that it does not cache m3u8s and mpds.

6. Defining caching policies for Ad media segments

Ad Media segments are either originated by broadpeak.io or by your own Ad origins. Caching should be enabled to limit the number of requests to broadpeak.io. It is also recommended to set an expiry time which suits the expected lifetime of Ads.

7. Defining caching policies for media segments

Media segments are not originated by broadpeak.io, but by your own origins. Define your own caching policies based on your preferences for all media segment requests.

8. Forwarding request's query parameters.

🚧

Allow your CDN to forward query parameters from the client requests to broadpeak.io

• Compulsory system query parameters are mm_sp, serviceid and sessionid. The CDN must forward them.
• When working with a conditional Content Replacement application, zip or category must be forwarded.

General system query parameters

For broadpeak.io to operate successfully, some query parameters must be forwarded by the CDN from the client request to broadpeak.io, and carried all the way through the session. See Context Management section for more information.
The following query parameters and their value must be allowed to be forwarded from the client request to broadpeak.io:

• mm_sp
• sessionid=${value}
• serviceid=${value}

📘

Note

If you need to forward specific query parameters to the origin for some reason, please contact us at [email protected] or via the web app chat.

Query parameters for targeting

In most cases when implementing DAI application, it is required to pass some information from the client to the Ad server so targeting can be best achieved. This can be done through the help of query parameters that are being sent together with the streaming request.

Make sure that the CDN allows forwarding query parameters and their value to broadpeak.io in their requests.

Example:
https://myCDN/d3d9446802a/myStream/myOutput/index.mpd?myQuery=value
The CDN should forward the query parameter "myQuery".

9. Forwarding request's Headers

As for query parameters, some targeting information are also passed through HTTP headers. Mandatory headers are the following are user-agent and x-forwarded-for. The x-forwarded-for should contain the client Ip.