Ad insertion with a CDN

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)

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.

Note that it is important that this routing rule is applied before the one that redirects ad media segments to the ad origin.

For further detail on SSAT, please visit the SSAT (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, bpkio_serviceid and bpkio_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 Session 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
• bpkio_sessionid=${value}
• bpkio_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.