[interactive_media_ads]: Adds additional methods to configure ad requests

packages/interactive_media_ads/CHANGELOG.md

@@ -1,3 +1,7 @@
+## 0.2.6
+
+* Adds support to configure ad requests. See `AdsRequest`.
+
 ## 0.2.5+1
 
 * Adds remaining methods for internal wrapper of the Android native `AdsRequest`.

packages/interactive_media_ads/android/src/main/kotlin/dev/flutter/packages/interactive_media_ads/AdsRequestProxyApi.kt

@@ -21,7 +21,7 @@ class AdsRequestProxyApi(override val pigeonRegistrar: ProxyApiRegistrar) :
      *
      * This must match the version in pubspec.yaml.
      */
-    const val pluginVersion = "0.2.5+1"
+    const val pluginVersion = "0.2.6"
   }
 
   override fun setAdTagUrl(pigeon_instance: AdsRequest, adTagUrl: String) {

packages/interactive_media_ads/ios/interactive_media_ads/Sources/interactive_media_ads/AdsRequestProxyAPIDelegate.swift

@@ -13,7 +13,7 @@ class AdsRequestProxyAPIDelegate: PigeonApiDelegateIMAAdsRequest {
   /// The current version of the `interactive_media_ads` plugin.
   ///
   /// This must match the version in pubspec.yaml.
-  static let pluginVersion = "0.2.5+1"
+  static let pluginVersion = "0.2.6"
 
   func pigeonDefaultConstructor(
     pigeonApi: PigeonApiIMAAdsRequest, adTagUrl: String, adDisplayContainer: IMAAdDisplayContainer,

packages/interactive_media_ads/lib/src/ads_request.dart

@@ -7,14 +7,57 @@ import 'platform_interface/platform_interface.dart';
 
 /// An object containing the data used to request ads from the server.
 class AdsRequest {
-  /// Creates an [AdsRequest].
+  /// Creates an [AdsRequest] with the given ad tag URL.
   AdsRequest({
     required String adTagUrl,
     ContentProgressProvider? contentProgressProvider,
+    bool? adWillAutoPlay,
+    bool? adWillPlayMuted,
+    bool? continuousPlayback,
+    Duration? contentDuration,
+    List<String>? contentKeywords,
+    String? contentTitle,
+    Duration? liveStreamPrefetchMaxWaitTime,
+    Duration? vastLoadTimeout,
   }) : this.fromPlatform(
-          PlatformAdsRequest(
+          PlatformAdsRequest.withAdTagUrl(
             adTagUrl: adTagUrl,
             contentProgressProvider: contentProgressProvider?.platform,
+            adWillAutoPlay: adWillAutoPlay,
+            adWillPlayMuted: adWillPlayMuted,
+            continuousPlayback: continuousPlayback,
+            contentDuration: contentDuration,
+            contentKeywords: contentKeywords,
+            contentTitle: contentTitle,
+            liveStreamPrefetchMaxWaitTime: liveStreamPrefetchMaxWaitTime,
+            vastLoadTimeout: vastLoadTimeout,
+          ),
+        );
+
+  /// Creates an [AdsRequest] with the given canned ads response.
+  AdsRequest.withAdsResponse({
+    required String adsResponse,
+    ContentProgressProvider? contentProgressProvider,
+    bool? adWillAutoPlay,
+    bool? adWillPlayMuted,
+    bool? continuousPlayback,
+    Duration? contentDuration,
+    List<String>? contentKeywords,
+    String? contentTitle,
+    Duration? liveStreamPrefetchMaxWaitTime,
+    Duration? vastLoadTimeout,
+  }) : this.fromPlatform(
+          PlatformAdsRequest.withAdsResponse(
+            adsResponse: adsResponse,
+            contentProgressProvider: contentProgressProvider?.platform,
+            adWillAutoPlay: adWillAutoPlay,
+            adWillPlayMuted: adWillPlayMuted,
+            continuousPlayback: continuousPlayback,
+            contentDuration: contentDuration,
+            contentKeywords: contentKeywords,
+            contentTitle: contentTitle,
+            liveStreamPrefetchMaxWaitTime: liveStreamPrefetchMaxWaitTime,
+            vastLoadTimeout: vastLoadTimeout,
           ),
         );
 
@@ -25,7 +68,20 @@ class AdsRequest {
   final PlatformAdsRequest platform;
 
   /// The URL from which ads will be requested.
-  String get adTagUrl => platform.adTagUrl;
+  String get adTagUrl => switch (platform) {
+        final PlatformAdsRequestWithAdTagUrl request => request.adTagUrl,
+        // TODO(bparrishMines): This returns an empty string rather than null
+        // to prevent a breaking change. This should be updated to return null
+        // on the next major release.
+        PlatformAdsRequestWithAdsResponse() => '',
+      };
+
+  /// Specifies a VAST, VMAP, or ad rules response to be used instead of making
+  /// a request through an ad tag URL.
+  String? get adsResponse => switch (platform) {
+        final PlatformAdsRequestWithAdsResponse request => request.adsResponse,
+        PlatformAdsRequestWithAdTagUrl() => null,
+      };
 
   /// A [ContentProgressProvider] instance to allow scheduling of ad breaks
   /// based on content progress (cue points).
@@ -34,4 +90,33 @@ class AdsRequest {
           null
       ? ContentProgressProvider.fromPlatform(platform.contentProgressProvider!)
       : null;
+
+  /// Notifies the SDK whether the player intends to start the content and ad in
+  /// response to a user action or whether it will be automatically played.
+  bool? get adWillAutoPlay => platform.adWillAutoPlay;
+
+  /// Notifies the SDK whether the player intends to start the content and ad
+  /// while muted.
+  bool? get adWillPlayMuted => platform.adWillPlayMuted;
+
+  /// Notifies the SDK whether the player intends to continuously play the
+  /// content videos one after another similar to TV broadcast.
+  bool? get continuousPlayback => platform.continuousPlayback;
+
+  /// Specifies the duration of the content to be shown.
+  Duration? get contentDuration => platform.contentDuration;
+
+  /// Specifies the keywords used to describe the content to be shown.
+  List<String>? get contentKeywords => platform.contentKeywords;
+
+  /// Specifies the title of the content to be shown.
+  String? get contentTitle => platform.contentTitle;
+
+  /// Specifies the maximum amount of time to wait, after calling requestAds,
+  /// before requesting the ad tag URL.
+  Duration? get liveStreamPrefetchMaxWaitTime =>
+      platform.liveStreamPrefetchMaxWaitTime;
+
+  /// Specifies the VAST load timeout in milliseconds for a single wrapper.
+  Duration? get vastLoadTimeout => platform.vastLoadTimeout;
 }

packages/interactive_media_ads/lib/src/android/android_ads_loader.dart

@@ -89,10 +89,36 @@ base class AndroidAdsLoader extends PlatformAdsLoader {
     final ima.AdsRequest androidRequest = await _sdkFactory.createAdsRequest();
 
     await Future.wait(<Future<void>>[
-      androidRequest.setAdTagUrl(request.adTagUrl),
-      if (request.contentProgressProvider != null)
+      if (request case final PlatformAdsRequestWithAdTagUrl request)
+        androidRequest.setAdTagUrl(request.adTagUrl),
+      if (request case final PlatformAdsRequestWithAdsResponse request)
+        androidRequest.setAdTagUrl(request.adsResponse),
+      if (request.adWillAutoPlay case final bool adWillAutoPlay)
+        androidRequest.setAdWillAutoPlay(adWillAutoPlay),
+      if (request.adWillPlayMuted case final bool adWillPlayMuted)
+        androidRequest.setAdWillPlayMuted(adWillPlayMuted),
+      if (request.continuousPlayback case final bool continuousPlayback)
+        androidRequest.setContinuousPlayback(continuousPlayback),
+      if (request.contentDuration case final Duration contentDuration)
+        androidRequest.setContentDuration(
+            contentDuration.inMilliseconds / Duration.millisecondsPerSecond),
+      if (request.contentKeywords case final List<String> contentKeywords)
+        androidRequest.setContentKeywords(contentKeywords),
+      if (request.contentTitle case final String contentTitle)
+        androidRequest.setContentTitle(contentTitle),
+      if (request.liveStreamPrefetchMaxWaitTime
+          case final Duration liveStreamPrefetchMaxWaitTime)
+        androidRequest.setLiveStreamPrefetchSeconds(
+          liveStreamPrefetchMaxWaitTime.inMilliseconds /
+              Duration.millisecondsPerSecond,
+        ),
+      if (request.vastLoadTimeout case final Duration vastLoadTimeout)
+        androidRequest
+            .setVastLoadTimeout(vastLoadTimeout.inMilliseconds.toDouble()),
+      if (request.contentProgressProvider
+          case final PlatformContentProgressProvider contentProgressProvider)
         androidRequest.setContentProgressProvider(
-          (request.contentProgressProvider! as AndroidContentProgressProvider)
+          (contentProgressProvider as AndroidContentProgressProvider)
               .progressProvider,
         ),
       adsLoader.requestAds(androidRequest),

packages/interactive_media_ads/lib/src/ios/ios_ads_loader.dart

@@ -73,16 +73,55 @@ base class IOSAdsLoader extends PlatformAdsLoader {
   }
 
   @override
-  Future<void> requestAds(PlatformAdsRequest request) async {
-    return _adsLoader.requestAds(_iosParams._proxy.newIMAAdsRequest(
-      adTagUrl: request.adTagUrl,
-      adDisplayContainer:
-          (_iosParams.container as IOSAdDisplayContainer).adDisplayContainer!,
-      contentPlayhead: request.contentProgressProvider != null
-          ? (request.contentProgressProvider! as IOSContentProgressProvider)
-              .contentPlayhead
-          : null,
-    ));
+  Future<void> requestAds(PlatformAdsRequest request) {
+    final IMAAdDisplayContainer adDisplayContainer =
+        (_iosParams.container as IOSAdDisplayContainer).adDisplayContainer!;
+    final IMAContentPlayhead? contentProgressProvider =
+        request.contentProgressProvider != null
+            ? (request.contentProgressProvider! as IOSContentProgressProvider)
+                .contentPlayhead
+            : null;
+
+    final IMAAdsRequest adsRequest = switch (request) {
+      final PlatformAdsRequestWithAdTagUrl request => IMAAdsRequest(
+          adTagUrl: request.adTagUrl,
+          adDisplayContainer: adDisplayContainer,
+          contentPlayhead: contentProgressProvider,
+        ),
+      PlatformAdsRequestWithAdsResponse() => IMAAdsRequest.withAdsResponse(
+          adsResponse: request.adsResponse,
+          adDisplayContainer: adDisplayContainer,
+          contentPlayhead: contentProgressProvider,
+        ),
+    };
+
+    return Future.wait(<Future<void>>[
+      if (request.adWillAutoPlay case final bool adWillAutoPlay)
+        adsRequest.setAdWillAutoPlay(adWillAutoPlay),
+      if (request.adWillPlayMuted case final bool adWillPlayMuted)
+        adsRequest.setAdWillPlayMuted(adWillPlayMuted),
+      if (request.continuousPlayback case final bool continuousPlayback)
+        adsRequest.setContinuousPlayback(continuousPlayback),
+      if (request.contentDuration case final Duration contentDuration)
+        adsRequest.setContentDuration(
+          contentDuration.inMilliseconds / Duration.millisecondsPerSecond,
+        ),
+      if (request.contentKeywords case final List<String> contentKeywords)
+        adsRequest.setContentKeywords(contentKeywords),
+      if (request.contentTitle case final String contentTitle)
+        adsRequest.setContentTitle(contentTitle),
+      if (request.liveStreamPrefetchMaxWaitTime
+          case final Duration liveStreamPrefetchMaxWaitTime)
+        adsRequest.setLiveStreamPrefetchSeconds(
+          liveStreamPrefetchMaxWaitTime.inMilliseconds /
+              Duration.millisecondsPerSecond,
+        ),
+      if (request.vastLoadTimeout case final Duration vastLoadTimeout)
+        adsRequest.setVastLoadTimeout(
+          vastLoadTimeout.inMilliseconds.toDouble(),
+        ),
+      _adsLoader.requestAds(adsRequest),
+    ]);
   }
 
   // This value is created in a static method because the callback methods for

packages/interactive_media_ads/lib/src/platform_interface/platform_ads_request.dart

@@ -5,17 +5,143 @@
 import 'platform_content_progress_provider.dart';
 
 /// An object containing the data used to request ads from the server.
-class PlatformAdsRequest {
-  /// Creates an [PlatformAdsRequest].
-  PlatformAdsRequest({
-    required this.adTagUrl,
+sealed class PlatformAdsRequest {
+  PlatformAdsRequest._({
     this.contentProgressProvider,
+    this.adWillAutoPlay,
+    this.adWillPlayMuted,
+    this.continuousPlayback,
+    this.contentDuration,
+    this.contentKeywords,
+    this.contentTitle,
+    this.liveStreamPrefetchMaxWaitTime,
+    this.vastLoadTimeout,
   });
 
-  /// The URL from which ads will be requested.
-  final String adTagUrl;
+  /// Creates a [PlatformAdsRequest] with the given ad tag URL.
+  factory PlatformAdsRequest.withAdTagUrl({
+    required String adTagUrl,
+    PlatformContentProgressProvider? contentProgressProvider,
+    bool? adWillAutoPlay,
+    bool? adWillPlayMuted,
+    bool? continuousPlayback,
+    Duration? contentDuration,
+    List<String>? contentKeywords,
+    String? contentTitle,
+    Duration? liveStreamPrefetchMaxWaitTime,
+    Duration? vastLoadTimeout,
+  }) =>
+      PlatformAdsRequestWithAdTagUrl._(
+        adTagUrl: adTagUrl,
+        contentProgressProvider: contentProgressProvider,
+        adWillAutoPlay: adWillAutoPlay,
+        adWillPlayMuted: adWillPlayMuted,
+        continuousPlayback: continuousPlayback,
+        contentDuration: contentDuration,
+        contentKeywords: contentKeywords,
+        contentTitle: contentTitle,
+        liveStreamPrefetchMaxWaitTime: liveStreamPrefetchMaxWaitTime,
+        vastLoadTimeout: vastLoadTimeout,
+      );
+
+  /// Creates a [PlatformAdsRequest] with the given canned ads response.
+  factory PlatformAdsRequest.withAdsResponse({
+    required String adsResponse,
+    PlatformContentProgressProvider? contentProgressProvider,
+    bool? adWillAutoPlay,
+    bool? adWillPlayMuted,
+    bool? continuousPlayback,
+    Duration? contentDuration,
+    List<String>? contentKeywords,
+    String? contentTitle,
+    Duration? liveStreamPrefetchMaxWaitTime,
+    Duration? vastLoadTimeout,
+  }) =>
+      PlatformAdsRequestWithAdsResponse._(
+        adsResponse: adsResponse,
+        contentProgressProvider: contentProgressProvider,
+        adWillAutoPlay: adWillAutoPlay,
+        adWillPlayMuted: adWillPlayMuted,
+        continuousPlayback: continuousPlayback,
+        contentDuration: contentDuration,
+        contentKeywords: contentKeywords,
+        contentTitle: contentTitle,
+        liveStreamPrefetchMaxWaitTime: liveStreamPrefetchMaxWaitTime,
+        vastLoadTimeout: vastLoadTimeout,
+      );
 
   /// A [PlatformContentProgressProvider] instance to allow scheduling of ad
   /// breaks based on content progress (cue points).
   final PlatformContentProgressProvider? contentProgressProvider;
+
+  /// Notifies the SDK whether the player intends to start the content and ad in
+  /// response to a user action or whether it will be automatically played.
+  final bool? adWillAutoPlay;
+
+  /// Notifies the SDK whether the player intends to start the content and ad
+  /// while muted.
+  final bool? adWillPlayMuted;
+
+  /// Notifies the SDK whether the player intends to continuously play the
+  /// content videos one after another similar to TV broadcast.
+  final bool? continuousPlayback;
+
+  /// Specifies the duration of the content to be shown.
+  final Duration? contentDuration;
+
+  /// Specifies the keywords used to describe the content to be shown.
+  final List<String>? contentKeywords;
+
+  /// Specifies the title of the content to be shown.
+  final String? contentTitle;
+
+  /// Specifies the maximum amount of time to wait, after calling requestAds,
+  /// before requesting the ad tag URL.
+  final Duration? liveStreamPrefetchMaxWaitTime;
+
+  /// Specifies the VAST load timeout for a single wrapper.
+  final Duration? vastLoadTimeout;
+}
+
+/// An object containing the data used to request ads from the server with an
+/// ad tag URL.
+base class PlatformAdsRequestWithAdTagUrl extends PlatformAdsRequest {
+  /// Constructs a [PlatformAdsRequestWithAdTagUrl].
+  PlatformAdsRequestWithAdTagUrl._({
+    required this.adTagUrl,
+    super.contentProgressProvider,
+    super.adWillAutoPlay,
+    super.adWillPlayMuted,
+    super.continuousPlayback,
+    super.contentDuration,
+    super.contentKeywords,
+    super.contentTitle,
+    super.liveStreamPrefetchMaxWaitTime,
+    super.vastLoadTimeout,
+  }) : super._();
+
+  /// The URL from which ads will be requested.
+  final String adTagUrl;
+}
+
+/// An object containing the data used to request ads from the server with an
+/// ad rules response.
+base class PlatformAdsRequestWithAdsResponse extends PlatformAdsRequest {
+  /// Constructs a [PlatformAdsRequestWithAdsResponse].
+  PlatformAdsRequestWithAdsResponse._({
+    required this.adsResponse,
+    super.contentProgressProvider,
+    super.adWillAutoPlay,
+    super.adWillPlayMuted,
+    super.continuousPlayback,
+    super.contentDuration,
+    super.contentKeywords,
+    super.contentTitle,
+    super.liveStreamPrefetchMaxWaitTime,
+    super.vastLoadTimeout,
+  }) : super._();
+
+  /// Specifies a VAST, VMAP, or ad rules response to be used instead of making
+  /// a request through an ad tag URL.
+  final String adsResponse;
 }