feat(Ads): Allow the use of custom interstitials ads (#6991)

Author: avelad

externs/shaka/ads.js

@@ -57,6 +57,58 @@ shaka.extern.AdsStats;
 shaka.extern.AdCuePoint;
 
 
+/**
+ * @typedef {{
+ *   startTime: number,
+ *   endTime: ?number,
+ *   uri: string,
+ *   isSkippable: boolean,
+ *   canJump: boolean,
+ *   resumeOffset: ?number,
+ *   playoutLimit: ?number,
+ *   once: boolean,
+ *   pre: boolean,
+ *   post: boolean,
+ *   timelineRange: boolean
+ * }}
+ *
+ * @description
+ * Contains the ad interstitial info.
+ *
+ * @property {number} startTime
+ *   The start time of the interstitial.
+ * @property {?number} endTime
+ *   The end time of the interstitial.
+ * @property {string} uri
+ *   The uri of the interstitial, can be any type that
+ *   ShakaPlayer supports (either in MSE or src=)
+ * @property {boolean} isSkippable
+ *   Indicate if the interstitial is skippable.
+ * @property {boolean} canJump
+ *   Indicate if the interstitial is jumpable.
+ * @property {?number} resumeOffset
+ *   Indicates where the primary playback will resume after the interstitial
+ *   plays. It is expressed as a time lag from when interstitial playback was
+ *   scheduled on the primary player's timeline. For live ad replacement it
+ *   must be null.
+ * @property {?number} playoutLimit
+ *   Indicate a limit for the playout time of the entire interstitial.
+ * @property {boolean} once
+ *   Indicates that the interstitial should only be played once.
+ * @property {boolean} pre
+ *   Indicates that an action is to be triggered before playback of the
+ *   primary asset begins, regardless of where playback begins in the primary
+ *   asset.
+ * @property {boolean} post
+ *   Indicates that an action is to be triggered after the primary asset has
+ *   been played to its end without error.
+ * @property {boolean} timelineRange
+ *   Indicates whether the  interstitial should be presented in a timeline UI
+ *   as a single point or as a range.
+ */
+shaka.extern.AdInterstitial;
+
+
 /**
  * An object that's responsible for all the ad-related logic
  * in the player.
@@ -187,9 +239,14 @@ shaka.extern.IAdManager = class extends EventTarget {
   /**
    * @param {!shaka.Player} basePlayer
    * @param {!HTMLMediaElement} baseVideo
-   * @param {shaka.extern.Interstitial} interstitial
+   * @param {shaka.extern.HLSInterstitial} interstitial
+   */
+  onHLSInterstitialMetadata(basePlayer, baseVideo, interstitial) {}
+
+  /**
+   * @param {shaka.extern.AdInterstitial} interstitial
    */
-  onInterstitialMetadata(basePlayer, baseVideo, interstitial) {}
+  addCustomInterstitial(interstitial) {}
 };
 
 

externs/shaka/player.js

@@ -596,7 +596,7 @@ shaka.extern.MetadataFrame;
  * @property {!Array.<shaka.extern.MetadataFrame>} values
  * @exportDoc
  */
-shaka.extern.Interstitial;
+shaka.extern.HLSInterstitial;
 
 
 /**

lib/ads/ad_manager.js

@@ -823,7 +823,7 @@ shaka.ads.AdManager = class extends shaka.util.FakeEventTarget {
    * @override
    * @export
    */
