Sessions are pivotal for delivering personalized content to user's devices. Every new request for the Service URL generated bybroadpeak.io generates a unique session. Sessions ensure continuity in the personalisation decisions and manifest manipulation strategy. broadpeak.io keeps contextual information for that session for as long as it is needed, as long as subsequent requests correctly make reference to the session.

Session ID

A session is identified by a unique identifier, which is generated by the platform on the first request coming from the player. Thereafter, it is provided as a query parameter to stream URLs, with the name bpkio_sessionid.

A manifest request without bpkio_sessionid query parameter will be interpreted as a new session with no previous context, and will be assigned a bpkio_sessionid value.

Session Creation

In order to be able to assign the bpkio_sessionid query parameter to the stream, the initial request for a Service URL from the player will be answered with an HTTP 307 redirection. The Location header in that response will contain the new URL that the player must request next, which now contains the bpkio_sessionid query parameter.

📘

Redirection

Note that in the majority of cases, the player will automatically follow the redirection. It is a building block of the internet, and will likely require no specific configuration of the player to handle it.

Most CDNs will also support it transparently, and return the 307 response to the player. You may want to ensure that it is the case for your CDN. More information can be found in Using broadpeak.io with a CDN

The figure below shows a sequence diagram of session creation between the client (player), the CDN and broadpeak.io. To simplify, we are using building blocks, but a CDN might be built with several nodes.

For example, if my Service's URL is https://stream.broadpeak.io/9bf31c7ff062936aa98ca3e56900abcd/myStream/myOutput/index.mpd?zipcode=25267, the initial response from broadpeak.iowill instruct the player to request https://stream.broadpeak.io/myStream/myOutput/index.mpd?zipcode=25267&bpkio_serviceid=9bf31c7ff062936aa98ca3e56900abcd&bpkio_sessionid=10a0e55a246-f8c09588-c798-4890-a4b7-54155d02b742 to get the first manifest

> curl -i -L https://stream.broadpeak.io/9bf31c7ff062936aa98ca3e56900abcd/myStream/myOutput/index.mpd?zipcode=25267
HTTP/2 307
location: /myStream/myOutput/index.mpd?zipcode=25267&bpkio_serviceid=53bc6412b1163ee1881ccbc1901e8fae&bpkio_sessionid=10a0e55a246-f8c09588-c798-4890-a4b7-54155d02b742

📘

Service hash

Note how the Service hash that was in the initial URL was also extracted and added as a query parameter bpkio_serviceid in the redirection URL. Both the bpkio_serviceid and bpkio_sessionid are critical in maintaining the session.

Maintaining the Session

It is essential from this point on that your player make use of the redirection URL containing those parameters.

For Live Services

With live services (in which the player needs to request the manifest regularly for updates), the player is expected to continue requesting this "resolved" session URL. This is critical to maintain the session, since the redirection URL contains that bpkio_sessionid parameter.

❗️

If your player (or monitoring tool) keeps requesting the initial Service URL, a new session will be created for each request. This is unlikely to provide the desired outcome, and in some cases (such as with HLS) will likely cause playback failure.

HLS

As described in The HLS format, HLS streams rely on individual media playlists to provide multiple renditions between which the player can choose or switch to mid-stream. HLS multi-variant manifests that are manipulated by broadpeak.iowill automatically contain the bpkio_sessionid (and bpkio_serviceid) query parameters, allowing the player to make its requests without needing to have to manage that aspect explicitely.

Session Expiration

For Live Services

The session is maintained by broadpeak.ioas long as requests with that bpkio_sessionid are received. If those requests stop, the session will expire 2 minutes after the last request.

📘

Pausing playback

If the user pauses a live stream, most players continue requesting the manifest in the background, in order to allow the user to continue streaming or move to the live edge. Those requests will keep the session active therefore.

For VOD Services

The session is maintained by broadpeak.iofor 1.5 times the duration of the VOD content. Even though a player gets the full manifest at the start of the session, this is necessary to enable HLS players to switch between renditions mid-stream whilst giving a reasonable time for users to pause and resume playback.

Expired sessions

If the client attempts to acquire a manifest for an expired session, the following will happen:

• For Live services, 2 possible use cases:
  • If done within a window of time after expiration, a new session is created with the same session ID. As it's a new session, behaviour will be as per normal, including insertion of a pre-roll if the Service is configured to do so
  • Otherwise, an HTTP 400 error
• For VOD services, an HTTP 404 or 400 error

Advanced topics

Location header format

By default, broadpeak.io sets the value of the Location header in the response to be root-relative. This will work in a majority of situations, including when going through a CDN.

However there are situations in which the path of the streaming URL through the CDN starts with elements that are not linked to the source URL, and therefore not handled by <. In such cases, you can configure the Service (through the WebApp or APIs) to use relative URLs instead.

broadpeak.io will then return a relative URL in the Location header that ensures that on resolution, the player is able to go through the CDN with the same start of path

Working with SmartLib

When using the SmartLib SDK, for example to implement client-side ad tracking, the creation of the session is managed by the SmartLib. SmartLib will append a response=200 query parameter to the initial request for the manifest. Instead of an HTTP 307,broadpeak.io will respond with an empty HTTP 200, containing the same location header mentioned above. This enables SmartLib to programmatically capture that URL.

📘

On browser-based players, this is only possible if the cross-origin resource sharing (CORS) policies allow it. Your CDN may need to be configured to ensure that the Access-Control-Expose-Header header contains "location" in its value. See Using broadpeak.io with a CDN for details.

Working with Broadpeak on-premise CDN

In the event you use Broadpeak on-premise CDN, it is possible to rely on the CDN itself to generate the session ID, and pass it to broadpeak.io in the request via specific headers. In this scenario, broadpeak.io will not generate the bpkio_sessionid value and will respond to the initial request with an HTTP 200 and the contextualized manifest directly in the body. This scenario is not enabled by default.

Contact us directly or your Broadpeak representative for more information.