VOD - DASH/HLS

DASH-VOD

1.-3. Manifest API Request (Manifest and VAST)

A request of a VOD-Manifest integrates steps 1-3 from the DASH and HLS live process.

The URL to the ad-insertion enabled channel is called outputUrl and can be viewed at Serverside.ai or via the https://admin.serverside.ai/api/v2/channels/:channelId API endpoint.

An outputUrl for DASH-VoD channels will have the following schema: https://live.serverside.ai/ad-aggregation-service/mrss/channel/:channelId

The URL and the request to obtain a manifest is very different from HLS or DASH-VoD. Please read the following lines carefully to not get confused

CURL request

curl -X POST \
  https://live.serverside.ai/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://staging-live.serverside.ai/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 playback the VoD asset with ad insertions

4. Detect the start of an ad in the stream

Depending on the player you are using you have to listen to the position of the player on the timeline.

Get the position when the player starts playback of the ad from the duration defined in the related ad block.

In the example above there is a preroll ad for 10091 ms

dash.clips[0].category: ”ad”
dash.clips[0].duration: 10091

followed by content for 30030 ms

dash.clips[1].category: ”content”
dash.clips[1].duration: 30030

followed by a mid roll ad 10091 ms

dash.clips[2].category: ”ad”
dash.clips[2].duration: 10091

followed by another piece of content for 30030 ms

dash.clips[3].category: ”content”
dash.clips[3].duration: 30030

5. Keep track of the ad playback and send beacons

As soon as the player timeline reaches the entry point of an ad the impression URLs have to be fired.

dash.clips.impressionUrlTemplates

Now you have to implement the handling for pause, resume, finish, firstQuartile, midpoint, thirdQuartile, and complete player events in order to fire the following DASH events correctly:

dash.clips.trackingEvents.firstQuartile

dash.clips.trackingEvents.midpoint

dash.clips.trackingEvents.thirdQuartile

dash.clips.trackingEvents.complete

Always request all url provided in the related Array

HLS-VOD

1.-3. Manifest API Request (Manifest and VAST)

HLS-VoD is very similar to DASH-VoD. The only difference is in the request and response of the manifest.

CURL Request:

curl -X POST \
  https://live.serverside.ai/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" ]
}'

You have to specify deliverytypes as hls instead of dash

Response body:

{
    "hls": {
        "url": "https://live.serverside.ai/ad-stitcher/m3u8/5955a297-e18e-47a9-9cb2-1fe30c0e235d.m3u8",
        "clips": [
          // ... as descibed above
        ]
    }
}

The data entry point changed from dash to hls

Steps 4 and 5 in the process are handled exactly as for the DASH-VoD case.