Skip to content

Commit cb9ab42

Browse files
astiviastivi
authored
[google_adsense] Adds H5 Games Ads support to package. (#7747)
This PR adds support for the H5 Games Ads (Ad Placement API) product to `package:google_adsense` through a new `h5.dart` library. Product page: * https://adsense.google.com/start/h5-games-ads JS API reference: * https://developers.google.com/ad-placement/apis ## Issues * Continuation of: #6871 * Continuation of: #8233 * Part of: flutter/flutter#40376
1 parent c3787ff commit cb9ab42

29 files changed

+1526
-270
lines changed

‎packages/google_adsense/CHANGELOG.md

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,7 @@
1+
## 0.1.0
2+
3+
* Adds H5 Games Ads API as `h5` library.
4+
15
## 0.0.2
26

37
* **Breaking changes**: Reshuffles API exports:

‎packages/google_adsense/README.md

Lines changed: 21 additions & 137 deletions
Original file line numberDiff line numberDiff line change
@@ -1,150 +1,34 @@
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)
14-
2. [Create your AdSense account](https://support.google.com/adsense/answer/10162)
15-
16-
### Initialize AdSense
17-
To start displaying ads, initialize AdSense with your [Publisher ID](https://support.google.com/adsense/answer/105516) (only use numbers).
18-
19-
<?code-excerpt "example/lib/main.dart (init)"?>
20-
```dart
21-
import 'package:google_adsense/experimental/ad_unit_widget.dart';
22-
import 'package:google_adsense/google_adsense.dart';
23-
24-
void main() async {
25-
// Call `initialize` with your Publisher ID (pub-0123456789012345)
26-
// (See: https://support.google.com/adsense/answer/105516)
27-
await adSense.initialize('0123456789012345');
28-
29-
runApp(const MyApp());
30-
}
31-
```
32-
33-
### Displaying Auto Ads
34-
In order to start displaying [Auto ads](https://support.google.com/adsense/answer/9261805):
35-
36-
1. Configure this feature in your AdSense Console.
1+
# Before you start
372

38-
Auto ads should start showing just with the call to `initialize`, when available.
3+
This package is only intended for use by web **games**.
394

40-
If you want to display ad units within your app content, continue to the next step
5+
Please apply to the beta using [this form]( https://adsense.google.com/start/h5-beta/?src=flutter). Once approved, you may use the package.
416

42-
### Display ad units (`AdUnitWidget`)
7+
Without approval, your code may not behave as expected, and your AdSense account may face policy issues.
438

44-
To display an Ad unit in your Flutter application:
45-
46-
1. Create [ad units](https://support.google.com/adsense/answer/9183549) in your AdSense account.
47-
This will provide an HTML snippet, which you need to translate to Dart.
48-
2. Pick the `AdUnitConfiguration` for your ad type:
49-
50-
| Ad Unit Type | `AdUnitConfiguration` constructor method |
51-
|----------------|--------------------------------------------|
52-
| Display Ads | `AdUnitConfiguration.displayAdUnit(...)` |
53-
| In-feed Ads | `AdUnitConfiguration.inFeedAdUnit(...)` |
54-
| In-article Ads | `AdUnitConfiguration.inArticleAdUnit(...)` |
55-
| Multiplex Ads | `AdUnitConfiguration.multiplexAdUnit(...)` |
56-
57-
3. The data-attributes from the generated snippet are available through the `AdUnitConfiguration` object.
58-
Their Dart name is created as follows:
59-
60-
- The `data-` prefix is **removed**.
61-
- `kebab-case` becomes `camelCase`
62-
63-
The only exception to this is `data-ad-client`, that is passed to `adSense.initialize`,
64-
instead of through an `AdUnitConfiguration` object.
65-
66-
For example snippet below:
67-
68-
```html
69-
<ins class="adsbygoogle"
70-
style="display:block"
71-
data-ad-client="ca-pub-0123456789012345"
72-
data-ad-slot="1234567890"
73-
data-ad-format="auto"
74-
data-full-width-responsive="true"></ins>
75-
<script>
76-
(adsbygoogle = window.adsbygoogle || []).push({});
77-
</script>
78-
```
79-
translates into:
80-
81-
<?code-excerpt "example/lib/main.dart (init-min)"?>
82-
```dart
83-
// Call `initialize` with your Publisher ID (pub-0123456789012345)
84-
// (See: https://support.google.com/adsense/answer/105516)
85-
await adSense.initialize('0123456789012345');
86-
87-
```
88-
89-
and:
9+
# google_adsense
9010

91-
<?code-excerpt "example/lib/main.dart (adUnit)"?>
92-
```dart
93-
AdUnitWidget(
94-
configuration: AdUnitConfiguration.displayAdUnit(
95-
// TODO: Replace with your Ad Unit ID
96-
adSlot: '1234567890',
97-
// Remove AdFormat to make ads limited by height
98-
adFormat: AdFormat.AUTO,
99-
),
100-
),
101-
```
11+
[Google AdSense](https://adsense.google.com/start/) plugin for Flutter Web.
10212

103-
#### `AdUnitWidget` customizations
13+
This package provides a way to initialize and use AdSense on your Flutter Web app.
14+
It includes libraries for the following products:
10415

105-
To [modify your responsive ad code](https://support.google.com/adsense/answer/9183363?hl=en&ref_topic=9183242&sjid=11551379421978541034-EU):
106-
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)
107-
2. Use Flutter instruments for [adaptive and responsive design](https://docs.flutter.dev/ui/adaptive-responsive)
16+
* [H5 Games Ads](https://adsense.google.com/start/h5-games-ads/) (beta)
17+
* (Experimental) [AdSense Ad Unit](https://support.google.com/adsense/answer/9183549) Widget
10818

109-
For example, when not using responsive `AdFormat` it is recommended to wrap adUnit widget in the `Container` with width and/or height constraints.
110-
Note some [policies and restrictions](https://support.google.com/adsense/answer/9185043?hl=en#:~:text=Policies%20and%20restrictions) related to ad unit sizing:
19+
## Documentation
11120

112-
<?code-excerpt "example/lib/main.dart (constraints)"?>
113-
```dart
114-
Container(
115-
constraints:
116-
const BoxConstraints(maxHeight: 100, maxWidth: 1200),
117-
padding: const EdgeInsets.only(bottom: 10),
118-
child: AdUnitWidget(
119-
configuration: AdUnitConfiguration.displayAdUnit(
120-
// TODO: Replace with your Ad Unit ID
121-
adSlot: '1234567890',
122-
// Do not use adFormat to make ad unit respect height constraint
123-
// adFormat: AdFormat.AUTO,
124-
),
125-
),
126-
),
127-
```
128-
## Testing and common errors
21+
Check the [Flutter API docs](https://pub.dev/documentation/google_adsense/latest/)
22+
to learn how to:
12923

130-
### Failed to load resource: the server responded with a status of 400
131-
Make sure to set correct values to adSlot and adClient arguments
24+
* [Initialize AdSense](https://pub.dev/documentation/google_adsense/latest/topics/Initialization-topic.html)
25+
* [Use H5 Games Ads](https://pub.dev/documentation/google_adsense/latest/topics/H5%20Games%20Ads-topic.html) (beta)
26+
* [Display Ad Units](https://pub.dev/documentation/google_adsense/latest/topics/Ad%20Units-topic.html) (experimental)
13227

133-
### Failed to load resource: the server responded with a status of 403
134-
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:
135-
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:
136-
`127.0.0.1 your-domain.com`
137-
`localhost your-domain.com`
138-
2. Specify additional run arguments in IDE by editing `Run/Debug Configuration` or by passing them directly to `flutter run` command:
139-
`--web-port=8080`
140-
`--web-hostname=your-domain.com`
141-
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
28+
## Support
14229

143-
### Ad unfilled
30+
For technical problems with the code of this package, please
31+
[create a Github issue](https://github.com/flutter/flutter/issues/new?assignees=&labels=&projects=&template=9_first_party_packages.yml).
14432

145-
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:
146-
- Ensure your ad units are correctly configured in AdSense
147-
- Try setting `adTest` parameter to `true`
148-
- Try setting AD_FORMAT to `auto` (default setting)
149-
- Try setting FULL_WIDTH_RESPONSIVE to `true` (default setting)
150-
- Try resizing the window or making sure that ad unit Widget width is less than ~1200px
33+
For any questions or support, please reach out to your Google representative or
34+
leverage the [AdSense Help Center](https://support.google.com/adsense#topic=3373519).

‎packages/google_adsense/dartdoc_options.yaml

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
dartdoc:
2+
categories:
3+
"Initialization":
4+
markdown: doc/initialization.md
5+
"H5 Games Ads":
6+
markdown: doc/h5.md
7+
"Ad Units":
8+
markdown: doc/ad_unit_widget.md
9+
categoryOrder:
10+
- "Initialization"
11+
- "H5 Games Ads"
12+
- "Ad Units"
13+
showUndocumentedCategories: true

‎packages/google_adsense/doc/ad_unit_widget.md

Lines changed: 140 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,140 @@
1+
# Before you start
2+
3+
This library is in a closed early access, and the list is closed for now.
4+
5+
Stay tuned for expanded availability of the Ad Unit Widget for Flutter web.
6+
7+
# `AdUnitWidget`
8+
9+
The `experimental/ad_unit_widget.dart` library provides an `AdUnitWidget` that
10+
can be configured and placed in the widget tree of your Flutter web app.
11+
12+
## Usage
13+
14+
First, initialize AdSense (see the
15+
[Initialization](https://pub.dev/documentation/google_adsense/latest/topics/Initialization-topic.html)
16+
topic).
17+
18+
### Displaying Auto Ads
19+
20+
In order to start displaying [Auto ads](https://support.google.com/adsense/answer/9261805):
21+
22+
1. Configure this feature in your AdSense Console.
23+
24+
Auto ads should start showing just with the call to `initialize`, when available.
25+
26+
If you want to display ad units within your app content, continue to the next steps:
27+
28+
### Import the widget
29+
30+
Import the **experimental** `AdUnitWidget` from the package:
31+
32+
<?code-excerpt "../example/lib/ad_unit_widget.dart (import-widget)"?>
33+
```dart
34+
import 'package:google_adsense/experimental/ad_unit_widget.dart';
35+
```
36+
37+
### Displaying Ad Units
38+
39+
To display AdSense Ad Units in your Flutter application layout:
40+
41+
1. Create [ad units](https://support.google.com/adsense/answer/9183549)
42+
in your AdSense account. This will provide an HTML snippet, which you need to
43+
_translate_ to Dart.
44+
2. The data-attributes from the generated snippet can be translated to Dart with the `AdUnitConfiguration` object.
45+
Their Dart name is created as follows:
46+
- The `data-` prefix is removed.
47+
- `kebab-case` becomes `camelCase`
48+
49+
The only exception to this is `data-ad-client`, that is passed to `adSense.initialize`,
50+
instead of through an `AdUnitConfiguration` object.
51+
52+
For example, the snippet below:
53+
54+
```html
55+
<ins class="adsbygoogle"
56+
style="display:block"
57+
data-ad-client="ca-pub-0123456789012345"
58+
data-ad-slot="1234567890"
59+
data-ad-format="auto"
60+
data-full-width-responsive="true"></ins>
61+
<script>
62+
(adsbygoogle = window.adsbygoogle || []).push({});
63+
</script>
64+
```
65+
66+
translates into:
67+
68+
<?code-excerpt "../example/lib/ad_unit_widget.dart (adUnit)"?>
69+
```dart
70+
AdUnitWidget(
71+
configuration: AdUnitConfiguration.displayAdUnit(
72+
// TODO: Replace with your Ad Unit ID
73+
adSlot: '1234567890',
74+
// Remove AdFormat to make ads limited by height
75+
adFormat: AdFormat.AUTO,
76+
),
77+
),
78+
```
79+
80+
#### **`AdUnitConfiguration` constructors**
81+
82+
In addition to `displayAdUnit`, there's specific constructors for each supported
83+
Ad Unit type. See the table below:
84+
85+
| Ad Unit Type | `AdUnitConfiguration` constructor method |
86+
|----------------|--------------------------------------------|
87+
| Display Ads | `AdUnitConfiguration.displayAdUnit(...)` |
88+
| In-feed Ads | `AdUnitConfiguration.inFeedAdUnit(...)` |
89+
| In-article Ads | `AdUnitConfiguration.inArticleAdUnit(...)` |
90+
| Multiplex Ads | `AdUnitConfiguration.multiplexAdUnit(...)` |
91+
92+
93+
#### **`AdUnitWidget` customizations**
94+
95+
To [modify your responsive ad code](https://support.google.com/adsense/answer/9183363?hl=en&ref_topic=9183242&sjid=11551379421978541034-EU):
96+
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)
97+
2. Use Flutter instruments for [adaptive and responsive design](https://docs.flutter.dev/ui/adaptive-responsive)
98+
99+
For example, when not using responsive `AdFormat` it is recommended to wrap adUnit widget in the `Container` with width and/or height constraints.
100+
Note some [policies and restrictions](https://support.google.com/adsense/answer/9185043?hl=en#:~:text=Policies%20and%20restrictions) related to ad unit sizing:
101+
102+
<?code-excerpt "../example/lib/ad_unit_widget.dart (constraints)"?>
103+
```dart
104+
Container(
105+
constraints:
106+
const BoxConstraints(maxHeight: 100, maxWidth: 1200),
107+
padding: const EdgeInsets.only(bottom: 10),
108+
child: AdUnitWidget(
109+
configuration: AdUnitConfiguration.displayAdUnit(
110+
// TODO: Replace with your Ad Unit ID
111+
adSlot: '1234567890',
112+
// Do not use adFormat to make ad unit respect height constraint
113+
// adFormat: AdFormat.AUTO,
114+
),
115+
),
116+
),
117+
```
118+
## Testing and common errors
119+
120+
### Failed to load resource: the server responded with a status of 400
121+
Make sure to set correct values to adSlot and adClient arguments
122+
123+
### Failed to load resource: the server responded with a status of 403
124+
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:
125+
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:
126+
`127.0.0.1 your-domain.com`
127+
`localhost your-domain.com`
128+
2. Specify additional run arguments in IDE by editing `Run/Debug Configuration` or by passing them directly to `flutter run` command:
129+
`--web-port=8080`
130+
`--web-hostname=your-domain.com`
131+
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
132+
133+
### Ad unfilled
134+
135+
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:
136+
- Ensure your ad units are correctly configured in AdSense
137+
- Try setting `adTest` parameter to `true`
138+
- Try setting AD_FORMAT to `auto` (default setting)
139+
- Try setting FULL_WIDTH_RESPONSIVE to `true` (default setting)
140+
- Try resizing the window or making sure that ad unit Widget width is less than ~1200px

0 commit comments

Comments
 (0)