Advertising

VP Audio Player supports VAST and VMAP advertising via the Google IMA SDK. Ads are configured on the audio.ads object, with the audio.advertising flag acting as the top-level switch that enables the ad pipeline for a given audio.

Ads

vpAudioPlayer("audio-ads").setup({
    audio: {
        file: "the_audio_file_path",
        advertising: true,
        adId: "",
        ads: {
            vastManager: "ima",
            type: "STATIC",
            skipAllAds: false,
            vmap: "",
            adBreaks: [
                {
                    adTagUrl: ["https://example.com/ad-tag.xml"],
                    breakType: "preroll",
                    breakTimingType: "time",
                    breakTimingValue: 0,
                },
            ],
        },
    }
});

PROPERTY	DESCRIPTION
advertising boolean	The top-level switch that enables ads on the audio. When false, the ad pipeline is skipped entirely.
adId string	Unique identifier of the ad schedule associated with the audio.
ads Object	Configures the ad source, scheduling, and behavior.
vastManager string	The VAST manager used to load and render ads. Possible values: "ima", "vp".
type string	The ad scheduling type. Possible values: "STATIC", "DYNAMIC".
skipAllAds boolean	Applies when there are multiple consecutive ads. When true, the user clicking skip on any ad also skips every following ad in the same break. When false, only the current ad is skipped and the next ad plays as usual. Ads the user does not skip always play normally.
vmap string	A single VMAP URL that contains all ad breaks for the audio. When provided, adBreaks is ignored.
adBreaks array[Object]	An array of ad break objects (used when vmap is not provided). See Ad Breaks below.

note

The Google IMA SDK is loaded automatically by the player when audio.advertising is true. If the SDK cannot be loaded (for example, because of an ad blocker), advertising is silently disabled and the audio plays without ads.

Ad Breaks

Each ad break inside the adBreaks array describes a single insertion of one or more VAST tags. Pre/post-rolls play at the beginning or end of the audio; midrolls play at a configured offset.

vpAudioPlayer("audio-ads").setup({
    audio: {
        file: "the_audio_file_path",
        advertising: true,
        ads: {
            adBreaks: [
                {
                    adTagUrl: ["https://example.com/ad-tag.xml"],
                    breakType: "midroll",
                    breakTimingType: "time",
                    breakTimingValue: 30,
                },
            ],
        },
    }
});

PROPERTY	DESCRIPTION
adBreaks array[Object]	An array of ad break objects.
adTagUrl array[string]	An array of VAST tag URLs used as a waterfall for the ad break. The first URL is requested, with subsequent URLs used as fallbacks.
breakType string	The type of ad break. Possible values: "preroll", "midroll", "postroll".
breakTimingType string	How midroll timing is interpreted. Possible values: "time" (seconds elapsed) or "percentage" (percent of audio played). Only used for midrolls.
breakTimingValue number	The value at which the midroll should trigger, in seconds or percent depending on breakTimingType. Only used for midrolls.

Static Ad Breaks

The STATIC ad type plays a fixed list of ad breaks. Each break is triggered based on its breakType and breakTimingType/breakTimingValue:

const staticAds = {
    type: "STATIC",
    adBreaks: [
        {
            adTagUrl: ["https://example.com/ad-tag.xml"],
            breakType: "preroll",
            breakTimingType: "time",
            breakTimingValue: 0,
        },
        {
            adTagUrl: ["https://example.com/ad-tag.xml"],
            breakType: "midroll",
            breakTimingType: "time",
            breakTimingValue: 30,
        },
        {
            adTagUrl: ["https://example.com/ad-tag.xml"],
            breakType: "midroll",
            breakTimingType: "percentage",
            breakTimingValue: 50,
        },
        {
            adTagUrl: ["https://example.com/ad-tag.xml"],
            breakType: "postroll",
            breakTimingType: "time",
            breakTimingValue: 0,
        },
    ],
};

note

In this configuration there are four ad breaks: a preroll at the start, two midrolls (at 30 seconds and at 50% of the audio), and a postroll at the end.

VMAP

Instead of declaring adBreaks manually, you can provide a single VMAP URL. The IMA SDK will then handle pre/mid/postroll scheduling internally based on the VMAP document.

vpAudioPlayer("audio-vmap").setup({
    audio: {
        file: "the_audio_file_path",
        advertising: true,
        ads: {
            vmap: "https://example.com/vmap.xml",
        },
    }
});

PROPERTY	DESCRIPTION
vmap string	A single VMAP URL. When provided, the IMA SDK schedules all ad breaks declared in the VMAP and adBreaks is ignored.

Fallback Ad Tag URLs

When an adBreak has an empty adTagUrl array, the player can substitute a fallback URL based on the break type. This is useful when you reuse the same ad schedule across multiple audios but want to override the tag URL per audio.

vpAudioPlayer("audio-fallback-ads").setup({
    audio: {
        file: "the_audio_file_path",
        advertising: true,
        ads: {
            prerollUrl: "https://example.com/preroll.xml",
            midrollUrl: "https://example.com/midroll.xml",
            postrollUrl: "https://example.com/postroll.xml",
            adBreaks: [
                {
                    adTagUrl: [],
                    breakType: "preroll",
                    breakTimingType: "time",
                    breakTimingValue: 0,
                },
            ],
        },
    }
});

PROPERTY	DESCRIPTION
prerollUrl string	VAST URL used when a preroll ad break has an empty adTagUrl.
midrollUrl string	VAST URL used when a midroll ad break has an empty adTagUrl.
postrollUrl string	VAST URL used when a postroll ad break has an empty adTagUrl.

Skip Ad

You can localize the skip-ad button via config.lang.ads.skipAd. See Localization for the full list of ad strings.

vpAudioPlayer("audio-skip-ad").setup({
    audio: {
        file: "the_audio_file_path",
        advertising: true,
        ads: { /* ... */ }
    },
    config: {
        lang: {
            ads: {
                skipAd: "Skip Ad",
                advertisement: "Advertisement",
            },
        },
    }
});