Video Ads
Pre-roll video advertising on Brightcove videos via the IMA3 plugin and Google Ad Manager
Written by Hughie Molloy
Updated at June 2nd, 2026
Table of Contents
Pugpig supports preroll video adverts on videos where it's possible to configure ads on the video provider's side. These are video adverts that play before the video, but after the user clicks the play button. On completion, or when skipped, the video will automatically start.
Supported Video Providers
Video ads are currently supported on Brightcove videos via the Brightcove IMA3 plugin. Brightcove videos can carry pre-roll ads in both in-article placements and timeline video cards.
The ad tag URL is supplied via the brightcove_ad_tag_url field in the content feed. This field contains a GAM (Google Ad Manager) ad tag URL which the Brightcove player uses to request and display pre-roll ads. The ad unit can be overridden at both the article and timeline level using the standard Express ad unit override fields:
-
Article level:
pugpig_express_dfp_ads_override_article_inline_ad_unit(changes dynamically based on article categories) -
Timeline level:
pugpig_express_dfp_ads_override_timeline_ad_unit
⚠️ Note: Video ad support for direct video files (MP4, M3U8) via the IMA HTML5 SDK has been deprecated. We have plans to reinstate support for this.
How It Works
For Brightcove videos, Pugpig uses Brightcove's built-in IMA3 plugin. The flow is:
- The content feed includes a
brightcove_ad_tag_urlfield containing a GAM VMAP ad tag URL. - Pugpig reads this URL and appends custom targeting parameters before passing it to the Brightcove player.
- The Brightcove IMA3 plugin uses the URL to request ads from GAM.
- A pre-roll ad plays before the video content begins.
The Brightcove player makes both a VMAP request (for ad scheduling, using output=xml_vmap1) and a VAST 4 request (for the ad creative, using output=xml_vast4 with vpos=preroll). Both are sent to pubads.g.doubleclick.net/gampad/ads.
Ad Format
The ads served use the Video Ad Serving Template (VAST) format, requested via VMAP (Video Multiple Ad Playlist). VAST and VMAP ads can be set up in your Google Ad Manager (GAM) account. The length of the advert, clickthrough URL, and whether it is skippable can all be configured in GAM.
Targeting and Passed Parameters
Pugpig automatically appends custom targeting parameters to the Brightcove ad tag URL. These are passed as cust_params key-value pairs that can be targeted in your GAM account.
Parameters set by Pugpig
| Parameter | Value / Description |
|---|---|
| iu | The ad unit ID path (e.g. /133009657/app-nca/section). Can be overridden per article or timeline. |
| sz | 640x480 |
| env | vp |
| gdfp_req | 1 |
| output |
xml_vmap1 (VMAP request) / xml_vast4 (VAST request) |
| plcmt | 1 |
| unviewed_position_start | 1 |
| vpa | click |
| vpmute | 0 |
| description_url | The URL the video is playing on (vanity domain for both web and native apps) |
| url | Same as description_url
|
| hl | The language set on the HTML page (typically from Express General Settings) |
| pp | Publisher profile identifier |
| vid | Video document ID |
| cmsid | CMS ID for the video |
| ppid | Publisher-provided ID (e.g. NUID) |
| correlator | Ad request correlator (shared across ad calls on the same page view) |
Custom targeting parameters (cust_params)
The following key-value pairs are passed inside the cust_params parameter. They automatically include article taxonomy and can be targeted in your GAM account:
| Key | Description |
|---|---|
| nuid | User identifier (e.g. Nine User ID) |
| apid | Time-based hash derivative of the user ID |
| device_id | Device identifier |
| optout | Consent/opt-out flag (0 or 1) |
| pagelevel01 through pagelevel04 | Hierarchical GAM ad unit path segments |
| pagetype |
article or index
|
| tag | Article tags / topics (comma-separated) |
| contentId | Unique content identifier for the video instance |
| collection | Timeline/collection name (for timeline video cards) |
| deployEnv |
production or staging
|
| deviceType | mobile |
| os |
ios, android, or web
|
| sysEnv | app |
| userAgentheader | Full Pugpig user agent string including app version, device model, and OS version |
| vendorVersion | Pugpig Bolt app version (e.g. PugpigBolt v5.0.2) |
Parameters handled by the IMA SDK / Google
The following parameters are populated automatically by the Google IMA SDK and do not need to be set by Pugpig or the publisher:
- rdid – Resettable device identifier
-
idtype – Device type identifier (e.g.
adid,idfa) -
ip – User IP address (sent as
user_ipby the SDK) - is_lat – Limit ad tracking flag
- gdpr / gdpr_consent – GDPR consent status and TCF string
Brightcove Player Configuration
To enable pre-roll ads on Brightcove videos, the customer's Brightcove account must be configured with:
- A Brightcove player with the IMA3 plugin enabled.
-
Data parameters configured on the player (e.g.
is_lat,pp,os) to accept values passed by Pugpig. - The
brightcove_ad_tag_urlfield populated in the content feed with a valid GAM ad tag URL.
Pugpig sanitises the ad tag URL before passing it to Brightcove, normalising it to use the pubads.g.doubleclick.net domain and fixing any double-slash issues in the ad unit path.
Where Ads Appear
- In-article Brightcove videos: Both feature (main media) videos and inline videos within article body content.
- Timeline video cards: Brightcove video cards displayed on timelines (e.g. a dedicated "Watch" timeline).
Analytics
The IMA3 SDK automatically tracks ad impressions and clicks, which can be seen in your GAM account. Additional ad analytics can be tracked to a third-party URL on the creative in GAM.
Components Involved
The Brightcove video ads feature spans several Pugpig components:
- Express – Handles ad targeting support, ad unit configuration, and the targeting filter.
- Bolt Widgets – Adds ad parameters to video cards and the ad unit ID to the generic video widget.
- Bolt Timeline – Passes ad targeting on timeline video cards.
- Native apps (iOS/Android) – Provides bridge values (consent, PPID, device info) that are forwarded to the ad request.