Ad metadata

This guide describes the supported ad metadata feature of the Video Stitcher API. Ad metadata is extracted from a VAST ad in an ad tag response, containing ad tracking events and companion ads. The ad tag url is configured in the session creation request. For more information, see create a live session and create a VOD session.

Before you begin

Make sure you are familiar with the introductory concepts and terminology in the Video Stitcher API. For more information, see the technical overview.

Introduction

Ad metadata contains ad tracking events and companion ads associated with a stitched ad. An ad tracking event contains a callback ping used to track the VAST ad and viewer interaction. A companion ad is an ad to supplement the parent VAST ad. In client-side tracking mode, you are responsible to trigger events based on the viewer's behavior.

Server-side ad tracking

In server-side tracking mode, each ad segment URI is wrapped in a redirect URI and the Video Stitcher API will handle the processing of progress events whenever the player requests those segments. However, activity events, such as pause, are not handled by the Video Stitcher API.

Client-side ad tracking

In client-side tracking mode, the client is responsible for triggering the events. For more details, see the event documentation.

Progress events are events that should be triggered when the specified time has elapsed during the ad. For example, event Start should be triggered at the beginning of the ad. For more details about progress events, see the progress event object.

Activity events are events that should be triggered when a viewer conducts a specific activity. For example, event pause should be triggered when the viewer pauses the ad video. For more details about activity events, see the activity event object.

VOD client-side ad tracking

An interstitials object is returned in the response of a VOD session create request. For instruction on how to create a VOD session, see create a VOD session.

Interstitials contains the metadata for each inserted ad. When client ad tracking mode is enabled, the client is responsible for triggering tracking events when necessary. For more details, see the interstitials object.

Live client-side ad tracking

The Video Stitcher API continuously inserts ads into a live stream; ad metadata information is generated whenever a new ad is inserted.

For HLS, the AdMetadataURI to fetch ad metadata can be found in the #EXT-X-DATERANGE tag.

For DASH, the AdMetadataURI to fetch ad metadata can be found in the <EventStream> element for each <Period> element.

For more details, see How to handle live client-side tracking.

Companion ads

Companion ads are supplemental ads that may appear along with inserted linear ads. For more details, see the companion ads object.

What's next