Overview
A companion banner uses advertising metadata to display companion advertising creatives alongside your player during supported ad breaks, synchronized to the active ad creative. This document provides a guide for activating this functionality and using the second metadata endpoint to retrieve companion banner metadata.
Impressions for the campaign will be reported when the player fetches the companion HTML from the DAS endpoint.
Instructions
Session Initialization and Metadata Flow
To receive companion banner content, the player or client application must:
- Request a listening session from the DAS /start-session endpoint
- Begin playback using the session-aware ICY or HLS stream URL
- Retrieve metadata from the second-metadata or second-metadata-json endpoint
- Detect available companion objects in the metadata response
- Select the companion creative that best fits the available banner placement
- Request the selected companion URL
- Render the returned HTML response within the player UI.
The general metadata flow is:
/start-session
↓
Stream connection established
↓
/metadata queried
↓
Metadata response contains companion objects
↓
Player requests companion.url
↓
DAS/SSP returns HTML markup
↓
Player renders returned markup
The player receives one or more companion objects in the second metadata response. Each companion includes a url, width, and height. The player should choose the companion creative that best fits its available banner slot, request that companion URL, and render the returned HTML. Requesting the companion URL triggers impression tracking for the selected creative.
Starting a listening session
Your player should start a listening session by sending an HTTP GET request to the DAS mount /start-session endpoint:
http://hostname:port/<mountName>/start-session
In the following example, the mount name is /banner:
curl https://das-instance:443/banner/start-session -o -|
{
"session-id": "R1BIWDdOVkEyWFNNQkc1RkVGTFZUVzVBV1lfY3ViZS5sb2NhbDo4MTg2",
"icy-url": "https://customer-live-a.edge.audiocdn.com/banner?listeningSessionId=R1BIWDdOVkEyWFNNQkc1RkVGTFZUVzVBV1lfY3ViZS5sb2NhbDo4MTg2",
"hls-url": "https://customer-live-a.edge.audiocdn.com/banner.m3u8?listeningSessionId=R1BIWDdOVkEyWFNNQkc1RkVGTFZUVzVBV1lfY3ViZS5sb2NhbDo4MTg2&masterPlaylist=true&codec=mp4a.40.34&bitrate=128",
"second-metadata": "https://customer-live-a.edge.audiocdn.com/metadata?listeningSessionId=R1BIWDdOVkEyWFNNQkc1RkVGTFZUVzVBV1lfY3ViZS5sb2NhbDo4MTg2",
"second-metadata-json": "https://customer-live-a.edge.audiocdn.com/metadata?listeningSessionId=R1BIWDdOVkEyWFNNQkc1RkVGTFZUVzVBV1lfY3ViZS5sb2NhbDo4MTg2&type=json&format=pretty"
}This response provides session-aware URLs that your player will use to begin the stream, in ICY or HLS format. Your player should select the stream format that is most appropriate for the capabilities of your player.
The streaming URLs contain a listeningSessionId that associates the listener session with metadata and companion banner delivery. Once the player begins consuming the live stream, the companion metadata can be retrieved.
Retrieving companion metadata
The client application should issue an HTTP GET request to the /metadata endpoint, utilizing the specific URLs provided by the second-metadata or second-metadata-json values.
curl https://customer-live-a.edge.audiocdn.com/metadata\?listeningSessionId\=R1BIWDdOVkEyWFNNQkc1RkVGTFZUVzVBV1lfY3ViZS5sb2NhbDo4MTg2\&type\=json\&format\=pretty | jq -r
{
"start": "145360",
"metadata": {
"title": "DAS TEST @ MIDROLL 1 ",
"url": "",
"artwork": ""
},
"companion": [
{
"url": "https://customer-live-a.edge.audiocdn.com/companion/banner?listeningSessionId=R1BIWDdOVkEyWFNNQkc1RkVGTFZUVzVBV1lfY3ViZS5sb2NhbDo4MTg2&cid=e2e-compBanner-mid-roll-1-1779396029762-60000/1.0/comp0",
"width": "280",
"height": "280"
},
{
"url": "https://customer-live-a.edge.audiocdn.com/companion/banner?listeningSessionId=R1BIWDdOVkEyWFNNQkc1RkVGTFZUVzVBV1lfY3ViZS5sb2NhbDo4MTg2&cid=e2e-compBanner-mid-roll-1-1779396029762-60000/1.0/comp1",
"width": "107",
"height": "95"
},
{
"url": "https://customer-live-a.edge.audiocdn.com/companion/banner?listeningSessionId=R1BIWDdOVkEyWFNNQkc1RkVGTFZUVzVBV1lfY3ViZS5sb2NhbDo4MTg2&cid=e2e-compBanner-mid-roll-1-1779396029762-60000/1.0/comp2",
"width": "400",
"height": "300"
}
]
},
{
"start": "175374",
"metadata": {
"title": "128000kps-a001_e2e-DAS-SONG-1",
"url": "",
"artwork": ""
}
},The metadata response includes a companion array containing the following creative attributes:
- The source URL for the companion creative
- The width of the banner
- The height of the banner
Next, your player should send an additional HTTP GET request to the companion.url value returned in the metadata response.
The response body will contain the HTML markup for the companion banner, which can then be rendered by the player or client application.
The player should periodically request the metadata endpoint while streaming is active, aligned with metadata refresh cadence.
The returned HTML should be rendered within a client-side container capable of supporting standard HTML, JavaScript, and third-party tracking execution.
Implementation details are determined by the player environment.
Example Responses
Plain Text:
start=180000 media_sequence=9 title="Some ad starting" url="http://www.ad.com" artwork="http://ad.artwork.com" companion="http://edge/comp3-1",width=12,height=34 companion="http://edge/comp3-2",width=56,height=78
XML:
<root>
<metadata-list>
<item>
<start>180000</start>
<media_sequence>9</media_sequence>
<metadata>
<title>Some ad starting</title>
<url>http://www.ad.com</url>
<artwork>http://ad.artwork.com</artwork>
</metadata>
<companion>
<url>http://edge/comp3-1</url>
<width>12</width>
<height>34</height>
</companion>
<companion>
<url>http://edge/comp3-2</url>
<width>56</width>
<height>78</height>
</companion>
</item>
</metadata-list>
</root>JSON:
{
"metadata-list": [
{
"start": "180000",
"media_sequence": "9",
"metadata": {
"title": "Some ad starting",
"url": "http://www.ad.com",
"artwork": "http:\/\/ad.artwork.com"
},
"companion": [
{
"url": "http:\/\/edge\/comp3-1",
"width": "12",
"height": "34"
},
{
"url": "http:\/\/edge\/comp3-2",
"width": "56",
"height": "78"
}
]
}
]
}JSON, No Companion Present:
{
"start": "175374",
"metadata": {
"title": "Song Title",
"artwork": "..."
}
}This indicates no companion creative is currently associated with the active metadata item.
Recommended Banner Display Behavior
- Display the companion banner while the associated ad-break metadata is active
- If subsequent metadata does not contain companion information and is not an ad break, restore normal artwork or metadata presentation
- If an ad-break metadata item does not include companion information, the player may leave the companion area empty or display fallback content
Impression Tracking
Requesting a companion URL triggers server-side VAST tracking associated with the displayed companion creative. Additional third-party tracking embedded within the returned HTML may execute client-side within the rendering environment.
Security/Sanitization
Companion creatives may contain third-party HTML and JavaScript provided by advertising partners.
Common Pitfalls
- Avoid prefetching companion URLs
- Prefetching all companion URLs may result in inaccurate ad impression reporting because requesting a companion URL triggers associated tracking events
- Request only the displayed companion creative
- If multiple companion creatives are provided, the player should only request the creative that will actually be rendered
- Ensure client-side HTML execution is supported
- Some companion creatives may contain JavaScript-based third-party tracking or interactive elements that must execute within the rendering environment