feat(Ads): Add double box format ad experience for Custom Overlay Int…

…erstitials (#8074)
shaka-project · Feb 13, 2025 · e344f5d · e344f5d
1 parent 2b8da99
commit e344f5d
Show file tree

Hide file tree

Showing 6 changed files with 275 additions and 52 deletions.
diff --git a/docs/tutorials/ad_monetization.md b/docs/tutorials/ad_monetization.md
@@ -116,7 +116,8 @@ adManager.addCustomInterstitial({
   loop: false,
   overlay: null,
   displayOnBackground: false,
-  percentageReductionOfCurrentVideo: null,
+  currentVideo: null,
+  background: null,
 });
 ```
 
@@ -156,14 +157,18 @@ player.addEventListener('timelineregionadded', (e) => {
     loop: false,
     overlay: null,
     displayOnBackground: false,
-    percentageReductionOfCurrentVideo: null,
+    currentVideo: null,
+    background: null,
   });
 });
 ```
 
 
 ##### Custom Overlay Interstitials
 
+Image, video (progressive or manifest) or website overlays are supported.
+
+
 Example:
 
 ```js
@@ -208,7 +213,130 @@ adManager.addCustomInterstitial({
     },
   },
   displayOnBackground: false,
-  percentageReductionOfCurrentVideo: null,
+  currentVideo: null,
+  background: null,
+});
+```
+
+Example of L-Shape format ad experience:
+```js
+const adManager = player.getAdManager();
+const video = document.getElementById('video');
+const ui = video['ui'];
+// If you're using a non-UI build, this is the div you'll need to create
+// for your layout.  The ad manager will clear this div, when it unloads, so
+// don't pass in a div that contains non-ad elements.
+const container = video.ui.getControls().getClientSideAdContainer();
+adManager.initInterstitial(container, player, video);
+adManager.addCustomInterstitial({
+  id: null,
+  groupId: null,
+  startTime: 10,
+  endTime: null,
+  uri: 'YOUR_URL',
+  mimeType: null,
+  isSkippable: true,
+  skipOffset: 10,
+  skipFor: null,
+  canJump: false,
+  resumeOffset: null,
+  playoutLimit: null,
+  once: true,
+  pre: false,
+  post: false,
+  timelineRange: false,
+  loop: false,
+  overlay: {
+    viewport: {
+      x: 1920,
+      y: 1080,
+    },
+    topLeft: {
+      x: 0,
+      y: 0,
+    },
+    size: {
+      x: 1920,
+      y: 1080,
+    },
+  },
+  displayOnBackground: true,
+  currentVideo: {
+    viewport: {
+      x: 1920,
+      y: 1080,
+    },
+    topLeft: {
+      x: 0,
+      y: 0,
+    },
+    size: {
+      x: 960,
+      y: 540,
+    },
+  },
+  background: null,
+});
+```
+
+Example of double box format ad experience:
+```js
+const adManager = player.getAdManager();
+const video = document.getElementById('video');
+const ui = video['ui'];
+// If you're using a non-UI build, this is the div you'll need to create
+// for your layout.  The ad manager will clear this div, when it unloads, so
+// don't pass in a div that contains non-ad elements.
+const container = video.ui.getControls().getClientSideAdContainer();
+adManager.initInterstitial(container, player, video);
+adManager.addCustomInterstitial({
+  id: null,
+  groupId: null,
+  startTime: 10,
+  endTime: null,
+  uri: 'YOUR_URL',
+  mimeType: null,
+  isSkippable: true,
+  skipOffset: 10,
+  skipFor: null,
+  canJump: false,
+  resumeOffset: null,
+  playoutLimit: null,
+  once: true,
+  pre: false,
+  post: false,
+  timelineRange: false,
+  loop: false,
+  overlay: {
+    viewport: {
+      x: 1920, // Pixels
+      y: 1080, // Pixels
+    },
+    topLeft: {
+      x: 960, // Pixels
+      y: 270, // Pixels
+    },
+    size: {
+      x: 960, // Pixels
+      y: 540, // Pixels
+    },
+  },
+  displayOnBackground: true,
+  currentVideo: {
+    viewport: {
+      x: 1920, // Pixels
+      y: 1080, // Pixels
+    },
+    topLeft: {
+      x: 160, // Pixels
+      y: 360, // Pixels
+    },
+    size: {
+      x: 640, // Pixels
+      y: 360, // Pixels
+    },
+  },
+  background: 'content-box radial-gradient(crimson, skyblue)',
 });
 ```
 

diff --git a/externs/shaka/ads.js b/externs/shaka/ads.js
@@ -79,9 +79,10 @@ shaka.extern.AdCuePoint;
  *   post: boolean,
  *   timelineRange: boolean,
  *   loop: boolean,
- *   overlay: ?shaka.extern.AdInterstitialOverlay,
+ *   overlay: ?shaka.extern.AdPositionInfo,
  *   displayOnBackground: boolean,
- *   percentageReductionOfCurrentVideo: ?number
+ *   currentVideo: ?shaka.extern.AdPositionInfo,
+ *   background: ?string
  * }}
  *
  * @description
