VAST tracking: VoD - DASH and HLS
Overview
This document explains how to request and handle DASH and HLS VoD manifests with server-side ad insertion. It covers obtaining the manifest URL, detecting ad playback within the stream, and sending tracking beacons for ad events.
DASH VoD
1. Manifest API request (manifest and VAST).
To request a VoD manifest, follow steps 1–3 described in VAST tracking: Live - DASH.
The URL for the ad-insertion-enabled channel is called the outputUrl. It can be viewed on Serverside.ai or retrieved via the following API endpoint: https://mydomain.com/api/v2/channels/:channelId.
An outputUrl for DASH VoD channels follows the format: https://mydomain.com/ad-aggregation-service/mrss/channel/:channelId
The URL and the request to obtain a manifest differ significantly from those of HLS or DASH VoD.
CURL request
curl -X POST \
https://mydomain.com/ad-aggregation-service/mrss/channel/:channelId \
-H 'Content-Type: application/json' \
-H 'api-key: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx' \
-d '{
"url": "https://vodcms.blob.core.windows.net/mrss/serverside_mrss_dash_preroll_midroll.mrss",
"context": "web",
"ifa": "ifa",
"deliverytypes": [ "dash" ]
}'Response body
{
"dash": {
"url": "https://mydomain.com/ad-stitcher/mpds/4e643b2c-1259-487f-b908-decd42ce4ad2.mpd",
"clips": [
{
"category": "ad",
"titleId": "serverside.ai-asset-id",
"title": "AD 10SEC",
"duration": 10091,
"impressionUrlTemplates": [
"https://ams01-event.spotxchange.com/vast/impression?_x=WzE1ODI5MTU0OTAsIjY2ODA4NTRlNWE1YTExZWE5MmRkMTkxMzQ0ODgwMDA2IiwiMjQ5ODMyIiwiM2M0Y2EuZTI5M2IuMWQzMiIsIjEiLCIzYzRjYS5lMjkzYi4xZDMyIiwiOWUzMjhiMDIxZTYzOGUyZWZhNmIzY2VlMzY2MmFkZDYiLCI2NjgwZTM5NC01YTVhLTExZWEtOTJkZC0xOTEzNDQ4ODAwMDYiLHRydWUsbnVsbCxbIjI0Njk4NiIsIjI0OTgzMiIsIjEiLCIiLCJ1bmtub3duIiw1NyxbInVua25vd24iXSwwLDAsMCwwLDIwMDBdLDAsbnVsbCwiNjY4MzIzODc1YTVhMTFlYTkyZGQxOTEzNDQ4ODAwMDYiXSZzZXRlYz1OMlkwTkRjMllUSmxZekJoWlRRME9USXpPVGRoTldNM09EVmhPREl3T1dZPQ~~",
"https://ams01-search.spotxchange.com/beacon?_a=249832&_p=3c4ca.e293b.1d32&_z=1&_m=eNpdis0KgkAURu8TjffOXzNBmxiDwFEERXQnKCSZBRmV9O4VuvM7cBaHTzJEACBluCUlLYLWBo2SrapVTdTWljcNWRJSGoOIGri0RnBwIVhiREwbRhuE0zje7tsgeAzn4focAojzKPqftTUavvOWNItgFVaihU%2BZpSIpUpkUVRe7%2FOWzfe8nTz47dN41fTmF78Slorocdz8j4Tmn&_l=eNp1Tt9PgzAQ7t%2FSZ0PaAt1Y4hubMRn4IEbhhZT2JmwUGoSgm%2FvfLZvTJcb0%2Bt3dd9%2F9oIgiHzGL1lzpSeEAC9zCocplf4lwiQhSIGqrPmAXLw64qBReYIJvsBEf7dB%2FJxuAKXIIIcymbwaaH91Q1JXM4V2WonmF%2FEo6leXQiR5UrkW3g97UQsK%2FWtOBrgY90bk0%2BrTgeETx03p9Bnvno2n7l3M7Gppd044NooT7VBAomM9hRmZMUQp0EyjgIJgobNvvjBMwjwdzfkVQ%2BxjnZO5d3Ges7%2FepXo7Z82qbJWWV7lVpf%2F1wl22jMBqzcFWlSVbFSXT7BWC%2FaOg%3D&_t=eNotjU2PwiAQhvktnI2BQmvFeFtjPNS9uGnWCxkpVkwtBFhX4%2Frft1gnma%2FnnTdz0KBsj4qiZBkrZznkQKmGedY0dE4Z52VJCCmQOoHpkfUt9Eahw%2Bh64HGQ8e40FjhE8BFPsOvgHs0lIUqmhJcDu5pGW3mFzjTyaHyI8ujhdTKIQYNXJxmcVlg8sIMkRe1D2hp9NUqnSd9iasHZeJMjluDc%2Bz19TvDFNrrDgkywHbzkOQRCdEoIAsHFIwwFKxPveGFExigniyAKgb1uje3fkM1H2Hb2AF2C6Wo2GO1PH%2F3Lm88WT5QVBSn537Ze8e16yPOGf9df%2BefuZKp6w6qd%2Bt1%2FtNl2XbF9vaLVuVr%2BAympcls%3D&_b=eNozYPAL9fFBI2r8qiINfbNCDSOr%2FHJ8s7IrI41CTXyNIk0jQ5LLI7MCjf3cA6v8w8OyfXMDbQF9gxRO&beacon_type=start&aid=6680e394-5a5a-11ea-92dd-191344880006&syn%5Btiming%5D=%24TIMING_DATA"
],
"trackingEvents": {
"complete": [
"https://event.spotxchange.com/vast/complete?_x=WzE1ODI5MTU0OTAsIjY2ODA4NTRlNWE1YTExZWE5MmRkMTkxMzQ0ODgwMDA2IiwiMjQ5ODMyIiwiM2M0Y2EuZTI5M2IuMWQzMiIsIjEiLCIzYzRjYS5lMjkzYi4xZDMyIiwiOWUzMjhiMDIxZTYzOGUyZWZhNmIzY2VlMzY2MmFkZDYiLCI2NjgwZTM5NC01YTVhLTExZWEtOTJkZC0xOTEzNDQ4ODAwMDYiLHRydWUsbnVsbCxbIjI0Njk4NiIsIjI0OTgzMiIsIjEiLCIiLCJ1bmtub3duIiw1NyxbInVua25vd24iXSwwLDAsMCwwLDIwMDBdLDAsbnVsbCwiNjY4MzIzODc1YTVhMTFlYTkyZGQxOTEzNDQ4ODAwMDYiXSZzZXRlYz1OMlkwTkRjMllUSmxZekJoWlRRME9USXpPVGRoTldNM09EVmhPREl3T1dZPQ~~"
],
"firstQuartile": [
"https://event.spotxchange.com/vast/25?_x=WzE1ODI5MTU0OTAsIjY2ODA4NTRlNWE1YTExZWE5MmRkMTkxMzQ0ODgwMDA2IiwiMjQ5ODMyIiwiM2M0Y2EuZTI5M2IuMWQzMiIsIjEiLCIzYzRjYS5lMjkzYi4xZDMyIiwiOWUzMjhiMDIxZTYzOGUyZWZhNmIzY2VlMzY2MmFkZDYiLCI2NjgzMjM4NzVhNWExMWVhOTJkZDE5MTM0NDg4MDAwNiJdJnNldGVjPU1HWXpaV0V6TVRrek5EQmlZVEV4WkROaE9ESmlPREl3WmpZNFkySXpNakk9"
],
"midpoint": [
"https://event.spotxchange.com/vast/50?_x=WzE1ODI5MTU0OTAsIjY2ODA4NTRlNWE1YTExZWE5MmRkMTkxMzQ0ODgwMDA2IiwiMjQ5ODMyIiwiM2M0Y2EuZTI5M2IuMWQzMiIsIjEiLCIzYzRjYS5lMjkzYi4xZDMyIiwiOWUzMjhiMDIxZTYzOGUyZWZhNmIzY2VlMzY2MmFkZDYiLCI2NjgzMjM4NzVhNWExMWVhOTJkZDE5MTM0NDg4MDAwNiJdJnNldGVjPU1HWXpaV0V6TVRrek5EQmlZVEV4WkROaE9ESmlPREl3WmpZNFkySXpNakk9"
],
"thirdQuartile": [
"https://event.spotxchange.com/vast/75?_x=WzE1ODI5MTU0OTAsIjY2ODA4NTRlNWE1YTExZWE5MmRkMTkxMzQ0ODgwMDA2IiwiMjQ5ODMyIiwiM2M0Y2EuZTI5M2IuMWQzMiIsIjEiLCIzYzRjYS5lMjkzYi4xZDMyIiwiOWUzMjhiMDIxZTYzOGUyZWZhNmIzY2VlMzY2MmFkZDYiLCI2NjgzMjM4NzVhNWExMWVhOTJkZDE5MTM0NDg4MDAwNiJdJnNldGVjPU1HWXpaV0V6TVRrek5EQmlZVEV4WkROaE9ESmlPREl3WmpZNFkySXpNakk9"
]
}
},
{
"category": "content",
"titleId": null,
"title": "Example_content",
"duration": 30030
},
{
"category": "ad",
"titleId": "serverside.ai-asset-id",
"title": "AD 10SEC",
"duration": 10091,
"impressionUrlTemplates": [
"https://ams01-event.spotxchange.com/vast/impression?_x=WzE1ODI5MTU0OTAsIjY2ODAyNzZkNWE1YTExZWFhY2ZjMTRlNTgzMzAwMDA2IiwiMjQ5ODMyIiwiM2M0Y2EuZTI5M2IuMWQzMiIsIjEiLCIzYzRjYS5lMjkzYi4xZDMyIiwiOWUzMjhiMDIxZTYzOGUyZWZhNmIzY2VlMzY2MmFkZDYiLCI2NjgwNjU0NC01YTVhLTExZWEtYWNmYy0xNGU1ODMzMDAwMDYiLHRydWUsbnVsbCxbIjI0Njk4NiIsIjI0OTgzMiIsIjEiLCIiLCJ1bmtub3duIiw1NyxbInVua25vd24iXSwwLDAsMCwwLDIwMDBdLDAsbnVsbCwiNjY4MTU5NTM1YTVhMTFlYWFjZmMxNGU1ODMzMDAwMDYiXSZzZXRlYz1aV0UwTldWbVlUWTRPVGcyWVRrek9UUTVPRFV3WXpobU9EVXhNalEyWkRjPQ~~",
"https://ams01-search.spotxchange.com/beacon?_a=249832&_p=3c4ca.e293b.1d32&_z=1&_m=eNpdikELgjAYhr9fNPfNbW5Bl7AO4uZlBnUbZoVrFmQE0n%2Bv0JvPC8%2Fh4eWEUgBAoZhGwTUFKRVlmTwJLzxi631zbpC3QqUp%2FSOBca1SBvkWNBJEIhXBjMJ1GB7PVZK8%2BtDf330Cti7L%2F1lqJeE7MadJCIuwEM77VPkmHl1gZgzUuCLYvOgOcd8ZZ9CyXbSxHk13i5W7rH987jqL&_l=eNp1Tt9PgzAQ7t%2FSZ0PaAt1Y4hubMRn4IEbhhZT2JmwUGoSgm%2FvfLZvTJcb0%2Bt3dd9%2F9oIgiHzGL1lzpSeEAC9zCocplf4lwiQhSIGqrPmAXLw64qBReYIJvsBEf7dB%2FJxuAKXIIIcymbwaaH91Q1JXM4V2WonmF%2FEo6leXQiR5UrkW3g97UQsK%2FWtOBrgY90bk0%2BrTgeETx03p9Bnvno2n7l3M7Gppd044NooT7VBAomM9hRmZMUQp0EyjgIJgobNvvjBMwjwdzfkVQ%2BxjnZO5d3Ges7%2FepXo7Z82qbJWWV7lVpf%2F1wl22jMBqzcFWlSVbFSXT7BWC%2FaOg%3D&_t=eNotjU1vwjAMhvNbckYooR%2BUVLsNTTtQaYeB2CUyaaDp2iZKMkZh%2FPclFEu2Xz%2F2Kx8kCD2gPC9otsqSDDKgVAKIo6CpzIokISFyJBpQA9L2BIMS6DC5bngS3I9GYoadB%2BvxDJsORq%2F6iCiZk7QI7KxqqfkZOlXzo7LO86OFx0lYOglWNNwZKTC7YQNx5aV1carlWQkZlbz42JzR%2FsInzMGY53t6n%2BFe17LDjMywDl5yD4EQnROCgKXs5kLBQvkRl4otEpqS0rGcYStPSg9PmKwmeOr0AboI49UyGPXP4O3Dmy3LO1rkOSnSv2q37b%2FePknVNu0mZNVu1Wa3H%2Fftx1hd17%2F76zro77F6fX%2F5Bw4OdW0%3D&_b=eNozYPAL9fFBI2r8qiINfbNCDSOr%2FHJ8s7IrI41CTXyNIk0jQ5LLI7MCjf3cA6v8w8OyfXMDbQF9gxRO&beacon_type=start&aid=66806544-5a5a-11ea-acfc-14e583300006&syn%5Btiming%5D=%24TIMING_DATA"
],
"trackingEvents": {
"complete": [
"https://event.spotxchange.com/vast/complete?_x=WzE1ODI5MTU0OTAsIjY2ODAyNzZkNWE1YTExZWFhY2ZjMTRlNTgzMzAwMDA2IiwiMjQ5ODMyIiwiM2M0Y2EuZTI5M2IuMWQzMiIsIjEiLCIzYzRjYS5lMjkzYi4xZDMyIiwiOWUzMjhiMDIxZTYzOGUyZWZhNmIzY2VlMzY2MmFkZDYiLCI2NjgwNjU0NC01YTVhLTExZWEtYWNmYy0xNGU1ODMzMDAwMDYiLHRydWUsbnVsbCxbIjI0Njk4NiIsIjI0OTgzMiIsIjEiLCIiLCJ1bmtub3duIiw1NyxbInVua25vd24iXSwwLDAsMCwwLDIwMDBdLDAsbnVsbCwiNjY4MTU5NTM1YTVhMTFlYWFjZmMxNGU1ODMzMDAwMDYiXSZzZXRlYz1aV0UwTldWbVlUWTRPVGcyWVRrek9UUTVPRFV3WXpobU9EVXhNalEyWkRjPQ~~"
],
"firstQuartile": [
"https://event.spotxchange.com/vast/25?_x=WzE1ODI5MTU0OTAsIjY2ODAyNzZkNWE1YTExZWFhY2ZjMTRlNTgzMzAwMDA2IiwiMjQ5ODMyIiwiM2M0Y2EuZTI5M2IuMWQzMiIsIjEiLCIzYzRjYS5lMjkzYi4xZDMyIiwiOWUzMjhiMDIxZTYzOGUyZWZhNmIzY2VlMzY2MmFkZDYiLCI2NjgxNTk1MzVhNWExMWVhYWNmYzE0ZTU4MzMwMDAwNiJdJnNldGVjPU56YzBaV0V3T0RZNE5XTXhPVFpqTXpFd01tUXpOR1ZqWXpOa05URm1ZelU9"
],
"midpoint": [
"https://event.spotxchange.com/vast/50?_x=WzE1ODI5MTU0OTAsIjY2ODAyNzZkNWE1YTExZWFhY2ZjMTRlNTgzMzAwMDA2IiwiMjQ5ODMyIiwiM2M0Y2EuZTI5M2IuMWQzMiIsIjEiLCIzYzRjYS5lMjkzYi4xZDMyIiwiOWUzMjhiMDIxZTYzOGUyZWZhNmIzY2VlMzY2MmFkZDYiLCI2NjgxNTk1MzVhNWExMWVhYWNmYzE0ZTU4MzMwMDAwNiJdJnNldGVjPU56YzBaV0V3T0RZNE5XTXhPVFpqTXpFd01tUXpOR1ZqWXpOa05URm1ZelU9"
],
"thirdQuartile": [
"https://event.spotxchange.com/vast/75?_x=WzE1ODI5MTU0OTAsIjY2ODAyNzZkNWE1YTExZWFhY2ZjMTRlNTgzMzAwMDA2IiwiMjQ5ODMyIiwiM2M0Y2EuZTI5M2IuMWQzMiIsIjEiLCIzYzRjYS5lMjkzYi4xZDMyIiwiOWUzMjhiMDIxZTYzOGUyZWZhNmIzY2VlMzY2MmFkZDYiLCI2NjgxNTk1MzVhNWExMWVhYWNmYzE0ZTU4MzMwMDAwNiJdJnNldGVjPU56YzBaV0V3T0RZNE5XTXhPVFpqTXpFd01tUXpOR1ZqWXpOa05URm1ZelU9"
]
}
},
{
"category": "content",
"titleId": null,
"title": "Example_content",
"duration": 30030
}
]
}
}You can now use the dash.url to forward it to the player, which will play back the VoD asset with ad insertions.
2. Detect the start of an ad in the stream.
To detect when an ad starts playing, compare the player’s current position to the durations defined in the related ad blocks. Depending on the media player being used, you might need to monitor its current playback position on the timeline.
In the response body shown in 1. Manifest API Request (Manifest and VAST), the following playback sequence is defined:
A pre-roll ad lasting 10091 ms:
dash.clips[0].category: "ad"
dash.clips[0].duration: 10091 Followed by content lasting 30030 ms:
dash.clips[1].category: "content"
dash.clips[1].duration: 30030 Then a mid-roll ad lasting 10091 ms:
dash.clips[2].category: "ad"
dash.clips[2].duration: 10091 Followed by another content segment lasting 30030 ms:
dash.clips[3].category: "content"
dash.clips[3].duration: 300303. Keep track of the ad playback and send beacons.
As soon as the player timeline reaches the start of an ad, you must trigger all impression URLs listed in dash.clips.impressionUrlTemplates.
Then, you need to implement handling for the player events: pause, resume, finish, firstQuartile, midpoint, thirdQuartile, and complete. This will ensure the corresponding DASH tracking events are fired correctly:
dash.clips.trackingEvents.firstQuartile
dash.clips.trackingEvents.midpoint
dash.clips.trackingEvents.thirdQuartile
dash.clips.trackingEvents.complete
Always request all URLs provided in the related array.
HLS VoD
1. Manifest API request (manifest and VAST).
HLS VoD is very similar to DASH VoD. The only difference lies in the request and response of the manifest.
In the CURL request, you must specify "deliverytypes": ["hls"] instead of "dash".
CURL request
curl -X POST \
https://mydomain.com/ad-aggregation-service/mrss/channel/:channelId \
-H 'Content-Type: application/json' \
-H 'api-key: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx' \
-d '{
"url": "https://vodcms.blob.core.windows.net/mrss/serverside_mrss_hls_preroll_midroll.mrss",
"context": "web",
"ifa": "ifa",
"deliverytypes": [ "hls" ]
}'In the response body, the data entry point changes from dash to hls.
Response body
{
"hls": {
"url": "https://mydomain.com/ad-stitcher/m3u8/5955a297-e18e-47a9-9cb2-1fe30c0e235d.m3u8",
"clips": [
// ... as descibed above
]
}
}2. Detect the start of an ad in the stream.
This step is handled exactly the same way as Step 2 in the DASH VoD.
3. Keep track of the ad playback and send beacons.
This step is handled exactly the same way as Step 3 in the DASH VoD.