feat: add adblocker bypass option, expose player props, and conditional captions menu (#1127)

ronalduQualabs · luwes · commit a1005fbe3d67 · 2025-06-03T11:46:40.000-06:00
This PR introduces the following improvements:
	•	New `allowPlaybackWithAdBlocker` prop
Allows the player to continue playback even when an adblocker is
detected.
• If false (default): shows a blocking popup when an adblocker is
present.
	  •	If true: bypasses the restriction and allows normal playback.
	•	Exposes underlying player props on MuxNewsPlayer
Enables more granular configuration and control over the embedded player
through MuxNewsPlayer.
	•	Conditional captions menu
Adds a captions menu that appears only when text tracks are available.
	•	Allows users to disable captions if they prefer not to see them.
diff --git a/examples/nextjs-with-typescript/pages/MuxPlayerAds.tsx b/examples/nextjs-with-typescript/pages/MuxPlayerAds.tsx
@@ -66,6 +66,8 @@ function MuxPlayerAdsPage() {
           video_title: "Elephants Dream",
           viewer_user_id: "user-id-6789",
         }}
+        // allow playback with ad blocker
+        allowAdBlocker={true}
         streamType="on-demand"
         // envKey="mux-data-env-key"
         autoPlay={autoplay}
diff --git a/examples/nextjs-with-typescript/pages/mux-video-ads-react.tsx b/examples/nextjs-with-typescript/pages/mux-video-ads-react.tsx
@@ -47,6 +47,9 @@ function MuxVideoPage() {
         setSdkLoaded(true);  // Mark SDK as loaded
         console.log("Google IMA SDK loaded");
       };
+      script.onerror = () => {
+        setSdkLoaded(true);
+      };
       document.head.appendChild(script);
     };
     
@@ -75,6 +78,8 @@ function MuxVideoPage() {
         ref={mediaElRef}
         playbackId="23s11nz72DsoN657h4314PjKKjsF2JG33eBQQt6B95I"
         controls
+        // allow playback with ad blocker
+        allowAdBlocker={true}
         autoplay={autoplay}
         muted={muted}
         playsInline={true}
diff --git a/examples/nextjs-with-typescript/pages/playlist-page.tsx b/examples/nextjs-with-typescript/pages/playlist-page.tsx
@@ -16,6 +16,9 @@ function MuxVideoPage() {
         setSdkLoaded(true);  // Mark SDK as loaded
         console.log("Google IMA SDK loaded");
       };
+      script.onerror = () => {
+        setSdkLoaded(true);
+      };
       document.head.appendChild(script);
     };
 
@@ -58,11 +61,15 @@ function MuxVideoPage() {
   return (
     <>
       <Head>
-        <title>&lt;Playlist/&gt; Demo</title>
+        <title>&lt;Playlist/&gt; Demo 3</title>
       </Head>
       
-      {sdkLoaded && <MuxNewsPlayer videoList={relatedVideos} />}
-
+      {sdkLoaded && 
+        <MuxNewsPlayer 
+          // allow playback with ad blocker
+          allowAdBlocker={true}
+          videoList={relatedVideos} 
+        />}
     </>
   );
 }
diff --git a/packages/mux-player-react/src/index.tsx b/packages/mux-player-react/src/index.tsx
@@ -71,6 +71,7 @@ type MuxMediaPropTypes = {
 };
 
 export type MuxPlayerProps = {
+  allowAdBlocker?: boolean;
   className?: string;
   hotkeys?: string;
   nohotkeys?: boolean;
diff --git a/packages/mux-player-react/src/news/README.md b/packages/mux-player-react/src/news/README.md
@@ -64,6 +64,9 @@ export default function YourComponent() {
         setSdkLoaded(true);
         console.log("Google IMA SDK loaded");
       };
+      script.onerror = () => {
+        setSdkLoaded(true);
+      };
       document.head.appendChild(script);
     };
 
@@ -143,6 +146,9 @@ export default function VideoMuxNewsPlayerPage() {
         setSdkLoaded(true);
         console.log("Google IMA SDK loaded");
       };
+      script.onerror = () => {
+        setSdkLoaded(true);
+      };
       document.head.appendChild(script);
     };
 
diff --git a/packages/mux-player-react/src/news/index.tsx b/packages/mux-player-react/src/news/index.tsx
@@ -2,6 +2,8 @@
 /// <reference types="google_interactive_media_ads_types" preserve="true"/>
 import React, { useRef, useState } from 'react';
 import '@mux/mux-video/ads';
+import type { MuxPlayerProps } from '@mux/mux-player-react';
+import '@mux/mux-video-ads';
 import MuxPlayer from '@mux/mux-player-react';
 import NewsTheme from '../themes/news-theme';
 import PlaylistEndScreen from './playlist-end-screen';
