BiddingStack Audio Player for Web
BiddingStack Audio Player Web Integration Guide
Embeddable audio player for websites. Supports 12 themes, embedded / floating / fullscreen modes, playlists, podcast subscribe links, and audio advertising through Google IMA and Prebid.
Integration
1. Configure the audio content
Create and configure the player in the BiddingStack console.
The Audio ID and Playlist ID identify content hosted on SyncCMS. A SyncCMS account is required to upload and manage audio and playlists. There are two ways to assign the content to a player:
Option A: in the BiddingStack console
- Set Player Type to Single Audio or Playlist in the player configuration.
- Enter the Audio ID (for Single Audio) or the Playlist ID (for Playlist) in the Audio Content section.
Option B: on the page
Set data-audioId or data-playlistId on the player container (see step 3) to override the console configuration per page:
<!-- Single audio -->
<div id="bsap-audio-player-1" data-audioId="YOUR_AUDIO_ID"></div>
<!-- Playlist -->
<div id="bsap-audio-player-1" data-playlistId="YOUR_PLAYLIST_ID"></div>
If both attributes are present, data-playlistId takes precedence.
2. Add the player tag
Add the loader script to your page. The script tag id must be bssdk-tag-aud, and data-bslid must be set to your publisher ID (provided by BiddingStack):
<script id="bssdk-tag-aud" data-bslid="YOUR_PUBLISHER_ID" src="https://pubtm.com/aud/tag.js" async></script>
You can also find the ready-to-copy player tag in the SyncCMS UI.
3. Add a player container
Add an empty container element where the player should render. The container is matched by the selector defined in your player configuration:
<div id="bsap-audio-player-1"></div>
On page load the player automatically finds each configured container and renders a player into it. Players, content, and ad settings are configured in the BiddingStack console.
The player supports two UI modes, set by Player Mode in the BiddingStack console:
- Embed: the player renders inline in the container element on the page.
- Float: the player renders in a floating container fixed over the page.
Player Configuration
Each player is configured per domain in the BiddingStack console.
General
| Setting | Default | Description |
|---|---|---|
| Domain | required | The website domain the player runs on, e.g. www.example.com |
| Enable | on | Turns the player on or off for the domain |
| Player Type | Playlist | Single Audio or Playlist |
| Player Mode | Embed | Embed (inline in the container) or Float (fixed over the page) |
| Auto Play | off | Starts playback automatically |
| Only Ads Mode | off | Plays ads only, without audio content |
| Enable Ads | on | Enables audio advertising |
| GAM Ad Unit Path | empty | Google Ad Manager ad unit path, e.g. /12345678/your_network/ad_unit_name. Used to generate the VAST ad tag URL |
| Theme | 1 | One of 12 themes, e.g. Classic Black & White, Dark Mode, Midnight Blue, Warm Sunset, Compact Pill |
Audio Content
| Setting | Description |
|---|---|
| Audio ID | Shown when Player Type is Single Audio. The SyncCMS audio ID |
| Playlist ID | Shown when Player Type is Playlist. The SyncCMS playlist ID |
| Audios | Optional manual list of episodes, each with an audio URL, title, poster image, duration, and description |
Prebid Configuration
| Setting | Default | Description |
|---|---|---|
| Enable Prebid | off | Enables header bidding for audio ads |
| Prebid Ad Unit (JSON) | empty | The Prebid videoAdUnit configuration as JSON, including mediaTypes.video and the bids array |
Advanced Settings
Player Behavior
| Setting | Default | Description |
|---|---|---|
| CSS Selector | #bsap-audio-player-1 | The container element the player renders into |
| Loop Playback | off | Restarts the content when it ends |
| Enable Sound | on | Starts playback with sound on |
| Lite Mode | off | Compact pill-shaped floating player |
| Enable Float | on | Floats the player when it scrolls out of view (embed mode only) |
Float Position
| Setting | Float default | Lite float default |
|---|---|---|
| Top (px) | unset | unset |
| Bottom (px) | 20 | 260 |
Ad Options
| Setting | Default | Description |
|---|---|---|
| Ad Count | 3 | Number of ads to play; use -1 for unlimited |
Share URLs
Share links for WhatsApp, Twitter / X, Facebook, LinkedIn, and Email.
Subscribe URLs
Podcast subscribe links shown in the player: Apple Podcasts, Spotify, Google Podcasts, Amazon Music, and RSS Feed.
Page-Level Overrides
Any player configuration option can be overridden per page with the data-config attribute on the container. Its value is a JSON object merged into the player configuration on load, taking precedence over the console settings:
<div
id="bsap-audio-player-1"
data-audioId="YOUR_AUDIO_ID"
data-config='{"themeid": 3, "mode": "embed", "lite": false, "enableFloat": false}'
></div>
Commonly used options:
| Option | Description |
|---|---|
themeid | Theme, 1 to 12 |
mode | embed (inline) or float (fixed over the page) |
lite | Compact pill-shaped floating player |
enableFloat | Floats the player when it scrolls out of view (embed mode only) |
floatConfig, liteFloatConfig | Floating position offsets in pixels, e.g. {"top": null, "bottom": 20} |
autoPlay, enableSound, loop | Playback behavior |
adConfig | Ad options, e.g. {"enableAds": false} disables ads on the page |
prebidConfig | Prebid options, e.g. {"enable": false} disables header bidding on the page |
Common placement patterns:
| Placement | Config |
|---|---|
| Inline + sticky pill | {"mode": "embed", "lite": true, "enableFloat": true, "liteFloatConfig": {"bottom": 20}} |
| Inline only | {"mode": "embed", "lite": false, "enableFloat": false} |
| Bottom bar on scroll | {"mode": "embed", "lite": false, "enableFloat": true, "floatConfig": {"bottom": 0}} |
| Always-on bottom bar | {"mode": "float", "lite": false, "enableFloat": false, "floatConfig": {"bottom": 0}} |
Runtime API
The audio player exposes a JavaScript API on window.BIDDINGSTACK_AP for changing the configuration without a page reload:
// Read the current configuration of a player
var config = window.BIDDINGSTACK_AP.getPlayerConfig('#bsap-audio-player-1')
// Reload the player with new options
window.BIDDINGSTACK_AP.reload('#bsap-audio-player-1', {
themeid: 5,
mode: 'embed',
lite: true,
enableFloat: true,
})
The API is available once the player tag has loaded, so wait for window.BIDDINGSTACK_AP to be defined before calling it.
Google Ad Manager Setup
Audio ads are served through the Google IMA SDK. To serve ads:
- Create an ad unit in Google Ad Manager.
- Enter the ad unit path (e.g.
/12345678/your_network/ad_unit_name) in the GAM Ad Unit Path field of the player configuration. BiddingStack generates the VAST ad tag URL from this path. - Make sure Enable Ads is on.
To add header bidding demand on top of GAM, turn on Enable Prebid and provide the Prebid ad unit JSON in the Prebid Configuration section.
If you do not have your own audio ads demand, BiddingStack can provide demand for your inventory. Contact the BiddingStack team to get set up.