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 general principles should remain the same.

📘

Summary Table

The typical rules are as follows, in the recommended order:

Rule for	URL pattern	Target origin	Origin policy	Cache policy	See sections
Manifests	*.mpd, *.m3u8	stream.broadpeak.io	Forward query params & headers Expose Location header	No caching	1 Q.a, Q.b, Q.c, H, R C.1
Empty subtitles	/empty.webvtt	stream.broadpeak.io	Forward query params	Cached	3 Q.a C.3
Replacement media segments	defined by the replacement origin	the replacement origin	defined by the replacement origin	Cached	2 Q.c C.2
Original media segments	-	your content origin	defined by your content origin	Cached	4 Q.c C.2

Routing rules

You will need to configure your CDN to send various requests (coming from the client player) to the appropriate Origin. Typically you will need to configure the following:

• Routing rules for manifest requests
• Routing rule for media segment requests

Note that the order in which these rules are evaluated by the CDN for any incoming request is important.

1. Routing rules for manifest requests

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

MPEG-DASH

• Path to match: *.mpd
• Origin FQDN: stream.broadpeak.io
• Protocol: HTTPS
• Caching: disabled (see cache policy A below)
• Origin policies: query parameters, headers, redirections and locations (see origin policies Q.a, Q.b, Q.c, H and R below)

HLS

• Path to match: *.m3u8
• Origin FQDN: stream.broadpeak.io
• Protocol: HTTPS
• Caching: disabled (see cache policy A below)
• Origin policies: query parameters, headers, redirections and locations (see origin policies Q.a, Q.b, Q.c, H and R below)

The rules above assume that your manifest URLs end with the typical filename extension for DASH and HLS manifests. You may need to adjust these if your URLs are different, or have paths that don't end in this way.

You may also want to be more specific in the (partial) path, if you want to avoid using (or cannot use) wildcards.

⚠️

Service hash in the service path

The URL endpoint generated by broadpeak.io always contains a hash string (the "service hash") at the start of the path.
E.g.: https://stream.broadpeak.io/d3d9446802a/myStream/myOutput/index.mpd.

On the first request, broadpeak.io returns a redirection (as an HTTP 307 or 200) in which the location header sends the player to a new path in which the service hash is moved to into a bpkio_serviceid query parameter.
E.g.: HTTP 307 with Location: /myStream/myOutput/index.mpd?**bpkio_serviceid=d3d9446802a**&bpkio_sessionid=xxxxx

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.

For example, in the example above the path to match would be "/myStream/myOutput/index.mpd".

2. Routing rules for replacement media segment requests

Media segment requests need to be directed to the component that originates the content. In the case of replacement content in a Content Replacement or Virtual Channel solution, if all content comes from the same Origin as the base live stream used in the service, the default rule will be sufficient (see rule 4 below)

Otherwise, you will need to create specific routing rules for each replacement content Origin, using an appropriate (partial) path pattern that uniquely identifies each one.

• Path to match: according to each replacement content's Origin
• Origin FQDN: the replacement content's Origin FQDN
• Protocol: HTTPS and/or HTTP, according to the replacement content's Origin configuration
• Caching: enabled (or in accordance with the replacement content's Origin rules, see cache policy C.4 below)
• Origin policies: as defined by the replacement content's Origin

3. Routing rules for dummy subtitle segments

If your HLS source content uses WebVTT subtitles, but the replacement content does not contain corresponding subtitles, broadpeak.io will insert references to a dummy WebVTT segment in the subtitle playlists for the duration of the replacement content, with path /empty.webvtt.

Requests for this segment must be directed to broadpeak.io's streaming origin.

• Path(s) to match: /empty.webvtt
• Origin FQDN: stream.broadpeak.io
• Protocol: HTTPS
• Caching: enabled (see cache policy C.3 below)
• Origin policies: broadpeak query parameters, headers (see origin policy Q.a below)

4. Routing rules for original media segment requests

This rule will be considered as the default rule: if the client player request has been matched against any of the previous rules, this one is applied.

• Path(s) to match: *
• Origin FQDN: your own Origin FQDN.
• Protocol: HTTPS and/or HTTP, according to your Origin configuration.
• Caching: enabled (or in accordance with your own Origin's rules, see cache policy C.2 below)
• Origin policies: as defined by your Origin

You may want to be more specific in terms of path pattern to match. This may for example be done by specifying the segment extensions, eg. *.ts, *.fmp4, *.vtt, etc. Or you can be more specific by specifying a more specific (full or partial) path to the expected segment paths. If so, do not forget to add routing policies for all media types: video, audio, subtitles, images, etc.

📘

Multiple origins

If you use several origins for replacement content, you need to be able to distinguish between based on the request's URL path, and create different routing rules accordingly.

Origin policies

Q. Query parameters

For broadpeak.io to operate successfully, in all routing rules that send the client requests to stream.broadpeak.io, it is essential that the query parameters are forwarded, and carried all the way through the session.

Q.a. General system query parameters

⚠️ These query parameters must be forwarded on all requests made to stream.broadpeak.io (rule 1 above)

• bpkio_serviceid
• bpkio_sessionid

📘

See Session management section for more information on the role of these query parameters

📘

Note that those query parameters will also appear on all segment requests, including segments sent to your content origin for original segments (See rule 5 above). If your origin is not able to receive (and ignore) those parameters, you may want to configure your CDN to remove them before sending the request to the origin.

Q.b. Query parameters specific to manifest requests

In addition to the previous rule, specific query parameters may be used on manifest requests, which need to be forwarded in the corresponding rules (see rule 1. above)

For all services

• bpkio_format

To identify the Audience

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

The following additional query parameters will need to be forwarded by the CDN:

• zip when working with zip codes
• category when working with category

For HLS services

• mm_sp
• mm_index

For sessions orchestrated by SmartLib

If you use the Broadpeak SmartLib SDK on your client (such as for Client-Side Ad Tracking), additional query parameters will be sent and must be forwarded

• response
• bk-ml
• bk-teardown

👍

Recommendation

For simplicity, we would recommend that all incoming query parameters on manifest requests are forwarded to broadpeak.io. Any unrecognised parameter will simply be ignored.

Q.c. Query parameters to forward to the Origin

If your content origin (and / or replacement origin) expects certain parameters on manifest or segment requests, those parameters will also need to appear on the request made by the client player, and therefore must also be forwarded by the CDN on the request to broadpeak.io.

R. Redirections

As indicated in rule 1. above, broadpeak.io responds to the first manifest request in a playback session with an HTTP 307 (or HTTP 200 if using the SmartLib SDK) redirection:

The response by broadpeak.io contains a Location header that the player needs to request next. The response must be forwarded to the client by the CDN.

Cache policies

C.1. Cache policy for manifest requests

Because content is contextualized down to the individual streaming session, manifests delivered by broadpeak.io to different users will always be different. It is therefore mandatory to disable caching on all manifest requests for your application to properly operate.

C.2. Cache policy for content segments

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

C.3. Cache policy for segments originated by broadpeak.io

In case dummy subtitles are added by broadpeak.io (rule 3 above), you may want to enable caching. Limiting the number of requests to broadpeak.io is important to reduce the egress costs we charge.