@@ -133,13 +134,17 @@ shaka.extern.AdCuePoint;
  *   Indicates that the interstitials should play in loop.
  *   Only applies if the interstitials is an overlay.
  *   Only supported when using multiple video elements for interstitials.
- * @property {?shaka.extern.AdInterstitialOverlay} overlay
+ * @property {?shaka.extern.AdPositionInfo} overlay
  *   Indicates the characteristics of the overlay
  *   Only supported when using multiple video elements for interstitials.
  * @property {boolean} displayOnBackground
  *   Indicates if we should display on background, shrinking the current video.
- * @property {?number} percentageReductionOfCurrentVideo
- *   Indicates the percentage reduction of current video if applies.
+ * @property {?shaka.extern.AdPositionInfo} currentVideo
+ *   Indicates the characteristics of the current video.
+ *   Only set if any feature changes.
+ * @property {?string} background
+ *   Specifies the background, the value can be any value of the CSS background
+ *   property.
  * @exportDoc
  */
 shaka.extern.AdInterstitial;
@@ -153,7 +158,7 @@ shaka.extern.AdInterstitial;
  * }}
  *
  * @description
- * Contains the ad interstitial overlay info.
+ * Contains the coordinates of a position info
  *
  * @property {{x: number, y: number}} viewport
  *   The viewport in pixels.
@@ -163,7 +168,7 @@ shaka.extern.AdInterstitial;
  *   The size in pixels.
  * @exportDoc
  */
-shaka.extern.AdInterstitialOverlay;
+shaka.extern.AdPositionInfo;
 
 
 /**

diff --git a/lib/ads/ad_utils.js b/lib/ads/ad_utils.js
@@ -119,7 +119,8 @@ shaka.ads.Utils = class {
         loop: false,
         overlay: null,
         displayOnBackground: false,
-        percentageReductionOfCurrentVideo: null,
+        currentVideo: null,
+        background: null,
       });
       break;
     }
@@ -201,7 +202,8 @@ shaka.ads.Utils = class {
         },
       },
       displayOnBackground: false,
-      percentageReductionOfCurrentVideo: null,
+      currentVideo: null,
+      background: null,
     });
   }
 

diff --git a/lib/ads/interstitial_ad.js b/lib/ads/interstitial_ad.js
@@ -50,7 +50,7 @@ shaka.ads.InterstitialAd = class {
     /** @private {boolean} */
     this.isUsingAnotherMediaElement_ = isUsingAnotherMediaElement;
 
-    /** @private {?shaka.extern.AdInterstitialOverlay} */
+    /** @private {?shaka.extern.AdPositionInfo} */
     this.overlay_ = interstitial.overlay;
   }