Live - DASH
The process to request a Serverside.ai DASH-Live stream with client-side tracking enabled can be broken down into the following steps (the technical details for every step follow below):
The App performs a request to the Serverside.ai endpoint for a channel and retrieves the URL to the DASH manifest (mediaURL) and VAST data (vastURL)
The mediaURL can now be used to initialize the player and start playback. (Note: in the example below we use a Shaka-Player in an HTML5 environment)
Parallel to step 2 the app can perform a request to the vastURL to load the current VAST information for the live-channel
While the player is constantly loading sub-manifests and media-chunks for playback the app has initialized the VAST handling and is waiting for the player to reach an ad
As soon as an ad signaled in the VAST-Tag is starting to playback, compared to the timeline information from the player or timeline-region-enter events the app will send requests to all tracking-URLs (beacons) defined in the VAST-response for the start event. The same logic applies to the events: pause, resume, finish, firstQuartile, midpoint, thirdQuartile, complete
1. Manifest API Request
The first request to obtain a dash-manifest and VAST tracking information will create a DASH-Live session for the requesting client. The URL to the ad-insertion enabled channel is called outputUrl and can be viewed at Serverside.ai or via https://admin.serverside.ai/api/v2/channels/:channelId API endpoint.
GET Request:
https://live.serverside.ai/dash/view/:channelId?api-key=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx Response body:
{
"mediaURL": "https://live.serverside.ai/dash/:channelId/sessionId.mpd",
"vastURL": "https://live.serverside.ai/dash/:channelId/sessionId/vast"
}Load VAST
The full URL schema is:
https://live.serverside.ai/dash/:channelId/:sessionId/vast/:adId.xml2. Player call with mediaURL
You will find below an example of how to playback a Serverside.ai DASH-Live stream in a browser.
HTML
<!DOCTYPE html>
<html>
<head>
<title>Test Player</title>
<script src="https://cdnjs.cloudflare.com/ajax/libs/shaka-player/2.5.6/shaka-player.compiled.js"></script>
</head>
<body>
<h1>Serverside.ai Test</h1>
<video id="video" controls autoplay></video>
</body>
</html>JavaScript
(async () => {
const response = await fetch('https://live.serverside.ai/dash/view/:channelId?api-key=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx')
const {mediaURL, vastURL} = await response.json()
const video = document.getElementById("video");
const player = new shaka.Player(video);
player.load(mediaURL);
})()3. Load VAST data
To gather the VAST-related data call the vastURL gathered in step 1.
GET Request:
https://live.serverside.ai/dash/:channelId/:sessionId/vast/:adId.xmlResponse Body:
<Period>
...
<EventStream schemeIdUri="urn:ssai:vast:event:2020" timescale="1000">
<Event id="0" presentationTime="0" duration="5000">vast:a2363da8-2331-4483-995d-5286220005d8</Event>
<Event id="1" presentationTime="500">beacon:start</Event>
<Event id="2" presentationTime="1250">beacon:firstQuartile</Event>
<Event id="3" presentationTime="2500">beacon:midpoint</Event>
<Event id="4" presentationTime="3750">beacon:thirdQuartile</Event>
<Event id="5" presentationTime="4500">beacon:complete</Event>
</EventStream>
...
</Period> The first event id=vast:adId signals an id under which the whole original VAST response, including all tracking event information for the respective clip, can be obtained from the SSAI-API under the provided vastURL contained in the initial session created response. The following events, id=beacon:start etc. trigger the VAST quartile reporting at the respective points in the clips presentation timeline.
4. Detect the start of an ad in the stream
At the time an ad is detected in the DASH-Stream fetch the vast information for this ad from the vastURL: ${vastBaseUrl}/${adId}.xml.
Javascript - Shaka-Player:
// If a new timeline-region (or segment) is added load the related VAST data
player.addEventListener("timelineregionadded", evt => {
// evt.detail.id is e.g. vast:f295a0cc-9d2b-4014-9858-87fb28fc6ec1
const [type, id] = evt.detail.id.split(":");
if (type === "vast") {
const response = await fetch(`${this.vastBaseUrl}/${id}.xml`)
const vastXML = await response.text()
const vast = document.createElement("div");
// remove xml document declaration as required by xhtml
vast.innerHTML = vastXml.substr(vastXml.indexOf("?>") + 2);
// work with the vast response
// ...
}
})5. Keep track of the ad playback and send beacons
As soon as the VAST information for the upcoming ad is loaded the client needs to track if the player reaches one of the predefined timeline positions and fire the events accordingly
Javascript - Shaka-Player:
// start of dash event
player.addEventListener("timelineregionenter", evt => {
const [type, arg] = evt.detail.id.split(":")
// 'id' and 'vast' from the request at 4 above
// fire the impression or beacon
if(type === 'vast) fire('Impression', vast)
if(type === 'beacon) fire(`Tracking[event='${arg}']`, vast)
});
function fire(selector, vast) {
$(vast) // this requires jQuery
.find(selector)
.each((n, elem) => {
const url = elem.firstChild.textContent.replace(/\[/g, "").replace(/\]/g, "").replace(/CDATA/g, "")
fetch(url, { mode: "no-cors" }).catch(err =>
// Error handling
);
});
}
See the below example implementation for a full example of the DASH Vast tracking.
Example Implementation
The example implementation handles Impression- and progress (beacon) events based on the DASH event timeline as well as the following tracking events based on HTML5 video element events:
mute/unmute
pause
resume
expand/collapse
Last updated