@@ -15,11 +17,12 @@ export interface VideoItem {
 
 export type PlaylistVideos = VideoItem[];
 
-export interface PlaylistProps {
+export interface PlaylistProps extends Omit<MuxPlayerProps, 'playbackId' | 'adTagUrl'> {
   videoList: PlaylistVideos;
+  allowAdBlocker?: boolean;
 }
 
-const MuxNewsPlayer = ({ videoList, ...props }: PlaylistProps) => {
+const MuxNewsPlayer = ({ allowAdBlocker, videoList, ...props }: PlaylistProps) => {
   const mediaElRef = useRef<any>(null);
   const [currentIndex, setCurrentIndex] = useState(0);
   const [isEndScreenVisible, setIsEndScreenVisible] = useState(false);
@@ -45,6 +48,8 @@ const MuxNewsPlayer = ({ videoList, ...props }: PlaylistProps) => {
     <div>
       <NewsTheme />
       <MuxPlayer
+        {...props}
+        allowAdBlocker={allowAdBlocker}
         ref={mediaElRef}
         theme="news-theme"
         key={`player-${playerKey}`}
diff --git a/packages/mux-player-react/src/themes/news-theme.tsx b/packages/mux-player-react/src/themes/news-theme.tsx
@@ -102,7 +102,7 @@ export default function NewsTheme() {
 
   <!-- Rendition Menu -->
   <style>
-    media-rendition-menu {
+    media-rendition-menu, media-captions-menu {
       position: absolute;
       border-radius: 0.3rem;
       right: 12px;
@@ -149,7 +149,7 @@ export default function NewsTheme() {
 
   <media-rendition-menu anchor="auto" hidden>
   </media-rendition-menu>
-
+  <media-captions-menu hidden anchor="auto"></media-captions-menu>
   <!-- Time Range / Progress Bar -->
 
   <style>
@@ -496,6 +496,7 @@ export default function NewsTheme() {
       </svg>
 
     </media-rendition-menu-button>
+    <media-captions-menu-button></media-captions-menu-button>
     </template>
 
     <!-- Fullscreen Button -->
@@ -584,7 +585,6 @@ export default function NewsTheme() {
         </g>
       </svg>
     </media-fullscreen-button>
-
   </media-control-bar>`,
         }}
       />
diff --git a/packages/mux-player/src/index.ts b/packages/mux-player/src/index.ts
@@ -186,6 +186,7 @@ function getProps(el: MuxPlayerElement, state?: any): MuxTemplateProps {
     // NOTE: since the attribute value is used as the "source of truth" for the property getter,
     // moving this below the `...state` spread so it resolves to the default value when unset (CJP)
     extraSourceParams: el.extraSourceParams,
+    allowAdBlocker: el.getAttribute('allow-ad-blocker'),
   };
 
   return props;
@@ -342,6 +343,7 @@ class MuxPlayerElement extends VideoApiElement implements MuxPlayerElement {
       if (!isFocusedElementInPlayer) event.preventDefault();
     },
   };
+  allowAdBlocker: any;
 
   static get NAME() {
     return playerSoftwareName;
diff --git a/packages/mux-player/src/template.ts b/packages/mux-player/src/template.ts
@@ -136,6 +136,7 @@ export const content = (props: MuxTemplateProps) => html`
       cast-receiver="${props.castReceiver ?? false}"
       drm-token="${props.tokens?.drm ?? false}"
       ad-tag-url="${props.adTagUrl ?? false}"
+      allow-ad-blocker="${props.allowAdBlocker ?? false}"
       exportparts="video"
     >
       ${props.storyboard
diff --git a/packages/mux-player/src/types.d.ts b/packages/mux-player/src/types.d.ts
@@ -59,6 +59,7 @@ export type MuxTemplateProps = Partial<MuxPlayerProps> & {
   proudlyDisplayMuxBadge?: boolean;
   adTagUrl: string | undefined;
   adBreak: boolean;
+  allowAdBlocker?: boolean;
 };
 
 export type DialogOptions = {
diff --git a/packages/mux-video/src/ads/mixin.ts b/packages/mux-video/src/ads/mixin.ts
@@ -10,6 +10,7 @@ import type { CustomVideoElement } from 'custom-media-element';
 export const Attributes = {
   AD_TAG_URL: 'ad-tag-url',
   AD_BREAK: 'ad-break',
+  ALLOW_AD_BLOCKER: 'allow-ad-blocker',
 } as const;
 
 export declare class AdsVideoInterface {
@@ -38,6 +39,7 @@ export function AdsVideoMixin<T extends CustomVideoElement>(superclass: T): Cons
             height: 100%;
             display: block;
           }
+
           video {
             display: block;
             max-width: 100%;
@@ -47,15 +49,18 @@ export function AdsVideoMixin<T extends CustomVideoElement>(superclass: T): Cons
             object-fit: var(--media-object-fit, contain);
             object-position: var(--media-object-position, 50% 50%);
           }
+
           video::-webkit-media-text-track-container {
             transform: var(--media-webkit-text-track-transform);
             transition: var(--media-webkit-text-track-transition);
           }
+
           #mainContainer {
               position: relative;
               width: 100%;
               height: 100%;
           }
+
           #adContainer {
               position: absolute;
               top: 0px;
@@ -66,24 +71,31 @@ export function AdsVideoMixin<T extends CustomVideoElement>(superclass: T): Cons
               width: 100%;
               height: 100%;
           }
+
           #mainContainer #adContainer.ad-playing {
-              z-index: 2;
+            z-index: 2;
           }
+
           #imaUnavailableMessage {
             position: absolute;
-            top: 40%;
-            left: 50%;
-            transform: translateX(-50%);
+            top: 0;
+            left: 0;
             z-index: 10;
             background: rgba(0, 0, 0, 0.75);
             color: white;
-            padding: 1em 1.5em;
-            border-radius: 6px;
             font-size: 0.9em;
             text-align: center;
-            max-width: 90%;
             line-height: 1.4;
-            box-shadow: 0 4px 12px rgba(0,0,0,0.5);
+            width: 100%;
+            height: 100%;
+            align-items: center;
+            align-content: center;
+            cursor: not-allowed;
+          }
+
+          #imaUnavailableMessage h4 {
+            font-size: 1rem;
+            margin: 0;
           }
         </style>
         <div id="mainContainer">
@@ -115,7 +127,11 @@ export function AdsVideoMixin<T extends CustomVideoElement>(superclass: T): Cons
 
       if (!GoogleImaAdsProvider.isGoogleImaSDKAvailable()) {
         console.error('Missing google.ima SDK. Make sure you include it via a script tag.');
-        this.#showAdBlockedMessage();
+        if (!this.allowAdBlocker) {
+          this.#showAdBlockedMessage();
+        } else {
+          this.#adBreak = false;
+        }
         return;
       }
 
@@ -136,7 +152,7 @@ export function AdsVideoMixin<T extends CustomVideoElement>(superclass: T): Cons
       const fallback = document.createElement('div');
       fallback.id = 'imaUnavailableMessage';
       fallback.innerHTML = `
-        <strong>Ad experience unavailable.</strong><br />
+        <h4>Ad experience unavailable.</h4>
         <span>This may be due to a missing SDK, network issue, or ad blocker.</span>
       `;
       this.shadowRoot?.getElementById('mainContainer')?.appendChild(fallback);
@@ -258,7 +274,10 @@ export function AdsVideoMixin<T extends CustomVideoElement>(superclass: T): Cons
         return Promise.resolve();
       }
 
-      if (this.adTagUrl) {
+      const adBlockerDetected = !this.#adProvider?.adsLoader;
+      const adBlockerAndAllowed = adBlockerDetected && this.allowAdBlocker;
+
+      if (this.adTagUrl && !adBlockerAndAllowed) {
         this.#lastCurrentime = this.nativeEl.currentTime;
         this.#adBreak = true;
         this.dispatchEvent(new Event('durationchange'));
@@ -385,6 +404,14 @@ export function AdsVideoMixin<T extends CustomVideoElement>(superclass: T): Cons
     get muxDataKeepSession(): boolean {
       return this.hasAttribute('mux-data-keep-session');
     }
+
+    get allowAdBlocker(): boolean {
+      return this.hasAttribute(Attributes.ALLOW_AD_BLOCKER);
+    }
+
+    set allowAdBlocker(val: boolean) {
+      this.toggleAttribute(Attributes.ALLOW_AD_BLOCKER, !!val);
+    }
   }
   return AdsVideo as unknown as Constructor<AdsVideoInterface> & T;
 }

Original file line number	Diff line number	Diff line change
@@ -136,6 +136,7 @@ export const content = (props: MuxTemplateProps) => html`
`136`	`136`	`cast-receiver="${props.castReceiver ?? false}"`
`137`	`137`	`drm-token="${props.tokens?.drm ?? false}"`
`138`	`138`	`ad-tag-url="${props.adTagUrl ?? false}"`
	`139`	`+ allow-ad-blocker="${props.allowAdBlocker ?? false}"`
`139`	`140`	`exportparts="video"`
`140`	`141`	`>`
`141`	`142`	`${props.storyboard`