-  onInterstitialMetadata(basePlayer, baseVideo, interstitial) {
+  onHLSInterstitialMetadata(basePlayer, baseVideo, interstitial) {
     if (!this.interstitialAdManager_) {
       this.initInterstitial(/* adContainer= */ null, basePlayer, baseVideo);
     }
@@ -832,6 +832,20 @@ shaka.ads.AdManager = class extends shaka.util.FakeEventTarget {
     }
   }
 
+  /**
+   * @override
+   * @export
+   */
+  addCustomInterstitial(interstitial) {
+    if (!this.interstitialAdManager_) {
+      throw new shaka.util.Error(
+          shaka.util.Error.Severity.RECOVERABLE,
+          shaka.util.Error.Category.ADS,
+          shaka.util.Error.Code.INTERSTITIAL_AD_MANAGER_NOT_INITIALIZED);
+    }
+    this.interstitialAdManager_.addInterstitials([interstitial]);
+  }
+
   /**
    * @param {!shaka.util.FakeEvent} event
    * @private

lib/ads/interstitial_ad_manager.js

@@ -61,11 +61,11 @@ shaka.ads.InterstitialAdManager = class {
     /** @private {!Set.<string>} */
     this.interstitialIds_ = new Set();
 
-    /** @private {!Set.<shaka.ads.InterstitialAdManager.Interstitial>} */
+    /** @private {!Set.<shaka.extern.AdInterstitial>} */
     this.interstitials_ = new Set();
 
     /**
-     * @private {!Map.<shaka.ads.InterstitialAdManager.Interstitial,
+     * @private {!Map.<shaka.extern.AdInterstitial,
      *                 Promise<?shaka.media.PreloadManager>>}
      */
     this.preloadManagerInterstitials_ = new Map();
@@ -204,48 +204,63 @@ shaka.ads.InterstitialAdManager = class {
 
 
   /**
-   * @param {shaka.extern.Interstitial} interstitial
+   * @param {shaka.extern.HLSInterstitial} hlsInterstitial
    */
-  async addMetadata(interstitial) {
+  async addMetadata(hlsInterstitial) {
     if (this.basePlayer_.getLoadMode() == shaka.Player.LoadMode.SRC_EQUALS &&
         this.usingBaseVideo_) {
       shaka.log.alwaysWarn(
-          'Unsupported interstitial when using single media element',
-          interstitial);
+          'Unsupported HLS interstitial when using single media element',
+          hlsInterstitial);
       return;
     }
     this.updatePlayerConfig_();
+    const adInterstitials = await this.getInterstitialsInfo_(hlsInterstitial);
+    if (adInterstitials.length) {
+      this.addInterstitials(adInterstitials);
+    } else {
+      shaka.log.alwaysWarn('Unsupported HLS interstitial', hlsInterstitial);
+    }
+  }
+
+
+  /**
+   * @param {!Array.<shaka.extern.AdInterstitial>} interstitials
+   */
+  addInterstitials(interstitials) {
+    if (this.basePlayer_.getLoadMode() == shaka.Player.LoadMode.SRC_EQUALS &&
+        this.usingBaseVideo_) {
+      shaka.log.alwaysWarn(
+          'Unsupported interstitial when using single media element',
+          interstitials);
+      return;
+    }
     let cuepointsChanged = false;
-    const interstitialsAd = await this.getInterstitialsInfo_(interstitial);
-    if (interstitialsAd.length) {
-      for (const interstitialAd of interstitialsAd) {
-        const interstitialId = JSON.stringify(interstitialAd);
-        if (this.interstitialIds_.has(interstitialId)) {
-          continue;
-        }
-        cuepointsChanged = true;
-        this.interstitialIds_.add(interstitialId);
-        this.interstitials_.add(interstitialAd);
-        let shouldPreload = false;
-        if (interstitial.pre && this.lastTime_ == null) {
-          shouldPreload = true;
-        } else if (interstitialAd.startTime == 0 && !interstitialAd.canJump) {
+    for (const interstitial of interstitials) {
+      const interstitialId = JSON.stringify(interstitial);
+      if (this.interstitialIds_.has(interstitialId)) {
+        continue;
+      }
+      cuepointsChanged = true;
+      this.interstitialIds_.add(interstitialId);
+      this.interstitials_.add(interstitial);
+      let shouldPreload = false;
+      if (interstitial.pre && this.lastTime_ == null) {
+        shouldPreload = true;
+      } else if (interstitial.startTime == 0 && !interstitial.canJump) {
+        shouldPreload = true;
+      } else if (this.lastTime_ != null) {
+        const difference = interstitial.startTime - this.lastTime_;
+        if (difference > 0 && difference <= 10) {
           shouldPreload = true;
-        } else if (this.lastTime_ != null) {
-          const difference = interstitial.startTime - this.lastTime_;
-          if (difference > 0 && difference <= 10) {
-            shouldPreload = true;
-          }
         }
-        if (shouldPreload) {
-          if (!this.preloadManagerInterstitials_.has(interstitialAd)) {
-            this.preloadManagerInterstitials_.set(
-                interstitialAd, this.player_.preload(interstitialAd.uri));
-          }
+      }
+      if (shouldPreload) {
+        if (!this.preloadManagerInterstitials_.has(interstitial)) {
+          this.preloadManagerInterstitials_.set(
+              interstitial, this.player_.preload(interstitial.uri));
         }
       }
-    } else {
-      shaka.log.alwaysWarn('Unsupported interstitial', interstitial);
     }
     if (cuepointsChanged) {
       this.cuepointsChanged_();
@@ -274,7 +289,7 @@ shaka.ads.InterstitialAdManager = class {
   /**
    * @param {boolean} needPreRoll
    * @param {number=} numberToSkip
-   * @return {?shaka.ads.InterstitialAdManager.Interstitial}
+   * @return {?shaka.extern.AdInterstitial}
    * @private
    */
   getCurrentInterstitial_(needPreRoll, numberToSkip = 0) {
@@ -314,7 +329,7 @@ shaka.ads.InterstitialAdManager = class {
 
 
   /**
-   * @param {shaka.ads.InterstitialAdManager.Interstitial} interstitial
+   * @param {shaka.extern.AdInterstitial} interstitial
    * @param {number} sequenceLength
    * @param {number} adPosition
    * @param {number} initialTime the clock time the ad started at
@@ -554,21 +569,22 @@ shaka.ads.InterstitialAdManager = class {
 
 
   /**
-   * @param {shaka.extern.Interstitial} interstitial
-   * @return {!Promise.<!Array.<shaka.ads.InterstitialAdManager.Interstitial>>}
+   * @param {shaka.extern.HLSInterstitial} hlsInterstitial
+   * @return {!Promise.<!Array.<shaka.extern.AdInterstitial>>}
    * @private
    */
-  async getInterstitialsInfo_(interstitial) {
+  async getInterstitialsInfo_(hlsInterstitial) {
     const interstitialsAd = [];
-    if (!interstitial) {
+    if (!hlsInterstitial) {
       return interstitialsAd;
     }
-    const assetUri = interstitial.values.find((v) => v.key == 'X-ASSET-URI');
-    const assetList = interstitial.values.find((v) => v.key == 'X-ASSET-LIST');
+    const assetUri = hlsInterstitial.values.find((v) => v.key == 'X-ASSET-URI');
+    const assetList =
+        hlsInterstitial.values.find((v) => v.key == 'X-ASSET-LIST');
     if (!assetUri && !assetList) {
       return interstitialsAd;
     }
-    const restrict = interstitial.values.find((v) => v.key == 'X-RESTRICT');
+    const restrict = hlsInterstitial.values.find((v) => v.key == 'X-RESTRICT');
     let isSkippable = true;
     let canJump = true;
     if (restrict && restrict.data) {
@@ -577,7 +593,8 @@ shaka.ads.InterstitialAdManager = class {
       canJump = !data.includes('JUMP');
     }
     let resumeOffset = null;
-    const resume = interstitial.values.find((v) => v.key == 'X-RESUME-OFFSET');
+    const resume =
+        hlsInterstitial.values.find((v) => v.key == 'X-RESUME-OFFSET');
     if (resume) {
       const resumeOffsetString = /** @type {string} */(resume.data);
       resumeOffset = parseFloat(resumeOffsetString);
@@ -586,7 +603,8 @@ shaka.ads.InterstitialAdManager = class {
       }
     }
     let playoutLimit = null;
-    const playout = interstitial.values.find((v) => v.key == 'X-PLAYOUT-LIMIT');
+    const playout =
+        hlsInterstitial.values.find((v) => v.key == 'X-PLAYOUT-LIMIT');
     if (playout) {
       const playoutLimitString = /** @type {string} */(playout.data);
       playoutLimit = parseFloat(playoutLimitString);
@@ -597,7 +615,7 @@ shaka.ads.InterstitialAdManager = class {
     let once = false;
     let pre = false;
     let post = false;
-    const cue = interstitial.values.find((v) => v.key == 'CUE');
+    const cue = hlsInterstitial.values.find((v) => v.key == 'CUE');
     if (cue) {
       const data = /** @type {string} */(cue.data);
       once = data.includes('ONCE');
@@ -606,7 +624,7 @@ shaka.ads.InterstitialAdManager = class {
     }
     let timelineRange = true;
     const timelineOccupies =
-        interstitial.values.find((v) => v.key == 'X-TIMELINE-OCCUPIES');
+        hlsInterstitial.values.find((v) => v.key == 'X-TIMELINE-OCCUPIES');
     if (timelineOccupies) {
       const data = /** @type {string} */(timelineOccupies.data);
       timelineRange = data.includes('RANGE');
@@ -619,8 +637,8 @@ shaka.ads.InterstitialAdManager = class {
         return interstitialsAd;
       }
       interstitialsAd.push({
-        startTime: interstitial.startTime,
-        endTime: interstitial.endTime,
+        startTime: hlsInterstitial.startTime,
+        endTime: hlsInterstitial.endTime,
         uri,
         isSkippable,
         canJump,
@@ -650,8 +668,8 @@ shaka.ads.InterstitialAdManager = class {
         for (const asset of dataAsJson.ASSETS) {
           if (asset.URI) {
             interstitialsAd.push({
-              startTime: interstitial.startTime,
-              endTime: interstitial.endTime,
+              startTime: hlsInterstitial.startTime,
+              endTime: hlsInterstitial.endTime,
               uri: asset.URI,
               isSkippable,
               canJump,
@@ -741,33 +759,3 @@ shaka.ads.InterstitialAdManager.AssetsList;
  * @property {string} URI
  */
 shaka.ads.InterstitialAdManager.Asset;
-
-
-/**
- * @typedef {{
- *   startTime: number,
- *   endTime: ?number,
- *   uri: string,
- *   isSkippable: boolean,
- *   canJump: boolean,
- *   resumeOffset: ?number,
- *   playoutLimit: ?number,
- *   once: boolean,
- *   pre: boolean,
- *   post: boolean,
- *   timelineRange: boolean
- * }}
- *
- * @property {number} startTime
- * @property {?number} endTime
- * @property {string} uri
- * @property {boolean} isSkippable
- * @property {boolean} canJump
- * @property {?number} resumeOffset
- * @property {?number} playoutLimit
- * @property {boolean} once
- * @property {boolean} pre
- * @property {boolean} post
- * @property {boolean} timelineRange
- */
-shaka.ads.InterstitialAdManager.Interstitial;