Remove stubs and expose AdUnitWidget directly.

Author: ditman

packages/google_adsense/CHANGELOG.md

@@ -1,11 +1,11 @@
 ## 0.0.2
 
 * **Breaking changes**: Reshuffles API exports:
-  * Renames `experimental/google_adsense` to `experimental/adsense`.
-  * Removes `AdStatus` and `AdUnitParams` from `experimental/google_adsense`.
-  * Moves `AdSense` and its `adSense` singleton to the root export.
-  * Removes the `adUnit` method from `AdSense`, which is now provided through
-    an extension from `experimental/adsense`.
+  * Removes the `adUnit` method, and instead exports the `AdUnitWidget` directly.
+  * Renames `experimental/google_adsense` to `experimental/ad_unit_widget.dart`.
+  * Removes the `AdStatus` and `AdUnitParams` exports.
+  * Removes the "stub" files, so this package is now web-only and must be used
+    through a conditional import.
 * Tweaks several documentation pages to remove references to internal APIs.
 * Splits tests to reflect the new code structure.
 

packages/google_adsense/README.md

@@ -18,7 +18,7 @@ To start displaying ads, initialize AdSense with your [Publisher ID](https://sup
 
 <?code-excerpt "example/lib/main.dart (init)"?>
 ```dart
-import 'package:google_adsense/experimental/adsense.dart';
+import 'package:google_adsense/experimental/ad_unit_widget.dart';
 import 'package:google_adsense/google_adsense.dart';
 
 void main() {
@@ -30,13 +30,22 @@ void main() {
 }
 ```
 
-### Enable Auto Ads
-In order to start displaying [Auto ads](https://support.google.com/adsense/answer/9261805) make sure to configure this feature in your AdSense Console. If you want to display ad units within your app content, continue to the next step
+### Displaying Auto Ads
+In order to start displaying [Auto ads](https://support.google.com/adsense/answer/9261805):
 
-### Display ad unit Widget
+1. Configure this feature in your AdSense Console.
 
-1. Create [ad units](https://support.google.com/adsense/answer/9183549) in your AdSense account
-2. Use relevant `AdUnitConfiguration` constructor as per table below
+Auto ads should start showing just with the call to `initialize`, when available.
+
+If you want to display ad units within your app content, continue to the next step
+
+### Display ad units (`AdUnitWidget`)
+
+To display an Ad unit in your Flutter application:
+
+1. Create [ad units](https://support.google.com/adsense/answer/9183549) in your AdSense account.
+   This will provide an HTML snippet, which you need to translate to Dart.
+2. Pick the `AdUnitConfiguration` for your ad type:
 
 | Ad Unit Type   | `AdUnitConfiguration` constructor method   |
 |----------------|--------------------------------------------|
@@ -81,14 +90,18 @@ and:
 
 <?code-excerpt "example/lib/main.dart (adUnit)"?>
 ```dart
-    adSense.adUnit(AdUnitConfiguration.displayAdUnit(
-  adSlot: '1234567890', // TODO: Replace with your Ad Unit ID
-  adFormat: AdFormat
-      .AUTO, // Remove AdFormat to make ads limited by height
-))
+    AdUnitWidget(
+  configuration: AdUnitConfiguration.displayAdUnit(
+    // TODO: Replace with your Ad Unit ID
+    adSlot: '1234567890',
+    // Remove AdFormat to make ads limited by height
+    adFormat: AdFormat.AUTO,
+  ),
+),
 ```
 
-#### Customize ad unit Widget
+#### `AdUnitWidget` customizations
+
 To [modify your responsive ad code](https://support.google.com/adsense/answer/9183363?hl=en&ref_topic=9183242&sjid=11551379421978541034-EU):
 1. Make sure to follow [AdSense policies](https://support.google.com/adsense/answer/1346295?hl=en&sjid=18331098933308334645-EU&visit_id=638689380593964621-4184295127&ref_topic=1271508&rd=1)
 2. Use Flutter instruments for [adaptive and responsive design](https://docs.flutter.dev/ui/adaptive-responsive)
@@ -102,10 +115,14 @@ Container(
   constraints:
       const BoxConstraints(maxHeight: 100, maxWidth: 1200),
   padding: const EdgeInsets.only(bottom: 10),
-  child: adSense.adUnit(AdUnitConfiguration.displayAdUnit(
-    adSlot: '1234567890', // TODO: Replace with your Ad Unit ID
-    // adFormat: AdFormat.AUTO, // Not using AdFormat to make ad unit respect height constraint
-  )),
+  child: AdUnitWidget(
+    configuration: AdUnitConfiguration.displayAdUnit(
+      // TODO: Replace with your Ad Unit ID
+      adSlot: '1234567890',
+      // Do not use adFormat to make ad unit respect height constraint
+      // adFormat: AdFormat.AUTO,
+    ),
+  ),
 ),
 ```
 ## Testing and common errors
@@ -126,6 +143,7 @@ Make sure to set correct values to adSlot and adClient arguments
 ### Ad unfilled  
 
 There is no deterministic way to make sure your ads are 100% filled even when testing. Some of the way to increase the fill rate:
+- Ensure your ad units are correctly configured in AdSense
 - Try setting `adTest` parameter to `true`  
 - Try setting AD_FORMAT to `auto` (default setting)
 - Try setting FULL_WIDTH_RESPONSIVE to `true` (default setting)

packages/google_adsense/example/integration_test/experimental_google_adsense_test.dart renamed to packages/google_adsense/example/integration_test/experimental_ad_unit_widget_test.dart

@@ -8,11 +8,10 @@
 
 import 'package:flutter/material.dart';
 import 'package:flutter_test/flutter_test.dart';
-import 'package:google_adsense/experimental/adsense.dart';
+import 'package:google_adsense/experimental/ad_unit_widget.dart';
 // Ensure we don't use the `adSense` singleton for tests.
 import 'package:google_adsense/google_adsense.dart' hide adSense;
 import 'package:google_adsense/src/adsense/ad_unit_params.dart';
-import 'package:google_adsense/src/adsense/ad_unit_widget.dart';
 import 'package:integration_test/integration_test.dart';
 
 import 'adsense_test_js_interop.dart';
@@ -48,11 +47,12 @@ void main() async {
 
       adSense.initialize(testClient);
 
-      final Widget adUnitWidget = adSense.adUnit(
-        AdUnitConfiguration.displayAdUnit(
+      final Widget adUnitWidget = AdUnitWidget(
+        configuration: AdUnitConfiguration.displayAdUnit(
           adSlot: testSlot,
           adFormat: AdFormat.AUTO, // Important!
         ),
+        adClient: adSense.adClient,
       );
 
       await pumpAdWidget(adUnitWidget, tester);
@@ -81,10 +81,11 @@ void main() async {
 
       adSense.initialize(testClient);
 
-      final Widget adUnitWidget = adSense.adUnit(
-        AdUnitConfiguration.displayAdUnit(
+      final Widget adUnitWidget = AdUnitWidget(
+        configuration: AdUnitConfiguration.displayAdUnit(
           adSlot: testSlot,
         ),
+        adClient: adSense.adClient,
       );
 
       final Widget constrainedAd = Container(
@@ -109,10 +110,11 @@ void main() async {
       mockAdsByGoogle(mockAd(adStatus: AdStatus.UNFILLED));
 
       adSense.initialize(testClient);
-      final Widget adUnitWidget = adSense.adUnit(
-        AdUnitConfiguration.displayAdUnit(
+      final Widget adUnitWidget = AdUnitWidget(
+        configuration: AdUnitConfiguration.displayAdUnit(
           adSlot: testSlot,
         ),
+        adClient: adSense.adClient,
       );
 
       await pumpAdWidget(adUnitWidget, tester);
@@ -142,19 +144,28 @@ void main() async {
 
       final Widget bunchOfAds = Column(
         children: <Widget>[
-          adSense.adUnit(AdUnitConfiguration.displayAdUnit(
-            adSlot: testSlot,
-            adFormat: AdFormat.AUTO,
-          )),
-          adSense.adUnit(AdUnitConfiguration.displayAdUnit(
-            adSlot: testSlot,
-            adFormat: AdFormat.AUTO,
-          )),
+          AdUnitWidget(
+            configuration: AdUnitConfiguration.displayAdUnit(
+              adSlot: testSlot,
+              adFormat: AdFormat.AUTO,
+            ),
+            adClient: adSense.adClient,
+          ),
+          AdUnitWidget(
+            configuration: AdUnitConfiguration.displayAdUnit(
+              adSlot: testSlot,
+              adFormat: AdFormat.AUTO,
+            ),
+            adClient: adSense.adClient,
+          ),
           Container(
             constraints: const BoxConstraints(maxHeight: 100),
-            child: adSense.adUnit(AdUnitConfiguration.displayAdUnit(
-              adSlot: testSlot,
-            )),
+            child: AdUnitWidget(
+              configuration: AdUnitConfiguration.displayAdUnit(
+                adSlot: testSlot,
+              ),
+              adClient: adSense.adClient,
+            ),
           ),
         ],
       );

packages/google_adsense/example/lib/main.dart

@@ -7,7 +7,7 @@
 import 'package:flutter/material.dart';
 
 // #docregion init
-import 'package:google_adsense/experimental/adsense.dart';
+import 'package:google_adsense/experimental/ad_unit_widget.dart';
 import 'package:google_adsense/google_adsense.dart';
 
 void main() {
@@ -69,13 +69,15 @@ class _MyHomePageState extends State<MyHomePage> {
                 padding: const EdgeInsets.only(bottom: 10),
                 child:
                     // #docregion adUnit
-                    adSense.adUnit(AdUnitConfiguration.displayAdUnit(
-                  adSlot: '1234567890', // TODO: Replace with your Ad Unit ID
-                  adFormat: AdFormat
-                      .AUTO, // Remove AdFormat to make ads limited by height
-                ))
+                    AdUnitWidget(
+                  configuration: AdUnitConfiguration.displayAdUnit(
+                    // TODO: Replace with your Ad Unit ID
+                    adSlot: '1234567890',
+                    // Remove AdFormat to make ads limited by height
+                    adFormat: AdFormat.AUTO,
+                  ),
+                ),
                 // #enddocregion adUnit
-                ,
               ),
               const Text(
                 'Responsive Ad Constrained by height of 100px and width of 1200px (to keep ad centered):',
@@ -85,10 +87,14 @@ class _MyHomePageState extends State<MyHomePage> {
                 constraints:
                     const BoxConstraints(maxHeight: 100, maxWidth: 1200),
                 padding: const EdgeInsets.only(bottom: 10),
-                child: adSense.adUnit(AdUnitConfiguration.displayAdUnit(
-                  adSlot: '1234567890', // TODO: Replace with your Ad Unit ID
-                  // adFormat: AdFormat.AUTO, // Not using AdFormat to make ad unit respect height constraint
-                )),
+                child: AdUnitWidget(
+                  configuration: AdUnitConfiguration.displayAdUnit(
+                    // TODO: Replace with your Ad Unit ID
+                    adSlot: '1234567890',
+                    // Do not use adFormat to make ad unit respect height constraint
+                    // adFormat: AdFormat.AUTO,
+                  ),
+                ),
               ),
               // #enddocregion constraints
               const Text(
@@ -98,10 +104,13 @@ class _MyHomePageState extends State<MyHomePage> {
                 height: 125,
                 width: 125,
                 padding: const EdgeInsets.only(bottom: 10),
-                child: adSense.adUnit(AdUnitConfiguration.displayAdUnit(
-                    adSlot: '1234567890', // TODO: Replace with your Ad Unit ID
-                    // adFormat: AdFormat.AUTO, // Not using AdFormat to make ad unit respect height constraint
-                    isFullWidthResponsive: false)),
+                child: AdUnitWidget(
+                  configuration: AdUnitConfiguration.displayAdUnit(
+                    // TODO: Replace with your Ad Unit ID
+                    adSlot: '1234567890',
+                    isFullWidthResponsive: false,
+                  ),
+                ),
               ),
             ],
           ),

packages/google_adsense/lib/experimental/adsense.dart renamed to packages/google_adsense/lib/experimental/ad_unit_widget.dart

@@ -2,8 +2,4 @@
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
-import 'src/core/core.dart';
-export 'src/core/core.dart';
-
-/// The singleton instance of the AdSense SDK.
-final AdSense adSense = AdSense();
+export 'src/core/google_adsense.dart';

packages/google_adsense/lib/google_adsense.dart

@@ -6,10 +6,7 @@ import 'package:flutter/foundation.dart';
 
 import 'ad_unit_params.dart';
 
-/// Ad request configuration object.
-///
-/// Used to configure the ad widget request through the `adSense.adUnit` method
-/// (see: [AdUnitExtension]).
+/// Configuration to customize the [AdUnitWidget].
 ///
 /// Contains named constructors for the following supported ad unit types:
 ///

packages/google_adsense/lib/src/adsense/ad_unit_configuration.dart

@@ -43,9 +43,9 @@ class AdUnitParams {
   static const String AD_TEST = 'adtest';
 }
 
-/// Possible values for [AdUnitParams.AD_FORMAT].
+/// Specifies the general shape that the ad unit should conform to.
 ///
-/// See [docs](https://support.google.com/adsense/answer/9183460?hl=en&ref_topic=9183242&sjid=2004567335727763076-EU#:~:text=Specify%20a%20general%20shape%20(desktop%20only)) for details
+/// See [docs](https://support.google.com/adsense/answer/9183460?hl=en&ref_topic=9183242&sjid=2004567335727763076-EU#:~:text=Specify%20a%20general%20shape%20(desktop%20only)) for details.
 enum AdFormat {
   /// Default which enables the auto-sizing behavior for the responsive ad unit
   AUTO('auto'),
@@ -81,8 +81,7 @@ enum AdFormat {
   String toString() => _adFormat;
 }
 
-/// Possible values for [AdUnitParams.AD_LAYOUT].
-///
+/// Controls the general layout of an in-feed/in-article ad unit.
 // TODO(sokoloff06): find docs link!
 enum AdLayout {
   ///
@@ -107,9 +106,9 @@ enum AdLayout {
   String toString() => _adLayout;
 }
 
-/// Possible values for [AdUnitParams.MATCHED_CONTENT_UI_TYPE].
+/// Controls the arrangement of the text and images in a Multiplex ad unit.
 ///
-/// See [docs](https://support.google.com/adsense/answer/7533385?hl=en#:~:text=Change%20the%20layout%20of%20your%20Multiplex%20ad%20unit)
+/// See [docs](https://support.google.com/adsense/answer/7533385?hl=en#:~:text=Change%20the%20layout%20of%20your%20Multiplex%20ad%20unit).
 enum MatchedContentUiType {
   /// In this layout, the image and text appear alongside each other.
   IMAGE_CARD_SIDEBYSIDE('image_card_sidebyside'),

packages/google_adsense/lib/src/adsense/ad_unit_params.dart

@@ -8,23 +8,38 @@ import 'dart:js_interop_unsafe';
 import 'package:flutter/widgets.dart';
 import 'package:web/web.dart' as web;
 
+import '../core/google_adsense.dart';
 import '../js_interop/adsbygoogle.dart';
-import '../logging.dart';
+import '../utils/logging.dart';
 import 'ad_unit_configuration.dart';
 import 'ad_unit_params.dart';
 import 'adsense_js_interop.dart';
 
-/// Widget displaying an ad unit
+/// Widget displaying an ad unit.
+///
+/// See the [AdUnitConfiguration] object for a complete reference of the available
+/// parameters.
+///
+/// When specifying an [AdFormat], the widget will behave like a "responsive"
+/// ad unit. Responsive ad units might attempt to overflow the container in which
+/// they're rendered.
+///
+/// To create a fully constrained widget (specific width/height), do *not* pass
+/// an `AdFormat` value, and wrap the `AdUnitWidget` in a constrained box from
+/// Flutter, like a [Container] or [SizedBox].
 class AdUnitWidget extends StatefulWidget {
   /// Constructs [AdUnitWidget]
-  const AdUnitWidget({
+  AdUnitWidget({
     super.key,
-    required String adClient,
     required AdUnitConfiguration configuration,
-  })  : _adClient = adClient,
-        _adUnitConfiguration = configuration;
+    @visibleForTesting String? adClient,
+  })  : _adClient = adClient ?? adSense.adClient,
+        _adUnitConfiguration = configuration {
+    assert(_adClient != null,
+        'Attempted to render an AdUnitWidget before calling adSense.initialize');
+  }
 
-  final String _adClient;
+  final String? _adClient;
 
   final AdUnitConfiguration _adUnitConfiguration;
 

packages/google_adsense/lib/src/adsense/ad_unit_widget.dart

@@ -4,5 +4,4 @@
 
 export 'ad_unit_configuration.dart';
 export 'ad_unit_params.dart' hide AdStatus, AdUnitParams;
-export 'adsense_extension_stub.dart'
-    if (dart.library.js_interop) 'adsense_extension.dart';
+export 'ad_unit_widget.dart';