feat: Google IMA support for mux-player and mux-video variants

[luwes]

fix #1120

This change adds support for the Google IMA client-side to the production variants of mux-video and mux-player.
Support is currently limited to linear pre, mid, and post roll ads. All ads logic is isolated from the standard mux-video and mux-player variants and requires a separate import path to include ad support.

Examples

• MuxPlayer: https://elements-demo-nextjs-git-ads-video-mixin-mux.vercel.app/MuxPlayerAds
• MuxVideo: https://elements-demo-nextjs-git-ads-video-mixin-mux.vercel.app/mux-video-ads-react
• news player (POC): https://elements-demo-nextjs-git-ads-video-mixin-mux.vercel.app/MuxNewsPlayer

Readme

• mux-video (ads): https://github.com/muxinc/elements/blob/ads-video-mixin/packages/mux-video/src/ads/README.md

New import paths

mux-player variants

web component

import '@mux/mux-player/ads';

<mux-player playback-id="..." ad-tag-url="..." allow-ad-blocker></mux-player>

React

import MuxPlayer from '@mux/mux-player-react/ads';

const Component = () => <MuxPlayer playbackId="..." adTagUrl="..." allowAdBlocker={true} />;

mux-video variants

web component

import '@mux/mux-video/ads';

<mux-video playback-id="..." ad-tag-url="..." allow-ad-blocker></mux-video>

React

import MuxVideo from '@mux/mux-video/ads/react';

const Component = () => <MuxVideo playbackId="..." adTagUrl="..." allowAdBlocker={true} />;

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated (UTC)
elements-demo-astro	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Jun 18, 2025 9:01pm
elements-demo-nextjs	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Jun 18, 2025 9:01pm
elements-demo-svelte-kit	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Jun 18, 2025 9:01pm
elements-demo-vanilla	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Jun 18, 2025 9:01pm
elements-demo-vue	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Jun 18, 2025 9:01pm

[snyk-io]

🎉 Snyk checks have passed. No issues have been found so far.

✅ security/snyk check is complete. No issues have been found. (View Details)

✅ license/snyk check is complete. No issues have been found. (View Details)

[cjpillsbury]

Phase 1 complete! 🚀

[cjpillsbury]

Found an issue smoke testing https://elements-demo-nextjs-git-ads-video-mixin-mux.vercel.app/MuxNewsPlayer (play first ad + video, let 2nd play, note that ad does not play)

[cjpillsbury]

Confirmed fix works and code changes make sense! One callout re: src vs. playback-id scenarios, but can treat as a fast follow if it's complicated. Pre-approving either way. 🚀

[cjpillsbury]

🏃‍♂️

[luwes]

@claude

[claude]

Claude finished @luwes's task —— View job

---

Hi! I see you've tagged me on this merged PR about Google IMA support.

How can I help you? Please let me know what you'd like me to:

• Review or analyze specific parts of the implementation
• Help with follow-up tasks or improvements
• Answer questions about the code
• Assist with related work

Just let me know what you need!

---

[luwes]

@claude could you give a summary of the changes in this PR?

[claude]

Claude finished @luwes's task —— View job

---

Summary of PR #1128 Changes

This PR adds Google IMA (Interactive Media Ads) support to both mux-player and mux-video components, implementing client-side ad playback for linear pre-roll, mid-roll, and post-roll advertisements.

Todo List:

• Analyze core mux-video ads implementation
• Analyze mux-player ads implementation
• Review new package exports and import paths
• Examine example implementations
• Review architectural decisions and mixins
• Summarize key features and changes

---

🎯 Core Features Added

Ad Support Types:

• Linear pre-roll, mid-roll, and post-roll ads via Google IMA SDK
• VAST and VMAP ad tag support
• Ad-blocker detection with configurable fallback behavior

New Import Paths:

• @mux/mux-video/ads - Web component with ads
• @mux/mux-video/ads/react - React wrapper for ads video
• @mux/mux-player/ads - Web component with ads
• @mux/mux-player-react/ads - React wrapper for ads player
• @mux/mux-player-react/news - News theme with playlist support

🏗️ Architecture & Implementation

Mixin-Based Design:

• AdsVideoMixin - Core ads functionality for mux-video
• AdsPlayerMixin - Player-specific ads integration
• GoogleImaClientProvider - Google IMA SDK integration layer
• Isolated ads logic - no impact on standard variants

Key Technical Decisions:

• Code isolation through separate entry points
• Mixin pattern for composability
• Custom ad container overlay system
• Event forwarding between IMA SDK and custom elements
• Backup/restore mechanism for video state during ad breaks

📦 Package Structure Changes

New Exports Added:

// mux-video exports
"./ads": ads web component
"./ads/mixin": ads mixin for custom implementations
"./ads/react": React wrapper

// mux-player exports  
"./ads": ads web component
"./ads/mixin": ads mixin for custom implementations
"./themes/news": news theme with playlist support

Build System Updates:

• New build targets for ads variants
• Separate bundle generation for ads components
• Type definitions for ads-specific APIs

🎮 New API Surface

HTML Attributes:

• ad-tag-url - VAST/VMAP ad tag URL
• allow-ad-blocker - Fallback behavior for blocked ads

JavaScript Properties:

• adTagUrl - Ad tag URL getter/setter
• allowAdBlocker - Ad blocker handling
• ad - Current ad object reference
• adsLoader - Google IMA ads loader instance

Events (16 new ad events):

• adrequest, adresponse, adimpression
• adbreakstart, adbreakend
• adplay, adplaying, adpause
• adfirstquartile, admidpoint, adthirdquartile
• adclick, adskip, adclose, adended, aderror

🛠️ Implementation Highlights

Ad Playback Flow:

1. SDK detection and initialization
2. Ad container setup with overlay positioning
3. Ad request/response handling
4. Video state backup during ad breaks
5. Seamless content resumption after ads
6. Error handling and fallback mechanisms

State Management:

• Video playback state preservation during ads
• Volume/mute state synchronization
• Current time backup/restore
• Duration calculations (content vs. ad)

Platform Considerations:

• iOS MSE compatibility fixes
• Track element removal during ad breaks (iOS bug workaround)
• Responsive ad container sizing
• Picture-in-picture restrictions during ads

🎨 News Theme Addition

New Component: MuxNewsPlayer

• Playlist-based video player for news content
• Integrated ad support between playlist items
• Custom end screen with related videos
• Specialized styling for news/editorial use cases

📋 Examples & Documentation

Demo Pages Added:

• MuxPlayerAds.tsx - Interactive ad tag testing
• mux-video-ads-react.tsx - React video ads example
• MuxNewsPlayer.tsx - News player with playlist
• Vanilla JavaScript ads examples

Documentation:

• Comprehensive ads README with API reference
• Integration guides for React and vanilla JS
• Ad event handling examples
• Troubleshooting guides

🔍 Testing & Quality

Dependencies Added:

• @mux/mux-data-google-ima for analytics integration
• @types/google_interactive_media_ads_types for TypeScript support
• Google IMA SDK integration (external dependency)

Error Handling:

• Graceful degradation when IMA SDK unavailable
• Ad blocker detection with user feedback
• Comprehensive error event forwarding
• Fallback to content when ads fail

---

Summary: This is a major feature addition that successfully isolates ads functionality while maintaining backward compatibility. The mixin-based architecture allows for clean separation of concerns, and the comprehensive event system provides full observability into the ad playback lifecycle.

Scale: 51 commits, 56 files changed, 6,225 additions, 3,088 deletions - representing a significant enhancement to the Mux Elements ecosystem.

---