feat(ads): allow adsResponse for making ad request (#2946)

Fixes #2892

Author: DDeis

AUTHORS

@@ -21,6 +21,7 @@ Alvaro Velad Galvan <alvaro.velad@mirada.tv>
 Anthony Stansbridge <github@anthonystansbridge.co.uk>
 Bonnier Broadcasting <*@bonnierbroadcasting.com>
 Bryan Huh <bhh1988@gmail.com>
+Damien Deis <developer.deis@gmail.com>
 Esteban Dosztal <edosztal@gmail.com>
 Fadomire <fadomire@gmail.com>
 Google Inc. <*@google.com>

CONTRIBUTORS

@@ -34,6 +34,7 @@ Bryan Huh <bhh1988@gmail.com>
 Chad Assareh <assareh@google.com>
 Chris Fillmore <fillmore.chris@gmail.com>
 Costel Madalin Grecu <madalin.grecu@adswizz.com>
+Damien Deis <developer.deis@gmail.com>
 Donato Borrello <donato@jwplayer.com>
 Duc Pham <duc.pham@edgeware.tv>
 Esteban Dosztal <edosztal@gmail.com>

externs/ima.js

@@ -227,11 +227,19 @@ google.ima.AdEvent.Type = {
 
 /**
  * @typedef {{
- *   adTagUrl: string,
+ *   adsResponse: (string|undefined),
+ *   adTagUrl: (string|undefined),
  * }}
  *
  * @description Request for the ad server
- * @property {string} adTagUrl
+ * @property {string|undefined} adTagUrl
+ *   Specifies the ad tag url that is requested from the ad server.
+ *   This parameter is optional if adsReponse is given.
+ * @property {string|undefined} adsResponse
+ *   Specifies a VAST 2.0 document to be used as the ads response instead of
+ *   making a request via an ad tag url. This can be useful for debugging
+ *   and other situations where a VAST response is already available.
+ *   This parameter is optional if adTagUrl is given.
  * @exportDoc
  */
 google.ima.AdsRequest;

lib/ads/client_side_ad_manager.js

@@ -84,8 +84,10 @@ shaka.ads.ClientSideAdManager = class {
    * @param {!google.ima.AdsRequest} imaRequest
    */
   requestAds(imaRequest) {
-    goog.asserts.assert(imaRequest.adTagUrl.length,
-        'The ad tag needs to be set up before requesting ads.');
+    goog.asserts.assert(
+        imaRequest.adTagUrl || imaRequest.adsResponse,
+        'The ad tag needs to be set up before requesting ads, ' +
+          'or adsResponse must be filled.');
     this.requestAdsStartTime_ = Date.now() / 1000;
     this.adsLoader_.requestAds(imaRequest);
   }