|
| 1 | +# google_adsense |
| 2 | +[Google AdSense](https://adsense.google.com/intl/en_us/start/) plugin for Flutter Web |
| 3 | + |
| 4 | +This package initializes AdSense on your website and provides an ad unit `Widget` that can be configured and placed in the desired location in your Flutter web app UI, without having to directly modify the HTML markup of the app directly. |
| 5 | + |
| 6 | +## Disclaimer: Early Access ⚠️ |
| 7 | +This package is currently in early access and is provided as-is. While it's open source and publicly available, it's likely that you'll need to make additional customizations and configurations to fully integrate it with your Flutter Web App. |
| 8 | +Please express interest joining Early Access program using [this form](https://docs.google.com/forms/d/e/1FAIpQLSdN6aOwVkaxGdxbVQFVZ_N4_UCBkuWYa-cS4_rbU_f1jK10Tw/viewform) |
| 9 | + |
| 10 | +## Usage |
| 11 | + |
| 12 | +### Setup your AdSense account |
| 13 | +1. [Make sure your site's pages are ready for AdSense](https://support.google.com/adsense/answer/7299563?hl=en&sjid=5790642343077592212-EU&visit_id=638657100661171978-1373860041&ref_topic=1319756&rd=1) |
| 14 | +2. [Create your AdSense account](https://support.google.com/adsense/answer/10162?hl=en&sjid=5790642343077592212-EU&visit_id=638657100661171978-1373860041&ref_topic=1250103&rd=1) |
| 15 | + |
| 16 | +### Initialize AdSense |
| 17 | +To start displaying ads, initialize the AdSense with your [client/publisher ID](https://support.google.com/adsense/answer/105516?hl=en&sjid=5790642343077592212-EU) (only use numbers). |
| 18 | +<?code-excerpt "example/lib/main.dart (init)"?> |
| 19 | +```dart |
| 20 | +import 'package:google_adsense/experimental/google_adsense.dart'; |
| 21 | +
|
| 22 | +void main() { |
| 23 | + adSense.initialize( |
| 24 | + '0123456789012345'); // TODO: Replace with your Publisher ID (pub-0123456789012345) - https://support.google.com/adsense/answer/105516?hl=en&sjid=5790642343077592212-EU |
| 25 | + runApp(const MyApp()); |
| 26 | +} |
| 27 | +
|
| 28 | +``` |
| 29 | + |
| 30 | +### Enable Auto Ads |
| 31 | +In order to start displaying [Auto ads](https://support.google.com/adsense/answer/9261805?hl=en) 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 |
| 32 | + |
| 33 | +### Display ad unit Widget |
| 34 | + |
| 35 | +1. Create [ad units](https://support.google.com/adsense/answer/9183549?hl=en&ref_topic=9183242&sjid=5790642343077592212-EU) in your AdSense account |
| 36 | +2. Use relevant `AdUnitConfiguration` constructor as per table below |
| 37 | + |
| 38 | +| Ad Unit Type | `AdUnitConfiguration` constructor method | |
| 39 | +|----------------|--------------------------------------------| |
| 40 | +| Display Ads | `AdUnitConfiguration.displayAdUnit(...)` | |
| 41 | +| In-feed Ads | `AdUnitConfiguration.inFeedAdUnit(...)` | |
| 42 | +| In-article Ads | `AdUnitConfiguration.inArticleAdUnit(...)` | |
| 43 | +| Multiplex Ads | `AdUnitConfiguration.multiplexAdUnit(...)` | |
| 44 | + |
| 45 | +3. Translate data-attributes from snippet generated in AdSense Console into constructor arguments as described below: |
| 46 | +- drop `data-` prefix |
| 47 | +- translate kebab-case to camelCase |
| 48 | +- no need to translate `data-ad-client` as it the value was already passed at initialization |
| 49 | + |
| 50 | +For example snippet below |
| 51 | +```html |
| 52 | +<ins class="adsbygoogle" |
| 53 | + style="display:block" |
| 54 | + data-ad-client="ca-pub-0123456789012345" |
| 55 | + data-ad-slot="1234567890" |
| 56 | + data-ad-format="auto" |
| 57 | + data-full-width-responsive="true"></ins> |
| 58 | +<script> |
| 59 | + (adsbygoogle = window.adsbygoogle || []).push({}); |
| 60 | +</script> |
| 61 | +``` |
| 62 | +translates into |
| 63 | +<?code-excerpt "example/lib/main.dart (init-min)"?> |
| 64 | +```dart |
| 65 | +adSense.initialize( |
| 66 | + '0123456789012345'); // TODO: Replace with your Publisher ID (pub-0123456789012345) - https://support.google.com/adsense/answer/105516?hl=en&sjid=5790642343077592212-EU |
| 67 | +``` |
| 68 | +and |
| 69 | +<?code-excerpt "example/lib/main.dart (adUnit)"?> |
| 70 | +```dart |
| 71 | + adSense.adUnit(AdUnitConfiguration.displayAdUnit( |
| 72 | + adSlot: '1234567890', // TODO: Replace with your Ad Unit ID |
| 73 | + adFormat: AdFormat |
| 74 | + .AUTO, // Remove AdFormat to make ads limited by height |
| 75 | +)) |
| 76 | +``` |
| 77 | + |
| 78 | +#### Customize ad unit Widget |
| 79 | +To [modify your responsive ad code](https://support.google.com/adsense/answer/9183363?hl=en&ref_topic=9183242&sjid=11551379421978541034-EU): |
| 80 | +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) |
| 81 | +2. Use Flutter instruments for [adaptive and responsive design](https://docs.flutter.dev/ui/adaptive-responsive) |
| 82 | + |
| 83 | +For example, when not using responsive `AdFormat` it is recommended to wrap adUnit widget in the `Container` with width and/or height constraints. |
| 84 | +Note some [policies and restrictions](https://support.google.com/adsense/answer/9185043?hl=en#:~:text=Policies%20and%20restrictions) related to ad unit sizing: |
| 85 | + |
| 86 | +<?code-excerpt "example/lib/main.dart (constraints)"?> |
| 87 | +```dart |
| 88 | +Container( |
| 89 | + constraints: |
| 90 | + const BoxConstraints(maxHeight: 100, maxWidth: 1200), |
| 91 | + padding: const EdgeInsets.only(bottom: 10), |
| 92 | + child: adSense.adUnit(AdUnitConfiguration.displayAdUnit( |
| 93 | + adSlot: '1234567890', // TODO: Replace with your Ad Unit ID |
| 94 | + adFormat: AdFormat |
| 95 | + .AUTO, // Not using AdFormat to make ad unit respect height constraint |
| 96 | + )), |
| 97 | +), |
| 98 | +``` |
| 99 | +## Testing and common errors |
| 100 | + |
| 101 | +### Failed to load resource: the server responded with a status of 400 |
| 102 | +Make sure to set correct values to adSlot and adClient arguments |
| 103 | + |
| 104 | +### Failed to load resource: the server responded with a status of 403 |
| 105 | +1. When happening in **testing/staging** environment it is likely related to the fact that ads are only filled when requested from an authorized domain. If you are testing locally and running your web app on `localhost`, you need to: |
| 106 | + 1. Set custom domain name on localhost by creating a local DNS record that would point `127.0.0.1` and/or `localhost` to `your-domain.com`. On mac/linux machines this can be achieved by adding the following records to you /etc/hosts file: |
| 107 | + `127.0.0.1 your-domain.com` |
| 108 | + `localhost your-domain.com` |
| 109 | + 2. Specify additional run arguments in IDE by editing `Run/Debug Configuration` or by passing them directly to `flutter run` command: |
| 110 | + `--web-port=8080` |
| 111 | + `--web-hostname=your-domain.com` |
| 112 | +2. When happening in **production** it might be that your domain was not yet approved or was disapproved. Login to your AdSense account to check your domain approval status |
| 113 | + |
| 114 | +### Ad unfilled |
| 115 | + |
| 116 | +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: |
| 117 | +- Try setting `adTest` parameter to `true` |
| 118 | +- Try setting AD_FORMAT to `auto` (default setting) |
| 119 | +- Try setting FULL_WIDTH_RESPONSIVE to `true` (default setting) |
| 120 | +- Try resizing the window or making sure that ad unit Widget width is less than ~1200px |
0 commit comments